{"uid":"cap_kiNh_AKCRfIf5BTQNcx-w","slug":"nansen-perp-trades-4da281f7","name":"Nansen Smart Money Perp Trades","description":"Access real-time perpetual trading activity from smart traders and funds on Hyperliquid. This endpoint provides granular transaction-level data showing exactly what sophisticated traders are trading on perpetual contracts.\n\nKey Features:\n- Hyperliquid perpetual contracts only (no chain field needed)\n- Real-time trading data from smart money wallets\n- Detailed trade information including coin, amount, price, action, and type\n- Smart money filtering capabilities\n- Type filtering (Market/Limit)\n- Only new positions filter to show only position opening trades (defaults to false - shows all trades)","url":"https://api.nansen.ai/api/v1/smart-money/perp-trades?utm_source=zero.xyz","method":"POST","headers":{},"bodySchema":{"type":"object","title":"SmartMoneyPerpTradesRequest","properties":{"filters":{"anyOf":[{"type":"object","title":"SmartMoneyPerpTradesFilters","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"],"description":"Position side filter - Long or Short"},"type":{"anyOf":[{"enum":["Market","Limit"],"type":"string","title":"TradeType","description":"Enum for trade types."}],"examples":["Market","Limit"],"description":"Trade type filter - Market or Limit"},"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 - Open Short"],"description":"Action filter - combined buy/sell with position action (e.g., 'Buy - Add Long', 'Sell - Open Short')"},"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":1000}],"description":"Trade value range filter in USD"},"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"},"token_symbol":{"anyOf":[{"type":"string"}],"title":"Token Symbol","examples":["BTC","ETH","SOL"],"description":"Token symbol 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 name or 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":[["Smart Trader"]],"description":"Remove members of the fixed Smart HL Perps Trader cohort that carry any selected label. Empty or omitted removes no traders."},"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":[["Smart Trader"]],"description":"Narrow the fixed Smart HL Perps Trader cohort to traders that also carry any selected label. Empty or omitted keeps the full cohort."}},"description":"Filters for smart money perpetual trades endpoint.\n\nThese filters control which perpetual trades and traders\nare included in the trades analysis.","additionalProperties":false}],"examples":[{"side":"Long","type":"Limit","action":"Buy - Add Long","value_usd":{"max":10000,"min":1000},"token_symbol":"BTC"}],"description":"Additional filters to apply. Only filters for columns that are being selected will be applied."},"order_by":{"anyOf":[{"type":"array","items":{"type":"object","title":"SmartMoneyPerpTradesSortOrder","required":["field","direction"],"properties":{"field":{"enum":["block_timestamp","token_amount","price_usd","value_usd"],"type":"string","title":"SmartMoneyPerpTradesSortField","description":"Enum for sortable fields in smart money 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\": \"value_usd\", \"direction\": \"DESC\"}] - Sort by trade value descending\n- [{\"field\": \"block_timestamp\", \"direction\": \"ASC\"}] - Sort by timestamp ascending\n- [{\"field\": \"token_amount\", \"direction\": \"DESC\"}, {\"field\": \"block_timestamp\", \"direction\": \"ASC\"}] - Sort by token amount descending, then timestamp ascending"},"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."},"lookback_hours":{"type":"integer","title":"Lookback Hours","default":168,"maximum":168,"minimum":1,"examples":[24],"description":"Length of the recent trade window in hours. Defaults to 168 hours to preserve the endpoint's existing seven-day behavior."},"only_new_positions":{"anyOf":[{"type":"boolean"}],"title":"Only New Positions","default":false,"examples":[true,false],"description":"When True, includes 'Open' position actions (Open Long, Open Short). Can be combined with other action filters using OR logic (union). When False (default), returns all trades."}},"description":"","additionalProperties":false},"responseSchema":{"type":"object","title":"SmartMoneyPerpTradesResponse","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"type":"object","title":"SmartMoneyPerpTrade","required":["trader_address_label","trader_address","token_symbol","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":"TradeType","description":"Enum for trade types."},"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","description":"Trade price in USD"},"value_usd":{"anyOf":[{"type":"number"}],"title":"Value Usd","description":"Notional trade value in USD"},"token_amount":{"anyOf":[{"type":"number"}],"title":"Token Amount","description":"Trade size in contract units"},"token_symbol":{"type":"string","title":"Token Symbol","description":"The token symbol"},"trader_address":{"type":"string","title":"Trader Address","description":"Hexadecimal representation of the trader's address, i.e. the signer of the transaction"},"block_timestamp":{"type":"string","title":"Block Timestamp","description":"The timestamp of the block"},"transaction_hash":{"type":"string","title":"Transaction Hash","description":"Hexadecimal representation of the transaction hash"},"trader_address_label":{"type":"string","title":"Trader Address Label","description":"Name of the trader, based on Nansen labels"}},"description":"Individual smart money perpetual trade record.\n\nRepresents a single perpetual trade made by smart money wallets on Hyperliquid."},"title":"Data","description":"List of smart money perpetual 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 smart money perpetual trades endpoint.\n\nContains the filtered smart money perpetual trades data with metadata."},"example":null,"exampleRequest":null,"tags":["blockchain","smart-money","wallet","tokens","defi","analytics","profiler","dex","pnl","onchain","prediction-market","data"],"displayCostAmount":"0.05","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.05/call","primary":{"kind":"static","protocol":"mpp","network":"tempo","amountUsd":"0.05","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"mpp","network":"tempo","amountUsd":"0.05","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_BROdszIL1rsPXpAhFtc-Q","protocol":"mpp","methodType":"crypto","chain":"tempo","mode":"charge","costAmount":"0.05","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":"Returns real-time perpetual contract trade activity by smart money wallets on Hyperliquid, with filtering by side, type, action, price, and value.","exampleAgentPrompt":"Pull the latest smart money perp trades on Hyperliquid for ETH — show only new Long positions opened via Market orders, and filter for trades worth at least $50,000.","exampleUseCases":null,"resultDescription":"A paginated list of perpetual trade records, each containing the Nansen-labeled trader address, token symbol, trade action (e.g. Buy - Open Long), type (Market/Limit), position side, price in USD, notional value in USD, token amount, block timestamp, and transaction hash.","failureModes":["Invalid filter enum values (e.g. unrecognized action type) return a 422 validation error","Missing or invalid authentication returns 401/402","No trades match the specified filters — returns empty data array with pagination metadata","Rate limiting or quota exceeded returns 429","Overly narrow time or value ranges may yield zero results silently"],"whenToPreferThis":"Use this endpoint when you need transaction-level perpetual trade data specifically from Nansen-identified smart money wallets on Hyperliquid. Prefer this over generic DEX trade endpoints when you want smart money signal filtering, Nansen wallet labels, and Hyperliquid-native perp contract granularity. Best for real-time trade surveillance, copy-trading research, or flow analysis.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-10-10T18:39:14.214Z","isFirstParty":false,"canonicalSlug":"nansen-perp-trades-4da281f7"}