Perpetuals API

Open positions in one perpetual-futures market

The positions currently open in ONE perpetual-futures market, keyed by trading symbol. Answers who is exposed and on which side, not what a token is worth.

GET/api/external/perps/perps-market-positions/{symbol}

Get a free API key Try it in the API reference

What it returns

Every open position on ONE leveraged derivatives market, across every trading account — entry/mark price, size, leverage, unrealized PnL and cumulative funding, one row per position. Chainless — symbol is a market ticker (e.g. "BTC"), not a token mint or contract address, and no chain applies. An unrecognised symbol returns 400 naming exactly that, rather than a blank 404. Use GET /perps/perps-markets to discover a real one.

Chains

This endpoint is not tied to a chain: it takes no chain in its request.

Request

Send your key in the x-dex-data-key header. Replace each <placeholder> with a real value.

curl -H "x-dex-data-key: $DEXDATA_API_KEY" \
  "https://api.dexdata.io/api/external/perps/perps-market-positions/<symbol>"

Parameters
Parameter	Description
`sort_by` query · string · optional	Which field to sort positions by. Defaults to when the position was opened.`position_valueopen_time`
`sort_type` query · string · optional	Sort direction. Defaults to descending.`ascdesc`
`offset` query · integer · optional	0-based row offset. An offset past the market's last open position answers an empty list.
`limit` query · integer · optional	How many rows to return. Defaults to 10; this endpoint caps it at 50.
`symbol` path · string · required	A coin ticker, e.g. "BTC" — the asset the market is on, not a token mint or contract address, and not scoped to any chain this API otherwise supports.

Response fields

A JSON response. Every field is always present; null means the value could not be established, never zero.

Response fields of Open positions in one perpetual-futures market
Field	Type	Description
`positions`	object[]
`positions[].trader`	string \| null	The trading-account address that holds this position. On `perps-market-positions` this identifies WHICH of many accounts; on `perps-trader-positions` it is always `null` — the account is already the request's own subject, never echoed back as if it were new data.
`positions[].traderFirstTradeAt`	number \| null	Unix seconds of the account's first recorded trade on this venue.
`positions[].symbol`	string \| null	The market ticker this position is on, e.g. "BTC".
`positions[].leverageType`	string \| null	Margin mode, e.g. "isolated" or "cross".
`positions[].leverageValue`	number \| null	Configured leverage multiplier on this position.
`positions[].maxLeverage`	number \| null	Maximum leverage allowed for this market at the time of the snapshot.
`positions[].entryPrice`	number \| null	Average entry price of the open position.
`positions[].markPrice`	number \| null	Current mark price used for PnL and liquidation calculations.
`positions[].liquidationPrice`	number \| null	Estimated liquidation price, when available.
`positions[].marginUsedUsd`	number \| null	Margin currently assigned to this position, USD.
`positions[].positionValueUsd`	number \| null	Current notional value of the open position, USD.
`positions[].roe`	number \| null	Return on equity for this position, when this endpoint provides it.
`positions[].size`	number \| null	Signed position size. Positive = net long exposure; negative = net short exposure.
`positions[].unrealizedPnlUsd`	number \| null	Current unrealized profit and loss, USD.
`positions[].cumulativeFundingSinceOpenUsd`	number \| null	Cumulative funding paid or received since the position was opened, USD.
`positions[].cumulativeFundingSinceChangeUsd`	number \| null	Cumulative funding paid or received since the last position size change, USD.
`positions[].openedAt`	number \| null	Unix seconds when the current position was opened.

Price per call

Every call: 40 credits

Charged only when the call succeeds. Prices as of 2026-10-30; the current ones are always in the API reference.

One perpetual-futures market, by symbol
The market those positions are in.
Liquidation levels for one perpetual-futures market
The positions these levels would liquidate.
Whale alerts: perpetual positions over $1M just opened or closed
The open positions in the alert's market, to see how large this one is against the rest.
Whale positions: perpetual positions over $1M open right now
Every open position on one market, not only the ones over $1,000,000.
Perpetual-futures trading accounts, ranked
Trading accounts on the perpetual-futures venue, ranked. An ACCOUNT is an address with no chain attached — a derivatives account, not an on-chain wallet with token balances.
One perpetual-futures trading account
The state of ONE perpetual-futures trading account, keyed by address with NO chain. Other wallet endpoints answer about on-chain holdings; this one about derivatives exposure.

Start building with DexData today

Sign in, create a key and make your first call in a minute. Free credits every month, and you only pay for calls that succeed.

Get a free API key