# Nansen Perpetual Trades by User

> Nansen Perpetual Trades by User 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-15).

Retrieves perpetual trade history for a specific user address, including trade price, size, side, fees, closed PnL, order IDs, and transaction hashes.

## Facts

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

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-b3902294
```

Example prompt: Pull all the perpetual trade history from Nansen for wallet address 0xAbc123...def456 from January 1 2024 to March 31 2024 — I want to see trade prices, sizes, directions, fees, and closed PnL for each trade.

## When to prefer this

Use this endpoint when you need per-trade perpetual futures history for a specific user address, including fee and PnL data at the trade level. Prefer this over the token-level perp trades endpoint when the lookup is user-centric rather than token-centric, and over the PnL summary endpoint when you need granular trade-by-trade breakdowns rather than aggregate performance.

## Known failure modes

- Invalid or malformed wallet address returns a 400 error
- Date range too large may result in timeout or truncated results
- Address with no perpetual trade activity returns an empty list
- Missing required parameters returns a 422 validation error
- Unauthorized or missing API credentials returns a 401 error

## How this service works

Get Perpetual Trade Data

## Output

Returns a list of perpetual trade records for the specified user address, each including trade price, size, side (long/short), trading fees paid, closed PnL, associated order ID, and transaction hash for on-chain verification.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "title": "PerpTradeRequest",
 "required": [
  "address",
  "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."
  },
  "address": {
   "type": "string",
   "title": "Address",
   "examples": [
    "0x45d26f28196d226497130c4bac709d808fed4029"
   ],
   "maxLength": 42,
   "minLength": 42,
   "description": "User's Hyperliquid address in 42-character hexadecimal format"
  },
  "filters": {
   "anyOf": [
    {
     "type": "object",
     "title": "PerpTradeFilters",
     "properties": {
      "oid": {
       "anyOf": [
        {
         "type": "object",
         "title": "IntegerRangeFilter",
         "properties": {
          "max": {
           "anyOf": [
            {
             "type": "integer"
            }
           ],
           "title": "Max",
           "examples": [
            100,
            1000,
            10000
           ],
           "description": "Maximum value (inclusive)"
          },
          "min": {
           "anyOf": [
            {
             "type": "integer"
            }
           ],
           "title": "Min",
           "examples": [
            10,
            100,
            1000
           ],
           "description": "Minimum value (inclusive)"
          }
         },
         "description": "Filter for integer values with optional min/max bounds.\nUse for counts, numbers of items, and other whole number values. - Values between 5 and 100"
        }
       ],
       "examples": [
        {
         "min": 100000000000
        }
       ],
       "description": "Order ID range filter"
      },
      "side": {
       "anyOf": [
        {
         "enum": [
          "Long",
          "Short"
         ],
         "type": "string",
         "title": "PerpTradeType",
         "description": "Enum for perp trade position types."
        }
       ],
       "examples": [
        "Lon
… (truncated)
```

## Response schema (JSON Schema)

```json
{
 "type": "object",
 "title": "PerpTradeResponse",
 "required": [
  "pagination",
  "data"
 ],
 "properties": {
  "data": {
   "type": "array",
   "items": {
    "type": "object",
    "title": "PerpTrade",
    "required": [
     "timestamp",
     "side",
     "action",
     "block_number",
     "token_symbol",
     "price",
     "size",
     "value_usd",
     "start_position",
     "closed_pnl",
     "crossed",
     "fee_usd",
     "fee_token_symbol",
     "transaction_hash",
     "user",
     "oid"
    ],
    "properties": {
     "oid": {
      "type": "integer",
      "title": "Oid",
      "examples": [
       191284609448,
       191284609449,
       191284609450,
       191284609451,
       191284609452
      ],
      "description": "Order ID of the trade"
     },
     "side": {
      "anyOf": [
       {
        "enum": [
         "Long",
         "Short"
        ],
        "type": "string",
        "title": "PerpTradeType",
        "description": "Enum for perp trade position types."
       }
      ],
      "examples": [
       "Long",
       "Short"
      ],
      "description": "Position side (Long or Short)"
     },
     "size": {
      "type": "number",
      "title": "Size",
      "examples": [
       6000,
       0.1,
       1.5,
       100,
       50,
       1000,
       0.001,
       10,
       5,
       200
      ],
      "description": "Total size of the trade (sum of all fills)"
     },
     "user": {
      "type": "string",
      "title": "User",
      "examples": [
       "0x45d26f28196d226497130c4bac709d808fed4029",
       "0x1234567890abcdef1234567890abcdef12345678",
       "0xabcdef1234567890abcdef1234567890abcdef12",
       "0x9876543210fedcba9876543210fedcba98765432",
       "0xfedcba9876543210fedcba9876543210fedcba98"
      ],
      "description": "User of the trade"
     },
     "price": {
      "anyOf": [
       {
        "type": "number"
       }
      ],
      "title": "Price",
      "examples": [
       0.25884,
       45000,
       3000,
       100,
       25,
       0.5,
       0.01,
       15,
       8,
       150
      ],
      "description": "Average price of the trade (averaged across fills)"
     },
     "action": {
      "type": "string",
      "title": "Action",
      "examples": [
       "Add",
       "Open",
       "Close",
       "Reduce",
       "Liquidation"
      ],
      "description": "Action taken (Open, Add, Close, Reduce, etc.)"
     },
     "crossed": {
      "type": "boolean",
      "title": "Crossed",
  
… (truncated)
```

## More

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