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.

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 <api_key>

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 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.
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]	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]	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

{
  "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.

• 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.