Top Transfer Counterparties

GET/gateway/v1/token/transfer-counterparties

Ranked top counterparties (receivers or senders) of a token over a window — answers "who are the top receivers/senders?".

Lookup: `address` (token contract) + `chain` + `direction` (`to` = top receivers, `from` = top senders). Rank by `metric` (`count`, `amount`, `amount_usd`).

Related: raw rows → `/v1/token/transfers`; aggregate summary → `/v1/token/transfer-stats`.

Chains: Ethereum, Base, BSC, Arbitrum, Tron · Refresh: ~24h

Query Parameters

addressstringrequired

Token CONTRACT ADDRESS (0x-hex for EVM; Tron accepts base58 `T...` or 0x-hex). Not a ticker — resolve a symbol via GET /v1/search/token?q={symbol}&chain={chain} and use a returned address whose chain is supported by this endpoint.

Example: 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48

chainenum<string>required

Chain the token contract is deployed on.

Available options:ethereumbasebscarbitrumtron

Example: ethereum

directionenum<string>required

Ranking direction: `to` = top receivers, `from` = top senders.

Available options:tofrom

Example: to

metricenum<string>

Ranking key: `count` = transfer frequency, `amount` = decimal-adjusted token sum, `amount_usd` = USD value sum (USD lags ~3 days; unreliable for recent windows).

Available options:countamountamount_usd

time_rangeenum<string>

Look-back window (hard 90d cap).

Available options:1d7d30d90d

limitinteger

Results per page.

offsetinteger

Pagination offset.

includestring

Comma-separated enrichments. `labels` attaches an entity label per counterparty.

Example: labels

exclude_labelsstring

Comma-separated entity categories to drop (best-effort): `cex`, `router`, `amm`, `bridge`. Results may be fewer than `limit` when top counterparties are infrastructure.

Example: cex,router

Top Transfer Counterparties

const options = {method: 'GET'};

fetch('https://api.asksurf.ai/gateway/v1/token/transfer-counterparties?address=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48&chain=ethereum&direction=to&include=labels&exclude_labels=cex,router', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "$schema": "https://example.com/schemas/DataResponseTransferCounterpartyItem.json",
  "data": [
    {
      "amount": "<string>",
      "amount_usd": 123,
      "counterparty_address": "<string>",
      "first_transfer_at": 123,
      "label": {
        "address": "<string>",
        "entity_name": "<string>",
        "entity_type": "<string>",
        "labels": [
          {
            "confidence": 123,
            "label": "<string>"
          }
        ]
      },
      "last_transfer_at": 123,
      "transfer_count": 123
    }
  ],
  "meta": {
    "cached": true,
    "credits_used": 123,
    "empty_reason": "<string>",
    "has_more": true,
    "limit": 123,
    "offset": 123,
    "total": 123,
    "watermark": 123
  }
}