# Nansen Smart Money Perpetual Trades

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

Retrieves perpetual futures trade data from smart money wallets tracked by Nansen, with filtering and pagination support

## Facts

- Endpoint: GET https://api.nansen.ai/api/v1/smart-money/perp-trades
- Price: $0.05/call
- Payment: MPP, x402
- Status: unknown
- Last checked: 2026-09-13
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/api-nansen-ai-70f70cb4
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_b653Kq2YAvN9hhYXU7TQu

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 api-nansen-ai-70f70cb4
```

Example prompt: Show me the most recent perpetual trades made by Nansen smart money wallets — only include new position openings (Open Long and Open Short), sorted by most recent first, and give me the first page of results.

## When to prefer this

Use this endpoint when you need aggregated smart money perpetual trade activity across wallets tracked by Nansen — ideal for on-chain trading signal research, momentum analysis, or monitoring what sophisticated crypto traders are doing in perp markets. Prefer over the token-specific Perp Trades endpoint when you want a broad cross-asset view of smart money perp activity rather than trades for a single token.

## Known failure modes

- Invalid filter columns return 400 error — only selectable columns can be filtered
- Malformed pagination parameters may return empty or error responses
- Unsupported order_by column names cause query failures
- Missing or invalid API key returns 401 unauthorized
- Rate limit exceeded returns 429 too many requests
- Requesting premium labels without appropriate subscription tier may return downgraded label data

## How this service works

Get Smart Money Perpetual Trades Data

## Output

A list of perpetual futures trade records from smart money wallets, including trade direction (long/short), position action type, timestamps, and wallet/entity labels. Results can be filtered, sorted, and paginated, with optional premium label tier data.

## Example request

```json
{
 "filters": {
  "token_symbol": "BTC",
  "include_smart_money_labels": [
   "Smart HL Perps Trader"
  ]
 },
 "order_by": [
  {
   "field": "block_timestamp",
   "direction": "DESC"
  }
 ],
 "pagination": {
  "page": 1,
  "per_page": 50
 },
 "only_new_positions": true
}
```

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "title": "SmartMoneyPerpTradesRequest",
 "properties": {
  "filters": {
   "anyOf": [
    {
     "type": "object",
     "title": "SmartMoneyPerpTradesFilters",
     "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"
       ],
       "description": "Position side filter - Long or Short"
      },
      "type": {
       "anyOf": [
        {
         "enum": [
          "Market",
          "Limit"
         ],
         "type": "string",
         "title": "TradeType",
         "description": "Enum for trade types."
        }
       ],
       "examples": [
        "Market",
        "Limit"
       ],
       "description": "Trade type filter - Market or Limit"
      },
      "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 - Close Long"
          ],
          "type": "string",
          "title": "PerpActionType",
          "description": "Shared enum for perpetual trade action types (combined buy/sell with position actions)."
         }
        },
        {
         "type": "null"
        }
       ],
       "title": "Action",
       "examples": [
        "Buy - Add Long",
      
… (truncated)
```

## Response schema (JSON Schema)

```json
{
 "type": "object",
 "title": "SmartMoneyPerpTradesResponse",
 "required": [
  "data",
  "pagination"
 ],
 "properties": {
  "data": {
   "type": "array",
   "items": {
    "type": "object",
    "title": "SmartMoneyPerpTrade",
    "required": [
     "trader_address_label",
     "trader_address",
     "token_symbol",
     "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": "TradeType",
      "description": "Enum for trade types."
     },
     "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",
      "description": "Trade price in USD"
     },
     "value_usd": {
      "anyOf": [
       {
        "type": "number"
       }
      ],
      "title": "Value Usd",
      "description": "Notional trade value in USD"
     },
     "token_amount": {
      "anyOf": [
       {
        "type": "number"
       }
      ],
      "title": "Token Amount",
      "description": "Trade size in contract units"
     },
     "token_symbol": {
      "type": "string",
      "title": "Token Symbol",
      "description": "The token symbol"
     },
     "trader_address": {
      "type": "string",
      "title": "Trader Address",
      "description": "Hexadecimal representation of the trader's address, i.e. the signer of the transaction"
     },
     "block_timestamp": {
      "type": "string",
      "title": "Block Timestamp",
      "description": "The timestamp of the block"
     },
     "transaction_hash": {
      "type": "string",
      "title": "Transaction Hash",
      "description": "Hexadecimal representation of the transaction hash"
     },
     "trader_address_label": {
      "type": "string",
      "title": "Trader Address Label",
      "description": "
… (truncated)
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/api-nansen-ai-70f70cb4/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)