API Documentation

RESTful API for PerpsTracker (Elite Only)

⚠️ Elite Feature

API access is available exclusively to Elite subscribers. Upgrade to Elite to get your API key.

Getting Started

Base URL

https://perpstracker.com/api

Authentication

All API requests require authentication using your API key. Include your key in the request header:

Authorization: Bearer YOUR_API_KEY

Obtaining Your API Key

  1. Subscribe to the Elite plan
  2. Log in to your account dashboard at perpstracker.com/dashboard
  3. Navigate to Settings → API
  4. Click "Generate API Key"
  5. Securely store your key (it will only be shown once)
Security Warning:

Never expose your API key in client-side code or public repositories. Use environment variables and keep your key secure.

Rate Limits

Elite API access includes dual-layer rate limiting to ensure fair usage and optimal performance:

  • Burst Limit: Maximum requests per second (prevents instant spikes)
  • Sustained Limit: Maximum requests per minute (controls average usage)
Endpoint Category Burst Limit (per second) Sustained Limit (per minute)
Leaderboard queries 5 req/sec 100 req/min
Live trades 10 req/sec 200 req/min
Trader profiles 5 req/sec 150 req/min
Historical data 3 req/sec 50 req/min

💡 Tip: If you hit the burst limit, wait 1 second before retrying. If you hit the sustained limit, wait until the minute resets. Response headers include RateLimit-Remaining and RateLimit-Reset to help you implement proper retry logic.

API Endpoints

GET /prices

Get current prices for all supported perpetual markets (SOL, ETH, BTC). Prices are sourced from Doves Oracle with Jupiter as fallback. Cached for 30 seconds.

Example Request

GET https://perpstracker.com/api/prices

Example Response

{
  "SOL": 187.45,
  "ETH": 3245.67,
  "BTC": 97234.50,
  "timestamp": 1704567890123
}

Response Fields

Field Description
SOL Current SOL-PERP price in USD
ETH Current ETH-PERP price in USD
BTC Current BTC-PERP price in USD
timestamp Unix timestamp (milliseconds) when prices were fetched
GET /perpetuals/market/overview

Get comprehensive market overview statistics including volume, sentiment, top tokens, and active trader counts.

Query Parameters

Parameter Type Default Description
timeframe string 1d One of: 1d, 7d, 30d, 365d

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \ "https://perpstracker.com/api/perpetuals/market/overview?timeframe=1d"

Example Response

{
  "tier": "elite",
  "updatedAt": "2025-12-06T19:44:38.000Z",
  "market": {
    "total_volume_24h": 45128008.94,
    "total_pnl_24h": 330509.12,
    "total_trades_24h": 7061,
    "active_traders_24h": 98,
    "avg_leverage": 55.84,
    "sentiment": {
      "indicator": "Bullish",
      "long_ratio": 71.1,
      "short_ratio": 28.9,
      "long_volume": 126793190.81,
      "short_volume": 76351439.06,
      "long_trades": 3835,
      "short_trades": 1557
    },
    "top_tokens": [
      {"token": "WSOL", "volume": 186505144.21, "percentage": 65.87},
      {"token": "WBTC", "volume": 59629891.62, "percentage": 21.06},
      {"token": "WETH", "volume": 36993576.95, "percentage": 13.07}
    ],
    "preview": {
      "traders_in_24h": 448,
      "traders_in_7d": 702,
      "traders_in_30d": 1611,
      "traders_in_365d": 1655
    },
    "public_trade_count": 82512,
    "trades_last_hour": 601,
    "traders_active_now": 138
  }
}
GET /perpetuals/leaderboard/periods

Get available historical leaderboard periods (daily, weekly, monthly) with their date ranges.

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \ "https://perpstracker.com/api/perpetuals/leaderboard/periods"

Example Response

{
  "success": true,
  "periods": {
    "daily": ["2025-11-28", "2025-11-27", "2025-11-26", ...],
    "weekly": ["2025-W48", "2025-W47", "2025-W46", ...],
    "monthly": ["2025-11", "2025-10", "2025-09", ...]
  }
}
GET /perpetuals/leaderboard/fixed/{periodType}

Get leaderboard for a specific fixed period (daily, weekly, or monthly). Useful for historical comparisons.

Path Parameters

Parameter Type Required Description
periodType string Required One of: daily, weekly, monthly

Query Parameters

Parameter Type Description
date string For daily: YYYY-MM-DD
week string For weekly: YYYY-Www (e.g., 2025-W48)
month string For monthly: YYYY-MM (e.g., 2025-11)
limit integer Number of traders to return (default: 100)

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \ "https://perpstracker.com/api/perpetuals/leaderboard/fixed/monthly?month=2025-11"

Example Response

{
  "periodType": "monthly",
  "periodValue": "2025-11",
  "tier": "elite",
  "count": 375,
  "stats": {
    "total_traders": 375,
    "total_volume": 3407479163.00,
    "total_pnl": 6458142.36,
    "avg_win_rate": 69.86
  },
  "data": [
    {
      "rank": 1,
      "owner": "7osRjdFqLm8NvT3xPwKcHgY5Rn2VbJsZeQd4WfXhPikD",
      "score": 86.9,
      "pnl": 80901.14,
      "volume": 790417.82,
      "win_rate": 100,
      "avg_leverage": 8.59
    }
  ]
}
GET /perpetuals/positions/recent-activity

Get recently opened and closed positions across all tracked traders.

Query Parameters

Parameter Type Default Description
limit integer 20 Number of positions per category (max 50)

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \ "https://perpstracker.com/api/perpetuals/positions/recent-activity?limit=5"

Example Response

{
  "tier": "elite",
  "recently_opened": [
    {
      "wallet": "E4DsbKzJn8XvTm3P7cNwQh5LfRgY2HjVpWkd6sZxBmyk",
      "position_key": "CgWruNJxT8gH4KwPvRM5nL2sYbVcXdKpQhxy9hJm3TnF",
      "market": "SOL",
      "side": "long",
      "size_usd": 20836.59,
      "collateral_usd": 1591.36,
      "leverage": 13.09,
      "entry_price": 123.53,
      "unrealized_pnl": -3.27,
      "open_time": 1764608075
    }
  ],
  "recently_closed": [
    {
      "wallet": "AePSAg93xDsQqY8Fnv5KzMpR7tNwLhG4vJkDctyYMZ8n",
      "market": "BTC",
      "side": "short",
      "size_usd": 15000.00,
      "realized_pnl": 450.25,
      "close_time": 1764607500
    }
  ]
}
GET /perpetuals/leaderboard/{timeframe}

Retrieve the leaderboard for a specific timeframe with trader rankings and performance metrics.

Path Parameters

Parameter Type Required Description
timeframe string Required One of: 24h, 7d, 30d, 365d

Query Parameters

Parameter Type Default Description
limit integer 100 Number of traders to return (max 1000)
offset integer 0 Pagination offset

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \ https://perpstracker.com/api/perpetuals/leaderboard/24h?limit=10

Example Response

{
  "timeframe": "24h",
  "tier": "elite",
  "updatedAt": "2025-12-06T19:44:38.000Z",
  "count": 98,
  "stats": {
    "total_traders": 98,
    "total_volume": 45128008.94,
    "total_pnl": 330509.12,
    "avg_win_rate": 90.67
  },
  "restrictions": null,
  "data": [
    {
      "wallet_address": "46XavcvseUFgENwWTct2ztncdayNNx7YBJ8rNWZpC8qM",
      "rank": 1,
      "score": 82.8,
      "total_pnl": 9861.45,
      "total_volume": 568651.37,
      "total_trades": 7,
      "win_rate": 100,
      "roi": 124.4,
      "risk_score": 18,
      "risk_level": "Conservative",
      "max_drawdown": 0,
      "total_liquidations": 0,
      "sharpe_ratio": 10.90,
      "avg_leverage": 23.91,
      "avg_collateral": 7926.97,
      "dominant_trade_type": "short",
      "dominant_token_pair": "WBTC",
      "open_position_count": 2,
      "open_unrealized_pnl": 166.39
    }
  ]
}

Trader Data Fields

Field Description
rankLeaderboard position
scoreComposite performance score (0-100)
total_pnlTotal realized PnL in USD
total_volumeTotal trading volume in USD
win_rateWin rate percentage
roiReturn on investment percentage
risk_scoreRisk score (0-100, lower is safer)
risk_levelConservative, Moderate, or Aggressive
sharpe_ratioRisk-adjusted returns metric
avg_leverageAverage leverage used
dominant_trade_type"long" or "short"
dominant_token_pairMost traded token (WSOL, WBTC, WETH)
open_position_countCurrent open positions
open_unrealized_pnlUnrealized PnL from open positions
GET /perpetuals/live-trades

Get real-time perpetual futures trades with flexible filtering options.

Query Parameters

Parameter Type Default Description
limit integer 100 Number of trades to return (max 500)
offset integer 0 Pagination offset
leaderboard string - Filter by leaderboard: 24h, 7d, 30d, 365d
rank integer - Show trades only from top N ranked traders

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \ "https://perpstracker.com/api/perpetuals/live-trades?leaderboard=24h&rank=10&limit=50"

Example Response

{
  "tier": "elite",
  "count": 50,
  "restrictions": null,
  "trades": [
    {
      "wallet_address": "HtXuYvqtALGkJjrHPqz8VPRPcmkdJ9fV7sJpRPiT2D4m",
      "signature": "4wAcTPDwKnqbR6tYz5NPmS8EKUJhv3xkLmDqVwJhg5kfNM8HpT2rWsYbVcXdKpQass5nR7mYzLk2",
      "timestamp": "2025-12-16T05:08:02.466Z",
      "instruction_type": "instantDecreasePosition",
      "trade_classification": "CLOSE",
      "position_pubkey": "4mxpEZQJnT8gH4KwPvRM5nL2sYbVcXdKpQhBmHSJm3TnF",
      "token": "WSOL",
      "side": "1",
      "is_long": 1,
      "size": 8306.33,
      "collateral_usd": 0,
      "leverage": null,
      "price_slippage": 123.71,
      "collected_fee": "5849676",
      "pnl_delta": "37092254",
      "entry_exit_price": 126.225,
      "amount_out": {
        "amount": 2.86,
        "token": "WSOL"
      },
      "entire_position": true
    }
  ]
}

Trade Classification Types

Type Description
OPEN New position opened
INCREASE Position size increased
REDUCE Position partially closed
CLOSE Position fully closed
SET_TP Take-profit order set
SET_SL Stop-loss order set
GET /perpetuals/chart-positions

Get open positions for a specific market from your watchlist or top leaderboard traders. Useful for chart overlay displays showing entry prices of tracked traders.

Query Parameters

Parameter Type Default Description
market string SOL Market to get positions for: SOL, BTC, or ETH
source string watchlist Source of traders: watchlist (your watchlist) or leaderboard (top traders)
maxRank integer 50 Maximum leaderboard rank to include (only applies when source=leaderboard)

Example Request (Watchlist)

curl -H "Authorization: Bearer YOUR_API_KEY" \ "https://perpstracker.com/api/perpetuals/chart-positions?market=SOL&source=watchlist"

Example Request (Leaderboard)

curl -H "Authorization: Bearer YOUR_API_KEY" \ "https://perpstracker.com/api/perpetuals/chart-positions?market=BTC&source=leaderboard&maxRank=25"

Example Response

{
  "source": "leaderboard",
  "market": "SOL",
  "maxRank": 50,
  "count": 12,
  "positions": [
    {
      "wallet": "HtXuYvqtALGkJjrHPqz8VPRPcmkdJ9fV7sJpRPiT2D4m",
      "walletShort": "HtXu...RPiT",
      "side": "long",
      "entryPrice": 198.45,
      "sizeUsd": 125000,
      "collateralUsd": 25000,
      "leverage": 5.0,
      "pnl": 3250.50,
      "openTime": 1734302400,
      "leaderboard": "7D",
      "rank": 3,
      "label": null
    },
    {
      "wallet": "7qjAjzZcP7ckTg8CQ6QBGWTvEVrW8KxPfvTkgnCkY3nm",
      "walletShort": "7qjA...Y3nm",
      "side": "short",
      "entryPrice": 202.10,
      "sizeUsd": 85000,
      "collateralUsd": 17000,
      "leverage": 5.0,
      "pnl": -1200.25,
      "openTime": 1734288000,
      "leaderboard": "1D",
      "rank": 7,
      "label": null
    }
  ]
}

Response Fields

Field Description
source The source used (watchlist or leaderboard)
market The market queried (SOL, BTC, or ETH)
maxRank Max rank filter applied (only for leaderboard source)
count Number of positions returned
positions[].wallet Full wallet address
positions[].walletShort Shortened wallet address for display
positions[].side Position direction (long or short)
positions[].entryPrice Entry price of the position
positions[].sizeUsd Position size in USD
positions[].collateralUsd Collateral amount in USD
positions[].leverage Position leverage
positions[].pnl Unrealized PnL in USD
positions[].openTime Unix timestamp when position was opened
positions[].leaderboard Best leaderboard the trader appears on (leaderboard source only)
positions[].rank Trader's rank on that leaderboard (leaderboard source only)
positions[].label Your custom label for this trader (watchlist source only)
GET /perpetuals/trader/{wallet}

Get comprehensive performance data for a specific trader across all timeframes (rolling and snapshots) with 60+ metrics per timeframe.

Path Parameters

Parameter Type Required Description
wallet string Required Solana wallet address

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \ https://perpstracker.com/api/perpetuals/trader/DRVRvzf8pSiMJi5BY1NmZu5STahBYKMVcfkPp3vxPump

Example Response

{
  "wallet": "J83ZtxeoHLwMNvjVrsD4gQw5nE8PKXUV9Ph6tW2dVamK",
  "tier": "elite",
  "rank": 73,
  "limited_view": false,
  "data": {
    "24h": {
      "wallet_address": "J83ZtxeoHLwMNvjVrsD4gQw5nE8PKXUV9Ph6tW2dVamK",
      "rank": 25,
      "score": 45.2,
      "total_pnl": 15230.50,
      "total_volume": 245000,
      "total_trades": 8,
      "win_rate": 72.0,
      "roi": 8.5,
      "risk_score": 20,
      "risk_level": "Conservative",
      "sharpe_ratio": 3.1,
      "avg_leverage": 7.5,
      "long_pnl": 12000.00,
      "short_pnl": 3230.50,
      "open_position_count": 1,
      "open_position_size_usd": 4304456.77,
      "open_unrealized_pnl": -1856352.58
      // ... 60+ fields per timeframe
    },
    "7d": { /* full stats */ },
    "30d": { /* full stats */ },
    "365d": { /* full stats */ },
    "snapshots": {
      "daily": {
        "rank": 114,
        "score": 39.2,
        "total_pnl": 557864.93,
        // ... snapshot stats
      },
      "weekly": { /* weekly snapshot */ },
      "monthly": { /* monthly snapshot */ }
    }
  }
}

Key Response Fields

Field Type Description
tier string Your subscription tier (determines data access)
rank number Trader's overall rank (null if not ranked)
limited_view boolean True if response is limited due to subscription tier
data.{timeframe} object Full stats for 24h, 7d, 30d, 365d timeframes
data.snapshots object Daily, weekly, monthly snapshot leaderboard appearances
GET /perpetuals/consistent-traders

Get traders who appear in all timeframes (24h, 7d, 30d, 365d), indicating consistent performance. Can also filter to a specific timeframe.

Query Parameters

Parameter Type Default Description
timeframe string all Filter by timeframe: all (traders in ALL timeframes), 24h, 7d, 30d, 365d
limit integer 50 Number of traders to return (max 1000)

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \ "https://perpstracker.com/api/perpetuals/consistent-traders?limit=100"

Example Response

{
  "tier": "pro",
  "timeframe": "all",
  "count": 42,
  "traders": [
    {
      "wallet": "DRVRvzf8pSiMJi5BY1NmZu5STahBYKMVcfkPp3vxPump",
      "avg_rank": 5.25,
      "avg_score": 92.3,
      "total_pnl": 1250430.50,
      "rank_24h": 1,
      "rank_7d": 3,
      "rank_30d": 8,
      "rank_365d": 9,
      "timeframes": {
        "24h": { "rank": 1, "pnl": 45230.50, "volume": 1250000, "win_rate": 68.5, "trades": 42 },
        "7d": { "rank": 3, "pnl": 182500.00, "volume": 5200000, "win_rate": 65.2, "trades": 156 },
        "30d": { "rank": 8, "pnl": 520000.00, "volume": 18500000, "win_rate": 62.8, "trades": 580 },
        "365d": { "rank": 9, "pnl": 502700.00, "volume": 125000000, "win_rate": 61.5, "trades": 2850 }
      }
    }
  ]
}
GET /perpetuals/new-traders

Find traders appearing on the snapshot leaderboard for the first time. Compares the latest period against all previous periods to identify new entrants.

Query Parameters

Parameter Type Default Description
period string daily Snapshot period: daily, weekly, or monthly
limit integer 20 Number of traders to return (max 50)
min_pnl number - Only include traders with PnL >= this value
sort string pnl Sort by: pnl, volume, or rank

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \ https://perpstracker.com/api/perpetuals/new-traders?period=daily&limit=10

Example Response

{
  "tier": "pro",
  "period": "daily",
  "latest_period": "2025-12-15",
  "previous_periods_compared": 45,
  "new_traders_count": 8,
  "traders": [
    {
      "wallet_address": "DRVRvzf8pSiMJi5BY1NmZu5STahBYKMVcfkPp3vxPump",
      "rank": 12,
      "pnl": 45230.50,
      "volume": 1250000.00,
      "win_rate": 68.5,
      "avg_leverage": 5.2,
      "trades": 42
    }
  ]
}
GET /perpetuals/whale-trades

Get recent large trades above a specified size threshold. Track big money moves in real-time.

Query Parameters

Parameter Type Default Description
min_size number 50000 Minimum trade size in USD (min: 10,000)
limit integer 20 Number of trades to return (max 100)
market string - Filter by market: SOL, BTC, or ETH

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \ https://perpstracker.com/api/perpetuals/whale-trades?min_size=100000&limit=10

Example Response

{
  "tier": "elite",
  "min_size": 100000,
  "market": "all",
  "count": 10,
  "trades": [
    {
      "wallet_address": "DRVRvzf8pSiMJi5BY1NmZu5STahBYKMVcfkPp3vxPump",
      "tx_hash": "5GHqt7RvPnL2cYsW9xTmKjN8bDfVhXzQgE4wJpMk3dZr6HqYtNvBcX8sLmRpTn2V",
      "market": "SOL",
      "side": "long",
      "action": "Increase",
      "order_type": "Market",
      "size_usd": 150000.00,
      "collateral_usd": 15000.00,
      "price": 195.50,
      "pnl": null,
      "fee": 105.00,
      "timestamp": "2025-12-15T14:30:00Z"
    }
  ]
}
GET /perpetuals/liquidations

Get recent liquidation events with 24h summary statistics.

Query Parameters

Parameter Type Default Description
limit integer 20 Number of liquidations to return (max 100)
market string - Filter by market: SOL, BTC, or ETH
min_size number - Minimum liquidation size in USD

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \ https://perpstracker.com/api/perpetuals/liquidations?limit=10&market=SOL

Example Response

{
  "tier": "elite",
  "market": "SOL",
  "count": 10,
  "stats_24h": {
    "liquidation_count": 156,
    "total_volume": 4250000.00,
    "total_losses": 385000.00
  },
  "liquidations": [
    {
      "wallet_address": "7qjAjzZcP7ckTg8CQ6QBGWTvEVrW8KxPfvTkgnCkY3nm",
      "tx_hash": "3ABJ4GHpQ5GPD4MP9gaU7Nn3XNjPGgnoUbTk6v7DaBZvXbsiG36DVTPAvPnUecF15",
      "market": "SOL",
      "side": "long",
      "size_usd": 125000.00,
      "price": 185.25,
      "pnl": -18500.00,
      "total_fee": 875.00,
      "liquidation_fee": 625.00,
      "timestamp": "2025-12-15T12:15:00Z"
    }
  ]
}
GET /perpetuals/active-traders

Get traders with the highest trading activity from leaderboard data. Shows trade counts per timeframe (24h, 7d, 30d, 365d).

Query Parameters

Parameter Type Default Description
timeframe string all Filter by timeframe: all, 24h, 7d, 30d, 365d
sort string total Sort by: total, 24h, 7d, 30d, 365d, pnl, win_rate
limit integer 50 Number of traders to return (max 100)
min_trades integer 1 Minimum total trades to qualify

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \ https://perpstracker.com/api/perpetuals/active-traders?timeframe=24h&sort=24h&limit=20

Example Response

{
  "tier": "pro",
  "timeframe": "24h",
  "sort": "24h",
  "count": 20,
  "traders": [
    {
      "wallet_address": "DRVRvzf8pSiMJi5BY1NmZu5STahBYKMVcfkPp3vxPump",
      "trades_24h": 47,
      "trades_7d": 185,
      "trades_30d": 520,
      "trades_365d": 2150,
      "total_trades": 2902,
      "total_pnl": 45230.50,
      "win_rate": 62.5,
      "best_rank": 12,
      "timeframe_appearances": ["24h", "7d", "30d", "365d"]
    }
  ]
}
GET /perpetuals/snapshot-frequency

Get traders ranked by how many times they appear on historical leaderboard snapshots. Counts appearances across daily, weekly, and monthly snapshots.

Query Parameters

Parameter Type Default Description
limit integer 50 Number of traders to return (max 100 for Pro/Elite, 20 for free)
min_appearances integer 3 Minimum total appearances to include in results

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \ https://perpstracker.com/api/perpetuals/snapshot-frequency?limit=20&min_appearances=5

Example Response

{
  "tier": "pro",
  "count": 20,
  "periods": {
    "daily": 30,
    "weekly": 8,
    "monthly": 3,
    "total": 41
  },
  "traders": [
    {
      "wallet_address": "DRVRvzf8pSiMJi5BY1NmZu5STahBYKMVcfkPp3vxPump",
      "daily_count": 28,
      "weekly_count": 7,
      "monthly_count": 3,
      "total_appearances": 38,
      "best_rank": 2,
      "latest_pnl": 125430.50
    }
  ]
}
GET /perpetuals/trader/{wallet}/trades

Get recent trades for a specific trader.

Path Parameters

Parameter Type Required Description
wallet string Required Solana wallet address

Query Parameters

Parameter Type Default Description
limit integer 50 Number of trades to return (max 100)

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \ https://perpstracker.com/api/perpetuals/trader/DRVRvzf8pSiMJi5BY1NmZu5STahBYKMVcfkPp3vxPump/trades?limit=20

Example Response

{
  "trades": [
    {
      "signature": "5GHqt7RvPnL2cYsW9xTmKjN8bDfVhXzQgE4wJpMk3dZr6HqYtNvBcX8sLmRpTn2V",
      "timestamp": "2025-11-30T12:30:00Z",
      "action_type": "instantIncreasePosition",
      "token": "SOL",
      "side": "long",
      "size_usd_delta": 25000.00,
      "leverage": 8.33,
      "collateral_usd_delta": 3000.00
    }
  ],
  "wallet": "DRVRvzf8pSiMJi5BY1NmZu5STahBYKMVcfkPp3vxPump",
  "count": 20
}
GET /perpetuals/trader/{wallet}/positions

Get current open positions for a specific trader with full position details.

Path Parameters

Parameter Type Required Description
wallet string Required Solana wallet address

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \ https://perpstracker.com/api/perpetuals/trader/DRVRvzf8pSiMJi5BY1NmZu5STahBYKMVcfkPp3vxPump/positions

Example Response

{
  "positions": [
    {
      "position_key": "5GHqt7RvPnL2cYsW9xTmKjN8bDfVhXzQgE4wJpmK3dZr",
      "market": "SOL",
      "side": "long",
      "size_usd": 50000.00,
      "collateral_usd": 5000.00,
      "leverage": 10.0,
      "entry_price": 195.50,
      "liquidation_price": 178.50,
      "unrealized_pnl": 700.00,
      "open_time": 1732792500,
      "last_updated": 1732796100
    }
  ],
  "totals": {
    "size_usd": 50000.00,
    "collateral_usd": 5000.00,
    "unrealized_pnl": 700.00
  },
  "wallet": "DRVRvzf8pSiMJi5BY1NmZu5STahBYKMVcfkPp3vxPump",
  "count": 1
}

Response Fields

Field Type Description
position_key string Unique position identifier
market string Trading market (SOL, ETH, BTC)
side string Position direction (long/short)
size_usd number Total position size in USD
collateral_usd number Collateral amount in USD
leverage number Effective leverage (size/collateral)
entry_price number Average entry price
liquidation_price number Price at which position will be liquidated
unrealized_pnl number Current unrealized profit/loss in USD
open_time integer Position open time (Unix timestamp in seconds)
last_updated integer Last position update time (Unix timestamp)
GET /perpetuals/trader/{wallet}/history

Get historical closed positions for a specific trader with pagination.

Path Parameters

Parameter Type Required Description
wallet string Required Solana wallet address

Query Parameters

Parameter Type Default Description
start integer 0 Pagination offset
limit integer 50 Number of positions to return (max 100)

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \ "https://perpstracker.com/api/perpetuals/trader/DRVRvzf8pSiMJi5BY1NmZu5STahBYKMVcfkPp3vxPump/history?start=0&limit=20"

Example Response

{
  "wallet": "AePSAg93xDsQqY8Fnv5KzMpR7tNwLhG4vJkDctyYMZ8n",
  "trades": [
    {
      "market": "BTC",
      "positionName": "BTC-PERP",
      "positionPubkey": "DatNgd2eJxT8gH4KwPvRM5nL2sYbVcXdKpScazNHmTnF",
      "side": "LONG",
      "action": "Decrease",
      "tradeType": "Decrease",
      "orderType": "Market",
      "size": 963047.43,
      "price": 90846.06,
      "collateralDelta": 31692.71,
      "leverage": null,
      "entirePosition": false,
      "pnl": 8644.39,
      "pnlPercent": 35.85,
      "fee": 1061.69,
      "baseFee": 577.83,
      "borrowFee": 194.95,
      "liquidationFee": 0,
      "txHash": "iBrjbwfxNp5mYz3kLqW8vT9dHgXcP2nRsJfVbQx7KmZyD4tLwEaGeFwNB8r2sXqY",
      "createdTime": 1765483199,
      "createdAt": "2025-12-11T19:59:59.000Z"
    }
  ],
  "count": 20,
  "totalCount": 427,
  "hasMore": true,
  "summary": {
    "totalPnl": 8539.29,
    "totalFees": 1503.27,
    "netPnl": 7036.02,
    "totalVolume": 1455582.23,
    "wins": 1,
    "losses": 1,
    "winRate": 50
  }
}

Trade Fields

Field Type Description
market string Trading market (BTC, ETH, SOL)
side string Position direction (LONG/SHORT)
action string Trade action (Open, Increase, Decrease, Close)
size number Trade size in USD
price number Execution price
pnl number Realized PnL for this trade
pnlPercent number PnL as percentage of collateral
fee number Total fees (base + borrow + liquidation)
entirePosition boolean Whether entire position was closed
txHash string Solana transaction signature
GET /perpetuals/compare

Compare performance metrics between multiple traders.

Query Parameters

Parameter Type Required Description
wallets string Required Comma-separated list of wallet addresses (max 5)
timeframe string Optional One of: 24h, 7d, 30d, 365d

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \ "https://perpstracker.com/api/perpetuals/compare?wallets=DRVRvzf8pSiMJi5BY1NmZu5STahBYKMVcfkPp3vxPump,AePSAg93xDsQqY8Fnv5KzMpR7tNwLhG4vJkDctyYMZ8n&timeframe=30d"

Example Response

{
  "comparison": [
    {
      "wallet": "DRVRvzf8pSiMJi5BY1NmZu5STahBYKMVcfkPp3vxPump",
      "rank": 3,
      "total_pnl": 125430.50,
      "win_rate": 68.5,
      "roi": 42.3,
      "total_trades": 156
    },
    {
      "wallet": "AePSAg93xDsQqY8Fnv5KzMpR7tNwLhG4vJkDctyYMZ8n",
      "rank": 12,
      "total_pnl": 89230.25,
      "win_rate": 62.1,
      "roi": 31.8,
      "total_trades": 203
    }
  ],
  "timeframe": "30d"
}
GET /perpetuals/positions/all

Get all currently open positions across all tracked traders with comprehensive statistics and market breakdown.

Query Parameters

Parameter Type Default Description
market string - Filter by market (e.g., SOL, BTC, ETH)
side string - Filter by side: long or short
limit integer 100 Number of positions to return (max 500)
page integer 1 Page number for pagination

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \ "https://perpstracker.com/api/perpetuals/positions/all?market=SOL&limit=50"

Example Response

{
  "tier": "elite",
  "positions": [
    {
      "wallet": "J83ZtxeoHLwMNvjVrsD4gQw5nE8PKXUV9Ph6tW2dVamK",
      "position_key": "BD5tKkWiJxT8gH4KwPvRM5nL2sYbVcXdKpQhzkqdryTnF",
      "market": "SOL",
      "side": "long",
      "size_usd": 4304456.77,
      "collateral_usd": 2377788.35,
      "leverage": 1.81,
      "entry_price": 232.42,
      "liquidation_price": 106.35,
      "unrealized_pnl": -1981582.65,
      "open_time": 1759772482,
      "last_updated": 1765860720
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 664,
    "totalPages": 14,
    "hasMore": true
  },
  "stats": {
    "total_positions": 664,
    "unique_traders": 501,
    "total_size": 85701198.58,
    "total_collateral": 25327107.24,
    "total_unrealized_pnl": -13515104.56,
    "avg_leverage": 14.85,
    "long_count": 541,
    "short_count": 123,
    "long_ratio": 81.48,
    "long_pnl": -13811844.96,
    "short_pnl": 296740.39,
    "winning_pnl": 436620.34,
    "losing_pnl": -13951724.90
  },
  "market_breakdown": [
    {"market": "SOL", "count": 355, "total_size": 53573927.91, "total_pnl": -10984816.31, "long_pnl": -11020634.72, "short_pnl": 35818.41},
    {"market": "BTC", "count": 196, "total_size": 24006660.60, "total_pnl": -2020128.10, "long_pnl": -2127922.85, "short_pnl": 107794.75},
    {"market": "ETH", "count": 113, "total_size": 8120610.06, "total_pnl": -510160.16, "long_pnl": -588287.39, "short_pnl": 78127.23}
  ],
  "last_synced": 1765860786,
  "filters_applied": {
    "market": null,
    "side": null,
    "minSize": null,
    "minPnl": null,
    "maxPnl": null,
    "profitFilter": null
  }
}

Position Fields

Field Type Description
wallet string Trader's wallet address
position_key string Unique position identifier
market string Token being traded (SOL, BTC, ETH)
side string Position direction: long or short
size_usd number Position size in USD
collateral_usd number Collateral amount in USD
leverage number Position leverage (size / collateral)
entry_price number Average entry price
liquidation_price number Price at which position will be liquidated
unrealized_pnl number Current unrealized profit/loss in USD
open_time integer Unix timestamp when position was opened
last_updated integer Unix timestamp of last position update
GET /perpetuals/positions/summary

Get a lightweight aggregated summary of all open positions across all tracked traders. Perfect for dashboards and quick market overview without fetching full position lists.

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \ "https://perpstracker.com/api/perpetuals/positions/summary"

Example Response

{
  "success": true,
  "summary": {
    "total_positions": 664,
    "unique_traders": 501,
    "total_value": 85701198.58,
    "total_collateral": 25327107.24,
    "long_count": 541,
    "short_count": 123,
    "long_value": 72345678.90,
    "short_value": 13355519.68,
    "long_short_ratio": 5.42,
    "avg_leverage": 14.85,
    "unrealized_pnl": -13515104.56,
    "pnl_percent": -53.38,
    "long_pnl": -13811844.96,
    "short_pnl": 296740.39,
    "profitable_count": 156,
    "losing_count": 508,
    "win_rate": 24
  },
  "by_market": {
    "SOL": {
      "position_count": 355,
      "total_value": 53573927.91,
      "total_collateral": 15234567.12,
      "unrealized_pnl": -10984816.31,
      "avg_leverage": 12.5,
      "long_count": 280,
      "short_count": 75
    },
    "BTC": {
      "position_count": 196,
      "total_value": 24006660.60,
      "total_collateral": 7234567.89,
      "unrealized_pnl": -2020128.10,
      "avg_leverage": 18.2,
      "long_count": 165,
      "short_count": 31
    }
  },
  "top_positions": [
    {
      "wallet": "J83ZtxeoHLwMNvjVrsD4gQw5nE8PKXUV9Ph6tW2dVamK",
      "market": "SOL",
      "side": "long",
      "size_usd": 4304456.77,
      "collateral_usd": 2377788.35,
      "leverage": 1.8,
      "entry_price": 232.42,
      "pnl_usd": -1981582.65,
      "pnl_percent": -83.4
    }
  ],
  "top_pnl": [
    {
      "wallet": "DRVRvzf8pSiMJi5BY1NmZu5STahBYKMVcfkPp3vxPump",
      "market": "BTC",
      "side": "short",
      "size_usd": 156789.00,
      "leverage": 5.2,
      "pnl_usd": 45678.90,
      "pnl_percent": 42.5
    }
  ],
  "worst_pnl": [
    {
      "wallet": "7qjAjzZcP7ckTg8CQ6QBGWTvEVrW8KxPfvTkgnCkY3nm",
      "market": "SOL",
      "side": "long",
      "size_usd": 2345678.00,
      "leverage": 3.5,
      "pnl_usd": -567890.12,
      "pnl_percent": -62.3
    }
  ],
  "top_traders": [
    {
      "wallet": "J83ZtxeoHLwMNvjVrsD4gQw5nE8PKXUV9Ph6tW2dVamK",
      "position_count": 5,
      "total_value": 5678901.23,
      "total_pnl": -2123456.78
    }
  ],
  "last_synced": 1765860786
}

Response Fields

Field Type Description
summary.total_positions integer Total count of open positions
summary.unique_traders integer Number of traders with open positions
summary.total_value number Combined USD value of all positions
summary.long_short_ratio number Ratio of long value to short value
summary.win_rate integer Percentage of positions currently profitable
by_market object Breakdown by market (SOL, BTC, ETH, etc.)
top_positions array Top 5 positions by size
top_pnl array Top 5 positions by profit
worst_pnl array Top 5 positions by loss
top_traders array Top 5 traders by total position value
Use Case: Dashboard Overview

Perfect for building dashboards that show platform-wide market sentiment. Monitor overall long/short ratios, identify the largest positions, and track which traders and markets are performing best or worst - all in a single efficient API call.

GET /perpetuals/watchlist

Get your watchlist with full trader statistics from leaderboard data. Returns performance metrics for each trader.

Query Parameters

Parameter Type Default Description
timeframe string 365d Timeframe for stats: 24h, 7d, 30d, 365d

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \ "https://perpstracker.com/api/perpetuals/watchlist?timeframe=7d"

Example Response

{
  "tier": "elite",
  "count": 5,
  "limit": 100,
  "watchlist": [
    {
      "wallet_address": "DRVRvzf8pSiMJi5BY1NmZu5STahBYKMVcfkPp3vxPump",
      "notes": "Top SOL trader",
      "label": "WHALE1",
      "added_at": "2025-12-10T14:30:00Z",
      "alerts_enabled": true,
      "stats": {
        "rank": 12,
        "pnl": 45230.50,
        "volume": 1250000,
        "win_rate": 68.5,
        "trades": 42,
        "score": 85.3
      }
    }
  ]
}
POST /perpetuals/watchlist/add

Add a trader to your watchlist. Pro users can have up to 3 traders, Elite users up to 100.

Request Body

Parameter Type Required Description
wallet_address string Required Solana wallet address to add
notes string Optional Notes about this trader (max 500 chars)
label string Optional Short label for display (max 10 chars, alphanumeric)

Example Request

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"wallet_address": "DRVRvzf8pSiMJi5BY1NmZu5STahBYKMVcfkPp3vxPump", "label": "WHALE1", "notes": "Top trader"}' \ "https://perpstracker.com/api/perpetuals/watchlist/add"

Example Response

{
  "success": true,
  "message": "Trader added to watchlist",
  "wallet_address": "DRVRvzf8pSiMJi5BY1NmZu5STahBYKMVcfkPp3vxPump",
  "label": "WHALE1",
  "watchlist_count": 6,
  "limit": 100
}
DELETE /perpetuals/watchlist/{wallet}

Remove a trader from your watchlist.

Path Parameters

Parameter Type Description
wallet string Wallet address to remove

Example Request

curl -X DELETE -H "Authorization: Bearer YOUR_API_KEY" \ "https://perpstracker.com/api/perpetuals/watchlist/DRVRvzf8pSiMJi5BY1NmZu5STahBYKMVcfkPp3vxPump"

Example Response

{
  "success": true,
  "message": "Trader removed from watchlist",
  "wallet_address": "DRVRvzf8pSiMJi5BY1NmZu5STahBYKMVcfkPp3vxPump"
}
PATCH /perpetuals/watchlist/{wallet}/notes

Update the notes for a watchlisted trader.

Path Parameters

Parameter Type Description
wallet string Wallet address to update

Request Body

Parameter Type Description
notes string New notes (max 500 chars)

Example Request

curl -X PATCH -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"notes": "Updated notes about this trader"}' \ "https://perpstracker.com/api/perpetuals/watchlist/DRVRvzf8pSiMJi5BY1NmZu5STahBYKMVcfkPp3vxPump/notes"

Example Response

{
  "success": true,
  "message": "Notes updated successfully",
  "wallet_address": "DRVRvzf8pSiMJi5BY1NmZu5STahBYKMVcfkPp3vxPump",
  "notes": "Updated notes about this trader"
}
PATCH /perpetuals/watchlist/{wallet}/label

Update the display label for a watchlisted trader. Labels are shown on charts and position displays.

Path Parameters

Parameter Type Description
wallet string Wallet address to update

Request Body

Parameter Type Description
label string New label (max 10 chars, alphanumeric only)

Example Request

curl -X PATCH -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"label": "WHALE2"}' \ "https://perpstracker.com/api/perpetuals/watchlist/DRVRvzf8pSiMJi5BY1NmZu5STahBYKMVcfkPp3vxPump/label"

Example Response

{
  "success": true,
  "message": "Label updated successfully",
  "wallet_address": "DRVRvzf8pSiMJi5BY1NmZu5STahBYKMVcfkPp3vxPump",
  "label": "WHALE2"
}
GET /perpetuals/watchlist/check/{wallet}

Check if a specific wallet is in your watchlist.

Path Parameters

Parameter Type Description
wallet string Wallet address to check

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \ "https://perpstracker.com/api/perpetuals/watchlist/check/DRVRvzf8pSiMJi5BY1NmZu5STahBYKMVcfkPp3vxPump"

Example Response

{
  "in_watchlist": true,
  "entry": {
    "wallet_address": "DRVRvzf8pSiMJi5BY1NmZu5STahBYKMVcfkPp3vxPump",
    "notes": "Top SOL trader",
    "added_at": "2025-12-10T14:30:00Z"
  }
}
POST /perpetuals/watchlist/{wallet}/alerts

Enable or disable trade alerts for a specific watchlisted trader. When enabled, you'll receive real-time notifications when this trader opens, closes, or modifies positions.

Path Parameters

Parameter Type Description
wallet string Wallet address (must be in your watchlist)

Request Body

Parameter Type Description
enabled boolean true to enable alerts, false to disable

Example Request

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"enabled": true}' \ "https://perpstracker.com/api/perpetuals/watchlist/DRVRvzf8pSiMJi5BY1NmZu5STahBYKMVcfkPp3vxPump/alerts"

Example Response

{
  "success": true,
  "wallet_address": "DRVRvzf8pSiMJi5BY1NmZu5STahBYKMVcfkPp3vxPump",
  "alerts_enabled": true
}
POST /perpetuals/watchlist/alerts/bulk

Enable or disable trade alerts for ALL traders in your watchlist at once.

Request Body

Parameter Type Description
enabled boolean true to enable all alerts, false to disable all

Example Request

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"enabled": true}' \ "https://perpstracker.com/api/perpetuals/watchlist/alerts/bulk"

Example Response

{
  "success": true,
  "alerts_enabled": true,
  "updated_count": 15
}
GET /perpetuals/watchlist/alerts/trades

Get recent trades from watchlisted traders that have alerts enabled. Useful for polling trade activity.

Query Parameters

Parameter Type Default Description
since integer 60 seconds ago Unix timestamp in milliseconds - get trades since this time

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \ "https://perpstracker.com/api/perpetuals/watchlist/alerts/trades?since=1734302400000"

Example Response

{
  "tier": "elite",
  "count": 3,
  "since": 1734302400000,
  "trades": [
    {
      "wallet_address": "DRVRvzf8pSiMJi5BY1NmZu5STahBYKMVcfkPp3vxPump",
      "signature": "4wAcTPDwKnqbR6tYz5NPmS8EKUJhv3xkLmDqVwJhg5kfNM8HpT2rWsYbVcXdKpQass5nR7mYzLk2",
      "timestamp": "2025-12-16T05:08:02Z",
      "instruction_type": "instantIncreasePosition",
      "trade_classification": "OPEN",
      "token": "WSOL",
      "side": "long",
      "size": 25000.00,
      "collateral_usd": 5000.00,
      "leverage": 5.0,
      "entry_exit_price": 198.45
    }
  ]
}
GET /perpetuals/watchlist/positions-summary

Get an aggregated summary of all open positions held by traders in your watchlist. Includes long/short ratios, total value, and per-market breakdowns.

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \ "https://perpstracker.com/api/perpetuals/watchlist/positions-summary"

Example Response

{
  "tier": "elite",
  "summary": {
    "total_positions": 24,
    "traders_with_positions": 8,
    "traders_total": 15,
    "total_value": 1250000,
    "long_count": 15,
    "short_count": 9,
    "long_value": 850000,
    "short_value": 400000,
    "long_short_ratio": 2.13,
    "avg_leverage": 4.2,
    "total_pnl": 45230.50,
    "by_market": {
      "SOL": { "long": 10, "short": 5, "value": 650000 },
      "BTC": { "long": 3, "short": 3, "value": 400000 },
      "ETH": { "long": 2, "short": 1, "value": 200000 }
    }
  },
  "positions": [
    {
      "wallet": "DRVRvzf8pSiMJi5BY1NmZu5STahBYKMVcfkPp3vxPump",
      "label": "WHALE1",
      "market": "SOL",
      "side": "long",
      "size_usd": 125000,
      "entry_price": 198.45,
      "leverage": 5.0,
      "pnl": 3250.50
    }
  ]
}
GET /perpetuals/watchlist/simulation/settings

Get your saved copy trading simulation settings. These settings define how potential copied positions would be sized when using the positions-with-simulation endpoint.

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \ "https://perpstracker.com/api/perpetuals/watchlist/simulation/settings"

Example Response

{
  "success": true,
  "settings": {
    "copy_mode": "percentage",
    "fixed_size_usd": 100,
    "percentage_of_trader": 10,
    "max_leverage": 10
  }
}

Response Fields

Field Type Description
copy_mode string Copy sizing mode: fixed_size, percentage, or match_trader
fixed_size_usd number Fixed position size in USD (used when copy_mode is "fixed_size")
percentage_of_trader number Percentage of trader's position size (used when copy_mode is "percentage")
max_leverage number Maximum leverage cap for simulated positions
POST /perpetuals/watchlist/simulation/settings

Save your copy trading simulation settings. These settings are persisted to your account and used when calculating simulated positions.

Request Body

Parameter Type Required Description
copyMode string Optional One of: fixed_size, percentage, match_trader
fixedSizeUsd number Optional Fixed position size in USD (1-100000)
percentageOfTrader number Optional Percentage of trader's size (1-100)
maxLeverage number Optional Maximum leverage cap (1-100)

Example Request

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"copyMode":"percentage","percentageOfTrader":15,"maxLeverage":5}' \ "https://perpstracker.com/api/perpetuals/watchlist/simulation/settings"

Example Response

{
  "success": true,
  "settings": {
    "copy_mode": "percentage",
    "fixed_size_usd": 100,
    "percentage_of_trader": 15,
    "max_leverage": 5
  }
}
GET /perpetuals/watchlist/positions-with-simulation

Get all open positions from your watchlisted traders with a simulation overlay showing what your copied position would look like based on your saved simulation settings. Useful for previewing copy trading strategies before execution.

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \ "https://perpstracker.com/api/perpetuals/watchlist/positions-with-simulation"

Example Response

{
  "success": true,
  "simulation_settings": {
    "copy_mode": "percentage",
    "fixed_size_usd": 100,
    "percentage_of_trader": 15,
    "max_leverage": 5
  },
  "summary": {
    "total_positions": 48,
    "total_traders": 31,
    "simulated_total_size": 7250.50,
    "simulated_total_collateral": 1450.10
  },
  "positions": [
    {
      "wallet": "DRVRvzf8pSiMJi5BY1NmZu5STahBYKMVcfkPp3vxPump",
      "label": "TopTrader1",
      "market": "SOL",
      "side": "long",
      "size_usd": 25000.00,
      "collateral_usd": 5000.00,
      "leverage": 5.0,
      "entry_price": 195.50,
      "pnl": 1250.00,
      "pnl_pct": 25.0,
      "simulation": {
        "your_size_usd": 3750.00,
        "your_collateral_usd": 750.00,
        "your_leverage": 5.0,
        "your_pnl": 187.50
      }
    }
  ]
}

Simulation Fields

Field Type Description
your_size_usd number Simulated position size based on your settings
your_collateral_usd number Required collateral for simulated position
your_leverage number Effective leverage (capped by max_leverage setting)
your_pnl number Proportional PnL based on your simulated size
GET /perpetuals/watchlist/backtest ELITE

Run a historical backtest on a specific trader's past positions using your simulation settings. Returns what your PnL would have been if you had copied their trades over the specified period. Requires Elite subscription.

Query Parameters

Parameter Type Required Description
wallet string Required Wallet address of the trader to backtest
days integer Optional Number of days to look back (default: 7, max: 30)

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \ "https://perpstracker.com/api/perpetuals/watchlist/backtest?wallet=DRVRvzf8pSiMJi5BY1NmZu5STahBYKMVcfkPp3vxPump&days=7"

Example Response

{
  "success": true,
  "wallet": "DRVRvzf8pSiMJi5BY1NmZu5STahBYKMVcfkPp3vxPump",
  "days": 7,
  "simulation_settings": {
    "copy_mode": "percentage",
    "fixed_size_usd": 100,
    "percentage_of_trader": 15,
    "max_leverage": 5
  },
  "summary": {
    "total_trades": 12,
    "winning_trades": 9,
    "losing_trades": 3,
    "trader_total_pnl": 8500.00,
    "simulated_total_pnl": 1275.00,
    "win_rate": 75.0
  },
  "trades": [
    {
      "market": "SOL",
      "side": "long",
      "entry_time": 1735430400000,
      "exit_time": 1735516800000,
      "trader_size_usd": 20000.00,
      "trader_pnl": 2500.00,
      "simulated_size_usd": 3000.00,
      "simulated_pnl": 375.00
    }
  ]
}

Summary Fields

Field Type Description
total_trades integer Number of closed positions in the period
winning_trades integer Number of profitable trades
losing_trades integer Number of unprofitable trades
trader_total_pnl number Trader's actual total PnL over the period
simulated_total_pnl number Your simulated PnL if you had copied
win_rate number Percentage of winning trades
GET /perpetuals/account

Get your account information including subscription details, days remaining, and watchlist usage.

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \ "https://perpstracker.com/api/perpetuals/account"

Example Response

{
  "subscription": {
    "plan": "elite",
    "status": "active",
    "expiresAt": 1735689600000,
    "daysRemaining": 30
  },
  "watchlist": {
    "count": 5,
    "limit": 30
  }
}

Response Fields

Field Type Description
subscription.plan string Your subscription tier: free, pro, or elite
subscription.status string Subscription status (usually active)
subscription.expiresAt integer Unix timestamp (ms) when subscription expires, or null if perpetual
subscription.daysRemaining integer Days until subscription expires, or null if perpetual
watchlist.count integer Number of wallets currently in your watchlist
watchlist.limit integer Maximum watchlist slots for your tier

Downloads API ELITE

Access downloadable tools and check for updates programmatically. Used by the Copytrader for auto-updates.

GET /downloads/available ELITE

Get list of available downloads for your plan, including version information for checking updates.

Example Request

GET https://perpstracker.com/api/downloads/available

Example Response

{
  "success": true,
  "downloads": [
    {
      "id": "copytrader-python",
      "displayName": "Copytrader (Python)",
      "description": "Full-featured copytrading bot...",
      "version": "1.5.40",
      "filename": "PerpsTracker-Copytrader-Python.zip"
    }
  ]
}
GET /downloads/{id} ELITE

Download a specific file. Can download the full package or individual updatable files.

Path Parameters

Parameter Type Description
id string Download ID (e.g., copytrader-python)

Query Parameters

Parameter Type Required Description
file string Optional Specific file to download (e.g., jupiter_perps.py). If omitted, downloads full ZIP package.

Example Requests

# Download full package GET /downloads/copytrader-python # Download specific file (for updates) GET /downloads/copytrader-python?file=jupiter_perps.py

Trading API & Copytrader

Execute trades on Jupiter Perpetuals directly through the PerpsTracker API. Our Copytrader bots use these endpoints to enable automated trade copying from your watchlisted traders.

🤖 Copytrader Desktop Applications

Download the Copytrader bot to automatically copy trades from top performers. Available as a Python application for Windows, macOS, and Linux.

🐍
Python Copytrader
Requires Python 3.8+
📥 How to Download

Download links are available on your Elite Dashboard after generating an API key. Go to Settings → API Keys to get started.

⚠️ Trading Fee

A 1% fee is applied to all position opens, increases, and TP/SL executions. This fee supports platform development and maintenance.

Increase Position

POST /trading/increase-position

Open a new position or increase an existing one. Returns an unsigned transaction for the user to sign.

Request Body

Parameter Type Required Description
owner string Required Wallet address opening the position
market string Required Market to trade: SOL, ETH, BTC
side string Required long or short
collateralUsd number Optional Collateral amount in USD (calculated from sizeUsd/leverage if not provided)
sizeUsd number Optional Position size in USD
leverage number Optional Leverage multiplier (default: 5)
inputMint string Optional Input token: USDC, USDT, SOL (default: USDC)
slippageBps number Optional Slippage tolerance in basis points (default: 50)

Example Response

{
  "success": true,
  "transaction": "base64_encoded_transaction...",
  "message": "Transaction ready for signing"
}

Decrease Position

POST /trading/decrease-position

Partially close or fully close a position.

Request Body

Parameter Type Required Description
owner string Required Wallet address
positionPubkey string Required Position public key from positions endpoint
sizeUsd number Required Amount to close in USD (use full size to close entirely)
outputMint string Optional Token to receive: USDC (default)
slippageBps number Optional Slippage tolerance (default: 50)

Close All Positions

POST /trading/close-all

Close all open positions for a wallet.

Request Body

Parameter Type Required Description
owner string Required Wallet address
outputMint string Optional Token to receive (default: USDC)
slippageBps number Optional Slippage tolerance (default: 100)

Example Response

{
  "success": true,
  "transactions": ["tx1_base64...", "tx2_base64..."],
  "message": "Transactions ready for signing"
}

Set Take-Profit / Stop-Loss

POST /trading/set-tpsl

Set take-profit and/or stop-loss orders for a position.

Request Body

Parameter Type Required Description
owner string Required Wallet address
positionPubkey string Required Position public key
takeProfitPrice number Optional Take-profit trigger price
stopLossPrice number Optional Stop-loss trigger price
outputMint string Optional Token to receive when triggered (default: USDC)

Get Your Positions

GET /trading/positions

Get open positions for your connected wallet. Returns full position details including position public key needed for TP/SL and closing.

Query Parameters

Parameter Type Required Description
wallet string Required Your wallet address

Example Response

{
  "success": true,
  "positions": [
    {
      "positionPubkey": "5GHqt7RvPnL2cYsW9xTmKjN8bDfVhXzQgE4wJpmK3dZr",
      "market": "SOL",
      "side": "long",
      "size_usd": 50000.00,
      "collateral_usd": 5000.00,
      "leverage": 10.0,
      "entry_price": 195.50,
      "mark_price": 198.25,
      "liquidation_price": 178.50,
      "unrealized_pnl": 700.00,
      "open_time": 1732924800,
      "last_updated": 1732928400,
      "take_profit": 210.00,
      "stop_loss": 185.00
    }
  ]
}

Get Your Trade History

GET /trading/trades

Get trade history for your wallet.

Query Parameters

Parameter Type Default Description
wallet string - Your wallet address
limit integer 50 Number of trades to return
offset integer 0 Pagination offset

Get Market Stats

GET /trading/market-stats

Get current market statistics including funding rates and open interest.

Query Parameters

Parameter Type Description
mint string Token mint address (optional - returns all if not specified)

Get Fee Info

GET /trading/fee-info

Get current fee configuration for trades executed through the API.

Example Response

{
  "success": true,
  "feeBps": 100,
  "feePercent": 1,
  "description": "1% fee on position opens/closes and TP/SL executions"
}

Update Take-Profit / Stop-Loss

PATCH /trading/update-tpsl

Update existing take-profit and/or stop-loss orders for a position.

Request Body

Parameter Type Required Description
owner string Required Wallet address
positionPubkey string Required Position public key
takeProfitPrice number Optional New take-profit trigger price
stopLossPrice number Optional New stop-loss trigger price

Cancel Take-Profit / Stop-Loss

DELETE /trading/cancel-tpsl

Cancel existing take-profit and stop-loss orders for a position.

Request Body

Parameter Type Required Description
owner string Required Wallet address
positionPubkey string Required Position public key

Execute Transaction

POST /trading/execute

Execute a signed transaction. After signing the transaction returned by other trading endpoints, use this to submit it to the network.

Request Body

Parameter Type Required Description
signedTransaction string Required Base64-encoded signed transaction
action string Optional Action type for logging (default: "increase-position")

Example Response

{
  "success": true,
  "signature": "5GHqt7RvPnL2cYsW9xTmKjN8bDfVhXzQgE4wJpMk3dZr6HqYtNvBcX8sLmRpTn2V",
  "message": "Transaction executed successfully"
}

Get Pool Info

GET /trading/pool-info

Get JLP (Jupiter Liquidity Pool) information including pool stats and liquidity data.

Example Response

{
  "success": true,
  "poolInfo": {
    "tvl": 150000000.00,
    "aum": 145000000.00,
    "utilizationRate": 0.35
  }
}

Get Markets List

GET /trading/markets

Get list of all available trading markets with custodies info. Cached for 60 seconds.

Example Response

{
  "success": true,
  "custodies": [
    {
      "symbol": "SOL",
      "mint": "So11111111111111111111111111111111111111112",
      "maxLeverage": 250,
      "targetRatio": 0.26,
      "currentWeight": 0.25,
      "utilizationPct": 35.2,
      "guaranteedUsd": "125000000",
      "globalShortSizes": "45000000"
    },
    {
      "symbol": "ETH",
      "mint": "7vfCXTUXx5WJV5JADk17DUJ4ksgau7utNKj4b963voxs",
      "maxLeverage": 200,
      "targetRatio": 0.11,
      "currentWeight": 0.10,
      "utilizationPct": 28.5
    },
    {
      "symbol": "BTC",
      "mint": "3NZ9JMVBmGAqocybic2c7LQCJScmgsAZ6vQqTDzcqmJh",
      "maxLeverage": 200,
      "targetRatio": 0.11,
      "currentWeight": 0.12,
      "utilizationPct": 42.1
    }
  ]
}

Get Trade History

GET /trading/trade-history

Get trade history for a specific wallet. Cached for 60 seconds.

Query Parameters

Parameter Type Required Description
wallet string Required Solana wallet address
start integer Optional Pagination start index (default: 0)
end integer Optional Pagination end index (default: 100)
action string Optional Filter by action: Open, Increase, Decrease, etc.
side string Optional Filter by side: Long or Short
mint string Optional Filter by token mint address

Example Response

{
  "success": true,
  "dataList": [
    {
      "txHash": "5abc123...",
      "createdTime": 1702567200,
      "action": "Increase",
      "side": "Long",
      "positionName": "SOL-PERP",
      "size": 25000.00,
      "collateralUsdDelta": 3000.00,
      "price": 187.50,
      "pnl": null,
      "fee": 25.00,
      "baseFee": 20.00,
      "borrowFee": 5.00,
      "priceImpactFee": 0.50,
      "orderType": "Market"
    }
  ],
  "count": 1
}
POST /trading/add-collateral ELITE

Add collateral to an existing position without increasing the position size. Useful for reducing leverage or avoiding liquidation.

Request Body

Parameter Type Required Description
owner string Required Your wallet public key
positionPubkey string Required Position account public key
collateralUsd number Required Amount of collateral to add in USD
inputMint string Optional Input token (USDC, SOL, etc.). Default: USDC
slippageBps integer Optional Max slippage in basis points (default: 100)

Example Response

{
  "success": true,
  "transaction": "base64_encoded_transaction...",
  "message": "Transaction ready for signing"
}
POST /trading/withdraw-collateral ELITE

Withdraw collateral from an existing position without closing any of the position size. Increases effective leverage.

Request Body

Parameter Type Required Description
owner string Required Your wallet public key
positionPubkey string Required Position account public key
collateralUsd number Required Amount of collateral to withdraw in USD
outputMint string Optional Output token (USDC, SOL, etc.). Default: USDC
slippageBps integer Optional Max slippage in basis points (default: 100)

Example Response

{
  "success": true,
  "transaction": "base64_encoded_transaction...",
  "message": "Transaction ready for signing"
}
GET /trading/expired-orders ELITE

Get expired limit orders (position requests) for a wallet. Returns transactions to close expired orders and recover locked collateral.

Query Parameters

Parameter Type Required Description
wallet string Required Solana wallet address

Example Response

{
  "success": true,
  "expiredOrders": [
    {
      "positionRequestPubkey": "ABC123...",
      "createdAt": 1702567200,
      "collateralUsd": 100.00,
      "closeTransaction": "base64_encoded_transaction..."
    }
  ]
}
GET /trading/collateral-limits ELITE

Get the minimum and maximum collateral deposit/withdrawal limits for a specific position. Useful for validating collateral operations before submitting.

Query Parameters

Parameter Type Required Description
positionPubkey string Required Position account public key
inputMint string Optional Input token mint address. Default: USDC

Example Response

{
  "success": true,
  "limits": {
    "minDepositUsd": 1.00,
    "maxDepositUsd": 100000.00,
    "minWithdrawUsd": 1.00,
    "maxWithdrawUsd": 5000.00
  }
}

WebSocket Real-Time Trade Alerts

Connect to our WebSocket server for instant trade alerts from your watchlist. Get real-time notifications when tracked wallets open, close, or modify positions.

Connection

wss://perpstracker.com:5001/ws/alerts

Authentication

After connecting, send an authentication message with your API key:

{ "type": "auth", "apiKey": "YOUR_API_KEY" }

Authentication Response

// Success
{
  "type": "auth_success",
  "plan": "elite",
  "watchedWallets": 95,
  "message": "Subscribed to 95 wallets with alerts enabled"
}

// Error
{
  "type": "auth_error",
  "message": "Elite subscription required for WebSocket alerts"
}

Trade Alert Message

When a watched wallet executes a trade, you'll receive: 

{
  "type": "trade",
  "wallet": "9B5XsNQyBE8KmV7nP3zLwTcXf2dRjHqYbJgDqKMT4xZp5WvNsE6rUhAoCyF8",
  "wallet_short": "9B5X...4xZp",
  "token": "SOL",
  "side": "LONG",
  "action": "OPEN",
  "size_usd": 25000.00,
  "collateral_usd": 3000.00,
  "leverage": 8.33,
  "price": 187.50,
  "pnl_usd": null,
  "tx_signature": "5GHqt7RvPnL2cYsW9xTmKjN8bDfVhXzQgE4wJpMk3dZr6HqYtNvBcX8sLmRpTn2V",
  "timestamp": 1702567200000
}

Message Types

Type Description
connected Initial connection acknowledgment
auth_success Authentication successful, subscribed to watchlist
auth_error Authentication failed (invalid key or not Elite)
trade Real-time trade alert from watched wallet
pong Response to ping message (heartbeat)

Trade Actions

Action Description
OPEN New position opened
CLOSE Position fully closed
INCREASE Position size increased
REDUCE Position size reduced (partial close)

JavaScript Example

const ws = new WebSocket('wss://perpstracker.com:5001/ws/alerts'); ws.onopen = () => { ws.send(JSON.stringify({ type: 'auth', apiKey: 'YOUR_API_KEY' })); }; ws.onmessage = (event) => { const data = JSON.parse(event.data); if (data.type === 'trade') { console.log(`Trade Alert: ${data.action} ${data.side} ${data.token}`); console.log(`Size: $${data.size_usd} @ ${data.leverage}x`); } }; // Keep connection alive with ping setInterval(() => { if (ws.readyState === WebSocket.OPEN) { ws.send(JSON.stringify({ type: 'ping' })); } }, 30000);

Python Example

import websocket import json def on_message(ws, message): data = json.loads(message) if data['type'] == 'trade': print(f"Trade: {data['action']} {data['side']} {data['token']}") print(f"Size: ${data['size_usd']} @ {data['leverage']}x") def on_open(ws): ws.send(json.dumps({ 'type': 'auth', 'apiKey': 'YOUR_API_KEY' })) ws = websocket.WebSocketApp( 'wss://perpstracker.com:5001/ws/alerts', on_message=on_message, on_open=on_open ) ws.run_forever()

Copytrader Integration

The official Python and TypeScript copytraders use WebSocket alerts by default for real-time trade execution. When a watched wallet trades, your copytrader receives the alert instantly and can execute the same trade within seconds.

Performance Note: WebSocket alerts are significantly faster than polling the API. Typical latency is under 500ms from on-chain transaction to alert delivery.

Webhooks (Elite)

Set up webhooks to receive real-time HTTP POST notifications when trades occur. Perfect for server-to-server integrations, serverless functions, and third-party service integrations (Discord, Slack, etc.).

Supported Events

  • trade.new - New position opened or increased
  • trade.close - Position closed or decreased
  • trade.liquidation - Position was liquidated

Creating a Webhook

POST /api/webhooks

Create a new webhook endpoint. The secret will only be shown once - save it securely!

Request Body

{ "url": "https://your-server.com/webhook", "events": ["trade.new", "trade.close"] }

Example Request

curl -X POST -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"url": "https://your-server.com/webhook", "events": ["trade.new"]}' \ https://perpstracker.com:5001/api/webhooks

Example Response

{
  "success": true,
  "webhook": {
    "id": "whk_abc123...",
    "url": "https://your-server.com/webhook",
    "events": ["trade.new"],
    "secret": "whsec_xyz789..."
  },
  "message": "Webhook created. Save your secret - it will only be shown once!"
}

List Webhooks

GET /api/webhooks

List all your configured webhooks with stats.

Example Response

{
  "webhooks": [{
    "id": "whk_abc123...",
    "url": "https://your-server.com/webhook",
    "events": ["trade.new"],
    "is_active": true,
    "created_at": "2025-12-14T09:00:00Z",
    "success_count": 150,
    "failure_count": 2
  }],
  "count": 1,
  "max_webhooks": 3
}

Delete Webhook

DELETE /api/webhooks/{webhook_id}

Test Webhook

POST /api/webhooks/{webhook_id}/test

Send a test event to verify your webhook endpoint is working correctly.

Webhook Payload

When a trade event occurs, PerpsTracker sends a POST request to your webhook URL with the following payload: 

{
  "event": "trade.new",
  "created_at": "2025-12-14T16:30:00.000Z",
  "data": {
    "wallet": "DRVRvzf8pSiMJi5BY1NmZu5STahBYKMVcfkPp3vxPump",
    "token": "SOL",
    "side": "LONG",
    "action": "Open Long",
    "size_usd": 25000.00,
    "collateral_usd": 3000.00,
    "leverage": 8.33,
    "entry_price": 185.50,
    "pnl_usd": null,
    "transaction_signature": "5GHqt7RvPnL2cYsW9xTmKjN8bDfVhXzQgE4wJpMk3dZr6HqYtNvBcX8sLmRpTn2V",
    "timestamp": "2025-12-14T16:30:00.000Z"
  }
}

Verifying Webhook Signatures

All webhook deliveries include an HMAC-SHA256 signature in the X-Webhook-Signature header. Verify this signature using your webhook secret to ensure the request came from PerpsTracker.

# Headers included in every webhook request: X-Webhook-Signature: sha256=abc123... X-Webhook-Timestamp: 1702567800000 X-Webhook-Id: whk_abc123... # Node.js signature verification example: const crypto = require('crypto'); function verifyWebhookSignature(payload, signature, secret) { const expected = 'sha256=' + crypto .createHmac('sha256', secret) .update(JSON.stringify(payload)) .digest('hex'); return crypto.timingSafeEqual( Buffer.from(signature), Buffer.from(expected) ); }
Best Practices:
  • Always verify the webhook signature before processing
  • Respond with 2xx status within 10 seconds to avoid retries
  • Webhooks retry up to 3 times on failure (1s, 5s, 30s delays)
  • Use HTTPS endpoints only (required for security)

Telegram Integration

Receive real-time trade alerts directly in Telegram when traders on your watchlist open or close positions.

Setup Instructions

  1. Find our bot: @PerpsTrackerBot on Telegram
  2. Start a conversation with the bot
  3. Use command: /connect YOUR_API_KEY to link your account
  4. Enable alerts on traders in your watchlist via the dashboard or API
  5. Receive instant notifications when those traders make trades
API Endpoints:

To manage alerts programmatically, see the Watchlist Management section for endpoints like Toggle Alerts, Bulk Toggle Alerts, and Alerted Trades.

API Key Management

API keys must be managed through the website dashboard.

To generate, view, or revoke your API key, please visit your account dashboard. Elite users are limited to one API key at a time for security purposes.

Error Handling

HTTP Status Codes

Status Code Meaning
200 Success
400 Bad Request - Invalid parameters
401 Unauthorized - Invalid or missing API key
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error

Error Response Format

{
  "error": "Invalid timeframe parameter",
  "code": "INVALID_PARAMETER",
  "details": "Timeframe must be one of: 24h, 7d, 30d, 365d",
  "timestamp": "2025-11-14T16:30:00Z"
}

Code Examples

Python

import requests API_KEY = "your_api_key_here" BASE_URL = "https://perpstracker.com/api" headers = { "Authorization": f"Bearer {API_KEY}" } # Get 24h leaderboard response = requests.get( f"{BASE_URL}/perpetuals/leaderboard/24h", headers=headers, params={"limit": 10} ) data = response.json() for trader in data["data"]: print(f"Rank {trader['rank']}: {trader['wallet_address']}") print(f" PnL: ${trader['total_pnl']:,.2f}")

JavaScript (Node.js)

const axios = require('axios'); const API_KEY = 'your_api_key_here'; const BASE_URL = 'https://perpstracker.com/api'; const headers = { 'Authorization': `Bearer ${API_KEY}` }; // Get live trades from top 10 traders async function getLiveTrades() { const response = await axios.get( `${BASE_URL}/perpetuals/live-trades`, { headers, params: { leaderboard: '24h', rank: 10, limit: 50 } } ); response.data.trades.forEach(trade => { console.log(`${trade.wallet_address} opened ${trade.is_long ? 'LONG' : 'SHORT'} ${trade.token}`); console.log(` Size: $${trade.size.toFixed(2)} @ ${trade.leverage}x leverage`); }); } getLiveTrades();

Need Help?

Our support team is here to help you integrate the API

Visit FAQ Full Documentation