# Nansen Hyperliquid Perpetual Trades

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

Retrieve individual perpetual contract trade records for a specific token on Hyperliquid, with detailed trader, side, action, order type, and trade metrics.

## Facts

- Endpoint: POST https://api.nansen.ai/api/v1/tgm/perp-trades?utm_source=zero.xyz
- Price: $0.01/call
- Payment: MPP
- Status: unknown
- Last checked: 2026-10-09
- Activations on Zero: 0
- Provider: Nansen
- Docs: https://docs.nansen.ai
- Website: https://nansen.ai
- Tags: blockchain, smart-money, wallet, tokens, defi, analytics, profiler, dex, pnl, onchain, prediction-market, data
- Canonical page: https://www.zero.xyz/c/nansen-perp-trades-37c5e695
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_nct52zolkssh-vibYOayY

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-perp-trades-37c5e695 -d '<json body>'
```

Example prompt: Pull all Hyperliquid perpetual trades for BTC from January 1 to January 31, 2025, filtering for Long side only and showing just the Open and Add actions — I want to see which wallets were entering new long positions.

## When to prefer this

Use this endpoint when you need granular, individual perpetual trade records on Hyperliquid for a specific token, especially when you need to track specific trader addresses, filter by position side (Long/Short), action type (Open/Close/Add/Reduce), or order type (Market/Limit). Prefer this over Position Intelligence when you need raw trade-level data rather than aggregated position analytics.

## Known failure modes

- Missing required token_symbol or date fields returns 400 validation error
- Invalid token symbol not traded on Hyperliquid returns empty data array
- Date range too broad may result in timeout or truncated results
- Invalid enum value for side or action filter returns 422 unprocessable entity
- Pagination beyond available pages returns empty data with correct pagination metadata

## How this service works

Retrieve perpetual trade data for a specific token on Hyperliquid. Shows individual trades with detailed information including trader address, trade side (Long/Short), action type (Add/Reduce/Open/Close), order type (Market/Limit), and trade metrics.

**Key Features:**
- Hyperliquid perpetual contracts only
- Smart money filtering capabilities
- Detailed trade breakdown with parsed action fields
- Support for both Long and Short position trading
- Market and Limit order types

**Request Parameters:**
- `token_symbol`: Token symbol to fetch trades for (e.g., "BTC", "ETH")
- `date`: Date range for the trades
- `filters`: Additional filters for side, action, order_type, etc.
- `pagination`: Page and per_page parameters

## Output

Returns a paginated list of individual perpetual trade records, each containing the trader's wallet address, position side (Long/Short), action (Add/Reduce/Open/Close), order type (MARKET/LIMIT), average fill price in USD, trade value in USD, token amount, token symbol, block timestamp, and a representative transaction hash.

## 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-perp-trades-37c5e695/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)