# Nansen Hyperliquid Perpetual Trades

> Nansen Hyperliquid Perpetual Trades is a paid API for AI agents from api.nansen.ai, paid per call via MPP or x402, $0.01/call, status unknown (last checked 2026-09-13).

Retrieves individual perpetual contract trade data for a specific token on Hyperliquid, with smart money filtering and detailed trade breakdowns.

## Facts

- Endpoint: GET https://api.nansen.ai/api/v1/tgm/perp-trades
- Price: $0.01/call
- Payment: MPP, x402
- Status: unknown
- Last checked: 2026-09-13
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/nansen-9e374dad
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_3l--JvjgBWauCdcxTkfO6

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability nansen-9e374dad
```

Example prompt: Pull all the BTC perpetual trades on Hyperliquid from the last 24 hours where smart money wallets were opening long positions using market orders — show me trader addresses and trade metrics.

## When to prefer this

Use this endpoint when you need granular, trade-level data for Hyperliquid perpetual contracts — specifically when you want to track individual trader behavior, filter by smart money, or analyze position actions (open/close/add/reduce) for a specific token. Prefer this over broader flow analytics endpoints when you need per-trade detail rather than aggregate flows.

## Known failure modes

- Invalid token symbol returns empty results or error
- Date range too broad may hit pagination limits or timeout
- Unsupported filter values (invalid side/action/order_type enum) return validation error
- Token not listed on Hyperliquid perpetuals returns no data
- Missing required token_symbol parameter returns 400 error
- Rate limiting if too many requests are made in quick succession

## How this service works

Get "Token God Mode" (TGM) perp trades data

## Output

A paginated list of individual perpetual trade records from Hyperliquid, each containing the trader wallet address, trade side (Long/Short), action type (Add/Reduce/Open/Close), order type (Market/Limit), and associated trade metrics like size and price for the requested token and date range.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "title": "TGMPerpTradesRequest",
 "required": [
  "token_symbol",
  "date"
 ],
 "properties": {
  "date": {
   "type": "object",
   "title": "DateRange",
   "properties": {
    "to": {
     "anyOf": [
      {
       "type": "string"
      }
     ],
     "title": "To",
     "examples": [
      "2025-01-31T23:59:59Z"
     ],
     "description": "End date in ISO 8601 format (e.g., 2025-01-31T23:59:59Z or 2025-01-31)"
    },
    "from": {
     "anyOf": [
      {
       "type": "string"
      }
     ],
     "title": "From",
     "examples": [
      "2025-01-01T00:00:00Z"
     ],
     "description": "Start date in ISO 8601 format (e.g., 2025-01-01T00:00:00Z or 2025-01-01)"
    }
   },
   "description": "Date range model matching the API schema."
  },
  "filters": {
   "anyOf": [
    {
     "type": "object",
     "title": "TGMPerpTradesFilters",
     "properties": {
      "side": {
       "anyOf": [
        {
         "enum": [
          "Long",
          "Short"
         ],
         "type": "string",
         "title": "PositionSide",
         "description": "Shared enum for position side direction."
        },
        {
         "type": "array",
         "items": {
          "enum": [
           "Long",
           "Short"
          ],
          "type": "string",
          "title": "PositionSide",
          "description": "Shared enum for position side direction."
         }
        },
        {
         "type": "null"
        }
       ],
       "title": "Side",
       "examples": [
        "Long",
        [
         "Short",
         "Long"
        ]
       ],
       "description": "Position side filter (Long or Short)"
      },
      "action": {
       "anyOf": [
        {
         "enum": [
          "Buy - Add Long",
          "Buy - Reduce Short",
          "Buy - Open Long",
          "Buy - Close Short",
          "Sell - Add Short",
          "Sell - Reduce Long",
          "Sell - Open Short",
          "Sell - Close Long"
         ],
         "type": "string",
         "title": "PerpActionType",
         "description": "Shared enum for perpetual trade action types (combined buy/sell with position actions)."
        },
        {
         "type": "array",
         "items": {
          "enum": [
           "Buy - Add Long",
           "Buy - Reduce Short",
           "Buy - Open Long",
           "Buy - Close Short",
           "Sell - Add Short",
           "Sell - Reduce Long",
           "Sell - Open Short",
           "Sell - Clos
… (truncated)
```

## Response schema (JSON Schema)

```json
{
 "type": "object",
 "title": "TGMPerpTradesResponse",
 "required": [
  "data",
  "pagination"
 ],
 "properties": {
  "data": {
   "type": "array",
   "items": {
    "type": "object",
    "title": "TGMPerpTrade",
    "required": [
     "trader_address",
     "action",
     "type",
     "block_timestamp",
     "transaction_hash"
    ],
    "properties": {
     "side": {
      "anyOf": [
       {
        "enum": [
         "Long",
         "Short"
        ],
        "type": "string",
        "title": "PositionSide",
        "description": "Shared enum for position side direction."
       }
      ],
      "examples": [
       "Long",
       "Short"
      ],
      "description": "The side of the position (Long or Short)"
     },
     "type": {
      "enum": [
       "MARKET",
       "LIMIT"
      ],
      "type": "string",
      "title": "OrderType",
      "description": "Order type."
     },
     "action": {
      "type": "string",
      "title": "Action",
      "examples": [
       "Add",
       "Reduce",
       "Open",
       "Close"
      ],
      "description": "The action taken by the trader (Add, Reduce, Open, Close)"
     },
     "price_usd": {
      "anyOf": [
       {
        "type": "number"
       }
      ],
      "title": "Price Usd",
      "examples": [
       60000
      ],
      "description": "Average fill price in USD across all fills in the trade, from exchange data."
     },
     "value_usd": {
      "anyOf": [
       {
        "type": "number"
       }
      ],
      "title": "Value Usd",
      "examples": [
       90000
      ],
      "description": "The value in USD"
     },
     "token_amount": {
      "anyOf": [
       {
        "type": "number"
       }
      ],
      "title": "Token Amount",
      "examples": [
       1.5
      ],
      "description": "The amount of the specified token traded"
     },
     "token_symbol": {
      "anyOf": [
       {
        "type": "string"
       }
      ],
      "title": "Token Symbol",
      "examples": [
       "BTC"
      ],
      "description": "The symbol of the token"
     },
     "trader_address": {
      "type": "string",
      "title": "Trader Address",
      "examples": [
       "0x28c6c06298d514db089934071355e5743bf21d60"
      ],
      "description": "The trader's address"
     },
     "block_timestamp": {
      "type": "string",
      "title": "Block Timestamp",
      "examples": [
       "2025-10-01T12:40:00Z"
      ],
      "description": "The block timestamp for the transaction"
  
… (truncated)
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/nansen-9e374dad/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from api.nansen.ai](https://www.zero.xyz/host/api.nansen.ai/llms.txt)