Skip to content
TraceFast Docs

One token contract

Open USDC on its entity page →

One token contract, as it describes itself and as the chain shows it: the standard its events follow, the symbol, name and decimals it declares, how many transfer events it has emitted, how many addresses hold it now, and how many have ever held it.

GET https://tracefast.xyz/api/v1/chains/1/tokens/{token}
ParameterInTypeNotes
tokenpathstringthe token contract, 0x-prefixed, 40 hex characters, any case

Access — an API key on the Enriched Data plan or higher (plans), or no key at all: pay per call with x402 at the same path on https://mpp.tracefast.xyz/api/v1, at the price its 402 states. As a tool for AI agents: get_token on the MCP server. Stable — see stability.

chains/1 is a literal: the method serves Ethereum mainnet data. Other chain ids answer 404 chain_not_supported. The method takes no query parameters — an unknown one is refused rather than ignored.

What it covers, and what it does not

  • The standard is observed, not declared. standard comes from the events the contract emits: erc20, erc721 or erc1155.
  • Symbol, name and decimals are verbatim. They are what the contract's symbol(), name() and decimals() return. Any contract can declare any text, so a familiar symbol is not proof of identity.
  • A missing value stays missing. A contract that declares no decimals (most NFTs, some fungible tokens) answers without the field, never with a default of 18.
  • No price. USD prices are served with the address portfolio, where each price carries its own hour.
  • A contract without transfer events is not a token here and answers 404.

Response

200 application/json:

{
  "data": {
    "chainId": 1,
    "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "standard": "erc20",
    "symbol": "USDC",
    "name": "USD Coin",
    "decimals": 6,
    "transferCount": 398022451,
    "holderCount": 9096063,
    "holderCountAllTime": 42553926
  },
  "meta": {
    "chain": "ethereum",
    "timestamp": 1792409967923,
    "cached": false,
    "docs": "https://docs.tracefast.xyz/api/token"
  }
}

data

FieldMeaning
chainId1, Ethereum mainnet
addressthe token contract, lowercase
standarderc20, erc721, erc1155, erc777 or erc4626, as observed from its events
symbolsymbol() as declared, verbatim. Absent when the contract declares none
namename() as declared, verbatim. Absent when the contract declares none
decimalsdecimals() as declared. Absent — never 18 — when the contract declares none
transferCountall-time number of transfer events
holderCounthow many addresses hold a positive balance now — the same number as holderCount of token holders. Absent — never 0 — when holders are not covered for this token, which today is every NFT collection
holderCountAllTimehow many distinct addresses have ever held the token, including those holding nothing now. Absent where it is not available for this token

The two counts answer different questions: current distribution versus lifetime reach. For USDC above, about 9 million addresses hold it now out of 42 million that ever did. An NFT collection answers with holderCountAllTime and without holderCount — its current holders are not covered, which is not the same as zero. For the current holders and their balances, use token holders.

Errors

Every error is JSON: { "error": { "code": "...", "message": "...", "details": { … } } }

StatuscodeWhendetails
404not_foundno token contract with transfer events at this address—
422block_not_availablethe contract's first transfer may lie in a coverage gap; the message names the contract ("the token contract 0x…, if its first transfer was recent, …"). Retry later — this is not "does not exist"reason: coverage_gap, coverageGapFromBlock, coverageGapToBlock, maxAvailableBlock

Malformed input, unknown parameters and the key check's 401/403/429 are the same for every method — see conventions and API keys.

Last updated 22 Oct 2026, 08:06 UTC · verified against TraceFast v1.0.261 · Markdown