# Nansen Smart Money Perp Trades

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

Returns real-time perpetual contract trade activity by smart money wallets on Hyperliquid, with filtering by side, type, action, price, and value.

## Facts

- Endpoint: POST https://api.nansen.ai/api/v1/smart-money/perp-trades?utm_source=zero.xyz
- Price: $0.05/call
- Payment: MPP
- Status: unknown
- Last checked: 2026-10-10
- 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-4da281f7
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_kiNh_AKCRfIf5BTQNcx-w

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-4da281f7 -d '<json body>'
```

Example prompt: Pull the latest smart money perp trades on Hyperliquid for ETH — show only new Long positions opened via Market orders, and filter for trades worth at least $50,000.

## When to prefer this

Use this endpoint when you need transaction-level perpetual trade data specifically from Nansen-identified smart money wallets on Hyperliquid. Prefer this over generic DEX trade endpoints when you want smart money signal filtering, Nansen wallet labels, and Hyperliquid-native perp contract granularity. Best for real-time trade surveillance, copy-trading research, or flow analysis.

## Known failure modes

- Invalid filter enum values (e.g. unrecognized action type) return a 422 validation error
- Missing or invalid authentication returns 401/402
- No trades match the specified filters — returns empty data array with pagination metadata
- Rate limiting or quota exceeded returns 429
- Overly narrow time or value ranges may yield zero results silently

## How this service works

Access real-time perpetual trading activity from smart traders and funds on Hyperliquid. This endpoint provides granular transaction-level data showing exactly what sophisticated traders are trading on perpetual contracts.

Key Features:
- Hyperliquid perpetual contracts only (no chain field needed)
- Real-time trading data from smart money wallets
- Detailed trade information including coin, amount, price, action, and type
- Smart money filtering capabilities
- Type filtering (Market/Limit)
- Only new positions filter to show only position opening trades (defaults to false - shows all trades)

## Output

A paginated list of perpetual trade records, each containing the Nansen-labeled trader address, token symbol, trade action (e.g. Buy - Open Long), type (Market/Limit), position side, price in USD, notional value in USD, token amount, block timestamp, and transaction hash.

## 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/nansen-perp-trades-4da281f7/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)