Perpetuals API

Open positions held by one perpetual-futures account

The positions currently open for ONE perpetual-futures trading account, keyed by address with no chain. Derivatives exposure, never token balances.

GET/api/external/perps/perps-trader-positions/{address}

Get a free API key Try it in the API reference

What it returns

Every position ONE trading account currently holds open, on any market, on the leveraged derivatives venue this family covers — entry/mark price, size, leverage, unrealized PnL and cumulative funding, one row per position. address is not a wallet on any of this API's six chains. A malformed address returns 400 naming exactly that.

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-trader-positions/<address>"

Parameters
Parameter	Description
`address` path · string · required	The address of a trading account on the leveraged derivatives venue this endpoint covers — not a wallet on 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 held by one perpetual-futures account
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: 20 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 trading account
The account these positions belong to.
Whale alerts: perpetual positions over $1M just opened or closed
Every other position the alerting account still holds, from its trader address.
Derivatives leaders across venues: open interest, volume, funding, liquidations
The coins with the most futures open interest across derivatives venues, each with 24h volume, funding rate, liquidations and price change. Keyed by ticker.
One coin's futures markets across venues: funding, open interest, volume
One coin's funding-quoting futures markets (nearly all perpetuals), venue by venue: price, open interest, volume, funding rate and interval, max leverage, tick size, liquidations. Keyed by ticker.
Futures venues ranked by open interest or volume, with liquidations
Ranks major futures venues by open interest or 24h volume, every coin summed, with 24h liquidations where the venue has a feed. Also names the followed venues the ranking leaves out.
What is this derivatives exchange, and what does it list?
One futures/perpetuals exchange: open interest, 24h volume, founding year, country, and every market it lists by open interest, with price, funding and last trade.

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