Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
// Tokens API v1 client (api.tokens.xyz, managed by the Solana Foundation).
//
// What it adds that the existing market stack does not have: a CANONICAL ASSET
// layer for Solana. Every other source in this repo is mint-scoped, so wSOL,
// bridged SOL and an LST look like three unrelated tokens. Tokens API groups
// mints into one canonical asset (`solana`, `usd`, `tesla`) and hands back
// every variant with its own market, liquidity tier and trust tier, so a wallet
// panel can say "you hold $412 of USD across 3 mints" instead of listing three
// rows it cannot relate.
//
// This module is deliberately coin-agnostic: every mint and every asset ref is
// supplied by the caller at runtime. Nothing here pins a specific token.
//
// Auth: TOKENS_XYZ_API_KEY, sent as `x-api-key`, server-side only. Every entry
// point returns null (or an empty result) when the key is absent, so an
// unconfigured deployment behaves exactly as it did before this module landed
// rather than surfacing a dead code path.
//
// Quota: limits AND monthly quotas are enforced per key, and both answer 429.
// The reads whose answers are stable (resolve, variants, trending, risk) go
// through the shared cache so repeated page loads cost one upstream call per
// window. The market read is left uncached on purpose: its only caller is the
// failover cascade in api/_lib/market/token-market.js, which already owns an
// L1 + L2 + single-flight cache and would otherwise cache the same value twice.
//
// Contract reference: docs/tokens-xyz.md
import { cacheWrap } from './cache.js';
const BASE = 'https://api.tokens.xyz/v1';
const DEFAULT_TIMEOUT_MS = 6000;
// Batch cap from the upstream contract: /assets/variant-markets accepts at most
// 50 mints per call. Callers pass any number; requests are chunked to this.
export const VARIANT_MARKETS_MAX_MINTS = 50;
// Cache windows, sized to how fast each answer actually moves. Mint-to-asset
// mappings change when the registry does (rarely); markets move constantly and
// are not cached here at all.
const TTL_RESOLVE_S = 6 * 3600;
const TTL_VARIANTS_S = 600;
const TTL_TRENDING_S = 60;
const TTL_RISK_S = 300;
/** Is the Tokens API key present? Every read no-ops when this is false. */
export function tokensXyzConfigured() {
return !!process.env.TOKENS_XYZ_API_KEY;
}
// Nearly every numeric field in the v1 contract is `number | null`, where null
// means "not cached yet", not zero. Number(null) is 0, so guard the nullish and
// empty cases explicitly: rendering an unknown liquidity as $0 would be a lie.
const num = (v) => {
if (v === null || v === undefined || v === '') return null;
const n = Number(v);
return Number.isFinite(n) ? n : null;
};
const str = (v) => (typeof v === 'string' && v ? v : null);
/**
* Read the upstream error envelope: { error: { _tag, message, details? } }.
* Falls back to the raw body so a proxy error (HTML, empty) is still legible.
*/
function errorMessage(body) {
try {
const parsed = JSON.parse(body);
const e = parsed?.error;
if (e?.message) return e._tag ? `${e._tag}: ${e.message}` : e.message;
} catch {
/* not JSON, fall through to the raw body */
}
return body.slice(0, 200);
}
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
/**
* One authenticated request against the Tokens API.
*
* Retries only what the upstream retry matrix marks retryable (429 and
* transient 5xx) with exponential backoff plus jitter. 400/401/403/404 throw
* immediately: retrying them burns quota and cannot succeed.
*
* Thrown errors carry `.status` and lead with the numeric status in the
* message, which is what the market cascade's circuit breaker matches on to
* bench a rate-limited source (api/_lib/market/token-market.js `cooldownFor`).
*
* @param {string} path path under /v1, e.g. `/assets/resolve?ref=usd`
* @param {{ method?: string, body?: object, retries?: number,
* timeoutMs?: number, signal?: AbortSignal }} [opts]
*/
async function request(path, opts = {}) {
const key = process.env.TOKENS_XYZ_API_KEY;
if (!key) throw Object.assign(new Error('TOKENS_XYZ_API_KEY is not configured'), { status: 503 });
const { method = 'GET', body, retries = 2, timeoutMs = DEFAULT_TIMEOUT_MS, signal } = opts;
const headers = { 'x-api-key': key, accept: 'application/json' };
if (body) headers['content-type'] = 'application/json';
for (let attempt = 0; ; attempt++) {
let res;
try {
res = await fetch(`${BASE}${path}`, {
method,
headers,
body: body ? JSON.stringify(body) : undefined,
signal: signal ?? AbortSignal.timeout(timeoutMs),
});
} catch (e) {
// Network error or timeout. Treated like a transient 5xx.
if (attempt >= retries) throw Object.assign(new Error(`tokens.xyz unreachable: ${e.message}`), { status: 502 });
await sleep(250 * 2 ** attempt + Math.floor(Math.random() * 150));
continue;
}
if (res.ok) return res.json();
const raw = await res.text().catch(() => '');
const retryable = res.status === 429 || (res.status >= 500 && res.status < 600);
if (!retryable || attempt >= retries) {
throw Object.assign(new Error(`${res.status} ${errorMessage(raw)}`.trim()), { status: res.status });
}
await sleep(250 * 2 ** attempt + Math.floor(Math.random() * 150));
}
}
/**
* Normalize a variant market row. Tokens API camelCases its fields; the rest of
* this repo's market layer is snake_case, so translate once here instead of at
* every call site. Missing fields stay null rather than being inferred.
*
* @param {object|null|undefined} m raw `market` object from a variant row
*/
export function normalizeVariantMarket(m) {
if (!m || typeof m !== 'object') return null;
return {
price_usd: num(m.price),
price_change_1h: num(m.priceChange1hPercent),
price_change_24h: num(m.priceChange24hPercent),
market_cap: num(m.marketCap),
fdv: num(m.fdv),
liquidity: num(m.liquidity),
// Holder count and supply are absent from the published v1 type but are
// present live on birdeye-sourced rows (verified 2026-08-11 against
// wSOL and the 27 USD variants). Mapped when present, null otherwise,
// so a clickhouse_trades row that omits them degrades honestly instead
// of reporting zero holders.
holders: num(m.holder),
supply: num(m.circulatingSupply),
total_supply: num(m.totalSupply),
volume_1h: num(m.volume1hUSD),
volume_24h: num(m.volume24hUSD),
volume_30d: num(m.volume30dUSD),
trades_1h: num(m.trade1h),
trades_24h: num(m.trade24h),
wallets_1h: num(m.uniqueWallet1h),
wallets_24h: num(m.uniqueWallet24h),
decimals: num(m.decimals),
logo_url: str(m.logoURI),
symbol: str(m.symbol),
name: str(m.name),
last_trade_at: num(m.lastTradeAt),
// Which upstream produced the numbers: birdeye, rwa_xyz, or the Solana
// trades rollup. Worth surfacing because a clickhouse_trades row is
// direct on-chain fill data rather than an aggregator estimate.
metrics_source: str(m.metricsSource) || str(m.source),
fetched_at: num(m.lastFetchedAt),
};
}
/**
* Normalize a variant row (a single mint inside a canonical asset).
* @param {object} v
*/
export function normalizeVariant(v) {
if (!v || typeof v !== 'object') return null;
const q = v.executionQuality;
return {
variant_id: str(v.variantId),
mint: str(v.mint),
chain: str(v.chain) || 'solana',
kind: str(v.kind),
label: str(v.label),
symbol: str(v.symbol),
name: str(v.name),
issuer: str(v.issuer),
issuer_url: str(v.issuerUrl),
tags: Array.isArray(v.tags) ? v.tags.filter((t) => typeof t === 'string') : [],
liquidity_tier: str(v.liquidityTier),
trust_tier: str(v.trustTier),
// Redeemability tier for tokenized equities. Provider metadata for
// routing and display only, never advice.
stock_variant_tier: str(v.stockVariantTier),
market: normalizeVariantMarket(v.market),
// Cached fill-quality window (24h / 5s horizon, USDC quote). Null for
// mints with no coverage, which is most of them.
execution: q
? {
score: num(q.executionScore),
eligible_for_primary: q.isEligibleForPrimary === true,
volume_24h: num(q.volume24hUSD),
trades_24h: num(q.trade24h),
bot_volume_ratio: num(q.botVolumeRatio),
fee_bps: num(q.feeBps),
flow_sources: num(q.flowSourceCount),
markout_bps: num(q.markoutBps),
as_of: num(q.asOf),
}
: null,
};
}
/**
* Resolve any asset reference to its canonical asset plus the matching variant.
*
* `ref` accepts an assetId (`usd`), an alias, a raw Solana mint, or the
* `solana-<mint>` singleton form. A mint that belongs to no canonical group
* comes back as its own singleton asset, so the result is never empty for a
* real mint that the registry has seen.
*
* @param {{ mint?: string, ref?: string, signal?: AbortSignal }} params
* @returns {Promise<null | {
* asset_id: string, resolved_by: string|null, mint: string|null,
* name: string|null, symbol: string|null, category: string|null,
* aliases: string[], variant: object|null,
* }>} null when unconfigured, unknown, or upstream is unavailable.
*/
export async function resolveAsset({ mint, ref, signal } = {}) {
if (!tokensXyzConfigured()) return null;
const q = mint ? `mint=${encodeURIComponent(mint)}` : ref ? `ref=${encodeURIComponent(ref)}` : null;
if (!q) return null;
return cacheWrap(`tokensxyz:resolve:v1:${q}`, TTL_RESOLVE_S, async () => {
let data;
try {
data = await request(`/assets/resolve?${q}`, { signal });
} catch (e) {
// A 404 is a real answer (this mint maps to nothing); anything else is
// an outage. Both degrade to null so callers keep their existing path.
if (e.status !== 404) console.warn(`[tokens.xyz] resolve failed: ${e.message}`);
return null;
}
const a = data?.asset;
if (!a?.assetId) return null;
return {
asset_id: a.assetId,
resolved_by: str(data.resolvedBy),
mint: str(data.mint),
name: str(a.name),
symbol: str(a.symbol),
category: str(a.category),
aliases: Array.isArray(a.aliases) ? a.aliases.filter((x) => typeof x === 'string') : [],
variant: normalizeVariant(data.variant),
};
});
}
/**
* Every known variant of a canonical asset, richest market first.
*
* @param {string} assetId canonical id from resolveAsset(), e.g. `usd`
* @param {{ kind?: string, liquidityTier?: string, stockVariantTier?: string,
* sortBy?: 'liquidity'|'execution_quality'|'stock_redeemability',
* signal?: AbortSignal }} [opts]
* @returns {Promise<Array<object>>} empty when unconfigured or unavailable.
*/
export async function fetchAssetVariants(assetId, opts = {}) {
if (!tokensXyzConfigured() || !assetId) return [];
const params = new URLSearchParams();
if (opts.kind) params.set('kind', opts.kind);
if (opts.liquidityTier) params.set('liquidityTier', opts.liquidityTier);
if (opts.stockVariantTier) params.set('stockVariantTier', opts.stockVariantTier);
if (opts.sortBy) params.set('sortBy', opts.sortBy);
const qs = params.toString();
const path = `/assets/${encodeURIComponent(assetId)}/variants${qs ? `?${qs}` : ''}`;
// The failure return is null, not [], so cacheWrap does not pin a transient
// outage as "this asset has no variants" for the whole TTL.
const rows = await cacheWrap(`tokensxyz:variants:v1:${path}`, TTL_VARIANTS_S, async () => {
let data;
try {
data = await request(path, { signal: opts.signal });
} catch (e) {
if (e.status !== 404) console.warn(`[tokens.xyz] variants failed for ${assetId}: ${e.message}`);
return null;
}
const variants = Array.isArray(data?.variants) ? data.variants : [];
return variants.map(normalizeVariant).filter(Boolean);
});
return rows || [];
}
/** Split an array into fixed-size chunks. */
function chunk(items, size) {
const out = [];
for (let i = 0; i < items.length; i += size) out.push(items.slice(i, i + size));
return out;
}
/**
* Batch market snapshot for a list of mints, in one upstream call per 50 mints.
*
* This is the read the per-mint sources in this repo cannot do: a portfolio of
* 40 tokens costs 40 DexScreener calls but one Tokens API call. Mints with no
* cached snapshot come back with `market: null` rather than being dropped, so
* the caller can tell "no data" apart from "not requested".
*
* The sibling POST /assets/market-snapshots endpoint takes 250 mints but its
* row shape is explicitly documented as unstable, so this uses the typed
* variant-markets endpoint and chunks instead.
*
* @param {string[]} mints
* @param {{ signal?: AbortSignal, retries?: number, strict?: boolean }} [opts]
* `strict` rethrows an upstream failure instead of logging it and returning a
* partial map. The market cascade wants that (its circuit breaker benches a
* source by reading the thrown status); UI callers do not.
* @returns {Promise<Map<string, { asset_id: string|null, market: object|null,
* execution: object|null }>>} empty map when unconfigured or unavailable.
*/
export async function fetchVariantMarkets(mints, opts = {}) {
const out = new Map();
if (!tokensXyzConfigured()) return out;
const unique = [...new Set((mints || []).filter((m) => typeof m === 'string' && m))];
if (!unique.length) return out;
const batches = await Promise.all(
chunk(unique, VARIANT_MARKETS_MAX_MINTS).map(async (group) => {
const path = `/assets/variant-markets?mints=${group.map(encodeURIComponent).join(',')}`;
try {
return await request(path, { signal: opts.signal, retries: opts.retries ?? 2 });
} catch (e) {
if (opts.strict) throw e;
console.warn(`[tokens.xyz] variant-markets failed for ${group.length} mints: ${e.message}`);
return null;
}
}),
);
for (const data of batches) {
for (const row of Array.isArray(data?.variants) ? data.variants : []) {
if (!row?.mint) continue;
const v = normalizeVariant(row);
out.set(row.mint, {
asset_id: str(row.assetId),
market: v.market,
execution: v.execution,
});
}
}
return out;
}
/**
* Market snapshot for exactly one mint. Thin wrapper over the batch read so the
* market-data cascade has a single-mint entry point.
*
* `retries` defaults to 0 and `strict` to true: the caller is a failover chain
* that would rather see the error and move to the next source than sit through
* a backoff, and its circuit breaker needs the status to bench a throttled key.
*
* @param {string} mint
* @param {{ signal?: AbortSignal, retries?: number, strict?: boolean }} [opts]
* @throws when strict (the default) and the upstream call fails.
*/
export async function fetchMintMarket(mint, opts = {}) {
const map = await fetchVariantMarkets([mint], { retries: 0, strict: true, ...opts });
return map.get(mint) || null;
}
/**
* Trending Solana mints, ranked by short-window momentum from direct
* USD-stable trades. Native/wrapped SOL and stablecoins are excluded upstream
* because they dominate routing volume.
*
* @param {{ category?: string, limit?: number, offset?: number,
* signal?: AbortSignal }} [opts]
* @returns {Promise<Array<object>>} empty when unconfigured or unavailable.
*/
export async function fetchTrending(opts = {}) {
if (!tokensXyzConfigured()) return [];
const params = new URLSearchParams();
if (opts.category) params.set('category', opts.category);
if (opts.limit) params.set('limit', String(Math.min(50, Math.max(1, Math.trunc(opts.limit)))));
if (opts.offset) params.set('offset', String(Math.max(0, Math.trunc(opts.offset))));
const qs = params.toString();
const path = `/assets/trending${qs ? `?${qs}` : ''}`;
// Null (not []) on failure for the same reason as fetchAssetVariants: a dead
// upstream must not be cached as an empty trending board.
const ranked = await cacheWrap(`tokensxyz:trending:v1:${path}`, TTL_TRENDING_S, async () => {
let data;
try {
data = await request(path, { signal: opts.signal });
} catch (e) {
console.warn(`[tokens.xyz] trending failed: ${e.message}`);
return null;
}
const rows = Array.isArray(data?.trending) ? data.trending : [];
return rows.map((r) => ({
rank: num(r.rank),
asset_id: str(r.assetId),
mint: str(r.mint),
symbol: str(r.symbol),
name: str(r.name),
category: str(r.category),
image_url: str(r.imageUrl),
decimals: num(r.decimals),
score: num(r.trending?.score),
scoring_version: str(r.trending?.scoringVersion),
market: {
price_usd: num(r.market?.price),
price_change_1h: num(r.market?.priceChange1hPercent),
price_change_24h: num(r.market?.priceChange24hPercent),
volume_5m: num(r.market?.volume5mUSD),
volume_1h: num(r.market?.volume1hUSD),
volume_24h: num(r.market?.volume24hUSD),
trades_1h: num(r.market?.trade1h),
trades_24h: num(r.market?.trade24h),
wallets_1h: num(r.market?.uniqueWallet1h),
wallets_24h: num(r.market?.uniqueWallet24h),
last_trade_at: num(r.market?.lastTradeAt),
},
}));
});
return ranked || [];
}
/**
* Market-based risk summary for a mint. Upstream needs a cached market snapshot
* to score at all; without one it answers with `hasInsufficientData: true`,
* which is passed through honestly rather than being scored as a pass.
*
* @param {string} mint
* @param {{ signal?: AbortSignal }} [opts]
* @returns {Promise<null | { score: number|null, grade: string|null,
* label: string|null, tone: string|null, trusted_launch: boolean,
* insufficient_data: boolean, insufficient_data_reason: string|null }>}
*/
export async function fetchRiskSummary(mint, opts = {}) {
if (!tokensXyzConfigured() || !mint) return null;
const path = `/assets/risk-summary?mint=${encodeURIComponent(mint)}`;
return cacheWrap(`tokensxyz:risk:v1:${mint}`, TTL_RISK_S, async () => {
let data;
try {
data = await request(path, { signal: opts.signal });
} catch (e) {
if (e.status !== 404) console.warn(`[tokens.xyz] risk-summary failed for ${mint.slice(0, 6)}: ${e.message}`);
return null;
}
if (!data || typeof data !== 'object') return null;
return {
score: num(data.score),
grade: str(data.grade),
label: str(data.label),
tone: str(data.tone),
trusted_launch: data.isTrustedLaunch === true,
insufficient_data: data.hasInsufficientData === true,
insufficient_data_reason: str(data.insufficientDataReason),
};
});
}