{"uid":"cap_EIMvbM6NP4LoMVrEIty3O","slug":"nansen-b3902294","name":"Nansen Perpetual Trades by User","description":"Get Perpetual Trade Data","url":"https://api.nansen.ai/api/v1/profiler/perp-trades","method":"GET","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":"SortOrder[PerpTradeSortField]","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":["x402"],"displayCostAmount":"0.01","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"settled","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"},{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.01","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_QkfAAFgqsyjVnWhYBdQ1W","protocol":"mpp","methodType":"crypto","chain":"tempo","mode":"charge","costAmount":"0.01","costPer":"request","priority":0,"asset":null,"unit":"request","depositMicros":null,"planRef":null},{"uid":"pm_LNLLH9H71rw-nEXhsg93h","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.01","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Retrieves perpetual trade history for a specific user address, including trade price, size, side, fees, closed PnL, order IDs, and transaction hashes.","exampleAgentPrompt":"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.","exampleUseCases":null,"resultDescription":"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.","failureModes":["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"],"whenToPreferThis":"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.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-09-15T12:57:00.097Z","isFirstParty":false}