# Nansen Wallet Counterparties

> Nansen Wallet Counterparties is a paid API for AI agents from Nansen at api.nansen.ai, paid per call via MPP, $0.05/call, status unknown (last checked 2026-10-09).

Returns top counterparties a wallet address has interacted with, including interaction counts, volume flows, token details, and entity labels.

## Facts

- Endpoint: POST https://api.nansen.ai/api/v1/profiler/address/counterparties?utm_source=zero.xyz
- Price: $0.05/call
- Payment: MPP
- Status: unknown
- Last checked: 2026-10-09
- Activations on Zero: 0
- Provider: Nansen
- Docs: https://docs.nansen.ai
- Website: https://nansen.ai
- Tags: blockchain, smart-money, wallet, tokens, defi, analytics, profiler, dex, pnl, onchain, prediction-market, data
- Canonical page: https://www.zero.xyz/c/nansen-counterparties-abf91e6d
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_I4celWkwzRgOMFpL8bZIH

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability nansen-counterparties-abf91e6d -d '<json body>'
```

Example prompt: 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.

## When to prefer this

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.

## Known failure modes

- 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

## How this service works

Get top counterparties that wallet addresses have interacted with, supporting different
grouping options (wallet or entity) and source filtering (Combined, Tokens, ETH).
Returns interaction statistics including volume, frequency, and timing data.

What it helps to answer:

- Most frequent transaction partners by count and volume
- Net value flows between addresses (inflows vs outflows)
- Exchange and protocol interaction patterns
- DeFi protocol usage and DEX trading counterparties
- High-value transfer relationships and funding sources

## Output

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).

## Request schema (JSON Schema)

```json
{
 "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": [
            {
   
… (truncated)
```

## Response schema (JSON Schema)

```json
{
 "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 unit
… (truncated)
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/nansen-counterparties-abf91e6d/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from api.nansen.ai](https://www.zero.xyz/host/api.nansen.ai/llms.txt)