# User Positions Returns all currently open trading positions for the provided wallet addresses. > **🔒 Affiliate-code gating:** Only include positions for addresses attributed to DexPal's affiliate code. If none of the provided addresses are DexPal-attributed, 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](https://github.com/dexpal-analytics/dexpal/blob/main/docs/dex-api-spec/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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.dexpal.io/for-partners/endpoints/user-positions.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.