API Documentation

Access Hyperliquid TWAP trade data programmatically

Access trade data programmatically through our RESTful API endpoints.

GET/api/trades

Retrieve trade data with optional filters and pagination. Supports fetching all trades for a TWAP ID beyond the 1000 row limit via pagination.

Query Parameters:

twap_id - Filter by TWAP strategy ID

coin - Filter by coin symbol (e.g., BTC, ETH)

user - Filter by user address

side - Filter by side: A (ask/sell) or B (bid/buy)

start_time - Filter trades after this time (ISO 8601)

end_time - Filter trades before this time (ISO 8601)

limit - Number of results per page (default: 50, max: 1000)

offset - Pagination offset (default: 0)

include_participants - Include participant details (default: true)

Example:

curl "https://twaptracker.xyz/api/trades?twap_id=568722&limit=50&offset=0"

# Response
{
  "data": [
    {
      "id": 123,
      "coin": "BTC",
      "time": "2025-03-22T10:30:00.000Z",
      "px": 83917.0,
      "sz": 0.5,
      "hash": "0x123...",
      "participants": [
        {
          "user_address": "0xabc...",
          "side": "B",
          "twap_id": 568722,
          "oid": 12345
        }
      ]
    }
  ],
  "count": 5234,
  "limit": 50,
  "offset": 0
}

GET/api/twap/:id

Get all trades and statistics for a specific TWAP ID with pagination support.

Query Parameters:

limit - Number of results per page (default: 100, max: 100)

offset - Pagination offset (default: 0)

Example:

curl "https://twaptracker.xyz/api/twap/568722?limit=50&offset=0"

# Response
{
  "twap_id": 568722,
  "trades": [...],
  "count": 45,
  "total_participants": 90,
  "limit": 50,
  "offset": 0,
  "statistics": {
    "user_addresses": ["0xabc..."],
    "trade_count": 45,
    "unique_coins": 1,
    "coins": ["BTC"],
    "total_volume": 125.5,
    "total_value": 10543252.50,
    "avg_price": 83917.0,
    "min_price": 83500.0,
    "max_price": 84200.0,
    "first_trade_time": "2025-03-22T10:00:00.000Z",
    "last_trade_time": "2025-03-22T15:30:00.000Z",
    "duration_seconds": 19800
  }
}

GET/api/trades/summary

Get a summary of all unique TWAP orders for a wallet address, including aggregate statistics.

Query Parameters:

user - User wallet address (required)

Example:

curl "https://twaptracker.xyz/api/trades/summary?user=0xabc123..."

# Response
{
  "data": [
    {
      "twap_id": 568722,
      "address": "0xabc123...",
      "coin": "BTC",
      "side": "Buy",
      "trade_count": 45,
      "total_volume": 10543252.5067,
      "avg_price": 83917.2456
    }
  ],
  "count": 12,
  "stats": {
    "unique_twaps": 12,
    "total_trades": 543,
    "total_volume": 125432156.7890
  }
}

GET/api/trades/stats

Get aggregated trade statistics by coin with time-based filtering.

Query Parameters:

coin - Filter by specific coin (optional)

hours - Time range in hours (default: 24)

limit - Number of results per page (default: 100, max: 100)

offset - Pagination offset (default: 0)

Example:

curl "https://twaptracker.xyz/api/trades/stats?hours=24&limit=10"

# Response
{
  "data": [
    {
      "coin": "BTC",
      "trade_count": 1234,
      "min_price": 83500.0,
      "max_price": 84200.0,
      "avg_price": 83917.0,
      "total_volume": 567.89,
      "first_trade": "2025-11-05T10:00:00.000Z",
      "last_trade": "2025-11-06T09:59:59.000Z"
    }
  ],
  "count": 15,
  "limit": 10,
  "offset": 0,
  "time_range_hours": 24,
  "generated_at": "2025-11-06T10:00:00.000Z"
}

GET/api/leaderboard

Get the top TWAP traders ranked by total volume. Leaderboard data is cached and updated regularly.

Query Parameters:

limit - Number of entries to return (default: 10, max: 100)

Example:

curl "https://twaptracker.xyz/api/leaderboard?limit=10"

# Response
{
  "data": [
    {
      "rank": 1,
      "user_address": "0x1234...5678",
      "total_volume": 1234567.89,
      "total_trades": 5678,
      "unique_twaps": 234,
      "last_updated": "2025-11-07T10:00:00.000Z"
    }
  ],
  "count": 100,
  "last_updated": "2025-11-07T10:00:00.000Z"
}

GET/api/stats

Get general database statistics including total trades indexed and trader count. Cached for 5 minutes.

Query Parameters:

None - this endpoint requires no parameters

Example:

curl "https://twaptracker.xyz/api/stats"

# Response
{
  "max_trade_id": 73548026,
  "total_traders": 1234
}

⚡ Rate Limits & Notes

All endpoints return JSON responses
Timestamps are in ISO 8601 format (UTC)
Most endpoints support pagination with a maximum of 100 records per request
/api/trades supports up to 1000 records per request for larger batches
Use pagination (limit + offset) to fetch data beyond the per-page limits
No authentication required for read operations
CORS enabled for browser requests
Data coverage: Historical TWAP trades from Hyperliquid