> For the complete documentation index, see [llms.txt](https://docs.dexpal.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.dexpal.io/for-partners/endpoints/user-positions.md). # User Positions Returns all currently open trading positions for the provided wallet addresses. > **Collection endpoint:** Return open positions for any requested address the DEX can read, even if the wallet has not used DexPal's affiliate code. If none of the provided addresses have open positions, return `200` with `"data": []`. See the [Overview](/for-partners/dex-api-spec.md). ## Overview | | | | -------------- | -------------- | | **Method** | GET | | **Auth** | Bearer API key | | **Rate limit** | 120 req/min | ## Request ### Query Parameters | Param | Type | Required | Description | | ------ | ------ | -------- | ------------------------------------------------------------------------------------------------ | | `addr` | string | yes | Comma-separated list of wallet addresses to query. Supports all address formats the DEX accepts. | ### Headers | Header | Required | Description | | --------------- | -------- | ------------------ | | `Authorization` | yes | `Bearer ` | ### Example Request ``` GET /dexpal/v1/users/positions?addr=0x1a2b...,0x9c3d...,0xdead... ``` ## Response Returns a `data` array of open position objects. Each item includes the address it belongs to. ### Fields — Position Object | Field | Type | Required | Description | | --------------------- | ---------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------- | | `positionId` | string | yes | Unique position identifier in the format `exchange:wallet:id` e.g. `"gmx:0x1a2b...:18"`. | | `address` | string | yes | The wallet address that owns this position. Matches one of the `addr` values in the request. | | `exchange` | string | yes | DEX slug e.g. `"gmx"`, `"gains"`, `"vela"`. | | `side` | enum | yes | Position direction. `long` or `short`. | | `baseAsset` | string | yes | Base currency symbol e.g. `"BTC"`. | | `quoteAsset` | string | yes | Quote currency symbol e.g. `"USD"`. | | `assetType` | string | yes | Asset category e.g. `"crypto"`. See [AssetObject](/for-partners/schemas/asset-object.md) for valid values. | | `avgEntryPrice` | number | yes | Average entry price in quote currency. Reflects the weighted average if the position was scaled in/out. | | `positionSizeUsd` | number | yes | Current position size in USD. | | `positionSizeToken` | number | yes | Current position size in base currency. | | `collateralUsd` | number | yes | Current collateral posted in USD. | | `leverage` | number | yes | Effective leverage at the current position size and collateral. | | `liquidationPrice` | number | yes | Price at which the position would be liquidated, in quote currency. | | `unrealizedPnl` | number | yes | Current unrealized profit/loss in USD. Positive = profit, negative = loss. | | `feeBorrowingUsd` | number | no | Total accrued borrow fees over the life of the position, in USD. | | `feeFundingUsd` | number | no | Total accrued funding fees over the life of the position, in USD. Negative if the position is receiving funding. | | `feeTradingUsd` | number | no | Total accrued trading fees over the life of the position, in USD. | | `feeNetworkUsd` | number | no | Total accrued gas/network fees over the life of the position, in USD. | | `chainId` | integer | no | Wagmi/viem chain ID of the network where the position is held. See [wagmi chains](https://wagmi.sh/core/api/chains). | | `tradeUrl` | string | no | Deep link to this specific position on the DEX. | | `createdAt` | ISO8601 | yes | Timestamp when the position was opened. | | `updatedAt` | ISO8601 | no | Timestamp of the most recent modification to the position (size change, collateral adjustment, etc.). | | `triggerOrders` | array\[[TriggerOrder](/for-partners/schemas/trigger-order.md)] | no | Associated stop loss and take profit orders. Empty array if none. | | `marginMode` | string | no | Margin isolation mode. `cross`, `isolated`, or `portfolio`. | | `collateralAsset` | string | no | Primary collateral asset symbol e.g. `"USDC"`. | | `collateralAmount` | number | no | Collateral amount in asset units (not USD). | | `collateralFactor` | number | no | Collateral haircut factor (0–1). Lower = less credit per unit of collateral. | | `collateralBreakdown` | array\[[CollateralBreakdown](/for-partners/schemas/collateral-breakdown.md)] | no | Per-asset collateral breakdown for multi-asset margin accounts. | | `accountId` | string | no | Subaccount or portfolio ID. For DEXes that support subaccounts. | | `adlRiskLevel` | integer | no | ADL risk queue position. `1` = lowest risk, `5` = highest (first in ADL queue). | | `healthFactor` | number | no | Position health ratio. `1.0` = at the liquidation threshold. Higher = healthier. | | `marginHealthStatus` | string | no | Human-readable health status. `healthy`, `warning`, `danger`, or `liquidatable`. | | `hedgeSide` | string | no | For hedge-mode DEXes, which side this position represents. `long` or `short`. | ## Example Response ```json { "success": true, "data": [ { "positionId": "gmx:0x1a2b3c4d5e6f7890abcdef1234567890abcdef12:18", "address": "0x1a2b3c4d5e6f7890abcdef1234567890abcdef12", "exchange": "gmx", "side": "long", "baseAsset": "BTC", "quoteAsset": "USD", "assetType": "crypto", "avgEntryPrice": 61760.20, "positionSizeUsd": 200.0, "positionSizeToken": 0.00319709, "collateralUsd": 20.0, "leverage": 10, "liquidationPrice": 58450.85, "unrealizedPnl": 59.73, "feeBorrowingUsd": 0.12, "feeFundingUsd": 0.08, "feeTradingUsd": 0.20, "feeNetworkUsd": 0.05, "chainId": 42161, "tradeUrl": "https://app.gmx.io/#/trade/BTC-USD", "createdAt": "2024-09-06T22:52:39Z", "updatedAt": "2024-09-09T17:43:57Z", "triggerOrders": [ { "action": "takeProfit", "triggerPrice": 70000.0, "amountPercent": 100.0, "createdAt": "2024-09-06T23:00:00Z" }, { "action": "stopLoss", "triggerPrice": 58000.0, "amountPercent": 100.0, "createdAt": "2024-09-06T23:00:00Z" } ] } ] } ``` ## Error Responses | Status | Error | When | | ------ | ------------------------------------ | ------------------------- | | `400` | `"Missing required parameter: addr"` | `addr` absent | | `401` | `"Invalid or missing API key"` | Bad or absent auth header | | `500` | `"Internal server error"` | Unexpected failure | ## Notes * Only return positions with status `open`. Closed or liquidated positions belong in [`history`](/for-partners/endpoints/user-history.md). * If none of the provided addresses have open positions, return `"data": []` — not a `404`. * `unrealizedPnl` should be calculated using the current mark price at the time of the response. * For positions that have been partially closed, return the current remaining size — not the original. * `feeFundingUsd` can be negative if the position is on the receiving side of funding.