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

# TokenRegistry

> Token metadata lookup by symbol or address, with built-in presets for StarkNet mainnet and Sepolia.

<Warning>
  `@chipi-stack/core` is in development (v0.1.0). APIs may change before stable release.
</Warning>

## Overview

`TokenRegistry` provides a lookup table for token metadata (symbol, decimals, address, name) on StarkNet networks. It ships with built-in presets for mainnet and Sepolia, eliminating the need to hardcode token addresses.

## Usage

```typescript theme={null}
import { TokenRegistry, Amount } from "@chipi-stack/core";

const registry = new TokenRegistry("mainnet");
const usdc = registry.bySymbol("USDC")!;

console.log(usdc.address);  // "0x033068F6539..."
console.log(usdc.decimals); // 6

// Use with Amount
const amount = Amount.parse("10.0", usdc);
```

## Constructor

```typescript theme={null}
new TokenRegistry(network: "mainnet" | "sepolia")
```

### Parameters

* `network` (`"mainnet"` | `"sepolia"`): The StarkNet network to load presets for

### Throws

* If `network` is not `"mainnet"` or `"sepolia"`

## Methods

### `bySymbol(symbol)`

Find a token by its symbol (case-insensitive).

```typescript theme={null}
const eth = registry.bySymbol("ETH");
const usdc = registry.bySymbol("usdc"); // case-insensitive
```

#### Parameters

* `symbol` (string): Token symbol (e.g., `"USDC"`, `"ETH"`)

#### Returns

`TokenEntry | undefined`

### `byAddress(address)`

Find a token by its contract address (case-insensitive).

```typescript theme={null}
// Native USDC on Starknet mainnet (not USDC.e bridged)
const token = registry.byAddress("0x033068F6539f8e6e6b131e6B2B814e6c34A5224bC66947c47DaB9dFeE93b35fb");
console.log(token?.symbol); // "USDC"
```

#### Parameters

* `address` (string): Token contract address

#### Returns

`TokenEntry | undefined`

### `all()`

List all tokens in this registry.

```typescript theme={null}
const tokens = registry.all();
console.log(tokens.map(t => t.symbol)); // ["ETH", "USDC", "USDT", "DAI", "STRK", "WBTC"]
```

#### Returns

`TokenEntry[]`

## Built-in Presets

### Mainnet

| Symbol | Decimals | Name            |
| ------ | -------- | --------------- |
| ETH    | 18       | Ether           |
| USDC   | 6        | USD Coin        |
| USDT   | 6        | Tether USD      |
| DAI    | 18       | Dai Stablecoin  |
| STRK   | 18       | Starknet Token  |
| WBTC   | 8        | Wrapped Bitcoin |

### Sepolia (Testnet)

| Symbol | Decimals | Name               |
| ------ | -------- | ------------------ |
| ETH    | 18       | Ether              |
| USDC   | 6        | USD Coin (Testnet) |
| STRK   | 18       | Starknet Token     |

## TokenEntry Type

```typescript theme={null}
interface TokenEntry {
  symbol: string;   // e.g., "USDC"
  decimals: number;  // e.g., 6
  address: string;   // StarkNet contract address
  name: string;      // e.g., "USD Coin"
}
```

`TokenEntry` extends `TokenInfo` (used by `Amount.parse()`) with an additional `name` field.

## Example

```typescript theme={null}
import { TokenRegistry, Amount, Erc20 } from "@chipi-stack/core";

// Set up registry for the target network
const network = process.env.STARKNET_NETWORK === "mainnet" ? "mainnet" : "sepolia";
const registry = new TokenRegistry(network);

// Look up token and create typed wrapper
const usdcInfo = registry.bySymbol("USDC");
if (!usdcInfo) throw new Error("USDC not found in registry");

const usdc = new Erc20(usdcInfo, account);
const amount = Amount.parse("50.0", usdcInfo);

const balance = await usdc.balanceOf(myAddress);
console.log(`Balance: ${balance.toFormatted()}`);
```

## Related

* [Amount](/sdk/core/amount): Use TokenEntry from the registry with `Amount.parse()`
* [Erc20](/sdk/core/erc20): Pass TokenEntry to the Erc20 constructor