# One token contract

[Open USDC on its entity page →](https://tracefast.xyz/entity/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48)

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, and how many distinct addresses have
ever held it.

```
GET https://tracefast.xyz/api/v1/chains/1/tokens/{token}
```

| Parameter | In | Type | Notes |
|---|---|---|---|
| `token` | path | string | the token contract, `0x`-prefixed, 40 hex characters, any case |

**Access** — an [API key](/api/authentication) on the **Enriched Data** plan or higher ([plans](/api/authentication#plans)), or no key at all: pay per call with [x402](/api/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](/api/mcp-server). **Stable** — see [stability](/api/conventions#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](/api/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`:

```json
{
  "data": {
    "chainId": 1,
    "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "standard": "erc20",
    "symbol": "USDC",
    "name": "USD Coin",
    "decimals": 6,
    "transferCount": 372200599,
    "holderCount": 40356949
  },
  "meta": {
    "chain": "ethereum",
    "timestamp": 1789047647507,
    "cached": false,
    "docs": "https://docs.tracefast.xyz/api/token"
  }
}
```

### `data`

| Field | Meaning |
|---|---|
| `chainId` | `1`, Ethereum mainnet |
| `address` | the token contract, lowercase |
| `standard` | `erc20`, `erc721`, `erc1155`, `erc777` or `erc4626`, as observed from its events |
| `symbol` | `symbol()` as declared, verbatim. Absent when the contract declares none |
| `name` | `name()` as declared, verbatim. Absent when the contract declares none |
| `decimals` | `decimals()` as declared. **Absent — never 18 — when the contract declares none** |
| `transferCount` | all-time number of transfer events |
| `holderCount` | all-time number of distinct holders. **Absent — never `0` — when the holder count is not available for this token** |

`holderCount` counts every address that has ever held the token. It is not
the number of holders right now — for the current holders and their balances,
use [token holders](/api/token-holders).

## Errors

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

| Status | `code` | When | `details` |
|---|---|---|---|
| 404 | `not_found` | no token contract with transfer events at this address | — |
| 422 | `block_not_available` | the 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](/api/conventions#errors) and [API keys](/api/authentication#when-a-key-is-refused).

## Related pages

* [Token holders](/api/token-holders) — who holds the token now
* [Transfers of a token](/api/token-transfers) — its transfer events, newest first
* [Token statistics](/api/token-stats) — the same counts for the whole network
* [Tokens & Assets](/explorer/entity/tokens) — the token's entity page in the app