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": 22695,
    "accounts_with_open_positions": 1808,
    "total_positions_ever": 1876092,
    "total_active_positions": 2397,
    "total_volume_usd": 132582980502.6772,
    "avg_net_pnl_usd": -200.59622501414051,
    "total_profits_usd": 17788737.116433725,
    "total_losses_usd": -22341268.44312942,
    "avg_win_rate": 0.3360850681395436
  }
}

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": "dukiyb5imvcdWyYH2BTQHuK1KjTd2awgAz5ie79tiToT",
    "trades": 1397,
    "wins": 492,
    "losses": 904,
    "win_rate": 0.3524355300859599,
    "volume_usd": 965539480.1353762,
    "net_pnl_usd": 743407.2486038281,
    "positions": 1397,
    "open_positions": 1,
    "first_trade_at": "2026-06-03T00:57:47.000Z",
    "last_trade_at": "2026-08-15T02:41:55.000Z",
    "realized_pnl_usd": 828993.1609978933,
    "fees_usd": 42229.48955671276,
    "funding_fees_usd": 12993.562141599024,
    "funding_earned_usd": 21542.656522010853,
    "borrowing_fees_usd": 33174.09141047863,
    "liquidation_fees_usd": 18731.425807285195,
    "avg_leverage": 54.7707494960047,
    "max_leverage": 418.1148053406746,
    "avg_position_size_usd": 299223.47300586617,
    "max_position_size_usd": 15705789.700218726,
    "avg_position_duration_hours": 4.183884845231846,
    "open_notional_usd": 12000,
    "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
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_usdMaximum collateral (USD) held during the lifecycle; null when unavailable.
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_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.
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": 33340224,
      "market": "LINK-PERP",
      "market_variant": "LINK/USD[WSOL-USDC]",
      "address": "dukiyb5imvcdWyYH2BTQHuK1KjTd2awgAz5ie79tiToT",
      "side": "short",
      "max_size_usd": 27033.91893713062,
      "max_collateral_usd": 617.8691137177079,
      "entry_price": 9.598656696071107,
      "opened_at": "2026-08-15T02:25:56.000Z",
      "status": "closed",
      "closed_at": "2026-08-15T02:41:55.000Z",
      "exit_price": 9.679754686135,
      "max_leverage": 43.83032514967824,
      "realized_pnl_usd": -225.2722650523535,
      "fees_usd": 5.085078390768,
      "liquidation_fees_usd": 0,
      "funding_fees_usd": 0.281529326373,
      "borrowing_fees_usd": 0,
      "funding_earned_usd": 0,
      "net_pnl_usd": -230.6388727694945,
      "fill_count": 4,
      "open_tx": "YALYx1eLLrmNiT7S1bCi6WX3qGvppWUF3yAYk8aqy47fTM3869tCjiHoZXLrqYfssetebX3j4A1cT4u3ve2YfLL8",
      "close_tx": "RDnZLtCkG4drkBGV1bWLXz6gdTXSHJ5tTAoPXH77ehX419PgCtn2iU74B9ZhjsQc77nUtM5MkGnLy1qnhJi3T8Ui"
    },
    {
      "protocol": "gmtrade",
      "position_id": 33217311,
      "market": "ETH-PERP",
      "market_variant": "ETH/USD[USDC]",
      "address": "dukiyb5imvcdWyYH2BTQHuK1KjTd2awgAz5ie79tiToT",
      "side": "long",
      "max_size_usd": 46780,
      "max_collateral_usd": 467.189331053412,
      "entry_price": 1868.5599619520658,
      "opened_at": "2026-08-14T08:27:53.000Z",
      "status": "closed",
      "closed_at": "2026-08-15T02:23:45.000Z",
      "exit_price": 1883.518714798119,
      "max_leverage": 303.55522283072514,
      "realized_pnl_usd": 375.75746202867134,
      "fees_usd": 8.799315113535,
      "liquidation_fees_usd": 0,
      "funding_fees_usd": 0,
      "borrowing_fees_usd": 9.781578399192,
      "funding_earned_usd": 5.111652869034,
      "net_pnl_usd": 362.2882213849784,
      "fill_count": 9,
      "open_tx": "Ywdya6PfFZHvXYnfMUfH6vUQtExpXWHzRiQ44Mw7S91P7GchcXdMwB2yXCBBn3f9HRtieYuyfukfTT2VLE2hcqWd",
      "close_tx": "p6x3U1i3epuQfrDePQPeGrJiwSUf4QgcmnXNi6Q65ThJ8mif4XXHC6jYP96gbAUJUNeNvAx41m2xNMJsgCnHzEBx"
    }
  ],
  "pagination": {
    "limit": 500,
    "offset": 0,
    "total": 1396
  }
}