Skip to main content
GET
Get wallet perp positions
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

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

Response

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)

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