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 /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-11-29T01:15:05.000Z",
  "market": {
    "total_volume_24h": 96101296.08,
    "total_pnl_24h": 302339.83,
    "total_trades_24h": 3660,
    "active_traders_24h": 185,
    "avg_leverage": 203.86,
    "sentiment": {
      "indicator": "Bullish",
      "long_ratio": 71,
      "short_ratio": 29,
      "long_volume": 58036778.44,
      "short_volume": 27755761.60
    },
    "top_tokens": [
      {"token": "WSOL", "volume": 94854143.58, "percentage": 69.15},
      {"token": "WBTC", "volume": 22941904.21, "percentage": 16.72}
    ],
    "preview": {
      "traders_in_24h": 415,
      "traders_in_7d": 1248,
      "traders_in_30d": 1332
    },
    "traders_active_now": 339
  }
}
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": "7osRjdF...PikD",
      "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. Requires Elite subscription.

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": "E4DsbK...myk",
      "position_key": "CgWruN...xy9h",
      "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": "7Kj2ab...LMn",
      "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

{
  "data": [
    {
      "rank": 1,
      "wallet_address": "9B5XsN...DqKMT",
      "total_pnl": 125430.50,
      "total_volume": 2450000.00,
      "win_rate": 68.5,
      "roi": 42.3,
      "sharpe_ratio": 2.45,
      "avg_leverage": 8.2,
      "total_trades": 156
    }
  ],
  "stats": {
    "total_traders": 283,
    "total_volume": 45250000.00,
    "total_pnl": 1250000.00
  },
  "timeframe": "24h",
  "timestamp": "2025-11-14T16:30:00Z"
}
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

{
  "trades": [
    {
      "wallet_address": "9B5XsN...DqKMT",
      "signature": "5GHqt7...mK3d",
      "timestamp": "2025-11-14T16:25:33Z",
      "instruction_type": "instantIncreasePosition",
      "token": "SOL",
      "is_long": true,
      "size": 25000.00,
      "collateral_value": 3000.00,
      "leverage": 8.33,
      "fee": 0.000025
    }
  ],
  "total": 139,
  "limit": 50,
  "offset": 0
}
GET /perpetuals/trader/{wallet}

Get comprehensive performance data for a specific trader across all timeframes.

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/9B5XsN...DqKMT

Example Response

{
  "wallet_address": "9B5XsN...DqKMT",
  "timeframes": {
    "24h": {
      "rank": 1,
      "total_pnl": 125430.50,
      "win_rate": 68.5,
      "roi": 42.3,
      "sharpe_ratio": 2.45,
      "total_trades": 156
    },
    "7d": {
      "rank": 3,
      "total_pnl": 450230.75,
      "win_rate": 65.2,
      "roi": 38.7,
      "sharpe_ratio": 2.18,
      "total_trades": 642
    }
  },
  "updated_at": "2025-11-14T16:30:00Z"
}
GET /perpetuals/consistent-traders

Get traders who appear in all timeframes, indicating consistent performance.

Example Request

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

Example Response

{
  "traders": [
    {
      "wallet": "9B5XsN...DqKMT",
      "avg_rank": 5.25,
      "avg_score": 92.3,
      "total_pnl": 1250430.50,
      "timeframes": {
        "24h": { "rank": 1 },
        "7d": { "rank": 3 },
        "30d": { "rank": 8 },
        "365d": { "rank": 9 }
      }
    }
  ],
  "count": 42
}
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/9B5XsN...DqKMT/trades?limit=20

Example Response

{
  "trades": [
    {
      "signature": "5GHqt7...mK3d",
      "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": "9B5XsN...DqKMT",
  "count": 20
}
GET /perpetuals/trader/{wallet}/positions

Get current open positions for a specific trader.

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/9B5XsN...DqKMT/positions

Example Response

{
  "positions": [
    {
      "token": "SOL",
      "side": "long",
      "size_usd": 50000.00,
      "collateral_usd": 5000.00,
      "leverage": 10.0,
      "entry_price": 195.50,
      "mark_price": 198.25,
      "pnl_usd": 700.00,
      "pnl_percent": 14.0,
      "opened_at": "2025-11-28T08:15:00Z"
    }
  ],
  "wallet": "9B5XsN...DqKMT",
  "count": 1
}
GET /perpetuals/trader/{wallet}/history PRO+

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/9B5XsN...DqKMT/history?start=0&limit=20"

Example Response

{
  "history": [
    {
      "token": "SOL",
      "side": "long",
      "size_usd": 50000.00,
      "entry_price": 185.00,
      "exit_price": 195.50,
      "pnl_usd": 2837.84,
      "pnl_percent": 5.68,
      "opened_at": "2025-11-25T10:30:00Z",
      "closed_at": "2025-11-27T14:45:00Z",
      "duration_hours": 52.25
    }
  ],
  "wallet": "9B5XsN...DqKMT",
  "total": 156,
  "start": 0,
  "limit": 20
}
GET /perpetuals/compare PRO+

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=9B5XsN...DqKMT,7Kj2ab...HqLMn&timeframe=30d"

Example Response

{
  "comparison": [
    {
      "wallet": "9B5XsN...DqKMT",
      "rank": 3,
      "total_pnl": 125430.50,
      "win_rate": 68.5,
      "roi": 42.3,
      "total_trades": 156
    },
    {
      "wallet": "7Kj2ab...HqLMn",
      "rank": 12,
      "total_pnl": 89230.25,
      "win_rate": 62.1,
      "roi": 31.8,
      "total_trades": 203
    }
  ],
  "timeframe": "30d"
}
GET /perpetuals/positions/all ELITE

Get all currently open positions across all tracked traders.

Query Parameters

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

Example Request

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

Example Response

{
  "positions": [
    {
      "wallet": "9B5XsN...DqKMT",
      "token": "SOL",
      "side": "long",
      "size_usd": 150000.00,
      "leverage": 10.0,
      "entry_price": 195.50,
      "pnl_usd": 2100.00,
      "opened_at": "2025-11-30T08:15:00Z"
    }
  ],
  "total": 234,
  "limit": 50
}

Webhooks (Elite) COMING SOON

Set up webhooks to receive real-time notifications when specific events occur.

Supported Events

  • trade.new - New trade from tracked wallet
  • trader.rank_change - Trader moved significantly in rankings
  • trader.new_leader - New trader entered top 10
  • alert.triggered - Custom alert condition met

Creating a Webhook

POST /webhooks

Request Body

{ "url": "https://your-server.com/webhook", "events": ["trade.new", "trader.rank_change"], "filters": { "wallets": ["9B5XsN...DqKMT"], "min_position_size": 10000 } }

Webhook Payload Example

{
  "event": "trade.new",
  "timestamp": "2025-11-14T16:30:00Z",
  "data": {
    "wallet_address": "9B5XsN...DqKMT",
    "signature": "5GHqt7...mK3d",
    "type": "OPEN",
    "side": "LONG",
    "token": "SOL",
    "size": 25000.00,
    "leverage": 8.33
  }
}

Telegram Integration ELITE

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

Toggle Alerts for Watchlist Trader

POST /perpetuals/watchlist/{wallet}/alerts

Enable or disable Telegram alerts for a specific trader on your watchlist.

Path Parameters

Parameter Type Required Description
wallet string Required Wallet address of the trader to toggle alerts for

Example Request

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \ https://perpstracker.com/api/perpetuals/watchlist/9B5XsN...DqKMT/alerts

Example Response

{
  "success": true,
  "wallet": "9B5XsN...DqKMT",
  "alerts_enabled": true,
  "message": "Alerts enabled for trader"
}

Get Alert Trades

GET /perpetuals/watchlist/alerts/trades

Get recent trades from all watchlisted traders with alerts enabled. Used by the Telegram bot to send notifications.

Query Parameters

Parameter Type Default Description
since integer - Unix timestamp (seconds) - only return trades after this time

Example Request

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

Example Response

{
  "trades": [
    {
      "wallet_address": "9B5XsN...DqKMT",
      "signature": "5GHqt7...mK3d",
      "timestamp": "2025-11-30T12:30:00Z",
      "instruction_type": "instantIncreasePosition",
      "token": "SOL",
      "is_long": true,
      "size": 25000.00,
      "collateral_value": 3000.00,
      "leverage": 8.33,
      "notes": "Whale trader"
    }
  ],
  "count": 1
}

Update Watchlist Notes

PATCH /perpetuals/watchlist/{wallet}/notes PRO+

Update the notes for a trader on your watchlist. Notes are included in trade alerts and help you identify traders.

Path Parameters

Parameter Type Required Description
wallet string Required Wallet address of the trader to update notes for

Request Body

{ "notes": "Whale trader - high win rate on SOL" }

Example Request

curl -X PATCH -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"notes": "Whale trader - high win rate on SOL"}' \ https://perpstracker.com/api/perpetuals/watchlist/9B5XsN...DqKMT/notes

Example Response

{
  "success": true,
  "wallet": "9B5XsN...DqKMT",
  "notes": "Whale trader - high win rate on SOL"
}

API Key Management ELITE

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.

Watchlist Management PRO+

Manage your trader watchlist programmatically.

Get Watchlist

GET /perpetuals/watchlist

Get all traders on your watchlist with their current performance metrics.

Example Response

{
  "watchlist": [
    {
      "wallet_address": "9B5XsN...DqKMT",
      "notes": "Whale trader - high win rate",
      "alerts_enabled": true,
      "added_at": "2025-11-25T10:30:00Z",
      "performance": {
        "total_pnl": 125430.50,
        "win_rate": 68.5,
        "rank": 3
      }
    }
  ],
  "count": 1
}

Add to Watchlist

POST /perpetuals/watchlist/add

Add a trader to your watchlist.

Request Body

{ "wallet": "9B5XsN...DqKMT", "notes": "Top SOL trader" }

Remove from Watchlist

DELETE /perpetuals/watchlist/{wallet}

Remove a trader from your watchlist.

Check Watchlist Status

GET /perpetuals/watchlist/check/{wallet}

Check if a trader is on your watchlist.

Example Response

{
  "isWatched": true,
  "wallet": "9B5XsN...DqKMT",
  "notes": "Whale trader",
  "alerts_enabled": true
}

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