@yodlpay/tokenlists

Chains, tokens, and router ABIs for the Yodl Web3 Payment Network.

Installation

npm install @yodlpay/tokenlists
# or
yarn add @yodlpay/tokenlists

Usage

Chains

import {
  chains,
  getChainById,
  getShortNames,
  getNativeToken,
  getRouter,
  getRouterByAddress,
  type YodlChain,
  type RouterConfig,
  type YodlChainExtension
} from '@yodlpay/tokenlists';

// Get all supported chains
const allChains = chains;

// Get chain by ID
const arbitrum = getChainById(42161);

// Get router config for a chain
const router = getRouter(1);
// { address: '0x...', version: '0.8', fee: '0.002' }

// Get native token symbol
const symbol = getNativeToken(1); // 'ETH'

Tokens

import {
  tokenlist,
  getTokens,
  getTokenByAddress,
  getTokenBySymbol,
  getFeaturedTokenBySymbol,
  getNativeWrappedToken,
  type TokenInfo
} from '@yodlpay/tokenlists';

// Get all tokens
const allTokens = tokenlist;

// Get tokens for a specific chain
const ethereumTokens = getTokens(1);

// Find token by address
const usdc = getTokenByAddress('0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48', 1);

// Find token by symbol
const dai = getTokenBySymbol('DAI', 1);

// Get wrapped native token
const weth = getNativeWrappedToken(1);

Stablecoins

Stablecoin peg information is stored directly in token extensions via the peggedTo field:

import {
  getTokenBySymbol,
  type FiatCurrency,
  type TokenInfo
} from '@yodlpay/tokenlists';

// Get a token and check if it's a stablecoin
const usdc = getTokenBySymbol('USDC', 1);

// Check the peggedTo field in extensions
if (usdc.extensions?.peggedTo) {
  console.log(`${usdc.symbol} is pegged to ${usdc.extensions.peggedTo}`);
  // "USDC is pegged to USD"
}

// Filter tokens by peg currency
import { tokenlist } from '@yodlpay/tokenlists';

const eurStablecoins = tokenlist.filter(
  (token) => token.extensions?.peggedTo === 'EUR'
);

Supported fiat currencies: USD, EUR, CHF, BRL, IDR, GBP, JPY, KRW, SGD, AUD, MXN, CNY, TRY

Router ABIs

import {
  getRouterAbi,
  YODL_ROUTER_ABIS,
  type AbiVersion
} from '@yodlpay/tokenlists';

// Get ABI for a specific version
const abiV08 = getRouterAbi('0.8');

// Use with viem
import { getContract } from 'viem';

const router = getContract({
  address: '0x...',
  abi: getRouterAbi('0.8'),
  client,
});

Supported Chains

Mainnets

• Ethereum (1)
• Arbitrum (42161)
• Optimism (10)
• Base (8453)
• Polygon (137)
• Gnosis (100)
• BSC (56)

Testnets

• Arbitrum Sepolia (421614)
• BSC Testnet (97)

Development

# Install dependencies
yarn install

# Run tests
yarn test

# Build
yarn build

# Update token lists
yarn update:tokens

# Type check
yarn typecheck

Token List Update Process

The package maintains these data files:

• Featured (tokenlist-featured.json) - Manually curated tokens with metadata updated from on-chain data
• Generated (tokenlist-generated.json) - Auto-fetched tokens from external sources (cross-checked with other services as they are added)

Stablecoin peg information is stored directly in token extensions via the peggedTo field (e.g., "peggedTo": "USD").

How yarn update:tokens Works

1. Fetch tokens from Relay Link API - Discovers tokens across all supported chains
2. Enrich with on-chain data - Verifies name, symbol, and decimals directly from contracts
3. Fetch stablecoin data - Gets stablecoin categories from CoinGecko to determine peggedTo values
4. Match CoinGecko IDs - Links tokens to CoinGecko for market data and adds peggedTo for stablecoins (tokens without a match are excluded)
5. Filter by market data - Removes low-quality tokens based on:
   • Market cap rank (must be ≤ 10,000)
   • 24h volume (must be ≥ $10,000)
   • Volume/market cap ratio (must be ≥ 0.1%)
   • Circulating/max supply ratio (must be ≥ 0.1%)
6. Remove duplicates - Tokens with duplicate symbols on the same chain are removed
7. Write to generated list - Updates tokenlist-generated.json

Note: Steps 3, 4, and 5 use the CoinGecko Pro API and require a COINGECKO_API_KEY environment variable with a valid Pro API key.

Featured Token Overrides

Some tokens intentionally have duplicates (e.g., native USDC + bridged USDC on the same chain). These are defined in FEATURED_TOKEN_OVERRIDES in src/tokens/index.ts:

FEATURED_TOKEN_OVERRIDES: Array<{
  symbol: string;    // Token symbol (e.g., 'USDC')
  chainId: number;   // Chain ID where duplicates exist
  primary: string;   // Default address returned by getTokenBySymbol()
  addresses: string[]; // All valid addresses for this token
}>

When querying by symbol, the primary address is returned. Use getTokenByAddress() to get a specific variant.

Symbol-Based Overrides

The tokenlist-overrides.json file allows you to customize generated tokens without modifying the auto-generated list. Overrides are applied by symbol (uppercase) and affect all tokens with that symbol across all chains.

{
  "name": "Yodl Token Overrides",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "version": { "major": 2, "minor": 0, "patch": 0 },
  "overrides": {
    "USDC": {
      "logoURI": "https://example.com/usdc.png",
      "extensions": {
        "peggedTo": "USD"
      }
    },
    "SPAM": {
      "_deleted": true
    }
  }
}

Override fields:

• name - Override the token name
• logoURI - Override the logo URL
• tags - Override tags array
• extensions - Merge additional extension fields
• _deleted - Set to true to hide all tokens with this symbol

Overrides are automatically re-applied after running yarn update:tokens.

Token Manager UI

A web-based UI for managing tokens is available:

yarn tool:tokens

This starts a local server at http://localhost:3456 where you can:

• Browse featured and generated tokens
• Filter by chain, source, and search
• Add/edit overrides for generated tokens
• Mark tokens as deleted
• Validate token lists against the Uniswap schema

Token Logo Management

Token logos are stored in Vercel Blob storage. Run:

yarn update:logos

This downloads logos from external URLs, converts them to optimized WebP format, and uploads them to Vercel Blob storage.

Requires BLOB_READ_WRITE_TOKEN environment variable (set in .env or export).

Version Management

This package uses semantic-release for automated versioning. Version bumps are determined automatically from commit messages using Conventional Commits.

Commit Message Format

<type>(<scope>): <description>

[optional body]

[optional footer]

Version Bump Rules

| Commit Type | Example | Release | |-------------|---------|---------| | fix: | fix: correct token decimals | Patch (0.9.7 → 0.9.8) | | feat: | feat: add Sonic chain support | Minor (0.9.7 → 0.10.0) | | feat!: or BREAKING CHANGE: | feat!: change API signature | Major (0.9.7 → 1.0.0) |

Other commit types (chore:, docs:, style:, refactor:, test:) do not trigger a release.

Release Process

1. Commit your changes using conventional commit messages
2. Push to main
3. GitHub Actions automatically:
   • Runs tests and builds
   • Determines the version bump from commits
   • Updates package.json and CHANGELOG.md
   • Creates a GitHub release with release notes
   • Publishes to npm

License

MIT