> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blockdb.io/llms.txt
> Use this file to discover all available pages before exploring further.

# ERC-20 Tokens

> Production-grade ERC-20 token registry with name, symbol & decimals verified across 10 EVM chains. REST API and bulk export.

## Overview

* **Dataset ID:** `0201`
* **Table:** `blockdb_evm.b0201_erc20_tokens_v1`
* **Description:** Catalog of ERC-20 token contracts (EIP-20).
* **Stable id:** `contract_id` (per deployment incarnation; multiple snapshot rows possible—see callout)
* **API:** [POST /evm/entities/tokens/erc20](/api-reference/evm/entities/tokens-erc20)
* **CSV Sample:** [Download](https://huggingface.co/datasets/BlockDB/ERC20-Tokens-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0201_erc20_tokens_v1.csv?download=true)
* **JSON Sample:** [Download](https://huggingface.co/datasets/BlockDB/ERC20-Tokens-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0201_erc20_tokens_v1.json?download=true)

### How we recognize ERC-20

We treat a contract as ERC-20 when it implements the [EIP-20 Token Standard](https://eips.ethereum.org/EIPS/eip-20). Detection requires that the contract exposes and returns valid results for the **three mandatory** EIP-20 functions: `totalSupply()`, `balanceOf(address)`, and `allowance(address, address)`. We call these at the block where the contract is first seen and only add the address to this catalog if all three calls succeed and return decodable data. The **optional** EIP-20 metadata — `name()`, `symbol()`, and `decimals()` — are read when present and stored in the table; they may be null for tokens that do not implement them.

<Callout icon="lightbulb" color="#3B82F6" iconType="regular">
  This table is **append-only**: the same `contract_id` can have **multiple rows** when an upgradeable proxy swaps implementation—we append refreshed view reads at **`upgradeBlock + 1`** with **`tx_index = -1`** (genesis rows use a normal tx index). For **current** metadata, take the **latest** `block_number` per `contract_id` (for point-in-time, add `block_number <= $target` first). Join on **`contract_id`**, not `contract_address` alone—redeploys at the same address get a new `contract_id`.
</Callout>

## Sample Viewer

<Frame>
  <iframe src="https://huggingface.co/datasets/BlockDB/ERC20-Tokens-Ethereum-And-EVM-Cryptocurrency-Data/embed/viewer/default/train" frameborder="0" width="100%" height="600px" />
</Frame>

## Columns

| Column                | Type          | Description                                                                               |
| --------------------- | ------------- | ----------------------------------------------------------------------------------------- |
| `contract_id`         | `BYTEA`       | Unique contract incarnation ID: 20B address + 4B creation block (BE) + 2B tx\_index (BE). |
| `contract_address`    | `BYTEA`       | Address of the ERC-20 token contract (20 bytes).                                          |
| `block_number`        | `BIGINT`      | Block of the log we attribute as the genesis/recognition point.                           |
| `block_time`          | `TIMESTAMPTZ` | UTC timestamp of the block.                                                               |
| `tx_index`            | `INTEGER`     | Transaction index in the block, or **`-1`** for proxy-upgrade refresh rows (see callout). |
| `name`                | `TEXT`        | Token name from name() (optional in EIP-20).                                              |
| `symbol`              | `TEXT`        | Token symbol from symbol() (optional in EIP-20).                                          |
| `decimals`            | `SMALLINT`    | Decimals from decimals() (optional in EIP-20; e.g. 8 = divide by 10^8).                   |
| `_tracing_id`         | `BYTEA`       | Tracing ID of this ERC-20 token record.                                                   |
| `_parent_tracing_ids` | `BYTEA[]`     | Tracing IDs of the parent records leading to this ERC-20 token record.                    |
| `_created_at`         | `TIMESTAMPTZ` | Record creation timestamp.                                                                |
| `_updated_at`         | `TIMESTAMPTZ` | Record last update timestamp.                                                             |

## Use Cases

* Token registry to normalize joins for swaps, transfers, pools, and prices
* Amount scaling via decimals for analytics, PnL, and model features
* App backends: display names/symbols and validate token addresses

## Related Datasets

<CardGroup cols={3}>
  <Card title="Token Transfers" icon="coins" href="/data-catalog/evm/transfers/token-transfers">
    ERC-20 transfer events for these tokens.
  </Card>

  <Card title="Liquidity Pools" icon="water" href="/data-catalog/evm/entities/liquidity-pools">
    Pools where these tokens are paired.
  </Card>

  <Card title="ERC-721 Tokens" icon="image" href="/data-catalog/evm/entities/erc721-tokens">
    NFT token registry for cross-standard analysis.
  </Card>
</CardGroup>