@xrise33/token-list - XRPL EVM Token List

Canonical, versioned, and validated token metadata registry for the XRPL EVM sidechain ecosystem.

This repository contains:

• A validated token list JSON file
• A JSON Schema for tooling
• Logos for supported assets
• TypeScript type definitions for developers
• CI validation

Install

npm install @xrise33/token-list
# or
pnpm add @xrise33/token-list

Usage

ESM:

import tokenList from "@xrise33/token-list";

console.log(tokenList.name);
console.log(tokenList.version);
console.log(tokenList.tokens.length);

Access types:

import type { TokenListFile, TokenInfo } from "@xrise33/token-list/schema";

const list: TokenListFile = tokenList;

function filterStablecoins(tokens: TokenInfo[]) {
  return tokens.filter((t) => t.tags?.includes("stablecoin"));
}

Node (CJS):

const tokenList = require("@xrise33/token-list");

From CDN (jsDelivr):

https://cdn.jsdelivr.net/npm/@xrise33/token-list/dist/tokenlist.json

Icons (example):

https://cdn.jsdelivr.net/npm/@xrise33/token-list/images/1440000/<CHECKSUM>.png

JSON structure

The list follows a JSON schema (see schema/tokenlist.schema.json).

Top-level fields:

• name: Human-readable name of this list.
• timestamp: ISO8601 timestamp when this list was generated.
• version: { major, minor, patch } (semantic versioning).
• logoURI: Logo for this list.
• keywords: Optional keywords for discovery.
• license: License metadata.
• tags: Registry of tag IDs (e.g. stablecoin, bluechip).
• sources: Where this data came from.
• verification: Info about manual/automatic review.
• tokens: Array of token entries.

Each token:

• address: EIP-55 checksummed contract address.
• chainId: EIP-155 chain ID (1440000 for XRPLEVM).
• symbol: Ticker string.
• decimals: ERC-20 decimals.
• name, description: Metadata.
• image: Repo-relative logo path (images//.svg).
• logoURI: Optional absolute logo URI.
• tags: Array of tag IDs (must exist in top-level tags).
• extensions: Free-form extension fields.

See the schema file for full details.

Versioning Policy

• PATCH: Fixes to existing token metadata (logos, names, decimals, links).
• MINOR: Add new tokens or non-breaking metadata fields.
• MAJOR: Breaking changes (removing tokens, schema changes, semantics).

Both the npm version and version field inside the JSON follow this policy.

Contributing (Adding a token)

1. Add your token entry to src/list.json.

2. Add a logo file to images/<chainId>/<checksummed-address>.svg or .png.

3. Run:

   pnpm validate

4. Open a PR.

Validation

Locally:

pnpm validate

CI runs the same validation on every push and pull request.

Rules enforced:

• JSON schema validation.
• Checksummed addresses and valid chain IDs.
• No duplicate (chainId, address) or (chainId, symbol) pairs.
• Logos live under images/<chainId>/.
• Logo filenames match checksummed addresses.
• Logos use allowed formats and size limits.
• Token tags reference existing top-level tags.

📦 SDK Usage

The package includes a small helper toolkit designed to make it easier to query tokens and construct logo URLs.

Importing the SDK (TypeScript / ESM)

import list from "@xrise33/token-list";
import {
  getTokensByChain,
  getTokenByAddress,
  getTokenBySymbol,
  getTokensByTag,
  getLogoUri,
} from "@xrise33/token-list/sdk";

const xrplevm = getTokensByChain(list, 1440000);
const usdc = getTokenBySymbol(list, 1440000, "USDC");
const logo = usdc && getLogoUri(usdc);

console.log({ xrplevmCount: xrplevm.length, logo });

CommonJS Usage (Node require)

Even though the package is ESM-native, CJS consumers can still use it:

const list = require("@xrise33/token-list/dist/tokenlist.json");

// dynamic ESM import for SDK
(async () => {
  const { getTokenBySymbol } = await import("@xrise33/token-list/sdk");
  const token = getTokenBySymbol(list, 1440000, "USDC");
  console.log(token);
})();

Full CJS support via .cjs builds may be added later if demand requires.

CDN Logo Helper

const token = getTokenBySymbol(list, 1440000, "XRP");
const logoUri = token && getLogoUri(token);

console.log(logoUri);
// → https://cdn.jsdelivr.net/npm/@xrise33/token-list@latest/images/1440000/<address>.svg

Helper Function Reference

| Function | Purpose | | ------------------------------------------- | ------------------------------- | | getTokensByChain(list, chainId) | returns all tokens on chain | | getTokenByAddress(list, chainId, address) | lookup by contract | | getTokenBySymbol(list, chainId, symbol) | lookup by ticker | | getTokensByTag(list, tagId) | filter by metadata tag | | getLogoUri(token, opts?) | deterministic CDN-safe logo URL |

License

MIT © Contributors