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

# Token list

> The Uniswap-standard token list for Whitechain: where it is served, what it contains, how to load it in a dapp or wallet, and how to add a token to it.

<Note>
  The list covers Whitechain Sepolia (chain ID `1874`) only. Whitechain Mainnet is not live, so it holds no mainnet entries. The generator handles several chains per token, so mainnet addresses go into the same list at Mainnet launch.
</Note>

Whitechain publishes a [Uniswap-standard token list](https://github.com/Uniswap/token-lists), so a wallet or a swap interface can load the token set at runtime instead of carrying hardcoded addresses. The list is a single JSON file, validated against the official `@uniswap/token-lists` schema before it ships.

| Artifact   | URL                                                      |
| ---------- | -------------------------------------------------------- |
| Token list | `https://whitechain.io/tokens/whitechain.tokenlist.json` |
| List logo  | `https://whitechain.io/tokens/whitechain_logo.svg`       |
| Token logo | `https://whitechain.io/tokens/data/<SYMBOL>/logo.svg`    |

The file is public, static, and needs no key. Serve it straight to a client or cache it behind your own origin.

## What the list contains

| Symbol | Name                      | Decimals | Chain ID | Address                                                                                                                                   |
| ------ | ------------------------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| USDT.e | Bridged USDT (Whitechain) | 6        | `1874`   | [`0xaa7962d073935D387e8d442DA1D7149C81388f46`](https://explorer.testnet.whitechain.io/address/0xaa7962d073935D387e8d442DA1D7149C81388f46) |
| WWBT   | Wrapped WhiteBIT Coin     | 18       | `1874`   | [`0x4200000000000000000000000000000000000006`](https://explorer.testnet.whitechain.io/address/0x4200000000000000000000000000000000000006) |

`WWBT` is the ERC-20 form of WBT, the native gas token. A list entry needs a contract address and a native coin has none, so the wrapped contract is what appears. The [Portal bridge](/build/bridge/portal-bridge#token-addresses) lists the same contract under the same symbol.

The bridge carries more than the list holds. Its Whitechain Sepolia table also has `USDC.e` and `ETH`, which have no entry here. A token joins the list when someone opens a pull request for it, so the list tracks what has been submitted rather than what is bridgeable.

Every address in the list is checksummed per EIP-55, and every `chainId` resolves to a network the build knows about. Both are asserted by the validator, so a list that ships has passed them.

Alongside `tokens`, the file carries a `name`, a `logoURI`, `keywords`, a `timestamp`, and a `version` object with `major`, `minor`, and `patch` fields. The [token-lists specification](https://github.com/Uniswap/token-lists) defines what each version field means for a consumer deciding whether to refresh.

## Load the list in a dapp

Fetch the file and filter by the chain your app is connected to:

```ts theme={null}
const CHAIN_ID = 1874; // Whitechain Sepolia

const res = await fetch("https://whitechain.io/tokens/whitechain.tokenlist.json");
if (!res.ok) throw new Error(`token list: ${res.status}`);

const list = await res.json();
const tokens = list.tokens.filter((t) => t.chainId === CHAIN_ID);
```

Each entry carries `chainId`, `address`, `name`, `symbol`, `decimals`, and `logoURI`, which is what a token selector needs to render a row and build a transfer.

Read `list.version` and `list.timestamp` to decide when to refetch. Pin a copy in your build if you need the token set to be stable across a release, and treat the hosted file as the source you reconcile against.

Interfaces that accept a token list URL, such as a Uniswap-derived swap UI, take `https://whitechain.io/tokens/whitechain.tokenlist.json` directly.

## Add a token

The list is generated from per-token source files, so you add a token by adding its folder and regenerating. Source lives in [`whitechain-labs/templates/whitechain-token-lists`](https://github.com/whitechain-labs/templates/tree/main/whitechain-token-lists).

1. Fork the repository and create `data/<SYMBOL>/`, named for the token symbol.

2. Add `data.json`:

   ```json data/WWBT/data.json theme={null}
   {
     "name": "Wrapped WhiteBIT Coin",
     "symbol": "WWBT",
     "decimals": 18,
     "description": "Short human-readable description.",
     "website": "https://example.com",
     "twitter": "@handle",
     "tokens": {
       "whitechain-testnet": {
         "address": "0x4200000000000000000000000000000000000006"
       }
     }
   }
   ```

3. Add `logo.svg`, 256 by 256, in the same folder.

4. Run `npm run generate` and commit both your `data/` changes and the regenerated `whitechain.tokenlist.json`.

5. Open a pull request.

The keys under `tokens` are network names, not chain IDs. They are defined in `src/chains.ts`, which maps `whitechain-testnet` to `1874` and is the single place a new network is added. The build resolves each name to its chain ID. To list one token on several networks, add another key under `tokens`; each becomes its own entry in the output.

Write the `address` in its EIP-55 checksummed form. `generate` normalizes an all-lowercase address to that form for you, but a mixed-case address whose checksum is wrong throws and stops the build. `validate` then requires the address in the generated list to be checksummed, so an address hand-edited into `whitechain.tokenlist.json` fails there.

## Run the tooling

The repository needs Node 20 or newer and npm.

```bash Terminal theme={null}
npx degit whitechain-labs/templates/whitechain-token-lists whitechain-token-lists
cd whitechain-token-lists
npm install
```

| Command            | What it does                                                                                                                                                                                                                               |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `npm run generate` | Reads every `data/<SYMBOL>/data.json`, resolves each network name to its chain ID, and rewrites `whitechain.tokenlist.json`. Sorts by symbol then chain ID, bumps the version, and sets a fresh timestamp.                                 |
| `npm run validate` | Checks the committed `whitechain.tokenlist.json` against the `@uniswap/token-lists` schema, asserts every address is a checksummed 40-hex EVM address, and asserts every chain ID exists in the chain config. Exits non-zero on any error. |

`generate` validates in memory before it writes, so it cannot emit an invalid list.

Use `degit` to run the tooling and inspect the output. To propose a token, fork the repository instead, because `degit` copies the tree without git history.

## How the list is published

Two workflows own the file.

| Workflow       | Trigger            | What it does                                                                                          |
| -------------- | ------------------ | ----------------------------------------------------------------------------------------------------- |
| `validate.yml` | Every pull request | Installs, checks the committed list is up to date with `data/`, then runs `npm run validate`.         |
| `publish.yml`  | Merge to `main`    | Regenerates and validates, commits the refreshed list if it changed, and deploys the repository root. |

The repository root is served verbatim under `https://whitechain.io/tokens/`, which is why a logo at `data/WWBT/logo.svg` in the repository answers at `https://whitechain.io/tokens/data/WWBT/logo.svg`.

## Related

* [Network reference](/learn/network/reference) for chain IDs and endpoints
* [Portal bridge](/build/bridge/portal-bridge) for the contract addresses of bridged assets
* [Wallets](/build/wallet/wallets) for adding Whitechain to a wallet