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
// Shared plumbing for the trading tool registry (api/_lib/trading-tools/registry.js).
//
// A trading tool runs the same way whether it is called over MCP
// (api/_mcpagent/trading-tools.js) or REST (/api/v1/trading/*): it receives its
// arguments and a context `{ principal, req }`, and either returns a plain JSON
// result or throws a ToolInputError that both surfaces render as a designed
// refusal (a tool result with isError over MCP, a typed error envelope over
// REST). Nothing here formats output for one surface.
//
// principal: { userId, source: 'session'|'apikey'|'oauth'|..., scope, apiKeyId?, clientId? }
// req: the caller's HTTP request. Tools that reuse an existing owner-gated
// handler forward to it with the caller's own headers, so that
// handler resolves the same account and runs its full guard chain.
import { sql } from '../db.js';
import { hasScope } from '../auth.js';
import { currentSignatureFor, agreementRequirement } from '../real-funds-agreement.js';
import { ToolInputError } from './market.js';
import { PreviewError } from './preview.js';
/** A designed refusal with the HTTP status the REST surface answers with. */
export function refuse(status, code, message, detail = null) {
const e = new ToolInputError(code, message, detail);
e.status = status;
return e;
}
const PREVIEW_STATUS = {
preview_required: 400,
preview_invalid: 400,
preview_mismatch: 409,
preview_stale: 410,
preview_used: 409,
};
/**
* Normalize anything a tool can throw into `{ status, code, message, detail }`
* when it is a designed refusal, or null when it is an unexpected failure the
* surface should redact.
*/
export function describeToolError(err) {
if (!err || typeof err !== 'object') return null;
if (err instanceof PreviewError) {
return { status: PREVIEW_STATUS[err.code] || 400, code: err.code, message: err.message, detail: null };
}
if (err.isToolError) {
return { status: Number(err.status) || 422, code: err.code, message: err.message, detail: err.detail ?? null };
}
// ApiError from the v1 route helpers, SpendLimitError and friends: a 4xx
// with a string code is a message written for the caller.
const status = Number(err.status);
if (status >= 400 && status < 500 && typeof err.code === 'string') {
return { status, code: err.code, message: String(err.message || err.code), detail: err.details ?? err.detail ?? null };
}
return null;
}
/** The signed-in account, or a 401 refusal. */
export function requireUser(ctx) {
const userId = ctx?.principal?.userId;
if (!userId) {
throw refuse(401, 'auth_required', 'Sign in to three.ws (or use an API key) to act on your agents. Market reads work without an account.');
}
return userId;
}
/**
* Require a token scope. A browser session carries the whole account; a
* wallet:write grant satisfies wallet:read, since a caller allowed to spend may
* read what it is spending (and wallet:trade, via hasScope's implication map).
*/
export function requireScope(ctx, scope) {
const p = ctx?.principal;
if (!p || p.source === 'session') return;
if (hasScope(p.scope, scope)) return;
if (scope === 'wallet:read' && hasScope(p.scope, 'wallet:write')) return;
throw refuse(403, 'insufficient_scope', `This action needs the "${scope}" scope. Re-authorize (or create an API key) with it granted.`, { required: scope });
}
const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
export function requireUuidArg(value, name) {
if (typeof value !== 'string' || !UUID_RE.test(value)) {
throw refuse(400, 'invalid_parameter', `${name} must be a UUID.`, { parameter: name });
}
return value;
}
/** Load an agent the caller owns. 404 for an unknown id, 403 for someone else's. */
export async function loadOwnedAgent(ctx, agentId) {
const userId = requireUser(ctx);
requireUuidArg(agentId, 'agent_id');
const [row] = await sql`
SELECT id, user_id, name, meta FROM agent_identities
WHERE id = ${agentId} AND deleted_at IS NULL
`;
if (!row) throw refuse(404, 'not_found', 'No agent with that id.');
if (row.user_id !== userId) throw refuse(403, 'forbidden', "That agent isn't on your account.");
return { ...row, meta: row.meta || {} };
}
/**
* Anything that trades or schedules trades from a mainnet wallet needs the
* owner's signed real-funds agreements, the same gate every dashboard path runs.
*/
export async function requireAgreement(ctx, network = 'mainnet') {
if (network === 'devnet') return;
const userId = requireUser(ctx);
let signed;
try {
signed = await currentSignatureFor(userId);
} catch {
throw refuse(503, 'agreement_check_unavailable', 'Could not verify your signed real-funds agreements, so nothing was done. Try again in a moment.');
}
if (!signed) {
const r = agreementRequirement();
throw refuse(403, 'risk_ack_required', `Sign the real-funds agreements before trading from an agent wallet. Nothing was done. Sign at ${r.sign_url}`, r);
}
}
/** A confirm flag must be literally true, and the refusal names the preview step. */
export function requireConfirm(args, flag, previewTool, tool) {
if (args?.[flag] === true) return;
throw refuse(
400,
'confirmation_required',
`${tool} moves funds or changes where they can go, so it needs ${flag}: true. Call ${previewTool} first, show the user its result, and call ${tool} only after they clearly say yes.`,
{ confirm_flag: flag, preview_tool: previewTool },
);
}
/**
* Run one route from an agents-v1 route table in-process, as if it had been
* requested, reusing its validation, forwarding and quote signing. Errors it
* throws (ApiError) propagate to the caller unchanged.
*/
export async function invokeRoute(routes, method, path, ctx, { params = {}, query = {}, body = {} } = {}) {
const route = routes.find((r) => r.method === method && r.path === path);
if (!route) throw new Error(`trading-tools: no ${method} ${path} route`);
return route.handler({
requestId: ctx.requestId || null,
req: ctx.req,
res: null,
principal: ctx.principal,
params,
query,
body,
});
}
/** Solana network argument: mainnet unless devnet is asked for by name. */
export function networkArg(v) {
if (v == null || v === '' || v === 'mainnet') return 'mainnet';
if (v === 'devnet') return 'devnet';
throw refuse(400, 'invalid_parameter', 'network must be "mainnet" or "devnet".', { parameter: 'network' });
}