{"uid":"cap_nNORl40bJvVtw87iJEWYD","slug":"nansen-perp-trades-c014a78c","name":"Nansen Perp Trades (User)","description":"Get perpetual trade data for a user. This endpoint provides trade information including trade price, size, side, fees, and other trade details.\n\n**What it helps to answer:**\n\n1. **What are the perpetual trades for a specific user address within a date range?**\n2. **What are the trade prices, sizes, and directions for each trade?**\n3. **What are the trading fees and closed PnL for each trade?**\n4. **What are the order IDs and transaction hashes for trade tracking?**","url":"https://api.nansen.ai/api/v1/profiler/perp-trades?utm_source=zero.xyz","method":"POST","headers":{},"bodySchema":{"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":["Long","Short"],"description":"Position side filter (Long or Short)"},"size":{"anyOf":[{"type":"object","title":"NumericRangeFilter","properties":{"max":{"anyOf":[{"type":"number"}],"title":"Max","examples":[50000,10000000,100],"description":"Maximum value (inclusive)"},"min":{"anyOf":[{"type":"number"}],"title":"Min","examples":[1000,1000000,-50,0],"description":"Minimum value (inclusive)"}},"description":"Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"}],"examples":[{"max":1000,"min":0.001}],"description":"Trade size range filter"},"price":{"anyOf":[{"type":"object","title":"NumericRangeFilter","properties":{"max":{"anyOf":[{"type":"number"}],"title":"Max","examples":[50000,10000000,100],"description":"Maximum value (inclusive)"},"min":{"anyOf":[{"type":"number"}],"title":"Min","examples":[1000,1000000,-50,0],"description":"Minimum value (inclusive)"}},"description":"Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"}],"examples":[{"max":1000,"min":0.001}],"description":"Price range filter"},"action":{"anyOf":[{"enum":["Open/Add","Close/Reduce","Liquidation"],"type":"string","title":"PerpTradeActionFilter","description":"Enum for perp trade action filters (grouped)."}],"examples":["Open/Add","Close/Reduce","Liquidation"],"description":"Action filter (Open/Add, Close/Reduce, Liquidation)"},"crossed":{"anyOf":[{"type":"boolean"}],"title":"Crossed","examples":[true,false],"description":"Whether the trade was crossed"},"fee_usd":{"anyOf":[{"type":"object","title":"NumericRangeFilter","properties":{"max":{"anyOf":[{"type":"number"}],"title":"Max","examples":[50000,10000000,100],"description":"Maximum value (inclusive)"},"min":{"anyOf":[{"type":"number"}],"title":"Min","examples":[1000,1000000,-50,0],"description":"Minimum value (inclusive)"}},"description":"Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"}],"examples":[{"max":1000,"min":0.001}],"description":"Fee in USD range filter"},"value_usd":{"anyOf":[{"type":"object","title":"NumericRangeFilter","properties":{"max":{"anyOf":[{"type":"number"}],"title":"Max","examples":[50000,10000000,100],"description":"Maximum value (inclusive)"},"min":{"anyOf":[{"type":"number"}],"title":"Min","examples":[1000,1000000,-50,0],"description":"Minimum value (inclusive)"}},"description":"Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"}],"examples":[{"max":1000000,"min":0.001}],"description":"Value in USD range filter"},"closed_pnl":{"anyOf":[{"type":"object","title":"NumericRangeFilter","properties":{"max":{"anyOf":[{"type":"number"}],"title":"Max","examples":[50000,10000000,100],"description":"Maximum value (inclusive)"},"min":{"anyOf":[{"type":"number"}],"title":"Min","examples":[1000,1000000,-50,0],"description":"Minimum value (inclusive)"}},"description":"Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"}],"examples":[{"max":10000,"min":-10000}],"description":"Closed PnL range filter"},"token_symbol":{"anyOf":[{"type":"string"}],"title":"Token Symbol","examples":["BTC","ETH","@107"],"description":"Token symbol filter"},"start_position":{"anyOf":[{"type":"object","title":"NumericRangeFilter","properties":{"max":{"anyOf":[{"type":"number"}],"title":"Max","examples":[50000,10000000,100],"description":"Maximum value (inclusive)"},"min":{"anyOf":[{"type":"number"}],"title":"Min","examples":[1000,1000000,-50,0],"description":"Minimum value (inclusive)"}},"description":"Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"}],"examples":[{"max":1000,"min":-1000}],"description":"Start position range filter"},"fee_token_symbol":{"anyOf":[{"type":"string"}],"title":"Fee Token Symbol","examples":["HYPE","USDC"],"description":"Fee token filter"}},"description":"Filters for perp trades endpoint.\n\nThese filters control which perpetual trades are included in the results\nbased on various trade criteria.","additionalProperties":false}],"examples":[{"size":{"max":1000,"min":0.001}}],"description":"Additional filters for the trades"},"order_by":{"anyOf":[{"type":"array","items":{"type":"object","title":"PerpTradeSortOrder","required":["field","direction"],"properties":{"field":{"enum":["timestamp","size","fee_usd","closed_pnl","price","value_usd"],"type":"string","title":"PerpTradeSortField","description":"Enum for perp trade sort fields."},"direction":{"enum":["ASC","DESC"],"type":"string","title":"SortDirection","description":"Enum for sort directions."}}}}],"title":"Order By","examples":[[{"field":"timestamp","direction":"DESC"}]],"description":"Sort order for the trades"},"pagination":{"type":"object","title":"PaginationRequest","properties":{"page":{"type":"integer","title":"Page","default":1,"minimum":1,"description":"Page number (1-based)"},"per_page":{"type":"integer","title":"Per Page","default":10,"maximum":1000,"minimum":1,"description":"Number of records per page (max 1000)"}},"description":"Pagination parameters for API requests."}},"description":"Request model for Perp Trades endpoint.","additionalProperties":false},"responseSchema":{"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","examples":[true,false],"description":"Crossed of the trade"},"fee_usd":{"type":"number","title":"Fee Usd","examples":[0.434851,2.25,2.25,5,0.625,0.25,0.005,0.075,0.02,15],"description":"Total fee in USD of the trade (sum of all fills)"},"timestamp":{"type":"string","title":"Timestamp","examples":["2025-10-08T18:46:11.452000","2025-10-08T15:30:22.123000","2025-10-08T12:15:33.789000","2025-10-08T09:45:44.456000","2025-10-08T06:20:55.234000"],"description":"Timestamp of the trade"},"value_usd":{"type":"number","title":"Value Usd","examples":[1553.04,4500,4500,10000,1250,500,0.01,150,40,30000],"description":"Total value in USD of the trade"},"closed_pnl":{"type":"number","title":"Closed Pnl","examples":[0,150,-75,500,-200,1000,-50,25,-10,750],"description":"Total closed PnL of the trade (sum of all fills)"},"block_number":{"type":"integer","title":"Block Number","examples":[756553592,756553593,756553594,756553595,756553596],"description":"Block number of the trade"},"token_symbol":{"type":"string","title":"Token Symbol","examples":["DOGE","BTC","ETH","SOL","AVAX","MATIC","DOT","LINK","UNI","AAVE"],"description":"Symbol of the token"},"start_position":{"type":"number","title":"Start Position","examples":[-7788000,0,1000,-500,2500,-100,0,50,-25,2000],"description":"Start position of the trade in token units"},"fee_token_symbol":{"type":"string","title":"Fee Token Symbol","examples":["USDC","HYPE","USDT"],"description":"Fee in token of the trade"},"transaction_hash":{"type":"string","title":"Transaction Hash","examples":["0x50cea34e7464d3055248042d1817780203b600340f67f1d7f4974ea13368acef","0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef","0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890","0x9876543210fedcba9876543210fedcba9876543210fedcba9876543210fedcba","0xfedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210"],"description":"Transaction hash of the trade"}},"description":"Perpetual trade with computed type and action fields for client response.","additionalProperties":false},"title":"Data","examples":[[{"oid":191284609448,"side":"Short","size":6000,"user":"0x45d26f28196d226497130c4bac709d808fed4029","price":0.25884,"action":"Add","crossed":true,"fee_usd":0.434851,"timestamp":"2025-10-08T18:46:11.452000","value_usd":1553.04,"closed_pnl":0,"block_number":756553592,"token_symbol":"DOGE","start_position":-7788000,"fee_token_symbol":"USDC","transaction_hash":"0x50cea34e7464d3055248042d1817780203b600340f67f1d7f4974ea13368acef"},{"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":"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"},{"oid":191284609450,"side":"Long","size":1.5,"user":"0x45d26f28196d226497130c4bac709d808fed4029","price":3000,"action":"Close","crossed":true,"fee_usd":2.25,"timestamp":"2025-10-08T12:15:33.789000","value_usd":4500,"closed_pnl":150,"block_number":756553594,"token_symbol":"ETH","start_position":1000,"fee_token_symbol":"USDC","transaction_hash":"0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"}]],"description":"List of perpetual trades"},"pagination":{"type":"object","title":"PaginationInfo","properties":{"page":{"type":"integer","title":"Page","default":1,"minimum":1,"description":"Current page number"},"per_page":{"type":"integer","title":"Per Page","default":10,"maximum":1000,"minimum":1,"description":"Number of records per page"},"is_last_page":{"type":"boolean","title":"Is Last Page","default":true,"description":"Whether this is the last page"}},"description":"Pagination information for API responses."}},"description":"Response model for perp trades endpoint.","additionalProperties":false},"example":null,"exampleRequest":null,"tags":["blockchain","smart-money","wallet","tokens","defi","analytics","profiler","dex","pnl","onchain","prediction-market","data"],"displayCostAmount":"0.01","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"probe","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"static","summary":"$0.01/call","primary":{"kind":"static","protocol":"mpp","network":"tempo","amountUsd":"0.01","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"mpp","network":"tempo","amountUsd":"0.01","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_cg5umcxpaH6wKV97RzDHf","protocol":"mpp","methodType":"crypto","chain":"tempo","mode":"charge","costAmount":"0.01","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":"Nansen","brandSlug":"nansen","brandBaseUrl":"https://nansen.ai","brandDocsUrl":"https://docs.nansen.ai","whatItDoes":"Retrieves perpetual futures trade history for a specific Hyperliquid wallet address, including prices, sizes, fees, closed PnL, and transaction metadata within a date range.","exampleAgentPrompt":"Pull all perpetual trades for Hyperliquid address 0x45d26f28196d226497130c4bac709d808fed4029 from January 1, 2025 to January 31, 2025, and show me the trade prices, sizes, fees, and closed PnL for each trade.","exampleUseCases":null,"resultDescription":"A paginated list of perpetual trade records, each containing timestamp, position side (Long/Short), action type (Open/Close/Add/Reduce/Liquidation), token symbol, average trade price, total size, USD value, closed PnL, USD fee, fee token symbol, transaction hash, order ID, block number, and the user address.","failureModes":["Invalid or non-42-character wallet address returns validation error","Date range not provided returns 400 missing required field","No trades found for the address in the given date range returns empty data array","Address with no Hyperliquid activity returns empty result","Malformed date format causes parsing error","Pagination parameters out of bounds return empty or error response"],"whenToPreferThis":"Use this endpoint when you need detailed per-trade perpetual futures history for a specific Hyperliquid wallet address, including individual trade prices, fees, and PnL. Prefer this over the Position Intelligence endpoint when you need granular trade-level data rather than aggregated position summaries, or when you need transaction hashes for on-chain verification.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-10-09T18:48:02.408Z","isFirstParty":false,"canonicalSlug":"nansen-perp-trades-c014a78c"}