Ctrlk
x-twitteryoutube
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Address Counterparties (Batch)

Batch counterparties lookup — counterparties and interaction statistics for up to 10 wallet addresses in a single request.

Batch version of Address Counterparties: fetch top counterparties for up to 10 distinct wallet addresses in a single request. Each input wallet gets its own counterparty set — results are not aggregated across wallets. Every response row carries a wallet_address field; group by it to split the flattened result back into per-wallet lists.

Common Scenarios

Usecase
Required Parameters
Expected Output

Counterparties for several EVM wallets at once

wallet_addresses = ["0x28c6...", "0x1522..."], chain = "ethereum"

Per-wallet counterparty lists with interaction stats, keyed by wallet_address

Batch across EVM chains in one request

wallet_addresses = ["0x...(eth)", "0x...(base)"], chain = "all"

Each address auto-routed to its chain; counterparties returned per wallet

Limitations

  • wallet_addresses: maximum 10 distinct addresses per request.

  • date: maximum 90 days per request; split wider windows into multiple requests.

  • chain: one ecosystem per request. Use all to batch across EVM chains (Ethereum, Base, Polygon, etc.) or solana for Solana; EVM and Solana addresses cannot be mixed in a single request.

Data Freshness & Historical Coverage

For data freshness and historical coverage, see Data Coverage by Chain; this endpoint follows it except where noted below.

  • Results are served from a server-side cache: once a requested date range has fully settled (about two days after it closes) it is cached for up to 7 days, while ranges that include today or a recently-closed window use a short cache of up to 5 minutes.

Get Address Counterparties Data (Batch)

post

Batch version of the address counterparties endpoint: fetch top counterparties for up to 10 distinct wallet addresses across a date range of up to 90 days.

Each input wallet gets its own counterparty set — results are not aggregated across the input wallets. Every row in the response carries a wallet_address field; group by it to demux the flattened result back into per-wallet counterparty lists.

Rows are returned as contiguous per-wallet blocks (each block matches what the single-wallet endpoint would return for that wallet), sorted within a block by the requested order_by (default total_volume_usd DESC).

Limitations:

  • wallet_addresses: maximum 10 distinct addresses per request.

  • date: maximum 90 days per request; split wider windows into multiple requests.

  • chain: one ecosystem per request. Use all to batch across EVM chains (Ethereum, Base, Polygon, etc.) or solana for Solana; EVM and Solana addresses cannot be mixed in a single request.

For a single wallet, or for entity-name / entity-grouped lookups, use /api/v1/profiler/address/counterparties instead.

Authorizations
apikeystringRequired

API key for authentication

Body

Request model for the batch profiler address counterparties endpoint.

Wallet-address input only (no entity_name / entity grouping — use the single-wallet /v1/profiler/address/counterparties endpoint for those).

wallet_addressesstring[] · min: 1Required

Wallet addresses to batch-query (max 10 distinct). Each address gets its own counterparty set; results are not aggregated across wallets. Every response row carries a wallet_address demux key.

Example: ["0x6df064f04ddfb2bb53da21af9d56701726700145","0xe780df05ed3d1d29b35edaf9c8f3131e9f4c799e"]
chainstring · enumRequired

Blockchain chain for the counterparties data. A single request covers one ecosystem: use all to batch addresses across EVM chains (auto-detected — Ethereum, Base, Polygon, etc. may be mixed), or solana for Solana. EVM and Solana addresses cannot be mixed in one request; query them separately.

Example: ethereumPossible values:
source_inputstring · enumOptional

Type of interactions to include

Default: CombinedPossible values:
filtersany ofOptional

Additional filters to apply. Numeric range filters (interaction_count, total_volume_usd, volume_in_usd, volume_out_usd) are applied per counterparty row; include/exclude smart money labels filter by label. Filters for columns that are not selected are ignored.

Example: {"include_smart_money_labels":["Exchange"],"total_volume_usd":{"min":1000}}
order_byany ofOptional

Sort order applied WITHIN each wallet's counterparty block.

The result is always grouped by wallet_address first (so each wallet's rows are contiguous, like an independent single-wallet response), then sorted by these fields, then by counterparty_address as a final tiebreaker to keep pagination deterministic across pages.

Defaults to total_volume_usd DESC.

Responses
200

Batch address counterparties data

application/json
post/api/v1/profiler/address/counterparties/batch
POST /api/v1/profiler/address/counterparties/batch HTTP/1.1
Host: api.nansen.ai
apikey: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 262

{
  "chain": "ethereum",
  "date": {
    "from": "2025-05-01T00:00:00Z",
    "to": "2025-05-03T23:59:59Z"
  },
  "pagination": {
    "page": 1,
    "per_page": 50
  },
  "source_input": "Combined",
  "wallet_addresses": [
    "0x6df064f04ddfb2bb53da21af9d56701726700145",
    "0xe780df05ed3d1d29b35edaf9c8f3131e9f4c799e"
  ]
}
{
  "pagination": {
    "page": 1,
    "per_page": 10,
    "is_last_page": true
  },
  "data": [
    {
      "counterparty_address": "text",
      "counterparty_address_label": [
        "text"
      ],
      "interaction_count": 1,
      "total_volume_usd": 1,
      "volume_in_usd": 1,
      "volume_out_usd": 1,
      "tokens_info": [
        {
          "token_address": "text",
          "token_symbol": "text",
          "token_name": "text",
          "num_transfer": "text",
          "total_token_amount": 14,
          "token_in_amount": 4,
          "token_out_amount": 10
        }
      ],
      "wallet_address": "text",
      "chain": "text"
    }
  ]
}
PreviousAddress Counterparties
NextAddress Related Wallets

Last updated

Was this helpful?