Skip to content

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.

43.2 KB
Raw Blame
// Upstream provider registry for the three.ws aggregator (/api/v1/x/*).
//
// This is the single source of truth for every THIRD-PARTY API three.ws
// bundles and re-offers as one API. Adding a new upstream — or a new endpoint
// on an existing one — is a descriptor here; no new route file, no new
// plumbing. The catch-all route (api/v1/x/[...slug].js) resolves a request
// against this registry and the aggregator engine (api/_lib/aggregator.js)
// runs it through one auth / rate-limit / metering / billing path.
//
// Provider descriptor:
//   id          url-safe slug (first path segment under /api/v1/x)
//   name        human label
//   category    grouping for discovery
//   base        upstream base URL (no trailing slash)
//   requiresKey true when the upstream needs an API key to function at all
//   envVar      env var holding three.ws's platform key for this upstream
//   byokHeader  request header a caller uses to supply THEIR OWN upstream key
//   applyKey    (headers, url, key) => void — places a key where the upstream wants it
//   endpoints   array of endpoint descriptors:
//     id        url-safe slug (second path segment)
//     method    'GET' | 'POST' — the CALLER-facing verb the aggregator front
//               door requires (api/v1/x/[...slug].js rejects any other verb).
//     upstreamMethod  optional; only set when the upstream verb differs from
//               `method` — e.g. a caller-side GET that drives a POST-only
//               JSON-RPC upstream (see the `solana` provider below). Handled
//               in api/_lib/aggregator.js (`executeUpstream`): when set to
//               'POST', the endpoint's `body()` builder receives the
//               caller's query params (a GET has no caller body to forward).
//     path      string, or (query) => string for path params
//     query     (query) => object of upstream query params (GET)
//     body      (body) => object forwarded as the upstream JSON body (POST,
//               or as the caller's query params when `upstreamMethod` lifts
//               a caller-side GET to an upstream POST)
//     transform (data) => normalized response (default: passthrough)
//     free      optional { perMin, perDay } — unauthenticated per-IP quota
//               served before the x402 402 challenge kicks in
//     priceAtomics  x402 price in USDC atomics (6 decimals; "1000" = $0.001)
//     scope     three.ws OAuth scope required for the plan-billing path
//     summary   one line for discovery
//     params    documented inputs for discovery

import { env } from '../_lib/env.js';
import { XAI_API_BASE, GROK_MENU_MODELS, GROK_DEFAULT_MODEL, resolveGrokModelId } from '../_lib/chat-models.js';

function required(value, name) {
	const v = value == null ? '' : String(value).trim();
	if (!v) {
		const err = new Error(`query param "${name}" is required`);
		err.status = 400;
		err.code = 'missing_param';
		throw err;
	}
	return v;
}

// ── DexScreener helpers ──────────────────────────────────────────────────────

// Cap a comma-separated address list at `cap` entries (DexScreener's own
// /latest/dex/tokens/ limit is 30) — trims whitespace, drops empties.
function capAddressList(csv, cap = 30) {
	return csv
		.split(',')
		.map((s) => s.trim())
		.filter(Boolean)
		.slice(0, cap)
		.join(',');
}

// DexScreener pairs are large (~30 fields incl. boosts/presale/social info);
// slim to the fields an agent actually reasons over. Shared by token/search/pair.
function slimDexPair(p) {
	if (!p || typeof p !== 'object') return null;
	return {
		chainId: p.chainId ?? null,
		dexId: p.dexId ?? null,
		pairAddress: p.pairAddress ?? null,
		baseToken: p.baseToken
			? { address: p.baseToken.address ?? null, name: p.baseToken.name ?? null, symbol: p.baseToken.symbol ?? null }
			: null,
		quoteToken: p.quoteToken ? { symbol: p.quoteToken.symbol ?? null } : null,
		priceUsd: p.priceUsd ?? null,
		priceNative: p.priceNative ?? null,
		liquidity: { usd: p.liquidity?.usd ?? null },
		fdv: p.fdv ?? null,
		marketCap: p.marketCap ?? null,
		volume: { h24: p.volume?.h24 ?? null },
		priceChange: { h1: p.priceChange?.h1 ?? null, h6: p.priceChange?.h6 ?? null, h24: p.priceChange?.h24 ?? null },
		txns: { h24: p.txns?.h24 ?? null },
		pairCreatedAt: p.pairCreatedAt ?? null,
		url: p.url ?? null,
	};
}

// token/search/pair all return `{ schemaVersion, pairs: [...] }` — slim + sort
// by liquidity desc + cap so one call never ships a multi-MB payload.
function slimDexPairs(data, cap) {
	const pairs = Array.isArray(data?.pairs) ? data.pairs : [];
	return pairs
		.map(slimDexPair)
		.filter(Boolean)
		.sort((a, b) => (b.liquidity?.usd || 0) - (a.liquidity?.usd || 0))
		.slice(0, cap);
}

// profiles/boosts are flat arrays of the same shape; slim to the identity +
// social fields agents actually use.
function slimDexProfile(entry) {
	if (!entry || typeof entry !== 'object') return null;
	return {
		chainId: entry.chainId ?? null,
		tokenAddress: entry.tokenAddress ?? null,
		description: entry.description ?? null,
		links: Array.isArray(entry.links) ? entry.links : [],
	};
}

function slimDexProfileList(data, cap = 30) {
	return Array.isArray(data) ? data.slice(0, cap).map(slimDexProfile).filter(Boolean) : [];
}

// ── Solana JSON-RPC helpers ──────────────────────────────────────────────────

// Primary Solana RPC — the best endpoint this deployment can name WITHOUT
// loading the heavy connection pool: an explicit operator URL, else a keyed
// provider (QuickNode/Helius/Alchemy), else the public endpoint. Production
// sets no SOLANA_RPC_URL but does hold HELIUS_API_KEY/ALCHEMY_API_KEY, and
// with the public endpoint as primary every call started with a near-certain
// 429 from a GCP egress IP and burned a failover hop (or two) recovering.
// Mirrors the priority order of solanaRpcEndpoints() in
// api/_lib/solana/connection.js, which remains the failover pool (`bases`).
// Computed once at module load per the registry contract — key changes need a
// redeploy to pick up, same as every other provider `base`.
const SOLANA_RPC_BASE =
	(process.env.SOLANA_RPC_URL && env.SOLANA_RPC_URL) ||
	process.env.QUICKNODE_RPC_URL ||
	(process.env.HELIUS_API_KEY && `https://mainnet.helius-rpc.com/?api-key=${process.env.HELIUS_API_KEY}`) ||
	(process.env.ALCHEMY_API_KEY && `https://solana-mainnet.g.alchemy.com/v2/${process.env.ALCHEMY_API_KEY}`) ||
	env.SOLANA_RPC_URL;

function rpcBody(method, params) {
	return { jsonrpc: '2.0', id: 1, method, params };
}

// Solana JSON-RPC returns errors as HTTP 200 with an `error` envelope — surface
// that as a real HTTP error (never as a 200 payload) before any transform runs.
// -32602/-32601/-32600 are caller mistakes (bad address, bad method/params);
// everything else (rate limits, internal errors) maps to a proxy 502.
function rpcResult(data) {
	if (data && typeof data === 'object' && data.error) {
		const code = data.error.code;
		const isCallerFault = code === -32602 || code === -32601 || code === -32600;
		const e = new Error(data.error.message || 'Solana RPC error');
		e.status = isCallerFault ? 400 : 502;
		e.code = isCallerFault ? 'rpc_invalid_request' : 'rpc_upstream_error';
		e.detail = data.error;
		throw e;
	}
	return data && typeof data === 'object' ? data.result : undefined;
}

function rpcNotFound(message, code) {
	const e = new Error(message);
	e.status = 404;
	e.code = code;
	throw e;
}

// p50/p75/p95/max over a numeric array — nearest-rank method (deterministic,
// no interpolation), sorted ascending internally so callers can pass raw order.
function percentiles(values) {
	const sorted = [...values].sort((a, b) => a - b);
	if (!sorted.length) return { p50: 0, p75: 0, p95: 0, max: 0 };
	const at = (p) => sorted[Math.min(sorted.length - 1, Math.ceil((p / 100) * sorted.length) - 1)];
	return { p50: at(50), p75: at(75), p95: at(95), max: sorted[sorted.length - 1] };
}

export const PROVIDERS = [
	{
		id: 'coingecko',
		name: 'CoinGecko',
		category: 'crypto-market-data',
		base: 'https://api.coingecko.com/api/v3',
		requiresKey: false,
		// CoinGecko's optional Pro key lifts rate limits; works key-free otherwise.
		envVar: 'COINGECKO_API_KEY',
		byokHeader: 'x-provider-key',
		applyKey: (headers, _url, key) => {
			if (key) headers['x-cg-pro-api-key'] = key;
		},
		endpoints: [
			{
				id: 'price',
				method: 'GET',
				path: '/simple/price',
				query: (q) => ({
					ids: required(q.ids, 'ids'),
					vs_currencies: q.vs_currencies || 'usd',
					include_24hr_change: q.include_24hr_change,
					include_market_cap: q.include_market_cap,
				}),
				// Keyless CoinGecko public tier — generous free quota, funnel-sized.
				free: { perMin: 30, perDay: 2000 },
				priceAtomics: '1000',
				scope: 'agents:read',
				summary: 'Spot price for one or more coins in any fiat/crypto.',
				params: {
					ids: 'comma-separated CoinGecko coin ids, e.g. "solana,bitcoin" (required)',
					vs_currencies: 'comma-separated quote currencies (default "usd")',
					include_24hr_change: 'true to include 24h change',
					include_market_cap: 'true to include market cap',
				},
			},
			{
				id: 'markets',
				method: 'GET',
				path: '/coins/markets',
				query: (q) => ({
					vs_currency: q.vs_currency || 'usd',
					ids: q.ids,
					order: q.order || 'market_cap_desc',
					per_page: Math.min(Math.max(1, Number(q.per_page) || 20), 100),
					page: Number(q.page) || 1,
					price_change_percentage: q.price_change_percentage,
				}),
				free: { perMin: 30, perDay: 2000 },
				priceAtomics: '2000',
				scope: 'agents:read',
				summary: 'Ranked market data (price, market cap, volume, change) per coin.',
				params: {
					vs_currency: 'quote currency (default "usd")',
					ids: 'comma-separated coin ids to filter (optional)',
					order: 'sort order (default "market_cap_desc")',
					per_page: 'number 1–100 (default 20)',
					page: 'page number (default 1)',
				},
			},
			{
				id: 'coin',
				method: 'GET',
				// Verified live 2026-07-08: /coins/{id} with the four heavy flags off
				// still returns a full market_data block + a per-language description.
				path: (q) => `/coins/${encodeURIComponent(required(q.id, 'id'))}`,
				query: () => ({
					localization: 'false',
					tickers: 'false',
					community_data: 'false',
					developer_data: 'false',
				}),
				// Full response is heavy (per-currency market_data + multi-language
				// descriptions); keep only USD market essentials + a truncated English
				// description so one call stays small.
				transform: (data) => {
					if (!data || typeof data !== 'object') return data;
					const md = data.market_data || {};
					const usd = (obj) => (obj && typeof obj === 'object' ? obj.usd : undefined);
					const description = typeof data.description?.en === 'string' ? data.description.en.slice(0, 500) : null;
					return {
						id: data.id,
						symbol: data.symbol,
						name: data.name,
						description,
						market_cap_rank: data.market_cap_rank,
						price_usd: usd(md.current_price),
						ath_usd: usd(md.ath),
						ath_change_percentage: usd(md.ath_change_percentage),
						atl_usd: usd(md.atl),
						atl_change_percentage: usd(md.atl_change_percentage),
						market_cap_usd: usd(md.market_cap),
						fully_diluted_valuation_usd: usd(md.fully_diluted_valuation),
						total_volume_usd: usd(md.total_volume),
						circulating_supply: md.circulating_supply,
						total_supply: md.total_supply,
						max_supply: md.max_supply,
						price_change_percentage_24h: md.price_change_percentage_24h,
						price_change_percentage_7d: md.price_change_percentage_7d,
						price_change_percentage_30d: md.price_change_percentage_30d,
						last_updated: md.last_updated,
					};
				},
				free: { perMin: 20, perDay: 1500 },
				priceAtomics: '1000',
				scope: 'agents:read',
				summary: 'Full market snapshot for one coin — price, ATH/ATL, supply, multi-window change, truncated description.',
				params: { id: 'CoinGecko coin id, e.g. "solana" (required)' },
			},
			{
				id: 'trending',
				method: 'GET',
				// Verified live 2026-07-08: /search/trending → { coins, nfts, categories }.
				path: '/search/trending',
				query: () => ({}),
				transform: (data) => {
					if (!data || typeof data !== 'object') return { coins: [], categories: [] };
					const coins = Array.isArray(data.coins)
						? data.coins.map((c) => ({
								id: c?.item?.id,
								symbol: c?.item?.symbol,
								name: c?.item?.name,
								market_cap_rank: c?.item?.market_cap_rank,
								price_btc: c?.item?.price_btc,
							}))
						: [];
					const categories = Array.isArray(data.categories)
						? data.categories.map((c) => ({
								id: c?.id,
								name: c?.name,
								slug: c?.slug,
								coins_count: c?.coins_count,
								market_cap_usd: c?.data?.market_cap,
							}))
						: [];
					return { coins, categories };
				},
				free: { perMin: 20, perDay: 1500 },
				priceAtomics: '1000',
				scope: 'agents:read',
				summary: 'Top trending searched coins and hot categories right now.',
				params: {},
			},
			{
				id: 'token-price',
				method: 'GET',
				// Verified live 2026-07-08: /simple/token_price/solana?contract_addresses=…
				path: (q) => `/simple/token_price/${encodeURIComponent(q.platform || 'solana')}`,
				query: (q) => ({
					contract_addresses: required(q.addresses, 'addresses'),
					vs_currencies: q.vs_currencies || 'usd',
				}),
				free: { perMin: 20, perDay: 1500 },
				priceAtomics: '1000',
				scope: 'agents:read',
				summary: 'Spot price for one or more token contract addresses on a given chain (default Solana).',
				params: {
					platform: 'CoinGecko asset platform id, e.g. "solana" or "ethereum" (default "solana")',
					addresses: 'comma-separated contract addresses, e.g. "FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump" (required)',
					vs_currencies: 'comma-separated quote currencies (default "usd")',
				},
			},
			{
				id: 'global',
				method: 'GET',
				// Verified live 2026-07-08: /global → { data: { ... } }.
				path: '/global',
				query: () => ({}),
				transform: (data) => {
					const d = data?.data || {};
					return {
						active_cryptocurrencies: d.active_cryptocurrencies,
						markets: d.markets,
						total_market_cap_usd: d.total_market_cap?.usd,
						total_volume_usd: d.total_volume?.usd,
						btc_dominance: d.market_cap_percentage?.btc,
						eth_dominance: d.market_cap_percentage?.eth,
						market_cap_change_percentage_24h_usd: d.market_cap_change_percentage_24h_usd,
						updated_at: d.updated_at,
					};
				},
				free: { perMin: 20, perDay: 1500 },
				priceAtomics: '1000',
				scope: 'agents:read',
				summary: 'Global crypto market snapshot — total market cap/volume, BTC/ETH dominance, active coin count.',
				params: {},
			},
			{
				id: 'ohlc',
				method: 'GET',
				// Verified live 2026-07-08: /coins/{id}/ohlc?vs_currency=usd&days=1 →
				// [[time_ms, open, high, low, close], …].
				path: (q) => `/coins/${encodeURIComponent(required(q.id, 'id'))}/ohlc`,
				query: (q) => ({
					vs_currency: q.vs_currency || 'usd',
					days: [1, 7, 14, 30].includes(Number(q.days)) ? String(Number(q.days)) : '1',
				}),
				transform: (data) =>
					Array.isArray(data)
						? data.map(([t, o, h, l, c]) => ({ t, o, h, l, c }))
						: [],
				free: { perMin: 20, perDay: 1500 },
				priceAtomics: '1000',
				scope: 'agents:read',
				summary: 'OHLC candles for one coin over 1/7/14/30 days.',
				params: {
					id: 'CoinGecko coin id, e.g. "solana" (required)',
					vs_currency: 'quote currency (default "usd")',
					days: 'candle window: 1, 7, 14, or 30 (default 1)',
				},
			},
		],
	},
	{
		id: 'defillama',
		name: 'DefiLlama',
		category: 'defi-data',
		base: 'https://api.llama.fi',
		requiresKey: false,
		envVar: null,
		byokHeader: null,
		applyKey: () => {},
		endpoints: [
			{
				id: 'protocols',
				method: 'GET',
				path: '/protocols',
				query: () => ({}),
				// DefiLlama returns ~3k protocols; slim to the fields callers actually
				// use so one call doesn't ship a multi-MB payload.
				transform: (data) =>
					Array.isArray(data)
						? data
								.map((p) => ({
									name: p.name,
									symbol: p.symbol,
									category: p.category,
									chains: p.chains,
									tvl: p.tvl,
									change_1d: p.change_1d,
									change_7d: p.change_7d,
									mcap: p.mcap,
								}))
								.sort((a, b) => (b.tvl || 0) - (a.tvl || 0))
						: data,
				// Keyless DefiLlama public tier — generous free quota, funnel-sized.
				free: { perMin: 30, perDay: 2000 },
				priceAtomics: '1000',
				scope: 'agents:read',
				summary: 'All DeFi protocols with current TVL, ranked.',
				params: {},
			},
			{
				id: 'tvl',
				method: 'GET',
				path: (q) => `/tvl/${encodeURIComponent(required(q.protocol, 'protocol'))}`,
				query: () => ({}),
				transform: (data) => ({ tvl_usd: typeof data === 'number' ? data : Number(data) }),
				free: { perMin: 30, perDay: 2000 },
				priceAtomics: '1000',
				scope: 'agents:read',
				summary: 'Current total value locked (USD) for a single protocol.',
				params: { protocol: 'DefiLlama protocol slug, e.g. "uniswap" (required)' },
			},
			{
				id: 'chains',
				method: 'GET',
				// Verified live 2026-07-08: /v2/chains → flat array of every tracked chain.
				path: '/v2/chains',
				query: () => ({}),
				transform: (data) =>
					Array.isArray(data)
						? data
								.map((c) => ({ name: c.name, tvl: c.tvl, tokenSymbol: c.tokenSymbol, chainId: c.chainId }))
								.sort((a, b) => (b.tvl || 0) - (a.tvl || 0))
						: [],
				free: { perMin: 30, perDay: 2000 },
				priceAtomics: '1000',
				scope: 'agents:read',
				summary: 'Every chain DefiLlama tracks, with current TVL, ranked.',
				params: {},
			},
			{
				id: 'protocol',
				method: 'GET',
				// Verified live 2026-07-08: /protocol/{slug} → a HUGE object (full daily
				// TVL history per chain since inception); slim hard.
				path: (q) => `/protocol/${encodeURIComponent(required(q.slug, 'slug'))}`,
				query: () => ({}),
				transform: (data) => {
					if (!data || typeof data !== 'object') return data;
					const series = Array.isArray(data.tvl) ? data.tvl.slice(-30) : [];
					return {
						name: data.name,
						category: data.category,
						chains: data.chains,
						current_chain_tvls_usd: data.currentChainTvls,
						tvl_usd: series.map((p) => ({ date: p.date, tvl: p.totalLiquidityUSD })),
						mcap_usd: data.mcap,
					};
				},
				free: { perMin: 30, perDay: 2000 },
				priceAtomics: '1000',
				scope: 'agents:read',
				summary: 'One protocol: category, per-chain current TVL, and the last 30 points of its total TVL series.',
				params: { slug: 'DefiLlama protocol slug, e.g. "uniswap" (required)' },
			},
			{
				id: 'chain-tvl',
				method: 'GET',
				// Verified live 2026-07-08: /v2/historicalChainTvl/{chain} → full daily
				// series since inception; slim to the last 90 points.
				path: (q) => `/v2/historicalChainTvl/${encodeURIComponent(required(q.chain, 'chain'))}`,
				query: () => ({}),
				transform: (data) =>
					Array.isArray(data) ? data.slice(-90).map((p) => ({ date: p.date, tvl: p.tvl })) : [],
				free: { perMin: 30, perDay: 2000 },
				priceAtomics: '1000',
				scope: 'agents:read',
				summary: 'Last 90 days of historical total TVL for one chain.',
				params: { chain: 'DefiLlama chain name, e.g. "Solana" (required)' },
			},
		],
	},
	{
		id: 'llama-prices',
		name: 'DefiLlama Prices',
		category: 'crypto-market-data',
		// Sibling API on its own base — separate provider so the descriptor `base`
		// stays a single static URL per the registry contract.
		base: 'https://coins.llama.fi',
		requiresKey: false,
		envVar: null,
		byokHeader: null,
		applyKey: () => {},
		endpoints: [
			{
				id: 'current',
				method: 'GET',
				// Verified live 2026-07-08: /prices/current/{chain:address,…} →
				// { coins: { "chain:address": { decimals, symbol, price, timestamp, confidence } } }.
				path: (q) => `/prices/current/${encodeURIComponent(required(q.coins, 'coins'))}`,
				query: () => ({}),
				transform: (data) => {
					const coins = data?.coins;
					if (!coins || typeof coins !== 'object') return {};
					const out = {};
					for (const [key, v] of Object.entries(coins)) {
						if (!v || typeof v !== 'object') continue;
						out[key] = {
							price: v.price,
							symbol: v.symbol,
							decimals: v.decimals,
							timestamp: v.timestamp,
							confidence: v.confidence,
						};
					}
					return out;
				},
				free: { perMin: 30, perDay: 2000 },
				priceAtomics: '1000',
				scope: 'agents:read',
				summary: 'Current price for one or more chain:address tokens (DefiLlama coin-price oracle — covers tokens CoinGecko/Jupiter don\'t index).',
				params: {
					coins: 'comma-separated "chain:address" pairs, e.g. "solana:FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump" (required)',
				},
			},
		],
	},
	{
		id: 'llama-stablecoins',
		name: 'DefiLlama Stablecoins',
		category: 'defi-data',
		base: 'https://stablecoins.llama.fi',
		requiresKey: false,
		envVar: null,
		byokHeader: null,
		applyKey: () => {},
		endpoints: [
			{
				id: 'list',
				method: 'GET',
				// Verified live 2026-07-08: /stablecoins?includePrices=true →
				// { peggedAssets: [...] }.
				path: '/stablecoins',
				query: () => ({ includePrices: 'true' }),
				transform: (data) => {
					const assets = data?.peggedAssets;
					if (!Array.isArray(assets)) return [];
					return assets
						.map((a) => ({
							name: a.name,
							symbol: a.symbol,
							pegType: a.pegType,
							price: a.price,
							circulating_usd: a.circulating?.peggedUSD,
							circulating_prev_day_usd: a.circulatingPrevDay?.peggedUSD,
						}))
						.sort((a, b) => (b.circulating_usd || 0) - (a.circulating_usd || 0))
						.slice(0, 50);
				},
				free: { perMin: 30, perDay: 2000 },
				priceAtomics: '1000',
				scope: 'agents:read',
				summary: 'Every tracked stablecoin — peg type, price, circulating supply — ranked by circulating USD.',
				params: {},
			},
		],
	},
	{
		id: 'jupiter',
		name: 'Jupiter',
		category: 'crypto-market-data',
		// Jupiter's keyless "lite" tier (no API key). The paid/keyed tier lives on
		// api.jup.ag behind an x-api-key header; the descriptor base is static, so
		// we intentionally stay on the lite base and expose no BYOK header — every
		// endpoint here is Jupiter's free keyless surface.
		base: 'https://lite-api.jup.ag',
		requiresKey: false,
		envVar: null,
		byokHeader: null,
		applyKey: () => {},
		endpoints: [
			{
				id: 'price',
				method: 'GET',
				// Verified live 2026-07-06: /price/v3 responds; /price/v2 → "Route not found".
				path: '/price/v3',
				query: (q) => ({ ids: required(q.ids, 'ids') }),
				// v3 returns { [mint]: { usdPrice, decimals, priceChange24h, liquidity,
				// blockId, createdAt, launchpad? } }. Keep the stable, agent-useful
				// fields under normalized names; unknown mints are simply absent.
				transform: (data) => {
					if (!data || typeof data !== 'object' || Array.isArray(data)) return {};
					const out = {};
					for (const [mint, v] of Object.entries(data)) {
						if (!v || typeof v !== 'object') continue;
						out[mint] = {
							price_usd: v.usdPrice,
							decimals: v.decimals,
							price_change_24h: v.priceChange24h,
							liquidity: v.liquidity,
							block_id: v.blockId,
						};
					}
					return out;
				},
				free: { perMin: 20, perDay: 2000 },
				priceAtomics: '1000',
				scope: 'agents:read',
				summary: 'Live USD price for one or more Solana tokens by mint (Jupiter keyless tier).',
				params: {
					ids: 'comma-separated Solana mint addresses, e.g. "FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump,So11111111111111111111111111111111111111112" (required)',
				},
			},
			{
				id: 'quote',
				method: 'GET',
				// Verified live 2026-07-06: /swap/v1/quote responds; /v6/quote → "Route not found".
				path: '/swap/v1/quote',
				query: (q) => ({
					inputMint: required(q.inputMint, 'inputMint'),
					outputMint: required(q.outputMint, 'outputMint'),
					amount: required(q.amount, 'amount'),
					slippageBps: q.slippageBps || '50',
				}),
				// The true executable price. Keep the amounts + impact + a slimmed route
				// (label, mints, percent per hop); drop the heavy AMM/quote-report noise.
				transform: (data) => {
					if (!data || typeof data !== 'object') return data;
					return {
						inputMint: data.inputMint,
						outputMint: data.outputMint,
						inAmount: data.inAmount,
						outAmount: data.outAmount,
						otherAmountThreshold: data.otherAmountThreshold,
						swapMode: data.swapMode,
						slippageBps: data.slippageBps,
						priceImpactPct: data.priceImpactPct,
						routePlan: Array.isArray(data.routePlan)
							? data.routePlan.map((hop) => ({
									label: hop?.swapInfo?.label,
									inputMint: hop?.swapInfo?.inputMint,
									outputMint: hop?.swapInfo?.outputMint,
									percent: hop?.percent,
								}))
							: [],
					};
				},
				free: { perMin: 20, perDay: 2000 },
				priceAtomics: '1000',
				scope: 'agents:read',
				summary: 'Executable swap quote (true routed price) between two Solana mints (Jupiter keyless tier).',
				params: {
					inputMint: 'input token mint address, e.g. "So11111111111111111111111111111111111111112" (required)',
					outputMint: 'output token mint address, e.g. USDC "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" (required)',
					amount: 'input amount in atomic units (integer string), e.g. "1000000000" for 1 SOL (required)',
					slippageBps: 'allowed slippage in basis points (default "50" = 0.5%)',
				},
			},
			{
				id: 'token-search',
				method: 'GET',
				// Verified live 2026-07-06: /tokens/v2/search responds; /tokens/v1/* → "Route not found".
				path: '/tokens/v2/search',
				query: (q) => ({ query: required(q.query, 'query') }),
				// v2 search returns a rich array; slim each hit to the identity fields
				// agents use and derive 24h volume from the stats24h buy/sell split.
				// Cap 20 so one call never ships a multi-hundred-KB payload.
				transform: (data) => {
					if (!Array.isArray(data)) return [];
					return data.slice(0, 20).map((t) => {
						const s = t?.stats24h;
						const daily_volume =
							s && (s.buyVolume != null || s.sellVolume != null)
								? (Number(s.buyVolume) || 0) + (Number(s.sellVolume) || 0)
								: undefined;
						return {
							address: t?.id,
							name: t?.name,
							symbol: t?.symbol,
							decimals: t?.decimals,
							logoURI: t?.icon,
							tags: Array.isArray(t?.tags) ? t.tags : undefined,
							daily_volume,
						};
					});
				},
				free: { perMin: 20, perDay: 2000 },
				priceAtomics: '1000',
				scope: 'agents:read',
				summary: 'Search Solana tokens by name/symbol/mint → address, metadata, tags, 24h volume (Jupiter keyless tier).',
				params: {
					query: 'search text — token name, symbol, or mint address, e.g. "three.ws" or a mint (required)',
				},
			},
		],
	},
	{
		id: 'openai',
		name: 'OpenAI-compatible LLM',
		category: 'ai-inference',
		base: 'https://api.openai.com/v1',
		requiresKey: true,
		envVar: 'OPENAI_API_KEY',
		byokHeader: 'x-provider-key',
		applyKey: (headers, _url, key) => {
			if (key) headers['authorization'] = `Bearer ${key}`;
		},
		endpoints: [
			{
				id: 'chat',
				method: 'POST',
				path: '/chat/completions',
				body: (b) => {
					if (!b || typeof b !== 'object' || !Array.isArray(b.messages)) {
						const err = new Error('body must include a "messages" array');
						err.status = 400;
						err.code = 'validation_error';
						throw err;
					}
					return b;
				},
				priceAtomics: '5000',
				scope: 'agents:write',
				summary: 'Chat completions against any OpenAI-compatible model (BYOK supported).',
				params: {
					model: 'model id (required)',
					messages: 'array of {role, content} (required)',
					'…': 'any other OpenAI chat-completions parameter is forwarded',
				},
			},
		],
	},
	{
		id: 'grok',
		name: 'Grok (xAI)',
		category: 'ai-inference',
		base: XAI_API_BASE,
		requiresKey: true,
		envVar: 'GROK_API_KEY',
		byokHeader: 'x-provider-key',
		applyKey: (headers, _url, key) => {
			if (key) headers['authorization'] = `Bearer ${key}`;
		},
		endpoints: [
			{
				id: 'chat',
				method: 'POST',
				path: '/chat/completions',
				body: (b) => {
					if (!b || typeof b !== 'object' || !Array.isArray(b.messages)) {
						const err = new Error('body must include a "messages" array');
						err.status = 400;
						err.code = 'validation_error';
						throw err;
					}
					// A retired Grok slug maps to its successor instead of 404ing.
					return typeof b.model === 'string' ? { ...b, model: resolveGrokModelId(b.model) } : b;
				},
				priceAtomics: '5000',
				scope: 'agents:write',
				summary: `Chat completions against xAI Grok models (${GROK_MENU_MODELS.map((m) => m.id).join(', ')}; BYOK supported).`,
				params: {
					model: `Grok model id, e.g. "${GROK_DEFAULT_MODEL}" (required)`,
					messages: 'array of {role, content} (required)',
					'…': 'any other OpenAI chat-completions parameter is forwarded',
				},
			},
		],
	},
	{
		id: 'dexscreener',
		name: 'DexScreener',
		category: 'crypto-market-data',
		// Keyless public API — no key, no BYOK header, no envVar. Upstream limits
		// are ~300/min for token/search/pair and ~60/min shared for profiles/
		// boosts; our `free` quotas below stay well under both.
		base: 'https://api.dexscreener.com',
		requiresKey: false,
		envVar: null,
		byokHeader: null,
		applyKey: () => {},
		endpoints: [
			{
				id: 'token',
				method: 'GET',
				// Verified live 2026-07-08: /latest/dex/tokens/{addresses} →
				// { schemaVersion, pairs: [...] } for the $THREE mint.
				path: (q) => `/latest/dex/tokens/${encodeURIComponent(capAddressList(required(q.addresses, 'addresses')))}`,
				query: () => ({}),
				transform: (data) => slimDexPairs(data, 30),
				free: { perMin: 30, perDay: 3000 },
				priceAtomics: '1000',
				scope: 'agents:read',
				summary: 'Live DEX pairs (price, liquidity, volume, txns) for one or more token addresses, deepest liquidity first.',
				params: {
					addresses: 'comma-separated token contract addresses, up to 30, e.g. "FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump" (required)',
				},
			},
			{
				id: 'search',
				method: 'GET',
				// Verified live 2026-07-08: /latest/dex/search?q= → same { pairs: [...] } shape.
				path: '/latest/dex/search',
				query: (q) => ({ q: required(q.q, 'q') }),
				transform: (data) => slimDexPairs(data, 20),
				free: { perMin: 30, perDay: 3000 },
				priceAtomics: '1000',
				scope: 'agents:read',
				summary: 'Search DEX pairs by token name, symbol, or address, deepest liquidity first.',
				params: {
					q: 'search text — token name, symbol, or address, e.g. "three.ws" or "FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump" (required)',
				},
			},
			{
				id: 'pair',
				method: 'GET',
				// Verified live 2026-07-08: /latest/dex/pairs/{chain}/{pair} → same { pairs: [...] } shape.
				path: (q) =>
					`/latest/dex/pairs/${encodeURIComponent(required(q.chain, 'chain'))}/${encodeURIComponent(required(q.pair, 'pair'))}`,
				query: () => ({}),
				transform: (data) => slimDexPairs(data, 30),
				free: { perMin: 30, perDay: 3000 },
				priceAtomics: '1000',
				scope: 'agents:read',
				summary: 'Live pair data for one DexScreener chainId + on-chain pair address.',
				params: {
					chain: 'DexScreener chainId, e.g. "solana" (required)',
					pair: 'on-chain pair/pool address, e.g. the $THREE/SOL pumpswap pair "5ByL7MZoLABYnwMPZKPKjf4MGkZ7FeBzrAnos19Pre2z" (required)',
				},
			},
			{
				id: 'profiles',
				method: 'GET',
				// Verified live 2026-07-08: /token-profiles/latest/v1 → flat array.
				path: '/token-profiles/latest/v1',
				query: () => ({}),
				transform: (data) => slimDexProfileList(data, 30),
				free: { perMin: 10, perDay: 500 },
				priceAtomics: '1000',
				scope: 'agents:read',
				summary: 'Latest DexScreener token profiles — freshly listed projects with descriptions and social links.',
				params: {},
			},
			{
				id: 'boosts',
				method: 'GET',
				// Verified live 2026-07-08: /token-boosts/latest/v1 → flat array.
				path: '/token-boosts/latest/v1',
				query: () => ({}),
				transform: (data) => slimDexProfileList(data, 30),
				free: { perMin: 10, perDay: 500 },
				priceAtomics: '1000',
				scope: 'agents:read',
				summary: 'Latest DexScreener boosted tokens — paid promotion signal, not an endorsement or ranking by quality.',
				params: {},
			},
		],
	},
	{
		id: 'solana',
		name: 'Solana RPC',
		category: 'onchain-data',
		// Same env resolution every other Solana caller on the platform uses
		// (api/_lib/env.js) — a configured Helius/Quicknode/Triton URL, or the
		// public mainnet endpoint as a working fallback.
		base: SOLANA_RPC_BASE,
		// The platform's full priority-ordered RPC pool (operator endpoint,
		// QuickNode, Helius, Alchemy, then public hosts), used by the aggregator
		// only after the primary answers 429/5xx — a public RPC rate-limiting us
		// is not a reason to fail a caller when six healthy alternates exist.
		// Imported lazily so the happy path never loads @solana/web3.js.
		bases: async () => {
			const { solanaRpcEndpoints, isEndpointCooling } = await import('../_lib/solana/connection.js');
			// Hosts the process-wide RPC registry already knows are cooling (quota
			// death, auth failure, recent 429) go to the back of the line, so the
			// aggregator's capped attempts land on believed-healthy rungs first.
			const pool = solanaRpcEndpoints('mainnet');
			return [...pool.filter((u) => !isEndpointCooling(u)), ...pool.filter((u) => isEndpointCooling(u))];
		},
		// Share host health with the rest of the platform, both directions: skip
		// hosts other subsystems (balances cron, indexers) found dead, and report
		// what the aggregator sees back into the same registry, which sizes the
		// cooldown to the failure class (6h quota death vs 10m transient 429).
		isHostCooling: async (url) => {
			const { isEndpointCooling } = await import('../_lib/solana/connection.js');
			return isEndpointCooling(url);
		},
		reportHostFailure: async (url, status, bodyText) => {
			const { markEndpointCooldown } = await import('../_lib/solana/connection.js');
			markEndpointCooldown(url, status, bodyText);
		},
		requiresKey: false,
		envVar: null,
		byokHeader: null,
		applyKey: () => {},
		endpoints: [
			{
				id: 'balance',
				method: 'GET',
				// GET caller-side; the upstream is Solana's single JSON-RPC POST
				// endpoint. See `upstreamMethod` in the descriptor contract above.
				upstreamMethod: 'POST',
				path: '',
				body: (q) => rpcBody('getBalance', [required(q.address, 'address')]),
				// Verified live 2026-07-08: { result: { context, value: <lamports> } }.
				transform: (data) => {
					const result = rpcResult(data);
					const lamports = typeof result?.value === 'number' ? result.value : null;
					return { lamports, sol: lamports != null ? lamports / 1e9 : null };
				},
				free: { perMin: 20, perDay: 2000 },
				priceAtomics: '1000',
				scope: 'agents:read',
				summary: 'Native SOL balance of any wallet address.',
				params: {
					address: 'Solana base58 wallet address, e.g. "11111111111111111111111111111111" (required)',
				},
			},
			{
				id: 'token-holdings',
				method: 'GET',
				upstreamMethod: 'POST',
				path: '',
				body: (q) =>
					rpcBody('getTokenAccountsByOwner', [
						required(q.owner, 'owner'),
						{ programId: 'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA' },
						{ encoding: 'jsonParsed' },
					]),
				// Verified live 2026-07-08: { result: { value: [{ pubkey, account: {
				// data: { parsed: { info: { mint, tokenAmount: { amount, decimals,
				// uiAmount } } } } } }] } }.
				transform: (data) => {
					const result = rpcResult(data);
					const value = Array.isArray(result?.value) ? result.value : [];
					return value
						.map((entry) => {
							const info = entry?.account?.data?.parsed?.info;
							const amt = info?.tokenAmount;
							if (!info || !amt) return null;
							return {
								mint: info.mint ?? null,
								amount: amt.amount ?? null,
								decimals: amt.decimals ?? null,
								uiAmount: amt.uiAmount ?? null,
							};
						})
						.filter((t) => t && t.uiAmount)
						.sort((a, b) => (b.uiAmount || 0) - (a.uiAmount || 0));
				},
				free: { perMin: 20, perDay: 2000 },
				priceAtomics: '1000',
				scope: 'agents:read',
				summary: 'SPL token holdings of a wallet (mint, amount, decimals), zero balances filtered, largest first.',
				params: {
					owner: 'Solana base58 wallet address, e.g. "11111111111111111111111111111111" (required)',
				},
			},
			{
				id: 'token-supply',
				method: 'GET',
				upstreamMethod: 'POST',
				path: '',
				body: (q) => rpcBody('getTokenSupply', [required(q.mint, 'mint')]),
				// Verified live 2026-07-08 ($THREE mint): { result: { value: {
				// amount, decimals, uiAmount, uiAmountString } } }.
				transform: (data) => {
					const result = rpcResult(data);
					const v = result?.value;
					if (!v) rpcNotFound('mint not found or not an SPL token', 'mint_not_found');
					return { amount: v.amount ?? null, decimals: v.decimals ?? null, uiAmount: v.uiAmount ?? null };
				},
				free: { perMin: 20, perDay: 2000 },
				priceAtomics: '1000',
				scope: 'agents:read',
				summary: 'Total circulating supply of an SPL token mint.',
				params: {
					mint: 'Solana token mint address, e.g. "FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump" (required)',
				},
			},
			{
				id: 'largest-holders',
				method: 'GET',
				upstreamMethod: 'POST',
				path: '',
				body: (q) => rpcBody('getTokenLargestAccounts', [required(q.mint, 'mint')]),
				// Documented shape (getTokenLargestAccounts, top 20 by protocol limit):
				// { result: { value: [{ address, amount, decimals, uiAmount,
				// uiAmountString }] } }.
				transform: (data) => {
					const result = rpcResult(data);
					const value = Array.isArray(result?.value) ? result.value : [];
					return value
						.slice(0, 20)
						.map((v) => ({ address: v.address ?? null, uiAmount: v.uiAmount ?? null }));
				},
				free: { perMin: 20, perDay: 2000 },
				priceAtomics: '1000',
				scope: 'agents:read',
				summary: 'Top 20 holder token-accounts of an SPL token mint by balance.',
				params: {
					mint: 'Solana token mint address, e.g. "FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump" (required)',
				},
			},
			{
				id: 'transaction',
				method: 'GET',
				upstreamMethod: 'POST',
				path: '',
				body: (q) =>
					rpcBody('getTransaction', [
						required(q.signature, 'signature'),
						{ encoding: 'jsonParsed', maxSupportedTransactionVersion: 1 },
					]),
				// Verified live 2026-07-08 (real $THREE transfer signature): { result: {
				// slot, blockTime, transaction: { message: { accountKeys: [{ pubkey,
				// signer }] }, signatures }, meta: { fee, err, logMessages,
				// preTokenBalances, postTokenBalances } } }. result is null when the
				// signature is unknown/not yet finalized — surfaced as 404, not a
				// payload of nulls.
				transform: (data) => {
					const result = rpcResult(data);
					if (!result) rpcNotFound('transaction not found (unknown signature or not yet finalized)', 'transaction_not_found');
					const meta = result.meta || {};
					const accountKeys = Array.isArray(result.transaction?.message?.accountKeys)
						? result.transaction.message.accountKeys
						: [];
					const signers = accountKeys.filter((k) => k?.signer).map((k) => k.pubkey);

					// Pre/post SPL token balance deltas keyed by accountIndex+mint — the
					// one number an agent actually wants ("how much moved"), not two
					// snapshots it has to diff itself.
					const byKey = new Map();
					for (const b of Array.isArray(meta.preTokenBalances) ? meta.preTokenBalances : []) {
						byKey.set(`${b.accountIndex}:${b.mint}`, { mint: b.mint, owner: b.owner ?? null, pre: b.uiTokenAmount?.uiAmount ?? 0, post: 0 });
					}
					for (const b of Array.isArray(meta.postTokenBalances) ? meta.postTokenBalances : []) {
						const key = `${b.accountIndex}:${b.mint}`;
						const existing = byKey.get(key);
						if (existing) existing.post = b.uiTokenAmount?.uiAmount ?? 0;
						else byKey.set(key, { mint: b.mint, owner: b.owner ?? null, pre: 0, post: b.uiTokenAmount?.uiAmount ?? 0 });
					}
					const tokenBalanceChanges = [...byKey.values()]
						.map((v) => ({ mint: v.mint, owner: v.owner, delta: (v.post || 0) - (v.pre || 0) }))
						.filter((v) => v.delta !== 0);

					return {
						slot: result.slot ?? null,
						blockTime: result.blockTime ?? null,
						fee: meta.fee ?? null,
						err: meta.err ?? null,
						signers,
						logMessages: Array.isArray(meta.logMessages) ? meta.logMessages.slice(0, 20) : [],
						tokenBalanceChanges,
					};
				},
				free: { perMin: 20, perDay: 2000 },
				priceAtomics: '1000',
				scope: 'agents:read',
				summary: 'Confirmed transaction detail by signature — fee, error, signers, log lines, and SPL token balance deltas.',
				params: {
					signature: 'base58 transaction signature (required)',
				},
			},
			{
				id: 'account',
				method: 'GET',
				upstreamMethod: 'POST',
				path: '',
				body: (q) => rpcBody('getAccountInfo', [required(q.address, 'address'), { encoding: 'jsonParsed' }]),
				// Verified live 2026-07-08 ($THREE mint): { result: { value: {
				// owner, lamports, executable, data: { program, parsed: { type } } } } }.
				// result.value is null for an unfunded/nonexistent address.
				transform: (data) => {
					const result = rpcResult(data);
					if (!result?.value) rpcNotFound('account not found (unfunded or nonexistent address)', 'account_not_found');
					const v = result.value;
					return {
						owner: v.owner ?? null,
						lamports: v.lamports ?? null,
						executable: Boolean(v.executable),
						program: v.data?.program ?? null,
						parsedType: v.data?.parsed?.type ?? null,
					};
				},
				free: { perMin: 20, perDay: 2000 },
				priceAtomics: '1000',
				scope: 'agents:read',
				summary: 'Account info for any address — owning program, lamports, executable flag, parsed data type.',
				params: {
					address: 'Solana base58 address, e.g. "FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump" (required)',
				},
			},
			{
				id: 'priority-fees',
				method: 'GET',
				upstreamMethod: 'POST',
				path: '',
				body: () => rpcBody('getRecentPrioritizationFees', []),
				// Verified live 2026-07-08: { result: [{ slot, prioritizationFee }, ...] }
				// for the last ~150 slots.
				transform: (data) => {
					const result = rpcResult(data);
					const fees = Array.isArray(result) ? result.map((r) => Number(r.prioritizationFee) || 0) : [];
					return percentiles(fees);
				},
				free: { perMin: 20, perDay: 2000 },
				priceAtomics: '1000',
				scope: 'agents:read',
				summary: 'Recent prioritization fee landscape (p50/p75/p95/max micro-lamports) over the last ~150 slots.',
				params: {},
			},
		],
	},
];

// Flat lookup map: "provider/endpoint" → { provider, endpoint }.
export const ENDPOINT_INDEX = new Map();
for (const provider of PROVIDERS) {
	for (const endpoint of provider.endpoints) {
		ENDPOINT_INDEX.set(`${provider.id}/${endpoint.id}`, { provider, endpoint });
	}
}

/** Machine-readable catalog of every aggregated endpoint, for discovery. */
export function providerCatalog() {
	return PROVIDERS.map((p) => ({
		id: p.id,
		name: p.name,
		category: p.category,
		key: p.requiresKey ? 'required (platform key or BYOK)' : 'optional',
		byok: Boolean(p.byokHeader),
		endpoints: p.endpoints.map((e) => ({
			id: e.id,
			method: e.method,
			path: `/api/v1/x/${p.id}/${e.id}`,
			scope: e.scope,
			price_usdc_atomics: e.priceAtomics,
			summary: e.summary,
			params: e.params,
			free: e.free || false,
		})),
	}));
}