TokensAPI

Variants

Look up one token on one chain by {chain}/{address}, or batch up to 50 <chain>:<address> keys.

All endpoints below use https://api.tokens.xyz/v2 with an x-api-key header; see Authentication. A variant is one token on one chain, keyed <chain>:<address>; the key rules, casing and capability flags are on Multichain assets, and V2Variant is in Shared shapes.

Only registered variants resolve here: a token the registry does not know is 404 variant_not_found (single lookup) or listed in missing[] (batch). For unregistered Solana tokens use GET /v2/search.

GET /v2/variants/{chain}/{address}

One token and a summary of the asset it represents.

Auth: x-api-key, scope assets:read.

Path params

  • {chain}: a chain id from GET /v2/chains. Otherwise 400 with details.code: "invalid_chain" and the valid ids in details.chains.
  • {address}: a valid address for the chain's family, base58 for solana and 0x plus 40 hex for EVM chains. Otherwise 400 with details.code: "invalid_address" and details.expected: "base58" | "0x40hex".

Query params

None.

Response

interface VariantResponse {
    variant: V2Variant; // `rank` is set: the asset's full variant set is loaded
    asset: {
        assetId: string;
        name: string | null;
        symbol: string | null;
        category: AssetCategory;
        imageUrl: string | null;
        chains: ChainId[]; // every chain the asset has a variant on
    };
}

Example

# USDC on Solana
curl -sS "$API_BASE_URL/v2/variants/solana/EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" \
  -H "x-api-key: $API_KEY"

# USDC on Base: any casing in, lowercase out
curl -sS "$API_BASE_URL/v2/variants/base/0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" \
  -H "x-api-key: $API_KEY"
{
  "variant": {
    "key": "base:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
    "chain": "base",
    "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
    "assetId": "usd",
    "variantId": "base:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
    "kind": "stablecoin",
    "issuance": "native",
    "symbol": "USDC",
    "name": "USD Coin",
    "label": null,
    "decimals": 6,
    "logoURI": "https://…",
    "issuer": "Circle",
    "issuerUrl": "https://www.circle.com",
    "trustTier": "tier1",
    "liquidityTier": "tier1",
    "stockVariantTier": null,
    "tags": [],
    "advisory": null,
    "rank": 2,
    "explorerUrl": "https://basescan.org/token/0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
    "market": { "source": "birdeye", "price": 0.9999, "liquidity": 52000000, "volume24hUSD": 380000000, "...": "..." }
  },
  "asset": {
    "assetId": "usd",
    "name": "US Dollar",
    "symbol": "USD",
    "category": "stablecoin",
    "imageUrl": "https://…",
    "chains": ["solana", "ethereum", "base", "arbitrum", "polygon", "bnb"]
  }
}

Notes

  • The variant carries the same identity, market and advisory fields as inside GET /v2/assets/{assetId}, including its cross-chain liquidity rank. Follow asset.assetId to GET /v2/assets/{assetId} for per-chain stats and the other variants.
  • A blocked variant is served with its advisory; it is only hidden from list surfaces.
  • The route never carries executionQuality, pegHealth or preStocks; those are opt-in on the asset detail.
  • Served from a last-good copy (up to 15 minutes old) when the data layer is unavailable. A 404 is never cached as good.

GET /v2/variants

Batch identity and market lookup by key. The multichain successor to GET /v1/assets/variant-markets.

Auth: x-api-key, scope assets:read.

Query params

  • keys (required): comma-separated <chain>:<address>, max 50; repeating the param is also accepted. Keys are deduped after normalisation and the response keeps request order. Any malformed key fails the whole call with 400: invalid_key (missing, or not <chain>:<address>, details.key), too_many_keys (details.max, details.count), invalid_chain or invalid_address.

Response

interface VariantsBatchResponse {
    variants: V2Variant[]; // request order; `rank` is null because the asset's full set is not loaded
    missing: Array<{ key: VariantKey; chain: ChainId; address: string }>; // well-formed keys the registry does not know
    total: number; // = variants.length
}

Example

curl -sS "$API_BASE_URL/v2/variants?keys=solana:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v,ethereum:0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2,base:0x000000000000000000000000000000000000dead" \
  -H "x-api-key: $API_KEY"
{
  "variants": [
    { "key": "solana:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "chain": "solana", "assetId": "usd", "symbol": "USDC", "rank": null, "...": "..." },
    { "key": "ethereum:0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2", "chain": "ethereum", "assetId": "ethereum", "symbol": "WETH", "rank": null, "...": "..." }
  ],
  "missing": [
    { "key": "base:0x000000000000000000000000000000000000dead", "chain": "base", "address": "0x000000000000000000000000000000000000dead" }
  ],
  "total": 2
}

Notes

  • Unknown keys never fail the call: a well-formed key that is not a registered variant is reported in missing[] in its normalised form.
  • Each variant is returned on its own: identity, market and advisory are as in the single lookup, but rank is null and there is no asset summary. Use variant.assetId with GET /v2/assets/{assetId} for the asset-level view.
  • Cached for 30 s (stale-while-revalidate 60 s).

On this page

GET /v2/variants/{chain}/{address}Path paramsQuery paramsResponseExampleNotesGET /v2/variantsQuery paramsResponseExampleNotes