{"uid":"cap_rceGvtRd8IuPDlviJfY2_","slug":"nansen-c8b5c368","name":"Nansen Token God Mode Perpetual Positions","description":"Get \"Token God Mode\" (TGM) perp positions data","url":"https://api.nansen.ai/api/v1/tgm/perp-positions","method":"GET","headers":{},"bodySchema":{"type":"object","title":"TGMPerpPositionsRequest","required":["token_symbol"],"properties":{"filters":{"anyOf":[{"type":"object","title":"TGMPerpPositionsFilters","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)"},"address":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"null"}],"title":"Address","examples":["0x28c6c06298d514db089934071355e5743bf21d60"],"description":"Trader address filter"},"upnl_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":"Unrealized PnL range filter in USD"},"entry_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":60000,"min":50000}],"description":"Entry price range filter"},"funding_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":"Funding range filter in USD"},"address_label":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"null"}],"title":"Address Label","examples":["Smart Money","%Fund%"],"description":"Trader label filter"},"position_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":[{"min":1.5}],"description":"Position size range filter (token amount)"},"position_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":[{"min":10000}],"description":"Position value range filter in USD"},"exclude_smart_money_labels":{"anyOf":[{"type":"array","items":{"enum":["30D Smart Trader","90D Smart Trader","180D Smart Trader","Fund","Smart Trader","Public Figure","Exchange","Whale","BananaGun Bot User","Top Maestro Bot User","Top BananaGun Bot User","Maestro Bot User","Early MAGIC Miner","First Mover LP","First Mover Staking","Profitable LP","Smart HL Perps Trader"],"type":"string","title":"LabelType","description":"Filter by entity label type."}}],"title":"Exclude Smart Money Labels","examples":[["Smart HL Perps Trader"],["Fund"]],"description":"Exclude smart money labels for traders"},"include_smart_money_labels":{"anyOf":[{"type":"array","items":{"enum":["30D Smart Trader","90D Smart Trader","180D Smart Trader","Fund","Smart Trader","Public Figure","Exchange","Whale","BananaGun Bot User","Top Maestro Bot User","Top BananaGun Bot User","Maestro Bot User","Early MAGIC Miner","First Mover LP","First Mover Staking","Profitable LP","Smart HL Perps Trader"],"type":"string","title":"LabelType","description":"Filter by entity label type."}}],"title":"Include Smart Money Labels","examples":[["Smart HL Perps Trader"],["Fund"]],"description":"Include smart money labels for traders"}},"description":"Filters for TGM perp positions endpoint.\n\nThese filters control which perp positions are included in the analysis.","additionalProperties":false}],"examples":[{"side":["Long"],"upnl_usd":{"min":0},"position_value_usd":{"min":10000},"include_smart_money_labels":["Smart HL Perps Trader","Fund"]}],"description":"Additional filters to apply to the query."},"order_by":{"anyOf":[{"type":"array","items":{"type":"object","title":"SortOrder[TGMPerpPositionsSortField]","required":["field","direction"],"properties":{"field":{"enum":["address","address_label","side","position_value_usd","position_size","leverage","entry_price","mark_price","liquidation_price","funding_usd","upnl_usd"],"type":"string","title":"TGMPerpPositionsSortField","description":"Enum for sortable fields in TGM perp positions."},"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\": \"position_value_usd\", \"direction\": \"DESC\"}] - Sort by position value USD descending\n- [{\"field\": \"upnl_usd\", \"direction\": \"ASC\"}] - Sort by unrealized PnL ascending\n- [{\"field\": \"leverage\", \"direction\": \"DESC\"}] - Sort by leverage descending"},"label_type":{"enum":["smart_money","all_traders","whale","public_figure"],"type":"string","title":"TGMPerpPositionsLabel","description":"TGM perp positions label types."},"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 positions endpoint.\n\nThis endpoint provides perp positions data for a specific token.","additionalProperties":false},"responseSchema":{"type":"object","title":"TGMPerpPositionsResponse","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"type":"object","title":"TGMPerpPosition","required":["leverage"],"properties":{"side":{"anyOf":[{"enum":["Long","Short"],"type":"string","title":"PositionSide","description":"Shared enum for position side direction."}],"examples":["Long"],"description":"Position direction (Long/Short)"},"address":{"anyOf":[{"type":"string"}],"title":"Address","examples":["0x1234567890123456789012345678901234567890"],"description":"The wallet address of the trader."},"leverage":{"type":"string","title":"Leverage","examples":["5X"],"description":"The leverage applied to the position."},"upnl_usd":{"anyOf":[{"type":"number"}],"title":"Upnl Usd","examples":[500],"description":"Unrealized profit/loss including funding."},"mark_price":{"anyOf":[{"type":"number"}],"title":"Mark Price","examples":[50500],"description":"The current mark price of the asset."},"entry_price":{"anyOf":[{"type":"number"}],"title":"Entry Price","examples":[50000],"description":"Average price where the position was opened."},"funding_usd":{"anyOf":[{"type":"number"}],"title":"Funding Usd","examples":[10.5],"description":"Net funding paid (-) or received (+) since entry."},"address_label":{"anyOf":[{"type":"string"}],"title":"Address Label","examples":["Smart Money"],"description":"Wallet or labeled entity holding the position."},"leverage_type":{"anyOf":[{"type":"string"}],"title":"Leverage Type","examples":["cross"],"description":"The type of leverage used, e.g., cross or isolated."},"position_size":{"anyOf":[{"type":"number"}],"title":"Position Size","examples":[1.5],"description":"The position size (token amount)."},"liquidation_price":{"anyOf":[{"type":"number"}],"title":"Liquidation Price","examples":[45000],"description":"The price at which the position would be liquidated."},"position_value_usd":{"anyOf":[{"type":"number"}],"title":"Position Value Usd","examples":[50000],"description":"USD notional size of the position."}},"description":"Individual TGM perp position record.\n\nRepresents a single perp position."},"title":"Data","description":"List of TGM perp position 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 positions endpoint.\n\nContains a list of perp position records with pagination and metadata."},"example":{"request":{"token_symbol":"AAVE"},"response":{"data":[{"side":"Long","address":"0xe2823659be02e0f48a4660e4da008b5e1abfdf29","leverage":"5X","upnl_usd":-1205163.5964679997,"mark_price":82.113,"entry_price":110.139,"funding_usd":-83468.348588,"address_label":"Former Smart Trader [0xe28236]","leverage_type":"cross","position_size":40023.38,"liquidation_price":22.1317675722,"position_value_usd":3286439.8019399997},{"side":"Short","address":"0x123dbca6a27005a3c4ce10cb66ee8ece8fc13bff","leverage":"10X","upnl_usd":656834.6129539998,"mark_price":82.113,"entry_price":99.1852,"funding_usd":41403.313926,"address_label":"​​Trading Bot [0x123dbc]","leverage_type":"cross","position_size":-36048.74,"liquidation_price":201.6428119918,"position_value_usd":2960070.18762},{"side":"Short","address":"0x77375a8c9d13bf79afb2a87f1b0ac1dfd5f5bf66","leverage":"10X","upnl_usd":65947.01284799993,"mark_price":82.113,"entry_price":84.1322,"funding_usd":278.671216,"address_label":"👤 mk4 [0x77375a]","leverage_type":"cross","position_size":-32521.96,"liquidation_price":430.7913544468,"position_value_usd":2670475.70148},{"side":"Short","address":"0x0514f2f3e0277c47117e3f33d9390efb0acfbdfe","leverage":"10X","upnl_usd":141869.38758800007,"mark_price":82.113,"entry_price":87.6212,"funding_usd":4164.387588,"address_label":"Former Smart Trader [0x0514f2]","leverage_type":"cross","position_size":-25000,"liquidation_price":114.4995305108,"position_value_usd":2052825},{"side":"Short","address":"0x51f63885534cb494f4592a0311551f369bff2b39","leverage":"10X","upnl_usd":335164.0869469998,"mark_price":82.113,"entry_price":96.0491,"funding_usd":34989.133329,"address_label":"High Activity [0x51f638]","leverage_type":"cross","position_size":-21539.379999999997,"liquidation_price":209.5240570198,"position_value_usd":1768663.1099399999},{"side":"Long","address":"0x051c2e6d49cf82ebc47f08f9b85800f94fc9693c","leverage":"10X","upnl_usd":-270740.3535160001,"mark_price":82.113,"entry_price":94.0104,"funding_usd":-16211.66098,"address_label":"High Balance [0x051c2e]","leverage_type":"cross","position_size":21393.64,"liquidation_price":0,"position_value_usd":1756695.96132},{"side":"Long","address":"0x3ee505ba316879d246a8fd2b3d7ee63b51b44fab","leverage":"10X","upnl_usd":-212450.52346100003,"mark_price":82.113,"entry_price":90.9521,"funding_usd":-27077.625389,"address_label":"​​🤓 brisket131: Smart HL Perps Trader [0x3ee505]","leverage_type":"cross","position_size":20971.92,"liquidation_price":11.3077778387,"position_value_usd":1722067.26696},{"side":"Long","address":"0xeadc152ac1014ace57c6b353f89adf5faffe9d55","leverage":"10X","upnl_usd":-211149.70850399992,"mark_price":82.113,"entry_price":91.8667,"funding_usd":-16075.708504,"address_label":"HL Perps Scalper [0xeadc15]","leverage_type":"cross","position_size":20000,"liquidation_price":0,"position_value_usd":1642260},{"side":"Long","address":"0x9cbf099ff424979439dfba03f00b5961784c06ce","leverage":"10X","upnl_usd":-990374.5277919999,"mark_price":82.113,"entry_price":131.4929,"funding_usd":-69385.568701,"address_label":"@brisket131 [0x9cbf09]","leverage_type":"cross","position_size":18651.09,"liquidation_price":51.5893216092,"position_value_usd":1531496.95317},{"side":"Long","address":"0x654016a8c9fcf0c4cb7ed6078aba21f7f399f7b7","leverage":"5X","upnl_usd":-128395.75110899998,"mark_price":82.113,"entry_price":89.08,"funding_usd":-16671.197359,"address_label":"HL Perps Scalper [0x654016]","leverage_type":"isolated","position_size":16036.25,"liquidation_price":63.979307514,"position_value_usd":1316784.59625}],"pagination":{"page":1,"per_page":10,"is_last_page":false}}},"exampleRequest":{"token_symbol":"AAVE"},"tags":["x402"],"displayCostAmount":"0.05","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.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"},{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.05","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_74aSGP0hwfVO94F0yNcJ4","protocol":"mpp","methodType":"crypto","chain":"tempo","mode":"charge","costAmount":"0.05","costPer":"request","priority":0,"asset":null,"unit":"request","depositMicros":null,"planRef":null},{"uid":"pm_8SO5nz8BI24Uio1Q2JhtD","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.05","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Retrieves Token God Mode (TGM) perpetual contract position data for a specific token, showing on-chain smart money perp exposure","exampleAgentPrompt":"Pull the Token God Mode perp positions data from Nansen for ETH — I want to see how smart money wallets are positioned in perpetual contracts right now, especially large longs and shorts.","exampleUseCases":null,"resultDescription":"Returns a list of perpetual contract positions for the queried token, including wallet addresses with Nansen labels, position sizes, direction (long/short), leverage, and other on-chain perp metrics reflecting smart money exposure.","failureModes":["Invalid or unrecognized token address returns an error or empty result","Token not supported on tracked perp venues returns no data","Authentication/payment failure returns 402 or 401 error","Rate limit exceeded returns 429 error","Malformed POST body returns 400 bad request","No positions found for a low-liquidity or new token"],"whenToPreferThis":"Use this endpoint when you need on-chain perpetual futures positioning data enriched with Nansen's smart money wallet labels for a specific token. Prefer this over generic DEX data endpoints when the goal is to understand institutional or whale-level perp exposure rather than spot holdings or trade history.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-09-14T00:47:36.445Z","isFirstParty":false}