{"uid":"cap_4rDm21DAPWUoYRVhFQurW","slug":"nansen-position-intelligence-2d307a23","name":"Nansen Position Intelligence","description":"This endpoint provides position intelligence analytics for perpetual contracts on Hyperliquid, showing aggregated position sizes (longs, shorts, and totals) broken down by various trader cohorts (Smart Money, Whales, Top PnL, Public Figures). It can be used for analyzing position distributions and sentiment across different trader segments.","url":"https://api.nansen.ai/api/v1/tgm/position-intelligence?utm_source=zero.xyz","method":"POST","headers":{},"bodySchema":{"type":"object","title":"TGMPositionIntelligenceRequest","required":["token_address"],"properties":{"token_address":{"type":"string","title":"Token Address","examples":["BTC"],"minLength":1,"description":"Token address (for perps and hyperliquid, validation is skipped)"}},"description":"Request model for TGM position-intelligence endpoint.\n\nThis endpoint provides position intelligence analytics for perpetual contracts\non Hyperliquid, showing aggregated position sizes by different trader cohorts.","additionalProperties":false},"responseSchema":{"type":"object","title":"TGMPositionIntelligenceResponse","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","title":"TGMPositionIntelligence","properties":{"whale_longs_usd":{"anyOf":[{"type":"number"}],"title":"Whale Longs Usd","examples":[2000000.5],"description":"Sum of absolute long sizes for addresses labeled Whale."},"whale_total_usd":{"anyOf":[{"type":"number"}],"title":"Whale Total Usd","examples":[3000000.75],"description":"Total absolute position size for addresses labeled Whale."},"whale_shorts_usd":{"anyOf":[{"type":"number"}],"title":"Whale Shorts Usd","examples":[1000000.25],"description":"Sum of absolute short sizes for addresses labeled Whale."},"smart_trader_longs_usd":{"anyOf":[{"type":"number"}],"title":"Smart Trader Longs Usd","examples":[1000000.5],"description":"Sum of absolute long sizes for addresses labeled Smart HL Perps Trader."},"smart_trader_total_usd":{"anyOf":[{"type":"number"}],"title":"Smart Trader Total Usd","examples":[1500000.75],"description":"Total absolute position size for addresses labeled Smart HL Perps Trader."},"public_figure_longs_usd":{"anyOf":[{"type":"number"}],"title":"Public Figure Longs Usd","examples":[500000.5],"description":"Sum of absolute long sizes for addresses labeled Public Figure."},"public_figure_total_usd":{"anyOf":[{"type":"number"}],"title":"Public Figure Total Usd","examples":[750000.75],"description":"Total absolute position size for addresses labeled Public Figure."},"smart_trader_shorts_usd":{"anyOf":[{"type":"number"}],"title":"Smart Trader Shorts Usd","examples":[500000.25],"description":"Sum of absolute short sizes for addresses labeled Smart HL Perps Trader."},"public_figure_shorts_usd":{"anyOf":[{"type":"number"}],"title":"Public Figure Shorts Usd","examples":[250000.25],"description":"Sum of absolute short sizes for addresses labeled Public Figure."}},"description":"Individual TGM position intelligence record.\n\nRepresents aggregated position sizes for different trader cohorts."},"title":"Data","description":"List of TGM position intelligence records"}},"description":"Response model for TGM position-intelligence endpoint.\n\nContains position intelligence data with pagination and metadata."},"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_Rky_TRP7o0iR2gx_r1wmi","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":"Returns aggregated long/short position sizes for a perpetual contract token on Hyperliquid, broken down by trader cohorts (Smart Money, Whales, Top PnL, Public Figures).","exampleAgentPrompt":"Pull up the Nansen position intelligence for BTC on Hyperliquid — I want to see how whales and smart money traders are positioned, whether they're net long or short, and what the public figures are doing.","exampleUseCases":null,"resultDescription":"Returns an array of position intelligence records with aggregated USD position sizes for each trader cohort: whale longs/shorts/total, smart trader (Smart HL Perps Trader) longs/shorts/total, top PnL trader longs/shorts/total, and public figure longs/shorts/total for the specified perpetual contract token.","failureModes":["Missing token_address returns 422 validation error","Invalid or unsupported token symbol returns empty data array","Network timeout or upstream Hyperliquid data unavailability returns 5xx error","Authentication failure (missing or invalid API key) returns 401 unauthorized"],"whenToPreferThis":"Use this endpoint when you need cohort-segmented position analysis for perpetual contracts on Hyperliquid — specifically when you want to compare how smart money, whales, and public figures are positioned relative to each other. Prefer this over general trade data endpoints when the goal is sentiment analysis or positioning intelligence across trader segments rather than individual trade records.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-10-10T18:43:25.935Z","isFirstParty":false,"canonicalSlug":"nansen-position-intelligence-2d307a23"}