Token Transfer History

GET/gateway/v1/token/transfers

Returns recent transfer events for a specific token (ERC-20/TRC-20 contract).

Pass the token contract address in `address` — returns every on-chain transfer of that token regardless of sender/receiver.

Included fields: sender, receiver, raw amount, block timestamp.

Use this to analyze a token's on-chain activity (e.g. large movements, distribution patterns).

Lookup: `address` (token contract) + `chain`. Sort by `asc` or `desc`.

Data refresh: ~24 hours · Chains: Ethereum, Base, BSC, Arbitrum, Tron (Solana uses a different source with no delay)

Query Parameters

addressstringrequired

Token CONTRACT ADDRESS — 0x-prefixed hex for EVM chains, base58 for Solana. This is NOT a ticker symbol (e.g. do NOT pass `USDC` or `BTC`). To resolve a ticker symbol to a contract address, call GET /v1/search/token?q={symbol}&chain={chain} and use the `address` whose `chain` is supported by this endpoint. This endpoint has no `symbol` parameter.

Example: 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48

chainenum<string>required

Chain. Can be `ethereum`, `base`, `solana`, `tron`, `bsc`, or `arbitrum`.

Available options:ethereumbasesolanatronbscarbitrum

Example: ethereum

fromstring

Start of date range. Accepts Unix seconds or YYYY-MM-DD. Defaults to 30 days ago.

Example: 2025-01-01

tostring

End of date range. Accepts Unix seconds or YYYY-MM-DD. Defaults to today.

Example: 2025-03-01

limitinteger

Results per page

Example: 20

offsetinteger

Pagination offset

Example: 0

includestring

Comma-separated enrichments to attach to each transfer. Currently valid: `labels` — adds `from_label` and `to_label` fields.

Example: labels

Token Transfer History

const options = {method: 'GET'};

fetch('https://api.asksurf.ai/gateway/v1/token/transfers?address=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48&chain=ethereum&from=2025-01-01&to=2025-03-01&limit=20&offset=0&include=labels', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "$schema": "https://example.com/schemas/DataResponseTokenTransferItem.json",
  "data": [
    {
      "amount": "<string>",
      "amount_usd": 123,
      "block_number": 123,
      "from_address": "<string>",
      "from_label": {
        "address": "<string>",
        "entity_name": "<string>",
        "entity_type": "<string>",
        "labels": [
          {
            "confidence": 123,
            "label": "<string>"
          }
        ]
      },
      "symbol": "<string>",
      "timestamp": 123,
      "to_address": "<string>",
      "to_label": {
        "address": "<string>",
        "entity_name": "<string>",
        "entity_type": "<string>",
        "labels": [
          {
            "confidence": 123,
            "label": "<string>"
          }
        ]
      },
      "tx_hash": "<string>"
    }
  ],
  "meta": {
    "cached": true,
    "credits_used": 123,
    "empty_reason": "<string>",
    "has_more": true,
    "limit": 123,
    "offset": 123,
    "total": 123,
    "watermark": 123
  }
}