POST

/v1/counterparties

Who an address transacts with, with labels, token flows and transaction counts. Requires a category, filter or kinds selector.

Returns the addresses on the other side of the transaction history, each with its label and category where known, its kind (personal, venue, hub, deposit_wallet, contract, mint_burn, unknown), per-token sent and received amounts with transaction counts, and first and last activity. The kind selector is what separates a person from an exchange hub: a counterparty with an enormous degree is infrastructure, not a peer, and the two should not be read the same way.

Request

curl -X POST https://intelapi.publicaml.org/v1/counterparties \
  -H 'Content-Type: application/json' \
  -d '{
  "wallet_address": "0x…",
  "chain": "ETH",
  "kinds": ["venue"],
  "limit": 20
}'

Response

{
  "wallet_address": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
  "chain": "ETH",
  "counterparties": [
    {
      "address": "0x9008d19f58aabd9ed0d60971565aa8510560ab41",
      "label": "CoW Protocol",
      "category": "dex-aggregator",
      "kind": "venue",
      "kind_reason": "term_index:dex-aggregator",
      "tx_count": 85,
      "received_usd": 1814701.45,
      "sent_usd": 0.0,
      "first_ts": 1669829687,
      "last_ts": 1784042435,
      "tokens": [
        {
          "symbol": "USDC",
          "token": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
          "decimals": 6,
          "received": 1000738.135833,
          "received_tx_count": 6,
          "sent": 0.0,
          "sent_tx_count": 0
        }
      ],
      "usd_coverage": {
        "complete": false,
        "priced_edges": 39,
        "unpriced_edges": 87
      }
    }
  ]
}

Response fields

Field	Type	Meaning
counterparties[].label	string	Entity name, when known.
counterparties[].kind	string	personal, venue, hub, deposit_wallet, contract, mint_burn or unknown. Derived from degree and terminality, not from the label alone.
counterparties[].tokens[]	array	Per-token sent/received amounts and transaction counts, with decimals.
counterparties[].usd_coverage	object	How much of the flow could be priced. complete:false means the USD figures cover only priced_edges of priced_edges+unpriced_edges.

Things that catch people out

One of filter[], category or kinds[] is required. Sending only wallet_address and chain returns 400 with "one of filter[], category or kinds[] is required".
Valid kinds are personal, venue, hub, deposit_wallet, contract, mint_burn, unknown. An entity category such as "cex" is not a kind - pass it as category.
Read usd_coverage before quoting a USD number. When complete is false the total is a floor, not the whole flow.

Try it

The interactive console runs this endpoint against live data from the browser, with no key and no signup.

Open the sandbox at intelapi.publicaml.org