Skip to main content
GET
/
2
/
wallet
/
positions
/
perp
/
open
Get wallet perp positions
curl --request GET \
  --url https://demo-api.mobula.io/api/2/wallet/positions/perp/open
{
  "data": [
    {
      "id": "<string>",
      "entryPriceQuote": 123,
      "currentLeverage": 123,
      "amountUSD": 123,
      "amountRaw": 123,
      "liquidationPriceQuote": 123,
      "currentPriceQuote": 123,
      "realizedPnlUSD": 123,
      "unrealizedPnlUSD": 123,
      "realizedPnlPercent": 123,
      "unrealizedPnlPercent": 123,
      "tp": [
        {
          "size": 123,
          "price": 123,
          "id": 123
        }
      ],
      "sl": [
        {
          "size": 123,
          "price": 123,
          "id": 123
        }
      ],
      "marketId": "<string>",
      "feesOpeningUSD": 123,
      "feesClosingUSD": 123,
      "feesFundingUSD": 123,
      "openDate": "<string>",
      "lastUpdate": "<string>",
      "address": "<string>",
      "chainId": "<string>",
      "collateralAsset": "<string>"
    }
  ]
}

Documentation Index

Fetch the complete documentation index at: https://docs.mobula.io/llms.txt

Use this file to discover all available pages before exploring further.

This endpoint returns filled positions only. For pending limit / stop / TP / SL orders that haven’t filled yet, use GET /2/wallet/positions/perp/unfilled. The two endpoints share the same response shape; unfilled rows add a type: "STOP" | "LIMIT" discriminator.For live streaming, see the Perp Positions WSS channels (perp-positions-open / perp-positions-unfilled) — REST is useful as a seed before the first WSS frame arrives.Composite id format. Position ids are composite strings of the form pos-<dex>-<base>-<quote>-<collateral>-<wallet>-<tradeIndex> (e.g. pos-gains-inj-usd-usdc-0xaa00...8741-0). When closing a Gains position via /2/perp/payloads/close-position, pass only the trailing trade-index segment as a string (e.g. "0") in positionId, not the composite id.

Query Parameters

wallet
string
required
The wallet address to query positions for.
chainId
string
Filter positions by chain ID (e.g. evm:42161). If omitted, returns positions from all supported chains.
dex
string
Filter positions by DEX. Supported values: gains, lighter. If omitted, returns positions from all supported DEXes.

Response

data
array
Array of open perpetual positions.

Query Parameters

wallet
string
required

Wallet address

chainIds
string

Comma-separated list of chain IDs (e.g., "evm:1,evm:8453,solana:solana"). If omitted, all chains.

limit
number

Number of positions per page (1-500, default: 100)

Required range: 1 <= x <= 500
offset
number | null

Offset for pagination (default: 0)

Required range: x >= 0
cursor
string

Cursor for cursor-based pagination (takes precedence over offset)

cursorDirection
enum<string>

Cursor direction (default: after)

Available options:
before,
after
sortBy
enum<string>

Sort field (default: lastActivity)

Available options:
lastActivity,
realizedPnl
order
enum<string>

Sort order (default: desc)

Available options:
asc,
desc
includeFees
required

Include fees in PnL calculation (deduct total_fees_paid_usd from PnL)

useSwapRecipient
required

Use swap recipient mode (query wallet_positions_recipients table instead of wallet_positions)

includeAllBalances
required

Include all tokens the wallet holds, not just tokens with trading history

onlyOpen
required

Return only positions still held on-chain (filters out fully closed positions)

minPositionValueUSD
number | null

Drop positions worth less than this USD value (live RPC balance × live pool price)

Required range: x >= 0

Response

200 - application/json

Wallet perp positions response

data
object[]
required