MPPtempoquality 0.82

Perpetual trading history for a token on Hyperliquid via Nansen's Token God Mode analytics

Price
$0.01 / call
Protocol
mpp
Verified
no
Endpoint
https://api.nansen.ai/api/v1/tgm/perp-trades

What it does

This endpoint retrieves perpetual trade data for a specific token on Hyperliquid through Nansen's Token God Mode (TGM) suite. It returns individual trade records including trader address, trade side (Long/Short), action type (Add/Reduce/Open/Close), order type (Market/Limit), price, size, value in USD, and transaction hash. The data covers smart money and all traders on Hyperliquid perpetual contracts.

The endpoint accepts POST requests with a JSON body specifying the token symbol (e.g., "BTC", "ETH"), a date range, optional filters (by trader address, side, action, order type, smart money labels, price/value ranges), pagination, and sort order. Responses include paginated trade records with rate-limit and credit-usage headers. The endpoint costs $0.01 per call via x402 protocol, or 10 credits (free tier) / 1 credit (pro tier) with an API key.

Nansen's API is documented via OpenAPI 3.1.0 and supports authentication via API key or x402 pay-per-request. The perp trades endpoint is part of a broader suite covering smart money analytics, wallet profiling, token flows, prediction markets, and more across 25+ chains.

Capabilities

perpetual-tradeshyperliquid-perpstoken-god-modesmart-money-filteringtrade-historylong-short-positionsmarket-limit-orderspaginationsortingdate-range-filtering

Use cases

  • —Track all perpetual trades for a specific token on Hyperliquid within a date range
  • —Filter perpetual trades by smart money labels to see what sophisticated traders are doing
  • —Analyze Long vs Short trade activity and Open/Close patterns for a token
  • —Monitor large-value perpetual trades by setting USD value filters
  • —Build trading signals from real-time perp trade flow data

Fit

Best for

  • —Crypto traders monitoring Hyperliquid perpetual contract activity
  • —Quant researchers analyzing derivatives trade flow by token
  • —Smart money tracking for perpetual futures positions
  • —Building dashboards showing perp trade activity for specific assets

Not for

  • —Spot/DEX trade data (use /tgm/dex-trades instead)
  • —Historical perp data beyond Hyperliquid (only Hyperliquid is supported)
  • —Real-time streaming trades (this is a polling/REST endpoint)

Quick start

curl -X POST https://api.nansen.ai/api/v1/tgm/perp-trades \
  -H 'Content-Type: application/json' \
  -H 'apiKey: YOUR_API_KEY' \
  -d '{
    "token_symbol": "BTC",
    "date": {"from": "2025-01-01T00:00:00Z", "to": "2025-01-02T23:59:59Z"},
    "pagination": {"page": 1, "per_page": 10}
  }'

Example

Request

{
  "date": {
    "to": "2025-01-02T23:59:59Z",
    "from": "2025-01-01T00:00:00Z"
  },
  "filters": {
    "side": "Long",
    "order_type": [
      "MARKET"
    ]
  },
  "order_by": [
    {
      "field": "block_timestamp",
      "direction": "DESC"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 10
  },
  "token_symbol": "BTC"
}

Response

{
  "data": [
    {
      "side": "Long",
      "type": "MARKET",
      "action": "Add",
      "price_usd": 95000,
      "value_usd": 47500,
      "token_amount": 0.5,
      "token_symbol": "BTC",
      "trader_address": "0x28c6c06298d514db089934071355e5743bf21d60",
      "block_timestamp": "2025-01-02T18:30:00Z",
      "transaction_hash": "0xabc123...",
      "trader_address_label": "Smart Money"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "is_last_page": false
  }
}

Endpoint

URLhttps://api.nansen.ai/api/v1/tgm/perp-trades
Transporthttp
Protocolmpp
CurrencypathUSD

Quality

0.82/ 1.00

Full OpenAPI 3.1.0 schema with detailed endpoint description, request/response models, filters, sort fields, and pricing info. The probe returned 401 (not 402) so the MPP payment challenge was not confirmed, but the OpenAPI spec explicitly documents x402 support at $0.01/call. The origin root returns 200 with {"message":"ok"}, confirming the API is live.

Warnings

  • —Probe returned 401 (Unauthorized) rather than 402 on HEAD/GET — the endpoint requires POST method and may need API key or x402 payment header to trigger the 402 challenge
  • —No direct crawl of Nansen documentation site was available; all info derived from OpenAPI spec
  • —Only Hyperliquid perpetual contracts are supported — no other perp exchanges

Citations

Provenance

Indexed frommpp_dev
Enriched2026-04-19 15:50:38Z · anthropic/claude-opus-4.6 · v2
First seen2026-04-18
Last seen2026-04-22

Agent access

JSONhttps://clawmart.sh/api/listings/yLQj8k