Reference

Accounts

Aggregate stats, ranked account search, per-account stats, and closed-position history for each protocol. Addresses are base58 wallet keys.

Accounts stats

GET
Aggregate totals across all GMTrade accounts.
Headers
x-api-keystringrequired
API key sent in the request header; never accepted as a query parameter.
Response
200
{ data: AccountsSummary }
AccountsSummary
total_accountsTotal accounts tracked.
accounts_with_open_positionsAccounts with at least one open position.
total_positions_everLifetime position count across all accounts.
total_active_positionsCurrently open position count across all accounts.
total_volume_usdLifetime traded notional across all accounts.
avg_net_pnl_usdAverage net PnL per account.
total_profits_usdNet PnL summed across profitable accounts.
total_losses_usdNet PnL summed across losing accounts.
avg_win_rateAverage account win rate, from 0 to 1.
Request
cURL
curl --request GET \
  --url https://api.perpdb.xyz/v1/gmtrade/accounts/stats \
  --header 'x-api-key: ak_...'
Example
{
  "data": {
    "total_accounts": 32189,
    "accounts_with_open_positions": 4225,
    "total_positions_ever": 2485703,
    "total_active_positions": 9017,
    "total_volume_usd": 189711264070.86728,
    "avg_net_pnl_usd": -281.97818238479897,
    "total_profits_usd": 23561386.75831598,
    "total_losses_usd": -32637982.47110027,
    "avg_win_rate": 0.32407235016174396
  }
}

Account stats

GET
Lifetime stats for a single GMTrade account (base58 wallet): totals, volume, and PnL. Open positions (with live fields) are served by GET /v1/gmtrade/open-positions/search?address={address}; historical positions by GET /v1/gmtrade/accounts/{address}/history.
Headers
x-api-keystringrequired
API key sent in the request header; never accepted as a query parameter.
Response
200
{ data: Account }
Account
addressWallet address (base58).
tradesClosed positions counted as trades.
winsTrades closed with positive net PnL.
lossesTrades closed with negative net PnL.
win_rateRatio of winning trades to closed trades, from 0 to 1.
volume_usdLifetime traded notional (USD).
net_pnl_usdLifetime realized PnL net of fees.
positionsLifetime positions opened.
open_positionsCurrently open positions.
first_trade_atTimestamp of the first fill.
last_trade_atTimestamp of the most recent fill.
realized_pnl_usdLifetime realized PnL before fees.
fees_usdLifetime trading fees paid.
funding_fees_usdLifetime funding paid.
funding_earned_usdLifetime funding received.
borrowing_fees_usdLifetime borrowing charges paid.
liquidation_fees_usdLifetime liquidation fees paid.
avg_leverageAverage leverage across the account's positions.
max_leverageMaximum leverage used.
avg_position_size_usdAverage position notional (USD).
max_position_size_usdMaximum position notional (USD).
avg_position_duration_hoursAverage position duration in hours.
open_notional_usdTotal notional of currently open positions.
markets_tradedDistinct markets traded by the account.
market_variants_tradedDistinct protocol-native market variants traded by the account.
Request
cURL
curl --request GET \
  --url https://api.perpdb.xyz/v1/gmtrade/accounts/So1aNa...WALLET \
  --header 'x-api-key: ak_...'
Example
{
  "data": {
    "address": "K2vteveaShd5P9QcNj4ySbfsDsAMLcAQkBiPXYzn7Mdk",
    "trades": 1473,
    "wins": 516,
    "losses": 955,
    "win_rate": 0.35078178110129166,
    "volume_usd": 969820180.3058103,
    "net_pnl_usd": 743145.1428177386,
    "positions": 1473,
    "open_positions": 2,
    "first_trade_at": "2026-06-03T00:57:47.000Z",
    "last_trade_at": "2026-10-23T14:33:29.000Z",
    "realized_pnl_usd": 829751.4956449554,
    "fees_usd": 42687.037806433196,
    "funding_fees_usd": 13148.328325399068,
    "funding_earned_usd": 21664.805125360534,
    "borrowing_fees_usd": 33658.98426585386,
    "liquidation_fees_usd": 18776.8075548905,
    "avg_leverage": 57.30006820149137,
    "max_leverage": 418.1148053406746,
    "avg_position_size_usd": 285240.7582052414,
    "max_position_size_usd": 15705789.700218726,
    "avg_position_duration_hours": 4.91578011701403,
    "open_notional_usd": 37300,
    "markets_traded": [
      "AAPL-PERP",
      "AAVE-PERP"
    ],
    "market_variants_traded": [
      "AAPL/USD[USDC]",
      "AAVE/USD[WSOL-USDC]"
    ]
  }
}

Account history

GET
Historical positions for a GMTrade account: closed and liquidated lifecycles, newest first. Open positions are served by GET /v1/gmtrade/open-positions/search?address={address}. Up to 500 rows per page.
History depth
Starter · 30dPro · 90dPremium · Full
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.
market_variantstring
Filter to a protocol-native market variant.
sort_byopened_at | closed_at | size | pnl | leverage
Field to sort by.
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
max_size_usdMaximum position notional (USD) reached during the lifecycle; null when unavailable.
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.
entry_priceSize-weighted average entry price.
opened_atTimestamp when the position lifecycle opened.
statusPosition lifecycle status.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.
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/accounts/So1aNa...WALLET/history \
  --header 'x-api-key: ak_...'
Example
{
  "data": [
    {
      "protocol": "gmtrade",
      "position_id": 43701174,
      "market": "XAU-PERP",
      "market_variant": "XAU/USD[USDC]",
      "address": "K2vteveaShd5P9QcNj4ySbfsDsAMLcAQkBiPXYzn7Mdk",
      "side": "long",
      "max_size_usd": 11940,
      "max_collateral_usd": 179.531472324154,
      "entry_price": 4023.530007860845,
      "opened_at": "2026-10-23T02:20:27.000Z",
      "status": "closed",
      "closed_at": "2026-10-23T14:28:07.000Z",
      "exit_price": 3991.110034765152,
      "max_leverage": 66.50644505628333,
      "realized_pnl_usd": -96.20748424945829,
      "fees_usd": 4.491826769217999,
      "liquidation_fees_usd": 0,
      "funding_fees_usd": 0,
      "borrowing_fees_usd": 6.8104328277979995,
      "funding_earned_usd": 0.031399687393999995,
      "net_pnl_usd": -107.47834415908028,
      "fill_count": 2,
      "open_tx": "uYfiQyNLf63btpWKyrKFJk3Bb8oBkHg281uRoXH1ia89JQt11SPLNnBsd4s1jAX3vxUXZHZwPUraE1YAEFL1kDVE",
      "close_tx": "C8rLe22fmLgXfmvXf3mvywHMH1aX8d2jEK9bwujt1hVj69Qtwa1TLnKMCeHwHTAKp5pwUpEia67JxS8NUz6o5Xy7"
    },
    {
      "protocol": "gmtrade",
      "position_id": 43695649,
      "market": "XAG-PERP",
      "market_variant": "XAG/USD[USDC]",
      "address": "K2vteveaShd5P9QcNj4ySbfsDsAMLcAQkBiPXYzn7Mdk",
      "side": "short",
      "max_size_usd": 6161.042079999999,
      "max_collateral_usd": 77.000010798606,
      "entry_price": 54.67381537526936,
      "opened_at": "2026-10-22T20:18:38.000Z",
      "status": "closed",
      "closed_at": "2026-10-23T01:59:40.000Z",
      "exit_price": 53.715259551052,
      "max_leverage": 82.44330099130084,
      "realized_pnl_usd": 108.01149457103661,
      "fees_usd": 2.136454125369,
      "liquidation_fees_usd": 0,
      "funding_fees_usd": 0,
      "borrowing_fees_usd": 2.254374784912,
      "funding_earned_usd": 0.17505439211399998,
      "net_pnl_usd": 103.79572005286961,
      "fill_count": 3,
      "open_tx": "KmoZv3SBZH3anQXXRL6d3A8UVYwEA3rCKkNWoe4iJ7bjUYD8kcocqjXzCPuXeua8WLvWG8EACwREMHm3atLq3DBK",
      "close_tx": "LeH2QPcMt1otswcDxgPrHa7mTyjDm7na5hbtnhsrRa6Ziu7HXqLJSQj8z2FNdFVoCjdRjgGdbSbmYBhzSx6cc5us"
    }
  ],
  "pagination": {
    "limit": 500,
    "offset": 0,
    "total": 1471
  }
}