---
title: "Get Address Counterparties Data"
method: POST
path: "/api/v1/profiler/address/counterparties"
tags: ["Profiler"]
---

# Get Address Counterparties Data

`POST /api/v1/profiler/address/counterparties`

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

## Request body

- ProfilerAddressCounterpartiesRequest
  - `address` string — Address to get counterparties for
  - `entity_name` string — Entity name to get counterparties for
  - `chain` 'all' | 'arbitrum' | 'avalanche' | 'base' | 'bitcoin' | 'bnb' | 'ethereum' | 'hyperevm' | 'injective' | 'iotaevm' | 'linea' | 'mantle' | 'mantra' | 'monad' | 'near' | 'optimism' | 'plasma' | 'polygon' | 'robinhood' | 'sei' | 'solana' | 'sonic' | 'starknet' | 'sui' | 'ton' | 'tron', required — Chains supported in profiler analysis.
  - `date` DateRange, required — Date range model matching the API schema.
    - `from` string — Start date in ISO 8601 format (e.g., 2025-01-01T00:00:00Z or 2025-01-01)
    - `to` string — End date in ISO 8601 format (e.g., 2025-01-31T23:59:59Z or 2025-01-31)
  - `source_input` 'Combined' | 'Tokens' | 'ETH' — Enum for source input types in counterparties endpoint.
  - `group_by` 'wallet' | 'entity' — Enum for grouping types in counterparties endpoint.
  - `filters` ProfilerAddressCounterpartiesFilters — Filters for profiler address counterparties endpoint. These filters control which counterparties and interactions are included.
    - `interaction_count` IntegerRangeFilter — Filter for integer values with optional min/max bounds. Use for counts, numbers of items, and other whole number values. - Values between 5 and 100
      - `min` integer — Minimum value (inclusive)
      - `max` integer — Maximum value (inclusive)
    - `total_volume_usd` NumericRangeFilter — Filter for numeric values (floats) with optional min/max bounds. Use for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75
      - `min` number — Minimum value (inclusive)
      - `max` number — Maximum value (inclusive)
    - `volume_in_usd` NumericRangeFilter — Filter for numeric values (floats) with optional min/max bounds. Use for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75
      - `min` number — Minimum value (inclusive)
      - `max` number — Maximum value (inclusive)
    - `volume_out_usd` NumericRangeFilter — Filter for numeric values (floats) with optional min/max bounds. Use for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75
      - `min` number — Minimum value (inclusive)
      - `max` number — Maximum value (inclusive)
    - `include_smart_money_labels` LabelType[] — Include smart money labels for counterparties
    - `exclude_smart_money_labels` LabelType[] — Exclude smart money labels for counterparties
  - `pagination` PaginationRequest — Pagination parameters for API requests.
    - `page` integer — Page number (1-based)
    - `per_page` integer — Number of records per page (max 1000)
  - `order_by` SortOrderProfilerAddressCounterpartiesSortField[] — Custom sort order to override the endpoint's default ordering. Examples: - [{"field": "total_volume_usd", "direction": "DESC"}] - Sort by total volume descending - [{"field": "interaction_count", "direction": "ASC"}] - Sort by interaction count ascending - [{"field": "volume_in_usd", "direction": "DESC"}] - Sort by incoming volume descending
    - `field` 'interaction_count' | 'total_volume_usd' | 'volume_in_usd' | 'volume_out_usd', required — Enum for sortable fields in profiler address counterparties.
    - `direction` 'ASC' | 'DESC', required — Enum for sort directions.

## Response `200`

Address counterparties data

- ProfilerAddressCounterpartiesResponse — Response model for profiler address counterparties endpoint. Contains the filtered counterparties data with metadata.
  - `pagination` PaginationInfo, required — Pagination information for API responses.
    - `page` integer — Current page number
    - `per_page` integer — Number of records per page
    - `is_last_page` boolean — Whether this is the last page
  - `data` ProfilerCounterparty[], required — List of counterparty records
    - `counterparty_address` string, required — Counterparty address in hex format
    - `counterparty_address_label` string[] — List of labels associated with this counterparty
    - `interaction_count` integer, required — Total number of interactions with this counterparty
    - `total_volume_usd` number — Total transaction volume in USD
    - `volume_in_usd` number — Incoming transaction volume in USD
    - `volume_out_usd` number — Outgoing transaction volume in USD
    - `tokens_info` TokenInfo[] — Information about tokens transferred with this counterparty
      - `token_address` string, required — Token contract address
      - `token_symbol` string, required — Token symbol
      - `token_name` string, required — Token name
      - `num_transfer` string, required — Number of transfers

## Other responses

- `400` — Bad Request - Invalid request parameters or malformed request
- `401` — Authentication error - No API key found in request
- `402` — Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.
- `403` — Forbidden - User does not have required subscription tier or has exceeded credit limit
- `404` — Not Found - The requested resource was not found
- `422` — Validation error - Invalid request parameters
- `429` — Too Many Requests - Rate limit exceeded
- `500` — Internal Server Error - An unexpected error occurred

---

[API](https://skmtc.net/nansen/apis/nansen-api.md) · [All operations](https://skmtc.net/nansen/apis/nansen-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/nansen/nansen-api/revisions/02a4d2e7d827/schema)