{"uid":"cap_I4celWkwzRgOMFpL8bZIH","slug":"nansen-counterparties-abf91e6d","name":"Nansen Wallet Counterparties","description":"Get top counterparties that wallet addresses have interacted with, supporting different\ngrouping options (wallet or entity) and source filtering (Combined, Tokens, ETH).\nReturns interaction statistics including volume, frequency, and timing data.\n\nWhat it helps to answer:\n\n- Most frequent transaction partners by count and volume\n- Net value flows between addresses (inflows vs outflows)\n- Exchange and protocol interaction patterns\n- DeFi protocol usage and DEX trading counterparties\n- High-value transfer relationships and funding sources","url":"https://api.nansen.ai/api/v1/profiler/address/counterparties?utm_source=zero.xyz","method":"POST","headers":{},"bodySchema":{"type":"object","title":"ProfilerAddressCounterpartiesRequest","examples":[{"date":{"to":"2025-05-03T23:59:59Z","from":"2025-05-01T00:00:00Z"},"chain":"ethereum","address":"0x6df064f04ddfb2bb53da21af9d56701726700145","group_by":"wallet","pagination":{"page":1,"per_page":10},"source_input":"Combined"},{"date":{"to":"2025-05-03T23:59:59Z","from":"2025-05-01T00:00:00Z"},"chain":"ethereum","group_by":"entity","pagination":{"page":1,"per_page":10},"entity_name":"Vitalik Buterin","source_input":"Combined"}],"required":["chain","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":["all","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":"ProfilerChain","description":"Chains supported in profiler analysis."},"address":{"anyOf":[{"type":"string"}],"title":"Address","examples":["0x6df064f04ddfb2bb53da21af9d56701726700145","8zFZHuSRuDpuAR7J6FzwyF3vKNx4CVW3DFHJerQhc7Zd"],"description":"Address to get counterparties for"},"filters":{"anyOf":[{"type":"object","title":"ProfilerAddressCounterpartiesFilters","properties":{"volume_in_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":1000000,"min":1000}],"description":"Volume in USD range filter"},"volume_out_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":1000000,"min":1000}],"description":"Volume out USD range filter"},"total_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":[{"max":1000000,"min":1000}],"description":"Total volume range filter in USD"},"interaction_count":{"anyOf":[{"type":"object","title":"IntegerRangeFilter","properties":{"max":{"anyOf":[{"type":"integer"}],"title":"Max","examples":[100,1000,10000],"description":"Maximum value (inclusive)"},"min":{"anyOf":[{"type":"integer"}],"title":"Min","examples":[10,100,1000],"description":"Minimum value (inclusive)"}},"description":"Filter for integer values with optional min/max bounds.\nUse for counts, numbers of items, and other whole number values. - Values between 5 and 100"}],"examples":[{"max":1000,"min":5}],"description":"Interaction count 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"]],"description":"Exclude smart money labels for counterparties"},"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"]],"description":"Include smart money labels for counterparties"}},"description":"Filters for profiler address counterparties endpoint.\n\nThese filters control which counterparties and interactions are included.","additionalProperties":false}],"examples":[{"total_volume_usd":{"min":1000},"interaction_count":{"min":5},"include_smart_money_labels":["Exchange"]}],"description":"Additional filters to apply. Only filters for columns that are being selected will be applied."},"group_by":{"enum":["wallet","entity"],"type":"string","title":"GroupBy","description":"Enum for grouping types in counterparties endpoint."},"order_by":{"anyOf":[{"type":"array","items":{"type":"object","title":"ProfilerAddressCounterpartiesSortOrder","required":["field","direction"],"properties":{"field":{"enum":["interaction_count","total_volume_usd","volume_in_usd","volume_out_usd"],"type":"string","title":"ProfilerAddressCounterpartiesSortField","description":"Enum for sortable fields in profiler address counterparties."},"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\": \"total_volume_usd\", \"direction\": \"DESC\"}] - Sort by total volume descending\n- [{\"field\": \"interaction_count\", \"direction\": \"ASC\"}] - Sort by interaction count ascending\n- [{\"field\": \"volume_in_usd\", \"direction\": \"DESC\"}] - Sort by incoming volume 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."},"entity_name":{"anyOf":[{"type":"string"}],"title":"Entity Name","examples":["Vitalik Buterin","Binance"],"description":"Entity name to get counterparties for"},"source_input":{"enum":["Combined","Tokens","ETH"],"type":"string","title":"SourceInput","description":"Enum for source input types in counterparties endpoint."}},"description":"","additionalProperties":false},"responseSchema":{"type":"object","title":"ProfilerAddressCounterpartiesResponse","required":["pagination","data"],"properties":{"data":{"type":"array","items":{"type":"object","title":"ProfilerCounterparty","required":["counterparty_address","interaction_count"],"properties":{"tokens_info":{"anyOf":[{"type":"array","items":{"type":"object","title":"TokenInfo","required":["token_address","token_symbol","token_name","num_transfer"],"properties":{"token_name":{"type":"string","title":"Token Name","description":"Token name"},"num_transfer":{"type":"string","title":"Num Transfer","description":"Number of transfers"},"token_symbol":{"type":"string","title":"Token Symbol","description":"Token symbol"},"token_address":{"type":"string","title":"Token Address","description":"Token contract address"},"token_in_amount":{"anyOf":[{"type":"number"}],"title":"Token In Amount","examples":[4,500],"description":"Amount of this token received from this counterparty, in token units, relative to the requested wallet or selected entity. Null when transferred token units cannot be determined."},"token_out_amount":{"anyOf":[{"type":"number"}],"title":"Token Out Amount","examples":[10,500],"description":"Amount of this token sent to this counterparty, in token units, relative to the requested wallet or selected entity. Null when transferred token units cannot be determined."},"total_token_amount":{"anyOf":[{"type":"number"}],"title":"Total Token Amount","examples":[14,1000],"description":"Total amount of this token transferred with this counterparty, in token units. Incoming and outgoing transfers of the same token are added together, matching total volume. Amounts of different tokens are not combined. Null when transferred token units cannot be determined."}},"description":"Token information for counterparty interactions."}}],"title":"Tokens Info","description":"Per-token transfers with this counterparty, including total, incoming, and outgoing amounts in token units. Different tokens are not combined."},"volume_in_usd":{"anyOf":[{"type":"number"}],"title":"Volume In Usd","description":"Incoming transaction volume in USD"},"volume_out_usd":{"anyOf":[{"type":"number"}],"title":"Volume Out Usd","description":"Outgoing transaction volume in USD"},"total_volume_usd":{"anyOf":[{"type":"number"}],"title":"Total Volume Usd","description":"Total transaction volume in USD"},"interaction_count":{"type":"integer","title":"Interaction Count","description":"Total number of interactions with this counterparty"},"counterparty_address":{"type":"string","title":"Counterparty Address","description":"Counterparty address in hex format"},"counterparty_address_label":{"anyOf":[{"type":"array","items":{"type":"string"}}],"title":"Counterparty Address Label","description":"List of labels associated with this counterparty"}},"description":"Individual profiler counterparty record.\n\nRepresents a counterparty that a wallet has interacted with."},"title":"Data","description":"List of counterparty 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 profiler address counterparties endpoint.\n\nContains the filtered counterparties data with metadata."},"example":null,"exampleRequest":null,"tags":["blockchain","smart-money","wallet","tokens","defi","analytics","profiler","dex","pnl","onchain","prediction-market","data"],"displayCostAmount":"0.05","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.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"}]},"paymentMethods":[{"uid":"pm_GrWZ2oKYJ4G3iWuBO8YYW","protocol":"mpp","methodType":"crypto","chain":"tempo","mode":"charge","costAmount":"0.05","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 top counterparties a wallet address has interacted with, including interaction counts, volume flows, token details, and entity labels.","exampleAgentPrompt":"Show me the top 10 counterparties for Ethereum wallet 0x28c6c06298d514db089934071355e5743bf21d60 between May 1 and May 3, 2025, grouped by wallet, across all token and ETH sources.","exampleUseCases":null,"resultDescription":"A paginated list of counterparty records, each containing the counterparty address, its Nansen entity labels, total interaction count, inbound/outbound/total volume in USD, and details of tokens transferred (symbol, name, contract address, transfer count).","failureModes":["Missing required fields (chain or date range) returns a validation error","Invalid chain enum value returns 400 bad request","No transactions found for address/date range returns empty data array","Invalid wallet address format returns an error","Pagination out of bounds returns empty results","Rate limit exceeded or insufficient credits returns 402 Payment Required"],"whenToPreferThis":"Use this endpoint when you need to understand who a wallet transacts with most — its counterparty network — including labeled entities, volume rankings, and token-level detail. Prefer this over general transaction lookup when the goal is relationship mapping, funding source discovery, or exchange/protocol usage patterns rather than inspecting individual transactions.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-10-09T18:50:20.907Z","isFirstParty":false,"canonicalSlug":"nansen-counterparties-abf91e6d"}