🆕Perp Trades

Get Smart Money Perpetual Trades Data

post

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)

Authorizations

ApiKeyAuth

apiKeystringRequired

API key for authentication

Body

application/json

filtersany ofOptional

Additional filters to apply. Only filters for columns that are being selected will be applied.

Example: {"action":"Buy - Add Long","side":"Long","token_symbol":"BTC","type":"Limit","value_usd":{"max":10000,"min":1000}}

only_new_positionsany ofOptional

When True, includes 'Open' position actions (Open Long, Open Short). Can be combined with other action filters using OR logic (union). When False (default), returns all trades.

Default: falseExample: true

booleanOptional

order_byany ofOptional

Custom sort order to override the endpoint's default ordering.

Examples:

• [{"field": "value_usd", "direction": "DESC"}] - Sort by trade value descending
• [{"field": "block_timestamp", "direction": "ASC"}] - Sort by timestamp ascending
• [{"field": "token_amount", "direction": "DESC"}, {"field": "block_timestamp", "direction": "ASC"}] - Sort by token amount descending, then timestamp ascending

Responses

200

Smart money perpetual trades data

application/json

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Entity

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

post

/api/v1/smart-money/perp-trades

HTTPcURLJavaScriptPython

POST /api/v1/smart-money/perp-trades HTTP/1.1
Host: api.nansen.ai
apiKey: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 249

{
  "filters": {
    "action": "Buy - Add Long",
    "side": "Long",
    "token_symbol": "BTC",
    "type": "Limit",
    "value_usd": {
      "max": 10000,
      "min": 1000
    }
  },
  "only_new_positions": true,
  "pagination": {
    "page": 1,
    "per_page": 10
  },
  "order_by": [
    {
      "field": "block_timestamp",
      "direction": "ASC"
    }
  ]
}

{
  "data": [
    {
      "trader_address_label": "text",
      "trader_address": "text",
      "token_symbol": "text",
      "side": "Long",
      "action": "Add",
      "token_amount": 1,
      "price_usd": 1,
      "value_usd": 1,
      "type": "Market",
      "block_timestamp": "text",
      "transaction_hash": "text"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "is_last_page": true
  }
}