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
// crypto_data + token_snapshot: MCP front door onto the /api/v1/x aggregator
// (api/v1/_providers.js). Generated from the live registry so the toolset
// grows automatically as provider prompts land, with no hand-enumerated endpoint
// list to keep in sync.
//
// Design (owner-approved, x402-catalog campaign work order 10):
// one generic tool + one curated convenience tool, not one tool per endpoint
// (a 30-tool flood degrades agent tool selection).
//
// Both tools run calls through the SAME engine the REST aggregator uses
// (executeUpstream, with the platform's own upstream key), and never re-fetch an
// upstream directly. An endpoint marked `free` in the registry is served
// within the identical per-IP quota the REST free lane enforces
// (api/v1/x/[...slug].js `serveFreeLane`) so the two doors share one budget
// instead of doubling it. A caller who exhausts the quota, or calls an
// endpoint with no free tier, gets a -32402 JSON-RPC error naming the exact
// REST URL + USDC price to pay via x402, the platform's one real payment
// rail, never a second payment flow invented for MCP.
import { ENDPOINT_INDEX, providerCatalog } from '../../v1/_providers.js';
import { executeUpstream, resolveUpstreamKey } from '../../_lib/aggregator.js';
import { limits, clientIp } from '../../_lib/rate-limit.js';
import { summarizeList } from '../../_lib/mcp-expand.js';
function rpcError(code, message, data) {
const e = new Error(message);
e.code = code;
e.data = data;
return e;
}
function toolResult(payload) {
return {
content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
structuredContent: payload,
};
}
function errorResult(message, data) {
return {
content: [{ type: 'text', text: message }],
isError: true,
structuredContent: data,
};
}
// Same per-IP identity the REST free lane keys its quota by. `req` is absent
// under some transports (unit tests, non-HTTP dispatch), so fall back to the
// caller's account id, then a shared anonymous bucket.
function callerKey(auth, req) {
if (req) {
try {
return `ip:${clientIp(req)}`;
} catch {
/* fall through */
}
}
return auth?.userId ? `user:${auth.userId}` : 'anon';
}
/** Every "provider/endpoint" pair currently registered, for error hints. */
function listPairs() {
return [...ENDPOINT_INDEX.keys()].sort();
}
/** One line per endpoint, generated fresh from the live registry at call time. */
function describePairs() {
return providerCatalog()
.flatMap((p) => p.endpoints.map((e) => `${p.id}/${e.id}: ${e.summary}`))
.join('\n');
}
/**
* Run one aggregator call, honoring the endpoint's free-tier quota (if any).
* Shared by both tools so token_snapshot's fan-out and crypto_data's direct
* call enforce identically. Never throws: every outcome is a tagged result
* so callers can degrade gracefully (token_snapshot) or surface a clean
* payment-required error (crypto_data).
*/
async function runEndpoint({ providerId, endpointId, params, auth, req }) {
const hit = ENDPOINT_INDEX.get(`${providerId}/${endpointId}`);
if (!hit) return { ok: false, reason: 'unknown_pair' };
const { provider, endpoint } = hit;
if (endpoint.free) {
const key = callerKey(auth, req);
const bucket = `${provider.id}:${endpoint.id}:mcp:${key}`;
const [minR, dayR] = await Promise.all([
limits.apiV1FreeMin(bucket, endpoint.free.perMin),
limits.apiV1FreeDay(bucket, endpoint.free.perDay),
]);
if (!minR.success || !dayR.success) {
const blocked = !minR.success ? minR : dayR;
return {
ok: false,
reason: 'quota_exceeded',
provider: provider.id,
endpoint: endpoint.id,
reset: new Date(blocked.reset).toISOString(),
priceAtomics: endpoint.priceAtomics,
restUrl: `/api/v1/x/${provider.id}/${endpoint.id}`,
};
}
} else {
return {
ok: false,
reason: 'payment_required',
provider: provider.id,
endpoint: endpoint.id,
priceAtomics: endpoint.priceAtomics,
restUrl: `/api/v1/x/${provider.id}/${endpoint.id}`,
};
}
const { key: apiKey } = resolveUpstreamKey(provider, null);
try {
const data = await executeUpstream({ provider, endpoint, query: params || {}, apiKey });
return { ok: true, provider: provider.id, endpoint: endpoint.id, data };
} catch (err) {
return {
ok: false,
reason: 'upstream_error',
provider: provider.id,
endpoint: endpoint.id,
message: err?.message || 'upstream call failed',
status: err?.status || 502,
};
}
}
// Rows per page for a summarized crypto_data answer.
const DATA_PAGE_SIZE = 10;
/**
* The longest array in an upstream answer: the answer itself when it is a list,
* else the biggest list one or two levels down (a `data` or `pairs` key).
* Returns { path, rows } or null when nothing in it is a list.
*/
export function findRows(data) {
if (Array.isArray(data)) return { path: [], rows: data };
let best = null;
const visit = (node, path, depth) => {
if (!node || typeof node !== 'object' || Array.isArray(node) || depth > 2) return;
for (const [key, value] of Object.entries(node)) {
if (Array.isArray(value) && (!best || value.length > best.rows.length)) best = { path: [...path, key], rows: value };
else visit(value, [...path, key], depth + 1);
}
};
visit(data, [], 0);
return best;
}
function labelOf(row) {
if (row === null || typeof row !== 'object') return String(row);
for (const key of ['symbol', 'name', 'id', 'pairAddress', 'address', 'slug']) {
if (typeof row[key] === 'string' || typeof row[key] === 'number') return String(row[key]);
}
return Object.keys(row).slice(0, 3).join('/');
}
// A list answer becomes a summary, a count, a handle and the first page; the
// rest of the upstream answer (everything outside the list) rides along in
// `meta` so nothing but the extra rows is withheld.
async function summarizeData({ pairKey, result, auth }) {
const found = findRows(result.data);
if (!found) return null;
const labels = found.rows.slice(0, 5).map(labelOf).join(', ');
let meta;
if (found.path.length) {
meta = structuredClone(result.data);
let node = meta;
for (const p of found.path.slice(0, -1)) node = node[p];
delete node[found.path[found.path.length - 1]];
}
return summarizeList({
tool: 'crypto_data',
auth,
items: found.rows,
pageSize: DATA_PAGE_SIZE,
summary: `${pairKey} returned ${found.rows.length} rows${found.path.length ? ` under ${found.path.join('.')}` : ''}. First: ${labels}.`,
extra: { provider: result.provider, endpoint: result.endpoint, ...(meta && Object.keys(meta).length ? { meta } : {}) },
});
}
const READ_ONLY_LIVE_FEED = {
readOnlyHint: true,
destructiveHint: false,
idempotentHint: false,
openWorldHint: true,
};
export const toolDefs = [
{
name: 'crypto_data',
title: 'Crypto Data API',
annotations: READ_ONLY_LIVE_FEED,
get description() {
return (
'Call any endpoint in the three.ws free crypto data API (the same aggregator behind ' +
'GET /api/v1/x/*): DEX pairs, CoinGecko/DefiLlama market data, Jupiter Solana prices ' +
'and swap quotes, and direct Solana RPC reads. Endpoints marked free run within a ' +
'per-IP quota, no wallet needed; an endpoint with no free tier (or an exhausted quota) ' +
'returns a payment-required error naming the exact REST URL and USDC price to pay via ' +
'x402. Use this for raw data from one named provider endpoint; for a merged one-call view of a ' +
'Solana token call token_snapshot. A list answer longer than ten rows comes back as a summary, a count, a handle and the first ten rows; the expand tool reads the rest.\n\nLive provider/endpoint pairs on this deployment:\n' + describePairs()
);
},
inputSchema: {
type: 'object',
required: ['provider', 'endpoint'],
properties: {
provider: {
type: 'string',
description: 'Registered provider id, e.g. "coingecko", "dexscreener", "jupiter", "solana", "defillama".',
},
endpoint: {
type: 'string',
description: 'Endpoint id under that provider, e.g. "price", "token", "quote".',
},
params: {
type: 'object',
description: 'Endpoint-specific query params. See the endpoint summary in the tool description for required fields.',
additionalProperties: true,
default: {},
},
},
additionalProperties: false,
},
async handler(args, auth, req) {
const providerId = String(args?.provider || '').trim();
const endpointId = String(args?.endpoint || '').trim();
const pairKey = `${providerId}/${endpointId}`;
if (!ENDPOINT_INDEX.has(pairKey)) {
return errorResult(
`unknown provider/endpoint "${pairKey}". Valid pairs:\n${listPairs().join('\n')}`,
{ error: 'unknown_pair', valid_pairs: listPairs() },
);
}
const result = await runEndpoint({ providerId, endpointId, params: args?.params, auth, req });
if (result.ok) {
const summarized = await summarizeData({ pairKey, result, auth });
if (summarized) return summarized;
return toolResult({ provider: result.provider, endpoint: result.endpoint, data: result.data });
}
if (result.reason === 'quota_exceeded' || result.reason === 'payment_required') {
throw rpcError(-32402, `payment required for ${pairKey}`, {
scheme: 'x402',
provider: result.provider,
endpoint: result.endpoint,
amount_usdc_atomics: result.priceAtomics,
pay_via: `${result.restUrl}: send an X-PAYMENT header (see docs/x402.md) for pay-per-call USDC`,
...(result.reset ? { free_tier_reset: result.reset } : {}),
});
}
return errorResult(`${pairKey} upstream error: ${result.message}`, result);
},
},
{
name: 'token_snapshot',
title: 'Crypto token snapshot',
annotations: READ_ONLY_LIVE_FEED,
description:
'One-call snapshot for a Solana token mint, fanning out to whichever free crypto-data ' +
'providers are registered on this deployment (DexScreener pairs, Jupiter price, Solana RPC ' +
'supply) and merging what answers. Degrades gracefully around any provider that is absent, ' +
'unconfigured, or fails, never throwing on a partial result. Example mint: the $THREE CA ' +
'"FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump". For pump.fun-specific bonding-curve / ' +
'launch data use the pump_snapshot tool instead. Use this for a quick general market read on one ' +
'Solana token (price, liquidity, supply) without choosing providers yourself.',
inputSchema: {
type: 'object',
required: ['mint'],
properties: {
mint: { type: 'string', description: 'Base58 Solana token mint address.' },
},
additionalProperties: false,
},
async handler(args, auth, req) {
const mint = String(args?.mint || '').trim();
if (!mint) return errorResult('"mint" is required', { error: 'validation_error' });
// Fixed, small candidate set (not every registered provider): a
// snapshot is meant to answer "what is this token" in one call, not
// fan out to every provider that happens to accept a mint-shaped param.
const CANDIDATES = [
{ provider: 'dexscreener', endpoint: 'token', params: { addresses: mint } },
{ provider: 'jupiter', endpoint: 'price', params: { ids: mint } },
{ provider: 'solana', endpoint: 'token-supply', params: { mint } },
];
const snapshot = { mint, sources: [], skipped: [], failed: [] };
for (const c of CANDIDATES) {
if (!ENDPOINT_INDEX.has(`${c.provider}/${c.endpoint}`)) {
snapshot.skipped.push({
provider: c.provider,
endpoint: c.endpoint,
reason: 'not_registered_on_this_deployment',
});
continue;
}
const r = await runEndpoint({ providerId: c.provider, endpointId: c.endpoint, params: c.params, auth, req });
if (r.ok) {
snapshot[c.provider] = r.data;
snapshot.sources.push(c.provider);
} else {
snapshot.failed.push({ provider: c.provider, endpoint: c.endpoint, reason: r.reason, message: r.message });
}
}
if (snapshot.sources.length === 0) {
return errorResult(`no registered provider could resolve ${mint}`, snapshot);
}
return toolResult(snapshot);
},
},
];