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

Subscribe to the Elite plan
Log in to your account dashboard at perpstracker.com/dashboard
Navigate to Settings → API
Click "Generate API Key"
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/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
}

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 COMING SOON

Receive alerts directly in Telegram for instant notifications.

Setup Instructions

Find our bot: @PerpsTrackerBot on Telegram
Start a conversation with the bot
Use command: /connect YOUR_API_KEY
Configure alerts using dashboard or API
Receive instant notifications in Telegram

Setting Up Alerts via API

                    curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
  "type": "trade_alert",
  "telegram_enabled": true,
  "conditions": {
    "wallets": ["9B5XsN...DqKMT"],
    "min_size": 50000,
    "tokens": ["SOL", "BTC"]
  }
}' \
     https://perpstracker.com/api/alerts
                

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