Sync the Token Catalog

Use the token catalog endpoint to keep token names, symbols, decimals, contract addresses, and logos current in your backend. The endpoint returns the catalog as a sequence of pages across supported chains and networks.

What you need

A Dynamic API token with the environment.settings.read scope. See API token permissions.
Server-side storage for the catalog and its ETag value.

Keep the API token server-side. Read it from an environment variable or a secrets manager, never from client-side code or a committed file.

Fetch the catalog

Call GET /api/v0/tokenCatalog with your API token. The endpoint paginates results: limit sets the page size (1 to 100, default 50) and cursor continues from a previous page:

curl

curl "https://app.dynamic.xyz/api/v0/tokenCatalog?limit=100" \
  --header "Authorization: Bearer $DYNAMIC_API_TOKEN"

A successful response contains one page of tokens, the cursor for the next page, and a version for the current catalog content:

{
  "nextCursor": "token-row-id-or-null",
  "tokens": [
    {
      "chain": "EVM",
      "contractAddress": "0xTokenContractAddress",
      "decimals": 6,
      "logoURI": "https://example.com/token-logo.png",
      "name": "Example USD",
      "networkId": 1,
      "symbol": "xUSD",
      "tokenId": "example-usd"
    }
  ],
  "version": "catalog-content-hash"
}

When nextCursor is a string, pass it as cursor on the next request to fetch the following page. When nextCursor is null, the page is the last one and the catalog is fully read. The logoURI field is optional. Identify a token by its chain, network, and contract address instead of its symbol, because the same symbol can exist on multiple networks.

Poll without downloading unchanged data

Each page response includes an ETag header and a version field. The ETag identifies one specific page request, so it only matches a later request with the same limit and cursor. The version hashes the entire catalog, so the first page’s version changes whenever any token changes. To poll efficiently, save the first page’s ETag together with your stored catalog. On the next scheduled request, send that value in If-None-Match on the first page only:

304 Not Modified means the catalog is unchanged. Keep using the saved copy.
200 OK with a new version means the catalog changed. Read every page until nextCursor is null and replace the saved snapshot and ETag.

This TypeScript example accepts the previously saved snapshot so the same path works on the first run and later runs:

TypeScript

type TokenCatalogEntry = {
  chain: string;
  contractAddress: string;
  decimals: number;
  logoURI?: string;
  name: string;
  networkId: number;
  symbol: string;
  tokenId: string;
};

type CatalogPage = {
  nextCursor: string | null;
  tokens: TokenCatalogEntry[];
  version: string;
};

type SavedCatalog = {
  etag: string;
  catalog: CatalogPage;
};

const ENDPOINT = 'https://app.dynamic.xyz/api/v0/tokenCatalog';

async function fetchPage(
  apiToken: string,
  cursor?: string,
  ifNoneMatch?: string,
): Promise<Response> {
  const url = new URL(ENDPOINT);
  url.searchParams.set('limit', '100');

  if (cursor) {
    url.searchParams.set('cursor', cursor);
  }

  return fetch(url, {
    headers: {
      Authorization: `Bearer ${apiToken}`,
      ...(ifNoneMatch ? { 'If-None-Match': ifNoneMatch } : {}),
    },
  });
}

function isCatalogPage(value: unknown): value is CatalogPage {
  if (!value || typeof value !== 'object') return false;

  const page = value as Record<string, unknown>;
  if (
    typeof page.version !== 'string' ||
    !(typeof page.nextCursor === 'string' || page.nextCursor === null) ||
    !Array.isArray(page.tokens)
  ) {
    return false;
  }

  return page.tokens.every((value) => {
    if (!value || typeof value !== 'object') return false;

    const token = value as Record<string, unknown>;
    return (
      typeof token.chain === 'string' &&
      typeof token.contractAddress === 'string' &&
      Number.isInteger(token.decimals) &&
      (token.logoURI === undefined || typeof token.logoURI === 'string') &&
      typeof token.name === 'string' &&
      Number.isInteger(token.networkId) &&
      typeof token.symbol === 'string' &&
      typeof token.tokenId === 'string'
    );
  });
}

async function syncTokenCatalog(
  previous?: SavedCatalog,
): Promise<SavedCatalog> {
  const apiToken = process.env.DYNAMIC_API_TOKEN;

  if (!apiToken) {
    throw new Error('DYNAMIC_API_TOKEN is required');
  }

  const firstResponse = await fetchPage(apiToken, undefined, previous?.etag);

  if (firstResponse.status === 304 && previous) {
    return previous;
  }

  if (!firstResponse.ok) {
    throw new Error(`Dynamic API returned ${firstResponse.status}`);
  }

  const etag = firstResponse.headers.get('etag');

  if (!etag) {
    throw new Error('Dynamic API response did not include an ETag');
  }

  const firstPage: unknown = await firstResponse.json();

  if (!isCatalogPage(firstPage)) {
    throw new Error('Dynamic API returned an invalid token catalog');
  }

  const tokens = [...firstPage.tokens];
  let nextCursor = firstPage.nextCursor;
  const { version } = firstPage;

  while (nextCursor !== null) {
    const response = await fetchPage(apiToken, nextCursor);

    if (!response.ok) {
      throw new Error(`Dynamic API returned ${response.status}`);
    }

    const page: unknown = await response.json();

    if (!isCatalogPage(page)) {
      throw new Error('Dynamic API returned an invalid token catalog');
    }

    tokens.push(...page.tokens);
    nextCursor = page.nextCursor;
  }

  return {
    etag,
    catalog: { nextCursor: null, tokens, version },
  };
}

Persist the returned object after each successful sync. If the process restarts, load both values before the next request; an ETag without its matching catalog is not useful.

Handle errors

Status	What to do
`400`	Check that `limit` is an integer from 1 to 100 and `cursor` is a valid page cursor.
`401`	Check that the token is present, valid, and uses the `Bearer` prefix.
`403`	Grant the API token the `environment.settings.read` scope.
`429`	Retry with exponential backoff and jitter. Keep serving the last saved catalog.
`5xx`	Retry with exponential backoff and jitter. Keep serving the last saved catalog.

Treat each successful sync as a complete replacement snapshot. Do not discard the last valid snapshot when a refresh fails.

Overview

Endpoints

Schemas

Sync the Token Catalog

What you need

Fetch the catalog

Poll without downloading unchanged data

Handle errors

​What you need

​Fetch the catalog

​Poll without downloading unchanged data

​Handle errors

What you need

Fetch the catalog

Poll without downloading unchanged data

Handle errors