Skip to main content
Token rates are read-only cached USD prices for supported tokens. Use them to show a fiat estimate before a user confirms a swap, sort token lists by USD value, or compare a swap output against current market prices.

​
Prerequisites

Before you begin, ensure that you’ve:

​
Look up token rates

Pass chain and a tokens array to look up rates for one or more tokens on the specified blockchain.
The App Kit SDK supports token aliases (such as "USDC", "EURC", "USDT").
TypeScript
import { AppKit } from "@circle-fin/app-kit";

const kit = new AppKit();

const result = await kit.getTokenRates({
  chain: "Ethereum",
  tokens: ["USDC"],
  kitKey: process.env.KIT_KEY as string,
});

console.dir(result, { depth: null, colors: true });
The response is keyed by blockchain, then by token address:
Shell
{
  rates: {
    Ethereum: {
      "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48": {
        priceUSD: "0.999615",
        fetchedAt: 1781758931073,
        decimals: 6,
      },
    },
  },
}
Each rate includes:
  • priceUSD: Latest cached USD price for the token, as a decimal string.
  • fetchedAt: Unix timestamp (milliseconds) of when the price was last refreshed. Use this to decide whether to refetch or warn the user about a stale quote.
  • decimals: Number of decimal places for the token.
If a cached price doesn’t exist for a requested token, that token’s address is omitted from the blockchain’s rate map.

​
List all token rates

Omit tokens to get every cached rate for the specified blockchain. This is useful for populating a token picker or refreshing a price column:
TypeScript
import { AppKit } from "@circle-fin/app-kit";

const kit = new AppKit();

const result = await kit.getTokenRates({
  chain: "Base",
  kitKey: process.env.KIT_KEY as string,
});

console.dir(result, { depth: null, colors: true });
The response has the same shape as the single-token lookup, with one entry per cached token:
Shell
{
  rates: {
    Base: {
      "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913": {
        priceUSD: "1.000112",
        fetchedAt: 1781758931073,
        decimals: 6,
      },
      "0xd46f9d14bd720f10714e2a2af5e0d617b2a0ba8c": {
        priceUSD: "0.000002619246974",
        fetchedAt: 1781829306975,
        decimals: 18,
      },
      "0xae8fc9288685516d2eca717056ca69303b348752": {
        priceUSD: "74227.78149573994",
        fetchedAt: 1781829306975,
        decimals: 18,
      },
    },
  },
}