@yodlpay/tokenlists 1.1.4 → 1.1.6

package/README.md

@@ -72,35 +72,34 @@ const weth = getNativeWrappedToken(1);
 
 ### Stablecoins
 
+Stablecoin peg information is stored directly in token extensions via the `peggedTo` field:
+
 ```typescript
 import {
-  isStablecoin,
-  getStablecoinCurrency,
-  getStablecoinInfo,
-  getStablecoinsByPeg,
+  getTokenBySymbol,
   type FiatCurrency,
-  type StablecoinCheckResult
+  type TokenInfo
 } from '@yodlpay/tokenlists';
 
-// Check if a token is a stablecoin (by coinGeckoId)
-isStablecoin('tether'); // true
-isStablecoin('ethereum'); // false
+// Get a token and check if it's a stablecoin
+const usdc = getTokenBySymbol('USDC', 1);
 
-// Get the currency a stablecoin is pegged to
-getStablecoinCurrency('usd-coin'); // 'USD'
-getStablecoinCurrency('euro-coin'); // 'EUR'
+// 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"
+}
 
-// Get detailed stablecoin info for a token
-// Checks coinGeckoId first, falls back to symbol if not in registry
-// (handles bridged stablecoins like l2-standard-bridged-usdt-base)
-const token = getTokenBySymbol('USDC', 1);
-const info = getStablecoinInfo(token);
-// { isStablecoin: true, peggedTo: 'USD' }
+// Filter tokens by peg currency
+import { tokenlist } from '@yodlpay/tokenlists';
 
-// Get all stablecoin coinGeckoIds for a currency
-getStablecoinsByPeg('EUR'); // ['euro-coin', 'monerium-eur-money', ...]
+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
 
 ```typescript
@@ -163,23 +162,24 @@ 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 Registry** (`stablecoin-registry.json`) - Mapping of CoinGecko IDs to fiat currencies (USD, EUR, etc.) for stablecoin detection
+
+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. **Match CoinGecko IDs** - Links tokens to CoinGecko for market data (tokens without a match are excluded)
-4. **Filter by market data** - Removes low-quality tokens based on:
+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%)
-5. **Remove duplicates** - Tokens with duplicate symbols on the same chain are removed
-6. **Write to generated list** - Updates `tokenlist-generated.json`
-7. **Update stablecoin registry** - Fetches stablecoin data from CoinGecko Pro API and updates `stablecoin-registry.json`
+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 7 use the CoinGecko Pro API and require a `COINGECKO_API_KEY` environment variable with a valid Pro API key.
+> **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
 
@@ -196,6 +196,53 @@ FEATURED_TOKEN_OVERRIDES: Array<{
 
 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.
+
+```json
+{
+  "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:
+
+```bash
+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: