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-08-15T23:38:41.001Z",
    "total_positions": 2389,
    "long_positions": 1119,
    "short_positions": 1270,
    "long_notional_usd": 27389036.088860426,
    "short_notional_usd": 30458789.803314805,
    "long_upnl_usd": 28815.459130371582,
    "short_upnl_usd": 153637.86691327224,
    "avg_leverage": 52.03074880487638
  }
}

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
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_usdMaximum collateral (USD) held during the lifecycle; null when unavailable.
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_priceCurrent oracle price; null when the lifecycle is not open.
unrealized_pnl_usdUnrealized PnL from the latest snapshot; null when the lifecycle is not open.
liquidation_priceEstimated liquidation price; null when unavailable.
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": 33297505,
      "market": "USDCAD-PERP",
      "market_variant": "USDCAD/USD[USDC]",
      "address": "hcLXVcWa4GvUjeLNN3pU1dPXt37ppP6YLBH9DFRZB5ZA",
      "side": "long",
      "current_size_usd": 1754888.05,
      "max_size_usd": 1754888.05,
      "current_collateral_usd": 25011.973420159287,
      "max_collateral_usd": 25008.101944480946,
      "unsettled_borrowing_usd": 0.06990581273592847,
      "unsettled_funding_usd": 0,
      "claimable_funding_usd": 3.4006827208077,
      "entry_price": 1.3872595178184524,
      "leverage": 70.16191887464528,
      "opened_at": "2026-08-14T16:18:01.000Z",
      "mark_price": 1.3874,
      "unrealized_pnl_usd": 177.7104416796584,
      "liquidation_price": 1.3689578108,
      "updated_at": "2026-08-15T23:35:50.126Z"
    },
    {
      "protocol": "gmtrade",
      "position_id": 33297553,
      "market": "USDCAD-PERP",
      "market_variant": "USDCAD/USD[USDC]",
      "address": "hcLXVcWa4GvUjeLNN3pU1dPXt37ppP6YLBH9DFRZB5ZA",
      "side": "short",
      "current_size_usd": 1754869.1124999998,
      "max_size_usd": 1754869.1124999998,
      "current_collateral_usd": 24965.16084436699,
      "max_collateral_usd": 24961.47138751259,
      "unsettled_borrowing_usd": 0.18474183684671677,
      "unsettled_funding_usd": 1.23539910610286,
      "claimable_funding_usd": 0,
      "entry_price": 1.3872764783665588,
      "leverage": 70.29272206335331,
      "opened_at": "2026-08-14T16:18:29.000Z",
      "mark_price": 1.3874,
      "unrealized_pnl_usd": -156.25169361102655,
      "liquidation_price": 1.40556829389,
      "updated_at": "2026-08-15T23:35:50.126Z"
    }
  ],
  "pagination": {
    "limit": 500,
    "offset": 0,
    "total": 2389
  },
  "meta": {
    "oldest_updated": "2026-08-15T23:35:50.126Z",
    "last_full_refresh": "2026-08-15T23:35:50.126Z"
  }
}

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
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_usdMaximum collateral (USD) held 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.
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_leverageMaximum leverage reached during the lifecycle.
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_priceCurrent oracle price; null when the lifecycle is not open.
unrealized_pnl_usdUnrealized PnL from the latest snapshot; null when the lifecycle is not open.
liquidation_priceEstimated liquidation price; null when unavailable.
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": 33297505,
    "market": "USDCAD-PERP",
    "market_variant": "USDCAD/USD[USDC]",
    "address": "hcLXVcWa4GvUjeLNN3pU1dPXt37ppP6YLBH9DFRZB5ZA",
    "side": "long",
    "max_size_usd": 1754888.05,
    "current_size_usd": 1754888.05,
    "max_collateral_usd": 25008.101944480946,
    "current_collateral_usd": 25011.973420159287,
    "unsettled_borrowing_usd": 0.06990581273592847,
    "unsettled_funding_usd": 0,
    "claimable_funding_usd": 3.4006827208077,
    "entry_price": 1.3872595205549707,
    "opened_at": "2026-08-14T16:18:01.000Z",
    "status": "open",
    "closed_at": null,
    "exit_price": null,
    "max_leverage": 70.17278056111282,
    "realized_pnl_usd": 0,
    "fees_usd": 60.017168960063,
    "liquidation_fees_usd": 0,
    "funding_fees_usd": 0,
    "borrowing_fees_usd": 0,
    "funding_earned_usd": 19.840173951422003,
    "net_pnl_usd": -40.176995008641,
    "fill_count": 3,
    "open_tx": "D54ea9GoCWhQde6RB6Aeq3vLmWxrJeLQjKqP2tyBiF4UE5YAK3kiRbaCWvr3pv8AmF5rh1y9wSjMBDcxGZhM9xD5",
    "close_tx": null,
    "mark_price": 1.3874,
    "unrealized_pnl_usd": 177.7104416796584,
    "liquidation_price": 1.3689578108,
    "updated_at": "2026-08-15T23:35:50.126Z"
  }
}

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-08-15T02:25:56.000Z",
      "type": "open",
      "size_delta_usd": 14149.4448143645,
      "position_size_usd": 14149.4448143645,
      "collateral_delta_usd": 617.86169796834,
      "price": 9.60121520646,
      "entry_price": 9.60121520646,
      "pnl_delta_usd": 0,
      "fee_usd": 1.20977709867,
      "borrowing_fee_usd": 0,
      "funding_fee_usd": 0,
      "liquidation_fee_usd": 0,
      "fee_total_usd": 1.20977709867,
      "tx": "YALYx1eLLrmNiT7S1bCi6WX3qGvppWUF3yAYk8aqy47fTM3869tCjiHoZXLrqYfssetebX3j4A1cT4u3ve2YfLL8"
    },
    {
      "time": "2026-08-15T02:26:33.000Z",
      "type": "increase",
      "size_delta_usd": 10559.999999999998,
      "position_size_usd": 24709.4448143645,
      "collateral_delta_usd": -0.9088861894559841,
      "price": 9.59369173315,
      "entry_price": 9.597999922638348,
      "pnl_delta_usd": 0,
      "fee_usd": 0.9028792588799999,
      "borrowing_fee_usd": 0,
      "funding_fee_usd": 0.006006930575999999,
      "liquidation_fee_usd": 0,
      "fee_total_usd": 0.9088861894559999,
      "tx": "mSThyNdiLQceno2Hr9sghueqH6n5rxQuvHSrucvqfe17NPYVn5dp34N2ZysborkKVopzaf7Wb8SUMRg2armC3FxG"
    }
  ],
  "pagination": {
    "limit": 500,
    "offset": 0,
    "total": 4
  }
}