Address Perp Trades

Common Scenarios

Usecase	Required Parameters	Optional Filters	Expected Output
Fetch all perp trades for an address within a specific date range	address ="0x45d26f28196d226497130c4bac709d808fed4029" date ={ "from": "2025-10-01", "to": "2025-10-10" }	(none needed for basic usage)	List of trades with timestamps, price, size, token, direction (Long/Short), action (Open/Close), and fees for the address
Analyze high-value trades with closed PnL details	address ="0x45d26f28196d226497130c4bac709d808fed4029" date ={ "from": "2025-10-01", "to": "2025-10-10" }	filters ={"value_usd": {"min": 1000}}	List of trades above $1,000 with closed PnL, fees paid, order IDs, and asset symbols
Track all short trades and compare performance by token	address ="0x45d26f28196d226497130c4bac709d808fed4029" date ={ "from": "2025-10-01", "to": "2025-10-10" }	filters ={"type": "Short"} order_by =[{"direction": "DESC", "field": "closed_pnl"}]	All short trades, sorted by closed profit, allowing analysis of which tokens and trades delivered the best results

Get Perpetual Trade Data

post

Get perpetual trade data for a user. This endpoint provides trade information including trade price, size, side, fees, and other trade details.

What it helps to answer:

1. What are the perpetual trades for a specific user address within a date range?

2. What are the trade prices, sizes, and directions for each trade?

3. What are the trading fees and closed PnL for each trade?

4. What are the order IDs and transaction hashes for trade tracking?

Authorizations

ApiKeyAuth

Body

application/json

Request model for Perp Trades endpoint.

addressstring · min: 42 · max: 42Required

User's Hyperliquid address in 42-character hexadecimal format

Example: 0x45d26f28196d226497130c4bac709d808fed4029

filtersany ofOptional

Additional filters for the trades

Example: {"size":{"max":1000,"min":0.001}}

order_byany ofOptional

Sort order for the trades

Example: [{"direction":"DESC","field":"timestamp"}]

Responses

200

Perpetual trade data for the user

application/json

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Content

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

post

/api/v1/profiler/perp-trades

HTTPcURLJavaScriptPython

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

{
  "address": "0x45d26f28196d226497130c4bac709d808fed4029",
  "date": {
    "from": "2025-10-01",
    "to": "2025-10-10"
  },
  "filters": {
    "size": {
      "max": 1000,
      "min": 0.001
    }
  },
  "pagination": {
    "page": 1,
    "per_page": 10
  },
  "order_by": [
    {
      "direction": "DESC",
      "field": "timestamp"
    }
  ]
}

{
  "pagination": {
    "page": 1,
    "per_page": 10,
    "is_last_page": true
  },
  "data": [
    {
      "action": "Add",
      "block_number": 756553592,
      "closed_pnl": 0,
      "crossed": true,
      "fee_token_symbol": "USDC",
      "fee_usd": 0.434851,
      "oid": 191284609448,
      "price": 0.25884,
      "side": "Short",
      "size": 6000,
      "start_position": -7788000,
      "timestamp": "2025-10-08T18:46:11.452000",
      "token_symbol": "DOGE",
      "transaction_hash": "0x50cea34e7464d3055248042d1817780203b600340f67f1d7f4974ea13368acef",
      "user": "0x45d26f28196d226497130c4bac709d808fed4029",
      "value_usd": 1553.04
    },
    {
      "action": "Open",
      "block_number": 756553593,
      "closed_pnl": 0,
      "crossed": false,
      "fee_token_symbol": "USDC",
      "fee_usd": 2.25,
      "oid": 191284609449,
      "price": 45000,
      "side": "Long",
      "size": 0.1,
      "start_position": 0,
      "timestamp": "2025-10-08T15:30:22.123000",
      "token_symbol": "BTC",
      "transaction_hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
      "user": "0x45d26f28196d226497130c4bac709d808fed4029",
      "value_usd": 4500
    },
    {
      "action": "Close",
      "block_number": 756553594,
      "closed_pnl": 150,
      "crossed": true,
      "fee_token_symbol": "USDC",
      "fee_usd": 2.25,
      "oid": 191284609450,
      "price": 3000,
      "side": "Long",
      "size": 1.5,
      "start_position": 1000,
      "timestamp": "2025-10-08T12:15:33.789000",
      "token_symbol": "ETH",
      "transaction_hash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
      "user": "0x45d26f28196d226497130c4bac709d808fed4029",
      "value_usd": 4500
    }
  ]
}