Get Perp Positions
Retrieve all active perpetual positions for a specific wallet.
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.
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
evm:42161). If omitted, returns positions from all supported chains.gains, lighter. If omitted, returns positions from all supported DEXes.Response
Query Parameters
Wallet address
Comma-separated list of chain IDs (e.g., "evm:1,evm:8453,solana:solana"). If omitted, all chains.
Number of positions per page (1-500, default: 100)
1 <= x <= 500Offset for pagination (default: 0)
x >= 0Cursor for cursor-based pagination (takes precedence over offset)
Cursor direction (default: after)
before, after Sort field (default: lastActivity)
lastActivity, realizedPnl Sort order (default: desc)
asc, desc Include fees in PnL calculation (deduct total_fees_paid_usd from PnL)
Use swap recipient mode (query wallet_positions_recipients table instead of wallet_positions)
Include all tokens the wallet holds, not just tokens with trading history
Return only positions still held on-chain (filters out fully closed positions)
Drop positions worth less than this USD value (live RPC balance × live pool price)
x >= 0Response
Wallet perp positions response