{"uid":"cap_3l--JvjgBWauCdcxTkfO6","slug":"nansen-9e374dad","name":"Nansen Hyperliquid Perpetual Trades","description":"Get \"Token God Mode\" (TGM) perp trades data","url":"https://api.nansen.ai/api/v1/tgm/perp-trades","method":"GET","headers":{},"bodySchema":{"type":"object","title":"TGMPerpTradesRequest","required":["token_symbol","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."},"filters":{"anyOf":[{"type":"object","title":"TGMPerpTradesFilters","properties":{"side":{"anyOf":[{"enum":["Long","Short"],"type":"string","title":"PositionSide","description":"Shared enum for position side direction."},{"type":"array","items":{"enum":["Long","Short"],"type":"string","title":"PositionSide","description":"Shared enum for position side direction."}},{"type":"null"}],"title":"Side","examples":["Long",["Short","Long"]],"description":"Position side filter (Long or Short)"},"action":{"anyOf":[{"enum":["Buy - Add Long","Buy - Reduce Short","Buy - Open Long","Buy - Close Short","Sell - Add Short","Sell - Reduce Long","Sell - Open Short","Sell - Close Long"],"type":"string","title":"PerpActionType","description":"Shared enum for perpetual trade action types (combined buy/sell with position actions)."},{"type":"array","items":{"enum":["Buy - Add Long","Buy - Reduce Short","Buy - Open Long","Buy - Close Short","Sell - Add Short","Sell - Reduce Long","Sell - Open Short","Sell - Close Long"],"type":"string","title":"PerpActionType","description":"Shared enum for perpetual trade action types (combined buy/sell with position actions)."}},{"type":"null"}],"title":"Action","examples":["Buy - Add Long","Sell - Reduce Long"],"description":"Action filter with combined buy/sell direction (e.g., 'Buy - Add Long', 'Sell - Reduce Long')"},"price_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":10000,"min":1000}],"description":"Price range filter in USD"},"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":10000,"min":-10000}],"description":"Trade value range filter in USD"},"order_type":{"anyOf":[{"enum":["MARKET","LIMIT"],"type":"string","title":"OrderType","description":"Order type."},{"type":"array","items":{"enum":["MARKET","LIMIT"],"type":"string","title":"OrderType","description":"Order type."}},{"type":"null"}],"title":"Order Type","examples":["MARKET","LIMIT"],"description":"Order type filter (MARKET or LIMIT)"},"token_amount":{"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":100}],"description":"Token amount range filter"},"trader_address":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"null"}],"title":"Trader Address","examples":["0x28c6c06298d514db089934071355e5743bf21d60"],"description":"Trader address filter"},"trader_address_label":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"null"}],"title":"Trader Address Label","examples":["Smart Money","%Fund%"],"description":"Trader label filter"},"exclude_smart_money_labels":{"anyOf":[{"type":"array","items":{"enum":["Fund","Smart Trader","30D Smart Trader","90D Smart Trader","180D Smart Trader","Smart HL Perps Trader"],"type":"string","title":"SmartMoneyFilterType","description":"Filter by smart money label type."}}],"title":"Exclude Smart Money Labels","examples":[["30D Smart Trader"]],"description":"Exclude smart money labels"},"include_smart_money_labels":{"anyOf":[{"type":"array","items":{"enum":["Fund","Smart Trader","30D Smart Trader","90D Smart Trader","180D Smart Trader","Smart HL Perps Trader"],"type":"string","title":"SmartMoneyFilterType","description":"Filter by smart money label type."}}],"title":"Include Smart Money Labels","examples":[["Fund","Smart Trader"]],"description":"Include smart money labels"}},"description":"Filters for TGM perp trades endpoint.\n\nThese filters control which perp trades are included in the results.","additionalProperties":false}],"examples":[{"side":["Long"],"order_type":["MARKET"]}],"description":"Additional filters to apply to the query."},"order_by":{"anyOf":[{"type":"array","items":{"type":"object","title":"SortOrder[TGMPerpTradesSortField]","required":["field","direction"],"properties":{"field":{"enum":["block_timestamp","token_amount","value_usd","transaction_hash","trader_address"],"type":"string","title":"TGMPerpTradesSortField","description":"Enum for sortable fields in TGM perp trades."},"direction":{"enum":["ASC","DESC"],"type":"string","title":"SortDirection","description":"Enum for sort directions."}}}}],"title":"Order By","description":"Custom sort order to override the endpoint's default ordering.\n\nExamples:\n- [{\"field\": \"block_timestamp\", \"direction\": \"DESC\"}] - Sort by timestamp descending\n- [{\"field\": \"value_usd\", \"direction\": \"DESC\"}] - Sort by trade value descending\n\nDefault: block_timestamp DESC, transaction_hash ASC, trader_address ASC (ensures stable pagination and prevents duplicate rows)"},"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."},"token_symbol":{"type":"string","title":"Token Symbol","examples":["BTC"],"description":"Token symbol"}},"description":"Request model for TGM perp trades endpoint.\n\nThis endpoint provides perp trades data for a specific token.","additionalProperties":false},"responseSchema":{"type":"object","title":"TGMPerpTradesResponse","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"type":"object","title":"TGMPerpTrade","required":["trader_address","action","type","block_timestamp","transaction_hash"],"properties":{"side":{"anyOf":[{"enum":["Long","Short"],"type":"string","title":"PositionSide","description":"Shared enum for position side direction."}],"examples":["Long","Short"],"description":"The side of the position (Long or Short)"},"type":{"enum":["MARKET","LIMIT"],"type":"string","title":"OrderType","description":"Order type."},"action":{"type":"string","title":"Action","examples":["Add","Reduce","Open","Close"],"description":"The action taken by the trader (Add, Reduce, Open, Close)"},"price_usd":{"anyOf":[{"type":"number"}],"title":"Price Usd","examples":[60000],"description":"Average fill price in USD across all fills in the trade, from exchange data."},"value_usd":{"anyOf":[{"type":"number"}],"title":"Value Usd","examples":[90000],"description":"The value in USD"},"token_amount":{"anyOf":[{"type":"number"}],"title":"Token Amount","examples":[1.5],"description":"The amount of the specified token traded"},"token_symbol":{"anyOf":[{"type":"string"}],"title":"Token Symbol","examples":["BTC"],"description":"The symbol of the token"},"trader_address":{"type":"string","title":"Trader Address","examples":["0x28c6c06298d514db089934071355e5743bf21d60"],"description":"The trader's address"},"block_timestamp":{"type":"string","title":"Block Timestamp","examples":["2025-10-01T12:40:00Z"],"description":"The block timestamp for the transaction"},"transaction_hash":{"type":"string","title":"Transaction Hash","examples":["0x61adb6da30853c5988f0204dd9f6e4abbc878e02c34030a4f707cf4ec3124bcb"],"description":"A representative transaction hash for this trade. Note: A single row may aggregate multiple fills that occurred at the same timestamp. If the trader had fills across multiple transactions at the exact same millisecond, only one transaction_hash is shown. The token_amount and value_usd reflect the total across all fills."},"trader_address_label":{"anyOf":[{"type":"string"}],"title":"Trader Address Label","examples":["Smart Money"],"description":"The label associated with the trader"}},"description":"Individual TGM perp trade record.\n\nRepresents a single perp trade with parsed action fields."},"title":"Data","description":"List of TGM perp trade records"},"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 TGM perp trades endpoint.\n\nContains a list of perp trade records with pagination and metadata."},"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_SepFEHwrUCXGEOHxVPiNx","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_E4me9XbhOCh--AuB7fAU1","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 individual perpetual contract trade data for a specific token on Hyperliquid, with smart money filtering and detailed trade breakdowns.","exampleAgentPrompt":"Pull all the BTC perpetual trades on Hyperliquid from the last 24 hours where smart money wallets were opening long positions using market orders — show me trader addresses and trade metrics.","exampleUseCases":null,"resultDescription":"A paginated list of individual perpetual trade records from Hyperliquid, each containing the trader wallet address, trade side (Long/Short), action type (Add/Reduce/Open/Close), order type (Market/Limit), and associated trade metrics like size and price for the requested token and date range.","failureModes":["Invalid token symbol returns empty results or error","Date range too broad may hit pagination limits or timeout","Unsupported filter values (invalid side/action/order_type enum) return validation error","Token not listed on Hyperliquid perpetuals returns no data","Missing required token_symbol parameter returns 400 error","Rate limiting if too many requests are made in quick succession"],"whenToPreferThis":"Use this endpoint when you need granular, trade-level data for Hyperliquid perpetual contracts — specifically when you want to track individual trader behavior, filter by smart money, or analyze position actions (open/close/add/reduce) for a specific token. Prefer this over broader flow analytics endpoints when you need per-trade detail rather than aggregate flows.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-09-13T12:59:27.771Z","isFirstParty":false}