Retrieve Hyperliquid perpetual trade history for any wallet address via Nansen's profiler API.
What it does
This endpoint returns perpetual trade data for a specific user address on Hyperliquid. It is part of Nansen's Profiler suite and provides granular trade-level information including trade price, size, side (Long/Short), action (Open/Add/Close/Reduce), fees, closed PnL, and transaction hashes. Results can be filtered by token symbol, side, action type, price/size ranges, and date range. Pagination and custom sort ordering are supported.
The endpoint accepts a POST request with a JSON body containing the user's 42-character Hyperliquid address and a required date range. Optional filters allow narrowing by token symbol, trade side, action type (Open/Add, Close/Reduce, Liquidation), crossed status, and numeric ranges on size, price, value, closed PnL, and fees. The response includes paginated trade records with full trade metadata.
Pricing is $0.01 per call via the x402 protocol, or 10 credits (pro) / 1 credit (free tier) when using a Nansen API key. Rate limits are enforced per-second and per-minute, reported in response headers. The endpoint is part of the broader Nansen API v1 which covers smart money analytics, token profiling, wallet analysis, prediction markets, and more across 25+ chains.
Capabilities
Use cases
- —Retrieve a wallet's complete Hyperliquid perpetual trading history within a date range
- —Analyze closed PnL and fees for a specific trader's perp positions
- —Filter for liquidation events on a given Hyperliquid address
- —Track position opening and closing activity for a specific token symbol
- —Build trading performance dashboards using per-trade data
Fit
Best for
- —Agents building Hyperliquid trader analytics dashboards
- —Researchers analyzing perpetual futures trading behavior by wallet
- —Portfolio trackers needing per-trade PnL and fee breakdowns
- —Automated systems monitoring specific wallet perp activity
Not for
- —Spot/DEX trade history on EVM chains (use /profiler/address/transactions instead)
- —Real-time streaming trade data (this is a polling/request-based API)
- —Wallets on chains other than Hyperliquid for perp data
Quick start
curl -X POST https://api.nansen.ai/api/v1/profiler/perp-trades \
-H 'Content-Type: application/json' \
-H 'apiKey: YOUR_API_KEY' \
-d '{
"address": "0x45d26f28196d226497130c4bac709d808fed4029",
"date": {"from": "2025-10-01T00:00:00Z", "to": "2025-10-10T23:59:59Z"},
"pagination": {"page": 1, "per_page": 10}
}'Example
Request
{
"date": {
"to": "2025-10-10T23:59:59Z",
"from": "2025-10-01T00:00:00Z"
},
"address": "0x45d26f28196d226497130c4bac709d808fed4029",
"filters": {
"side": "Long",
"token_symbol": "BTC"
},
"order_by": [
{
"field": "timestamp",
"direction": "DESC"
}
],
"pagination": {
"page": 1,
"per_page": 10
}
}Response
{
"data": [
{
"oid": 191284609449,
"side": "Long",
"size": 0.1,
"user": "0x45d26f28196d226497130c4bac709d808fed4029",
"price": 45000,
"action": "Open",
"crossed": false,
"fee_usd": 2.25,
"timestamp": "2025-10-08T15:30:22.123000",
"value_usd": 4500,
"closed_pnl": 0,
"block_number": 756553593,
"token_symbol": "BTC",
"start_position": 0,
"fee_token_symbol": "USDC",
"transaction_hash": "0x1234567890abcdef..."
}
],
"pagination": {
"page": 1,
"per_page": 10,
"is_last_page": false
}
}Endpoint
Quality
Full OpenAPI 3.1 schema with detailed request/response models and examples is available. The endpoint has clear x-payment-info ($0.01 via x402) and credit costs. However, the MPP probe returned 401 (not 402), so the MPP payment challenge was not confirmed live. The endpoint is likely live behind API key auth, but the payment protocol handshake was not directly observed.
Warnings
- —MPP probe returned 401 (Unauthorized) rather than 402 — the endpoint requires an API key and did not present an MPP payment challenge on unauthenticated HEAD/GET requests.
- —The listing is categorized as MPP but the OpenAPI spec indicates x402 protocol for payment, not MPP. The payment mechanism may differ from the listing's stated protocol.
- —No direct crawl documentation was available beyond the OpenAPI spec; Nansen docs site was not crawled.
Citations
- —Endpoint is POST /api/v1/profiler/perp-trades with x402 payment at $0.01 per callhttps://api.nansen.ai
- —Credit cost is 10 (free tier) or 1 (pro tier) per requesthttps://api.nansen.ai
- —Endpoint provides trade data including price, size, side, fees, closed PnL, and transaction hashes for Hyperliquid perpshttps://api.nansen.ai
- —Request requires a 42-character Hyperliquid address and a date rangehttps://api.nansen.ai