{"uid":"cap_rP-GTBPfbirEI89TIpRon","slug":"nansen-who-bought-sold-adf54581","name":"Nansen Who Bought Sold","description":"This endpoint provides an aggregated summary of trade volumes in USD for addresses. It can be used to identify addresses that are net buyers or sellers of a token within a time period.","url":"https://api.nansen.ai/api/v1/tgm/who-bought-sold?utm_source=zero.xyz","method":"POST","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","arc","avalanche","base","bnb","ethereum","hyperevm","hyperliquid","injective","iotaevm","linea","mantle","mantra","monad","near","optimism","plasma","polygon","robinhood","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":"TGMWhoBoughtSoldSortOrder","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":["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"},{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.01","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_QQUwc3wroZ_dLzllOOfnI","protocol":"mpp","methodType":"crypto","chain":"tempo","mode":"charge","costAmount":"0.01","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null},{"uid":"pm_eCzaGs2ywocYWMCBRvN7n","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.01","costPer":"request","priority":0,"asset":null,"unit":"request","depositMicros":null,"planRef":null}],"brandName":"Nansen","brandSlug":"nansen","brandBaseUrl":"https://nansen.ai","brandDocsUrl":"https://docs.nansen.ai","whatItDoes":"Returns aggregated buy/sell trade volumes in USD for wallet addresses trading a specific token within a given time range, enabling identification of net buyers and sellers.","exampleAgentPrompt":"Who are the top net buyers of the token at address 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 on Ethereum between January 1 and January 31 2025, with a minimum bought volume of $10,000 USD?","exampleUseCases":[{"title":"Track whale accumulation patterns","prompt":"Show me which wallets have been accumulating the most ETH on Ethereum over the last 30 days, focusing on addresses that bought more than $50,000 USD worth."},{"title":"Identify smart money sellers","prompt":"Which labeled smart money addresses are net sellers of USDC on Solana this week? I want to see the top 20 by sold volume in USD."},{"title":"Monitor DeFi protocol buyers","prompt":"Find all addresses that were net buyers of this Arbitrum DeFi token in the last 7 days with at least $5,000 USD in purchases - I need to understand who's accumulating."}],"resultDescription":"Returns a paginated list of wallet addresses with their aggregated bought volume in USD, sold volume in USD, net trade volume in USD, and corresponding token volumes for the specified token and time period. Each record may include an address label (e.g. 'High Gas Consumer') if Nansen has classified the wallet. Pagination metadata indicates current page and whether more results exist.","failureModes":["Missing required fields (chain, token_address, date) returns 400 validation error","Invalid chain enum value returns 400 with list of supported chains","Token address not found or not tracked on the specified chain returns empty data array","Date range too broad may time out or return partial results","Invalid ISO 8601 date format returns 400 parse error","Insufficient API credits or unauthorized access returns 402 or 401","Pagination page exceeding available records returns empty data with is_last_page=true"],"whenToPreferThis":"Use this endpoint when you need to identify who is buying or selling a specific token, rank wallets by trade volume, or detect accumulation/distribution patterns. Prefer over generic token analytics when you need per-wallet buy/sell breakdown with USD values. Best for smart money flow analysis, whale tracking, and identifying net buyers vs sellers of a token in a defined time window across any of the 25+ supported chains.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-10-09T18:51:51.634Z","isFirstParty":false,"canonicalSlug":"nansen-who-bought-sold-adf54581"}