Reference

Positions

Live open positions per protocol, market-level summaries, and single-position detail.

Open positions stats

GET
Aggregate stats of open GMTrade positions: counts, notional, average leverage.
Headers
x-api-keystringrequired
API key sent in the request header; never accepted as a query parameter.
Query parameters
marketstring
Filter to a market. Results may aggregate protocol-native variants that share the market symbol.
Response
200
{ data: PositionsSummary }
PositionsSummary
marketMarket symbol; null for a protocol-wide aggregate.
snapshot_tsTimestamp of the snapshot.
total_positionsCount of open positions.
long_positionsCount of open long positions.
short_positionsCount of open short positions.
long_notional_usdTotal long notional (USD).
short_notional_usdTotal short notional (USD).
long_upnl_usdTotal unrealized PnL of open long positions (USD).
short_upnl_usdTotal unrealized PnL of open short positions (USD).
avg_leverageAverage leverage across open positions.
Request
cURL
curl --request GET \
  --url https://api.perpdb.xyz/v1/gmtrade/open-positions/stats \
  --header 'x-api-key: ak_...'
Example
{
  "data": {
    "market": null,
    "snapshot_ts": "2026-10-25T01:27:06.001Z",
    "total_positions": 8866,
    "long_positions": 4452,
    "short_positions": 4414,
    "long_notional_usd": 104270529.50337303,
    "short_notional_usd": 108188178.21750464,
    "long_upnl_usd": 389461.13731397636,
    "short_upnl_usd": -15226.777590231193,
    "avg_leverage": 106.11289750340131
  }
}

Open positions search

GET
Search open GMTrade positions with live PnL and liquidation price. Up to 500 rows per page.
Headers
x-api-keystringrequired
API key sent in the request header; never accepted as a query parameter.
Query parameters
market_variantstring
Filter to a protocol-native market variant.
marketstring
Filter to a market. Results may aggregate protocol-native variants that share the market symbol.
addressstring
Filter to a wallet address.
sidelong | short
Filter by position side.
min_size_usdnumber
Exclude positions smaller than this notional value.
sort_bysize | pnl | collateral | leverage | opened_at | liq_proximity
When sorting by liquidation proximity, order by the distance between mark and liquidation prices; positions without a liquidation price are excluded.
orderasc | desc
Sort direction.
offsetinteger
Number of items to skip for pagination.
Response
200
{ data: Position[], pagination }
Position
protocolProtocol identifier.gmtrade | jupiter | phoenix
position_idIdentifier of the position lifecycle; null when unavailable.
market_variantProtocol-native market variant identifier; null when unavailable.
marketMarket symbol (e.g. SOL-PERP).
addressOwner wallet address (base58).
sidePosition side.long | short
current_size_usdCurrent position notional (USD) from the latest snapshot; null when the lifecycle is not open.
max_size_usdMaximum position notional (USD) reached during the lifecycle; null when unavailable.
current_collateral_usdCurrent posted collateral (USD) from the latest snapshot, before applicable unsettled charges and credits; null when the lifecycle is not open.
max_collateral_usdPeak collateral (USD) held during the lifecycle. For Phoenix cross-margin positions this is the subaccount's shared collateral; see the Phoenix position notes for how historical values are derived. Absent when no figure could be established.
unsettled_borrowing_usdBorrowing charges accrued since the last settlement and not yet deducted from posted collateral; null when unavailable.
unsettled_funding_usdFunding owed since the last settlement and not yet deducted from posted collateral; null when unavailable.
claimable_funding_usdFunding receivable accrued since the last settlement; null when unavailable.
entry_priceSize-weighted average entry price.
leverageCurrent position notional divided by current collateral at the latest update.
opened_atTimestamp when the position lifecycle opened.
mark_priceDeprecated (2026-10-25): the mark the position is valued at, quoted as a number; leaves the response when the operator turns the mark-number fields off. Use last_price for a price and liquidation_distance_pct for proximity; unrealized_pnl_usd and liquidation_price are still computed from the mark.
unrealized_pnl_usdUnrealized PnL from the latest snapshot; null when the lifecycle is not open.
liquidation_priceEstimated liquidation price; null when unavailable.
liquidation_distance_pct|liquidation_price − mark| / mark × 100: the percentage move that would liquidate the position, computed server-side from the same mark that values unrealized_pnl_usd. Null when either input is missing. sort_by=liq_proximity orders by it.
updated_atTimestamp of the latest snapshot; null when the lifecycle is not open.
Pagination
limitLimit applied to this page.
offsetOffset applied to this page.
totalTotal rows matching the query, ignoring limit/offset.
Request
cURL
curl --request GET \
  --url https://api.perpdb.xyz/v1/gmtrade/open-positions/search?side=long&sort_by=size \
  --header 'x-api-key: ak_...'
Example
{
  "data": [
    {
      "protocol": "gmtrade",
      "position_id": 39927951,
      "market": "WTI-PERP",
      "market_variant": "WTI/USD[USDC]",
      "address": "dZSvHaDGvNopP2pSmDeJUQ938hovzVVyyT6jozYgikGd",
      "side": "short",
      "current_size_usd": 2206248.1869899584,
      "max_size_usd": 2339511.0619899584,
      "current_collateral_usd": 524461.1956031679,
      "max_collateral_usd": 524855.4301319689,
      "unsettled_borrowing_usd": 0,
      "unsettled_funding_usd": 0,
      "claimable_funding_usd": 0,
      "entry_price": 91.81995603309133,
      "leverage": 4.206694805041992,
      "opened_at": "2026-09-29T07:37:49.000Z",
      "mark_price": 103.535,
      "unrealized_pnl_usd": -281608.9973307769,
      "liquidation_price": 113.169594128732,
      "liquidation_distance_pct": 9.305639763106202,
      "updated_at": "2026-10-25T01:25:14.156Z",
      "last_price": 103.65449,
      "last_price_ts": "2026-10-24T22:46:26.000Z",
      "last_price_stale": true,
      "mark_source": "gmtrade_tickers",
      "mark_ts": "2026-10-25T01:25:14.156Z"
    },
    {
      "protocol": "gmtrade",
      "position_id": 43470503,
      "market": "USDCAD-PERP",
      "market_variant": "USDCAD/USD[USDC]",
      "address": "HPWF9Qg5rE7YhGLjZZL3KjrDDuX3LYRH4Q44apFRrz1T",
      "side": "short",
      "current_size_usd": 699730.5770031706,
      "max_size_usd": 719766.7613079029,
      "current_collateral_usd": 4362.490624907314,
      "max_collateral_usd": 4565.055963751331,
      "unsettled_borrowing_usd": 0.491709206897109,
      "unsettled_funding_usd": 18.413146725897477,
      "claimable_funding_usd": 0,
      "entry_price": 1.4012486238645174,
      "leverage": 160.39703856510573,
      "opened_at": "2026-10-21T14:23:35.000Z",
      "mark_price": 1.4004125,
      "unrealized_pnl_usd": 417.52864138507584,
      "liquidation_price": 1.40837749267,
      "liquidation_distance_pct": 0.5687604666482081,
      "updated_at": "2026-10-25T01:25:14.156Z",
      "last_price": 1.40066500491,
      "last_price_ts": "2026-10-23T20:59:07.000Z",
      "last_price_stale": false,
      "mark_source": "gmtrade_tickers",
      "mark_ts": "2026-10-25T01:25:14.156Z"
    }
  ],
  "pagination": {
    "limit": 500,
    "offset": 0,
    "total": 8866
  },
  "meta": {
    "oldest_updated": "2026-10-25T01:25:14.156Z",
    "last_full_refresh": "2026-10-25T01:25:14.156Z"
  }
}

Position stats

GET
One GMTrade position lifecycle's stats: aggregates plus live fields (mark/liq/uPnL) for an open lifecycle. The fill-event timeline is a separate paginated resource — see Position lifecycle.
Headers
x-api-keystringrequired
API key sent in the request header; never accepted as a query parameter.
Response
200
{ data: Position }
Position
protocolProtocol identifier.gmtrade | jupiter | phoenix
position_idIdentifier of the position lifecycle; null when unavailable.
market_variantProtocol-native market variant identifier; null when unavailable.
marketMarket symbol (e.g. SOL-PERP).
addressOwner wallet address (base58).
sidePosition side.long | short
max_size_usdMaximum position notional (USD) reached during the lifecycle; null when unavailable.
current_size_usdCurrent position notional (USD) from the latest snapshot; null when the lifecycle is not open.
max_collateral_usdPeak collateral (USD) held during the lifecycle. For Phoenix cross-margin positions this is the subaccount's shared collateral; see the Phoenix position notes for how historical values are derived. Absent when no figure could be established.
current_collateral_usdCurrent posted collateral (USD) from the latest snapshot, before applicable unsettled charges and credits; null when the lifecycle is not open.
unsettled_borrowing_usdBorrowing charges accrued since the last settlement and not yet deducted from posted collateral; null when unavailable.
unsettled_funding_usdFunding owed since the last settlement and not yet deducted from posted collateral; null when unavailable.
claimable_funding_usdFunding receivable accrued since the last settlement; null when unavailable.
entry_priceSize-weighted average entry price.
opened_atTimestamp when the position lifecycle opened.
statusPosition lifecycle status.open | closed | liquidated
closed_atTimestamp when the position lifecycle closed; null while open.
exit_priceSize-weighted average exit price.
max_leveragePeak leverage reached during the lifecycle, notional divided by collateral. Phoenix values are capped at 100×; absent when no figure could be established.
realized_pnl_usdRealized PnL before fees.
fees_usdTrading fees paid during the lifecycle.
liquidation_fees_usdLiquidation fees paid during the lifecycle.
funding_fees_usdFunding paid during the lifecycle.
borrowing_fees_usdBorrowing charges paid during the lifecycle.
funding_earned_usdFunding received during the lifecycle.
net_pnl_usdRealized PnL net of fees.
fill_countNumber of fills in the lifecycle.
open_txTransaction signature that opened the position.
close_txTransaction signature that closed the position; null while open.
mark_priceDeprecated (2026-10-25): the mark the position is valued at, quoted as a number; leaves the response when the operator turns the mark-number fields off. Use last_price for a price and liquidation_distance_pct for proximity; unrealized_pnl_usd and liquidation_price are still computed from the mark.
unrealized_pnl_usdUnrealized PnL from the latest snapshot; null when the lifecycle is not open.
liquidation_priceEstimated liquidation price; null when unavailable.
liquidation_distance_pct|liquidation_price − mark| / mark × 100: the percentage move that would liquidate the position, computed server-side from the same mark that values unrealized_pnl_usd. Null when either input is missing. sort_by=liq_proximity orders by it.
updated_atTimestamp of the latest snapshot; null when the lifecycle is not open.
Request
cURL
curl --request GET \
  --url https://api.perpdb.xyz/v1/gmtrade/positions/So1aNa...WALLET/12345 \
  --header 'x-api-key: ak_...'
Example
{
  "data": {
    "protocol": "gmtrade",
    "position_id": 39927951,
    "market": "WTI-PERP",
    "market_variant": "WTI/USD[USDC]",
    "address": "dZSvHaDGvNopP2pSmDeJUQ938hovzVVyyT6jozYgikGd",
    "side": "short",
    "max_size_usd": 2339511.0619899584,
    "current_size_usd": 2206248.1869899584,
    "max_collateral_usd": 524855.4301319689,
    "current_collateral_usd": 524461.1956031679,
    "unsettled_borrowing_usd": 0,
    "unsettled_funding_usd": 0,
    "claimable_funding_usd": 0,
    "entry_price": 91.85515728056934,
    "opened_at": "2026-09-29T07:37:49.000Z",
    "status": "open",
    "closed_at": null,
    "exit_price": null,
    "max_leverage": 25.128048787339267,
    "realized_pnl_usd": 3909.0945060583526,
    "fees_usd": 596.0478750064531,
    "liquidation_fees_usd": 0,
    "funding_fees_usd": 14112.545943039691,
    "borrowing_fees_usd": 115921.26675404988,
    "funding_earned_usd": 0,
    "net_pnl_usd": -126720.76606603767,
    "fill_count": 66,
    "open_tx": "YgBeygjEoUxY4DiGErLHjXxLJkac2H7j9wCHiu2Mb9VUvtwkoGvu8tj1cUerrKj5Y2hjaWisTw2DQe5c3Z26qPV",
    "close_tx": null,
    "mark_price": 103.535,
    "unrealized_pnl_usd": -281608.9973307769,
    "last_price": 103.65449,
    "last_price_ts": "2026-10-24T22:46:26.000Z",
    "last_price_stale": true,
    "mark_source": "gmtrade_tickers",
    "mark_ts": "2026-10-25T01:25:14.156Z",
    "liquidation_price": 113.169594128732,
    "liquidation_distance_pct": 9.305639763106202,
    "updated_at": "2026-10-25T01:25:14.156Z"
  }
}

Position lifecycle

GET
The fill-event timeline for one GMTrade position lifecycle, paginated and sortable. Split from the position stats so a long-running position with thousands of fills stays cheap to poll. Chronological by default (order=asc). Up to 500 rows per page.
Headers
x-api-keystringrequired
API key sent in the request header; never accepted as a query parameter.
Query parameters
sort_bytime | size
Sort by fill timestamp or absolute notional change; defaults to timestamp.
orderasc | desc
Sort direction; defaults to ascending chronological order.
typeopen | increase | decrease | close | liquidation
Filter to a position lifecycle event type.
offsetinteger
Number of items to skip for pagination.
Response
200
{ data: PositionEvent[], pagination }
PositionEvent
timeTimestamp when the fill executed.
typeEffect of the fill on the position lifecycle; open is the first fill, while close and liquidation are terminal.open | increase | decrease | close | liquidation
size_delta_usdSigned notional change: positive for an increase and negative for a decrease.
position_size_usdPosition notional after the fill.
collateral_delta_usdSigned collateral change.
priceExecution price.
entry_priceRunning size-weighted average entry price after the fill.
pnl_delta_usdRealized PnL on the fill, if any.
fee_usdTrading fee charged on the fill; excludes borrowing, funding, and liquidation charges.
borrowing_fee_usdBorrowing charge settled on the fill; null when none was settled.
funding_fee_usdFunding charge settled on the fill; null when none was settled.
liquidation_fee_usdLiquidation charge settled on the fill; null when none was settled and not included in the trading fee.
fee_total_usdTotal of all applicable fee components on the fill.
txTransaction signature.
Pagination
limitLimit applied to this page.
offsetOffset applied to this page.
totalTotal rows matching the query, ignoring limit/offset.
Request
cURL
curl --request GET \
  --url https://api.perpdb.xyz/v1/gmtrade/positions/So1aNa...WALLET/12345/lifecycle?order=asc \
  --header 'x-api-key: ak_...'
Example
{
  "data": [
    {
      "time": "2026-10-23T02:20:27.000Z",
      "type": "open",
      "size_delta_usd": 11940,
      "position_size_usd": 11940,
      "collateral_delta_usd": 179.531472324154,
      "price": 4023.530007860845,
      "entry_price": 4023.530007860845,
      "pnl_delta_usd": 0,
      "fee_usd": 2.041739335798,
      "borrowing_fee_usd": 0,
      "funding_fee_usd": 0,
      "liquidation_fee_usd": 0,
      "fee_total_usd": 2.041739335798,
      "tx": "uYfiQyNLf63btpWKyrKFJk3Bb8oBkHg281uRoXH1ia89JQt11SPLNnBsd4s1jAX3vxUXZHZwPUraE1YAEFL1kDVE"
    },
    {
      "time": "2026-10-23T14:28:07.000Z",
      "type": "close",
      "size_delta_usd": 11940,
      "position_size_usd": 0,
      "collateral_delta_usd": -179.528060605247,
      "price": 3991.110034765152,
      "entry_price": 4023.530007860845,
      "pnl_delta_usd": -96.20748424945829,
      "fee_usd": 2.45008743342,
      "borrowing_fee_usd": 6.8104328277979995,
      "funding_fee_usd": 0,
      "liquidation_fee_usd": 0,
      "fee_total_usd": 9.260520261218,
      "tx": "C8rLe22fmLgXfmvXf3mvywHMH1aX8d2jEK9bwujt1hVj69Qtwa1TLnKMCeHwHTAKp5pwUpEia67JxS8NUz6o5Xy7"
    }
  ],
  "pagination": {
    "limit": 500,
    "offset": 0,
    "total": 2
  }
}