{"uid":"cap_4WBvkW_2gaVX6L9uI6Nwe","slug":"nansen-transfers-7d8284f5","name":"Nansen TGM Token Transfers","description":"Track all token transfer activity including direct transfers, DEX trades, and CEX movements. This endpoint is particularly useful for monitoring exchange flows - both centralized (CEX) and decentralized (DEX) - to identify accumulation or distribution patterns.","url":"https://api.nansen.ai/api/v1/tgm/transfers?utm_source=zero.xyz","method":"POST","headers":{},"bodySchema":{"type":"object","title":"TGMTransfersRequest","required":["chain","token_address","date"],"properties":{"date":{"type":"object","title":"DateRangeMaxOneYear","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 with a maximum duration of 1 year.\n\nInherits all functionality from DateRange but adds validation to ensure\nthe date range does not exceed 366 days (to account for leap years).\n\nThis limit ensures optimal query performance."},"chain":{"enum":["arbitrum","arc","avalanche","base","bitcoin","bnb","ethereum","hyperevm","injective","iotaevm","linea","mantle","mantra","monad","near","optimism","plasma","polygon","robinhood","sei","solana","sonic","starknet","sui","ton","tron"],"type":"string","title":"TGMTransfersChain","description":"Chains supported for TGM transfers endpoint."},"filters":{"anyOf":[{"type":"object","title":"TGMTransfersFilters","properties":{"to_address":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"null"}],"title":"To Address","examples":["0x28c6c06298d514db089934071355e5743bf21d60"],"description":"To address filter"},"include_cex":{"anyOf":[{"type":"boolean"}],"title":"Include Cex","examples":[true],"description":"Whether to include CEX transfers"},"include_dex":{"anyOf":[{"type":"boolean"}],"title":"Include Dex","examples":[true],"description":"Whether to include DEX transfers"},"from_address":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"null"}],"title":"From Address","examples":["0x28c6c06298d514db089934071355e5743bf21d60"],"description":"From address filter"},"transfer_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":[{"min":100}],"description":"Transfer amount range filter"},"only_smart_money":{"anyOf":[{"type":"boolean"}],"title":"Only Smart Money","examples":[true],"description":"Whether to include only smart money transfers"},"to_address_label":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"null"}],"title":"To Address Label","examples":["Smart Money","%Exchange%"],"description":"To address label filter"},"transaction_hash":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"null"}],"title":"Transaction Hash","examples":["0x61adb6da30853c5988f0204dd9f6e4abbc878e02c34030a4f707cf4ec3124bcb"],"description":"Transaction hash filter"},"transaction_type":{"anyOf":[{"type":"string"}],"title":"Transaction Type","examples":["transfer","dex_trade"],"description":"Transaction type filter"},"from_address_label":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"null"}],"title":"From Address Label","examples":["Smart Money","%Fund%"],"description":"From address label filter"},"transfer_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":1000}],"description":"Transfer value range filter in USD"},"non_exchange_transfers":{"anyOf":[{"type":"boolean"}],"title":"Non Exchange Transfers","examples":[true],"description":"Whether to include non-exchange transfers"},"to_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":"To Exclude Smart Money Labels","examples":[["Public Figure"],["Exchange"]],"description":"Exclude smart money labels for to address"},"to_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":"To Include Smart Money Labels","examples":[["Public Figure"],["Exchange"]],"description":"Include smart money labels for to address"},"from_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":"From Exclude Smart Money Labels","examples":[["Public Figure"],["Exchange"]],"description":"Exclude smart money labels for from address"},"from_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":"From Include Smart Money Labels","examples":[["Public Figure"],["Exchange"]],"description":"Include smart money labels for from address"}},"description":"Filters for TGM transfers endpoint.\n\nThese filters control which transfers are included in the analysis.","additionalProperties":false}],"examples":[{"include_cex":true,"include_dex":true,"only_smart_money":true,"non_exchange_transfers":true}],"description":"Additional filters to apply to the query."},"order_by":{"anyOf":[{"type":"array","items":{"type":"object","title":"TGMTransfersSortOrder","required":["field","direction"],"properties":{"field":{"enum":["block_timestamp","transaction_hash","from_address","to_address","from_address_label","to_address_label","transaction_type","transfer_amount","transfer_value_usd"],"type":"string","title":"TGMTransfersSortField","description":"Enum for sortable fields in TGM transfers."},"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\": \"transfer_value_usd\", \"direction\": \"ASC\"}] - Sort by transfer value ascending\n- [{\"field\": \"transfer_amount\", \"direction\": \"DESC\"}] - Sort by transfer amount descending"},"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_address":{"type":"string","title":"Token Address","examples":["0x6982508145454ce325ddbe47a25d4ec3d2311933"],"description":"Token address"}},"description":"Request model for TGM transfers endpoint.\n\nThis endpoint provides top token transfers for a specific token, with support for ERC-20 tokens. The model selection is dynamic based\non the token address.","additionalProperties":false},"responseSchema":{"type":"object","title":"TGMTransfersResponse","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"type":"object","title":"TGMTransfer","required":["block_timestamp","transaction_hash","from_address","to_address"],"properties":{"to_address":{"type":"string","title":"To Address","examples":["0x742d35cc6634c0532925a3b8d4c9db96c4b4d8b6"],"description":"to address"},"from_address":{"type":"string","title":"From Address","examples":["0x28c6c06298d514db089934071355e5743bf21d60"],"description":"from address"},"block_timestamp":{"type":"string","title":"Block Timestamp","examples":["2025-05-01T12:00:00Z"],"description":"The block timestamp for the transaction"},"transfer_amount":{"anyOf":[{"type":"number"}],"title":"Transfer Amount","examples":[1000],"description":"value of the token traded"},"to_address_label":{"anyOf":[{"type":"string"}],"title":"To Address Label","examples":["High Balance"],"description":"to address label"},"transaction_hash":{"type":"string","title":"Transaction Hash","examples":["0x1234567890abcdef..."],"description":"The transaction hash for the transaction"},"transaction_type":{"anyOf":[{"type":"string"}],"title":"Transaction Type","examples":["DEX"],"description":"Transaction type"},"from_address_label":{"anyOf":[{"type":"string"}],"title":"From Address Label","examples":["🏦 Binance 14 [0x28c6c0]"],"description":"from address label"},"transfer_value_usd":{"anyOf":[{"type":"number"}],"title":"Transfer Value Usd","examples":[2500],"description":"value of the token traded in USD"}},"description":"Individual TGM transfer record.\n\nRepresents a single token transfer with transaction details and participant information."},"title":"Data","description":"List of TGM transfer 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 transfers endpoint.\n\nContains a list of transfer 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"}]},"paymentMethods":[{"uid":"pm_qMQCa4Vhq9wYdvIHHMX2p","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":"Retrieves paginated token transfer history for a specific token on a given chain, including DEX trades, CEX movements, and direct transfers with smart money labels.","exampleAgentPrompt":"Show me all token transfers for USDC (0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48) on Ethereum between January 1 and January 31 2025, including both DEX trades and CEX movements — I want to see if big wallets are accumulating or distributing.","exampleUseCases":null,"resultDescription":"A paginated list of token transfer records, each containing the transaction hash, block timestamp, sender and receiver addresses (with Nansen smart money labels like 'Binance 14'), transfer amount in token units and USD, and transaction type (DEX, CEX, or direct transfer). Also includes pagination metadata (current page, per-page count, total records).","failureModes":["Missing required fields (chain, token_address, date) returns 422 validation error","Date range exceeding 1 year returns validation error","Unsupported chain enum value returns 422","Invalid token address format may return empty results or error","Payment not provided returns 402 Payment Required","No transfers found for given filters returns empty data array"],"whenToPreferThis":"Use this endpoint when you need granular, transaction-level token transfer data for a specific token, especially when you want to track exchange flows (CEX inflows/outflows) or DEX trade activity with Nansen's smart money address labels. Prefer this over aggregated flow endpoints when you need individual transaction hashes, timestamps, and labeled counterparties to trace specific wallets' accumulation or distribution behavior.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-10-09T18:52:06.615Z","isFirstParty":false,"canonicalSlug":"nansen-transfers-7d8284f5"}