{"uid":"cap_jjJRuNmqvA_hxq60qF0dg","slug":"api-nansen-ai-e3f2f74a","name":"Nansen Token God Mode - Who Bought/Sold","description":"Get \"Token God Mode\" (TGM) who bought/sold data","url":"https://api.nansen.ai/api/v1/tgm/who-bought-sold?utm_source=zero.xyz","method":"GET","headers":{},"bodySchema":{"type":"object","title":"TGMWhoBoughtSoldRequest","required":["chain","token_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."},"chain":{"enum":["arbitrum","avalanche","base","bnb","ethereum","hyperevm","injective","iotaevm","linea","mantle","mantra","monad","near","optimism","plasma","polygon","ronin","scroll","sei","solana","sonic","starknet","sui","ton","tron"],"type":"string","title":"TGMChain","description":"Chains supported in TGM (Token God Mode) endpoints."},"filters":{"anyOf":[{"type":"object","title":"TGMWhoBoughtSoldFilters","properties":{"address":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"null"}],"title":"Address","examples":["0x28c6c06298d514db089934071355e5743bf21d60"],"description":"Trader address filter"},"address_label":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"null"}],"title":"Address Label","examples":["High Gas Consumer"],"description":"Trader label filter"},"sold_volume_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":1000}],"description":"Sold volume range filter in USD"},"trade_volume_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":1000}],"description":"Total trade volume range filter in USD"},"bought_volume_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":1000}],"description":"Bought volume range filter in USD"},"sold_token_volume":{"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":1000}],"description":"Sold token volume range filter"},"token_trade_volume":{"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":1000}],"description":"Total token trade volume range filter"},"bought_token_volume":{"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":1000}],"description":"Bought token volume range filter"},"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":[["Public Figure"],["Exchange"],["Smart HL Perps Trader"]],"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":[["Public Figure"],["Exchange"],["Smart HL Perps Trader"]],"description":"Include smart money labels for traders"}},"description":"Filters for TGM who bought/sold endpoint.\n\nThese filters control which traders and trade data are included.","additionalProperties":false}],"examples":[{"trade_volume_usd":{"min":1},"include_smart_money_labels":["Whale","Smart Trader"]},{"trade_volume_usd":{"min":1000},"include_smart_money_labels":["Smart HL Perps Trader"]}],"description":"Additional filters to apply to the query."},"order_by":{"anyOf":[{"type":"array","items":{"type":"object","title":"SortOrder[TGMWhoBoughtSoldSortField]","required":["field","direction"],"properties":{"field":{"enum":["bought_volume_usd","sold_volume_usd","token_trade_volume","trade_volume_usd","bought_token_volume","sold_token_volume"],"type":"string","title":"TGMWhoBoughtSoldSortField","description":"Sortable fields for TGM who-bought-sold endpoint."},"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\": \"bought_volume_usd\", \"direction\": \"DESC\"}] - Sort by bought volume descending\n- [{\"field\": \"sold_volume_usd\", \"direction\": \"ASC\"}] - Sort by sold volume 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."},"buy_or_sell":{"enum":["BUY","SELL"],"type":"string","title":"TGMWhoBoughtSoldType","description":"TGM who bought/sold type."},"token_address":{"type":"string","title":"Token Address","examples":["2zMMhcVQEXDtdE6vsFS7S7D5oUodfJHE8vd1gnBouauv"],"description":"Address of token"}},"description":"Request model for TGM who bought/sold endpoint.\n\nThis endpoint provides an aggregated summary of trade volumes in USD for addresses\ninvolved in DEX (Decentralized Exchange) trades for a specific token.","additionalProperties":false},"responseSchema":{"type":"object","title":"TGMWhoBoughtSoldResponse","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"type":"object","title":"TGMWhoBoughtSold","required":["address"],"properties":{"address":{"type":"string","title":"Address","examples":["0x1234567890123456789012345678901234567890"],"description":"The address that did the trades"},"address_label":{"anyOf":[{"type":"string"}],"title":"Address Label","examples":["High Gas Consumer"],"description":"Label associated with the address"},"sold_volume_usd":{"anyOf":[{"type":"number"}],"title":"Sold Volume Usd","examples":[12500],"description":"The aggregate sold volume in USD for the address"},"trade_volume_usd":{"anyOf":[{"type":"number"}],"title":"Trade Volume Usd","examples":[12500],"description":"The net trade volume in USD for the address"},"bought_volume_usd":{"anyOf":[{"type":"number"}],"title":"Bought Volume Usd","examples":[25000],"description":"The aggregate bought volume in USD for the address"},"sold_token_volume":{"anyOf":[{"type":"number"}],"title":"Sold Token Volume","examples":[500.25],"description":"The aggregate sold token volume for the address"},"token_trade_volume":{"anyOf":[{"type":"number"}],"title":"Token Trade Volume","examples":[500.25],"description":"The net token trade volume for the address"},"bought_token_volume":{"anyOf":[{"type":"number"}],"title":"Bought Token Volume","examples":[1000.5],"description":"The aggregate bought token volume for the address"}},"description":"Individual TGM who bought/sold record.\n\nRepresents a single address with aggregated trade volumes."},"title":"Data","description":"List of TGM who bought/sold 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 who bought/sold endpoint.\n\nContains a list of address 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":"x402","network":"base","amountUsd":"0.01","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.01","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_ew6c2rUVO6aawO39pm52Q","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":"Returns on-chain data about which wallets bought or sold a specific token, filterable by chain, date range, and smart money labels","exampleAgentPrompt":"Using Nansen Token God Mode, show me who bought the token at address 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 on Ethereum over the past 7 days — filter for buy transactions and sort by largest volume first.","exampleUseCases":null,"resultDescription":"A list of wallet addresses and associated transaction data showing which addresses bought or sold the specified token on the given chain within the date range, potentially including smart money labels, trade sizes, and timestamps.","failureModes":["Invalid token address returns empty results or 400 error","Unsupported chain identifier causes validation error","Date range too wide may result in pagination limits or timeouts","Missing required parameters (token_address, buy_or_sell) return 422 validation error","Payment failure returns 402 when USDC balance is insufficient","Chain not supported by TGM endpoints returns error"],"whenToPreferThis":"Use this endpoint when you need to identify specific wallets that bought or sold a token — especially for smart money tracking, whale watching, or detecting accumulation/distribution patterns. Prefer this over general token screeners when the focus is WHO traded (wallet-level), not just price or volume metrics.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-10-13T06:54:02.051Z","isFirstParty":false,"canonicalSlug":"api-nansen-ai-e3f2f74a"}