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
// A2A (Agent-to-Agent) x402 transport — server side.
//
// USE-12: Implements the google-a2a/a2a-x402 v0.1 extension. The A2A protocol
// uses JSON-RPC `message/send` calls with task-based state. Payment is
// signalled via the task's `status.state` plus `x402.payment.*` metadata
// fields on the agent reply message — distinct from the HTTP 402 + X-PAYMENT
// dance we use for /api/x402/*.
//
// Wire shape (per spec):
// • First call (no payment metadata) → reply task with
// state = 'input-required'
// message.metadata['x402.payment.status'] = 'payment-required'
// message.metadata['x402.payment.required'] = PaymentRequirements
// • Retry with `x402.payment.payload` + `x402.payment.status = payment-submitted`
// and `taskId` set → server verifies via facilitator, runs handler, settles,
// replies with state = 'completed' (or 'failed') and
// message.metadata['x402.payment.status'] = 'payment-completed'
// message.metadata['x402.payment.receipts'] = [SettlementResponse]
//
// Extension activation: both peers MUST attach
// `X-A2A-Extensions: https://github.com/google-a2a/a2a-x402/v0.1`
// on their HTTP transport. We emit it on every reply and require it on the
// inbound side per spec (treat-as-disabled-when-absent is opt-in by the
// AgentCard, but our card declares `required: true`).
//
// Verification + settlement reuse the existing facilitator client in
// api/_lib/x402-spec.js so A2A inherits Base / Solana / BSC support, builder
// code echo enforcement, and direct-scheme handling automatically.
import { randomUUID } from 'node:crypto';
import { env } from '../env.js';
import { readBody } from '../http.js';
import {
BUILDER_CODE,
NETWORK_BASE_MAINNET,
NETWORK_BSC_MAINNET,
NETWORK_SOLANA_MAINNET,
X402Error,
X402_VERSION,
permit2VariantOf,
settlePayment,
verifyPayment,
} from '../x402-spec.js';
import { declareBuilderCodeExtension } from '../x402-builder-code.js';
import { PAYMENT_EVENT_TOPIC as BSC_PAYMENT_EVENT_TOPIC } from '../x402-bsc-direct.js';
import {
get as idemGet,
set as idemSet,
hashPaymentProof,
} from './idempotency-cache.js';
// Idempotency TTL for the A2A leg, mirroring the HTTP payment-identifier cache.
function a2aIdempotencyTtl() {
const n = Number.parseInt(env.X402_IDEMPOTENCY_TTL_SECONDS, 10);
return Number.isFinite(n) && n > 0 ? n : 3600;
}
export const A2A_X402_EXTENSION_URI = 'https://github.com/google-a2a/a2a-x402/v0.1';
export const A2A_EXTENSIONS_HEADER = 'X-A2A-Extensions';
const NETWORK_ALIASES = {
base: NETWORK_BASE_MAINNET,
'base-mainnet': NETWORK_BASE_MAINNET,
bsc: NETWORK_BSC_MAINNET,
'bsc-mainnet': NETWORK_BSC_MAINNET,
solana: NETWORK_SOLANA_MAINNET,
'solana-mainnet': NETWORK_SOLANA_MAINNET,
};
function resolveNetwork(name) {
return NETWORK_ALIASES[name] || name;
}
function buildAccept(network, priceAtomics, resourceUrl, payToOverride) {
const common = {
scheme: 'exact',
amount: String(priceAtomics),
maxTimeoutSeconds: 600,
resource: resourceUrl,
};
if (network === NETWORK_BASE_MAINNET) {
return {
...common,
network: NETWORK_BASE_MAINNET,
payTo: payToOverride?.base || env.X402_PAY_TO_BASE,
asset: env.X402_ASSET_ADDRESS_BASE,
extra: { name: 'USD Coin', version: '2', decimals: 6 },
};
}
if (network === NETWORK_SOLANA_MAINNET) {
return {
...common,
network: NETWORK_SOLANA_MAINNET,
payTo: payToOverride?.solana || env.X402_PAY_TO_SOLANA,
asset: env.X402_ASSET_MINT_SOLANA,
extra: { name: 'USDC', decimals: 6, feePayer: env.X402_FEE_PAYER_SOLANA },
};
}
if (network === NETWORK_BSC_MAINNET) {
const contract = payToOverride?.bsc || env.X402_PAY_TO_BSC;
return {
...common,
scheme: 'direct',
network: NETWORK_BSC_MAINNET,
payTo: contract,
asset: env.X402_ASSET_ADDRESS_BSC,
extra: {
name: 'Binance-Peg USD Coin',
decimals: 6,
contract,
method: 'pay(bytes32)',
eventTopic: BSC_PAYMENT_EVENT_TOPIC,
},
};
}
throw new X402Error('unsupported_network', `a2a: unsupported network ${network}`, 500);
}
function buildAccepts({ priceAtomics, networks, resourceUrl, payToOverride }) {
const out = [];
for (const name of networks) {
const net = resolveNetwork(name);
const baseTo = payToOverride?.base || env.X402_PAY_TO_BASE;
const solTo = payToOverride?.solana || env.X402_PAY_TO_SOLANA;
const bscTo = payToOverride?.bsc || env.X402_PAY_TO_BSC;
// Offer a network only when EVERY field its accept needs is present, so a
// half-configured chain never takes down the others (asset included — an
// advertised-but-assetless accept is rejected at settle, same broken UX as
// a 500). Drop the unwired networks; 402-fail only when none are payable.
if (net === NETWORK_BASE_MAINNET && (!baseTo || !env.X402_ASSET_ADDRESS_BASE)) continue;
// Solana also needs a fee payer to be co-signable — skip the network
// rather than advertise an accept the facilitator will reject.
if (
net === NETWORK_SOLANA_MAINNET &&
(!solTo || !env.X402_FEE_PAYER_SOLANA || !env.X402_ASSET_MINT_SOLANA)
)
continue;
if (net === NETWORK_BSC_MAINNET && (!bscTo || !env.X402_ASSET_ADDRESS_BSC)) continue;
const accept = buildAccept(net, priceAtomics, resourceUrl, payToOverride);
out.push(accept);
const sibling = permit2VariantOf(accept);
if (sibling) out.push(sibling);
}
if (!out.length) {
throw new X402Error(
'no_payto_configured',
'a2a: no X402_PAY_TO_* configured for any requested network',
500,
);
}
return out;
}
function paymentRequiredObject({ resourceUrl, description, mimeType, accepts }) {
return {
x402Version: X402_VERSION,
error: 'Payment required to access this resource',
resource: { url: resourceUrl, description, mimeType },
accepts,
};
}
function agentMessage({ taskId, text, metadata }) {
return {
kind: 'message',
role: 'agent',
messageId: randomUUID(),
taskId,
parts: [{ kind: 'text', text }],
metadata,
};
}
function task({ id, state, message, artifacts }) {
const out = {
kind: 'task',
id,
status: { state, message },
};
if (Array.isArray(artifacts) && artifacts.length) out.artifacts = artifacts;
return out;
}
function jsonrpcResult(id, result) {
return { jsonrpc: '2.0', id, result };
}
function jsonrpcError(id, code, message, data) {
const err = { code, message };
if (data !== undefined) err.data = data;
return { jsonrpc: '2.0', id, error: err };
}
function readClientPaymentStatus(metadata) {
const status = metadata?.['x402.payment.status'];
return typeof status === 'string' ? status : null;
}
function readClientPaymentPayload(metadata) {
const payload = metadata?.['x402.payment.payload'];
return payload && typeof payload === 'object' ? payload : null;
}
function encodePaymentHeaderFromPayload(payload) {
// verifyPayment() decodes the X-PAYMENT header value back to JSON. We
// re-encode the A2A-supplied payload object to base64-JSON so we can reuse
// that path without forking the verifier. The spec's payload shape (with
// `accepted` instead of `paymentRequirements`) is structurally compatible
// with what selectRequirement() needs once we normalise the field name.
const normalised = { ...payload };
if (payload.accepted && !payload.paymentRequirements) {
normalised.paymentRequirements = payload.accepted;
}
if (!normalised.x402Version) normalised.x402Version = X402_VERSION;
return Buffer.from(JSON.stringify(normalised), 'utf8').toString('base64');
}
function clientAcceptsExtension(headers) {
// Per the A2A x402 spec: clients activate the extension by listing its URI
// in the X-A2A-Extensions header. We require it when the AgentCard
// declared the extension as `required: true`. Header names are
// case-insensitive — Node lowercases them on `req.headers`.
const raw = headers['x-a2a-extensions'];
if (!raw) return false;
const values = Array.isArray(raw) ? raw : String(raw).split(',');
for (const v of values) {
if (v.trim() === A2A_X402_EXTENSION_URI) return true;
}
return false;
}
function activateExtensionHeader(res) {
res.setHeader(A2A_EXTENSIONS_HEADER, A2A_X402_EXTENSION_URI);
}
// Build the agent's payment-required reply. Returned synchronously so callers
// can decide whether to emit it as a JSON-RPC result, an SSE event, or wrap it
// in an A2A `streamingResponse`.
export function buildPaymentRequiredTask({
taskId = randomUUID(),
resourceUrl,
description,
mimeType = 'application/json',
priceAtomics,
networks = ['base', 'solana'],
payTo,
prompt = 'Payment required to invoke this skill.',
}) {
const accepts = buildAccepts({
priceAtomics,
networks,
resourceUrl,
payToOverride: payTo,
});
const required = paymentRequiredObject({ resourceUrl, description, mimeType, accepts });
const message = agentMessage({
taskId,
text: prompt,
metadata: {
'x402.payment.status': 'payment-required',
'x402.payment.required': required,
},
});
return { task: task({ id: taskId, state: 'input-required', message }), accepts, required };
}
function builderCodeForServices(services) {
const appCode = env.X402_BUILDER_CODE_APP;
if (!appCode) return null;
if (Array.isArray(services) && services.length) {
return declareBuilderCodeExtension({ a: appCode, s: services });
}
return declareBuilderCodeExtension({ a: appCode });
}
// Run a single inbound `message/send` JSON-RPC call. The caller owns reading
// the body off the wire — we want `body` parsed and the framework-agnostic
// `req` only for `req.headers` access (extension activation check).
//
// `handler({ taskId, payer, requirement, settled, payload, message })` returns either:
// • { text, artifacts? } — wrapped in a `completed` task message + artifacts.
// • A string — wrapped as the text reply with no artifacts.
// • undefined / null — defaults to "Payment settled." text.
//
// Any thrown Error with `.status === 402` re-emits the payment-required task
// (e.g. payment for the wrong network). Other errors become a `failed` task
// with `x402.payment.status = payment-failed`.
export async function handleA2ARequest({
req,
body,
route,
resourceUrl,
description,
mimeType = 'application/json',
priceAtomics = env.X402_MAX_AMOUNT_REQUIRED,
networks = ['base', 'solana'],
payTo,
services,
prompt,
handler,
}) {
if (!body || typeof body !== 'object') {
return jsonrpcError(null, -32700, 'Parse error: body must be JSON');
}
if (body.jsonrpc !== '2.0') {
return jsonrpcError(body.id ?? null, -32600, 'Invalid Request: jsonrpc must be "2.0"');
}
if (body.method !== 'message/send') {
return jsonrpcError(body.id ?? null, -32601, `Method not found: ${body.method}`);
}
const reqId = body.id ?? null;
const message = body.params?.message;
if (!message || typeof message !== 'object') {
return jsonrpcError(reqId, -32602, 'Invalid params: message is required');
}
if (!clientAcceptsExtension(req.headers || {})) {
const failed = task({
id: message.taskId || randomUUID(),
state: 'failed',
message: agentMessage({
taskId: message.taskId,
text: `This agent requires the x402 extension. Send the ${A2A_EXTENSIONS_HEADER} header with ${A2A_X402_EXTENSION_URI}.`,
metadata: {
'x402.payment.status': 'payment-rejected',
'x402.payment.error': 'EXTENSION_REQUIRED',
},
}),
});
return jsonrpcResult(reqId, failed);
}
const status = readClientPaymentStatus(message.metadata);
const payload = readClientPaymentPayload(message.metadata);
// First-leg: no payment payload → return the payment-required task.
if (!payload || status === 'payment-required' || status === null) {
const built = buildPaymentRequiredTask({
taskId: message.taskId,
resourceUrl,
description,
mimeType,
priceAtomics,
networks,
payTo,
prompt,
});
return jsonrpcResult(reqId, built.task);
}
const taskId = message.taskId || randomUUID();
// Second-leg: client supplied a payment payload. Verify → run → settle.
const builderCode = builderCodeForServices(services);
const paymentHeader = encodePaymentHeaderFromPayload(payload);
// Proof-bound idempotency. The A2A leg has no payment-identifier header, so
// we key on a hash of the signed payment proof itself: a resubmission of the
// SAME payment (network blip, client retry, or a deliberate replay) returns
// the cached completed task instead of re-verifying, re-settling, and
// re-running the handler. Only the original payer can reproduce the exact
// proof, so this can't be abused to replay someone else's payment.
const paymentHash = hashPaymentProof(paymentHeader);
if (paymentHash) {
try {
const cached = await idemGet(resourceUrl, paymentHash);
if (cached?.task) return jsonrpcResult(reqId, cached.task);
} catch {
/* cache read is best-effort — fall through to the live path */
}
}
// Reconstruct the same accepts list we advertised on the first leg so the
// facilitator sees the resource/network/payTo trio it expects.
let requirements;
try {
requirements = buildAccepts({
priceAtomics,
networks,
resourceUrl,
payToOverride: payTo,
});
} catch (err) {
return jsonrpcResult(
reqId,
task({
id: taskId,
state: 'failed',
message: agentMessage({
taskId,
text: err.message,
metadata: {
'x402.payment.status': 'payment-failed',
'x402.payment.error': err.code || 'INVALID_CONFIGURATION',
},
}),
}),
);
}
let verified;
try {
verified = await verifyPayment({ paymentHeader, requirements, builderCode });
} catch (err) {
// 402 from verify → re-issue payment-required (e.g. wrong network).
if (err instanceof X402Error && err.status === 402) {
const built = buildPaymentRequiredTask({
taskId,
resourceUrl,
description,
mimeType,
priceAtomics,
networks,
payTo,
prompt: err.message,
});
return jsonrpcResult(reqId, built.task);
}
const receipt = {
success: false,
errorReason: err.message,
network: payload?.accepted?.network || payload?.paymentRequirements?.network || '',
transaction: '',
};
return jsonrpcResult(
reqId,
task({
id: taskId,
state: 'failed',
message: agentMessage({
taskId,
text: `Payment verification failed: ${err.message}`,
metadata: {
'x402.payment.status': 'payment-failed',
'x402.payment.error': err.code || 'INVALID_PAYMENT',
'x402.payment.receipts': [receipt],
},
}),
}),
);
}
// Settle BEFORE delivering the work. Prior ordering (deliver → settle)
// risked the payer receiving the skill result and only then seeing
// settlement fail in the metadata; for idempotent skills it also meant
// we did the compute without an on-chain charge to back it. Settle-first
// inverts the risk: if settlement fails, we refuse the work and the
// client can retry with a fresh payment. If the handler fails AFTER a
// successful settle, the payer paid for a failed execution — we surface
// the settled receipt in the failure response so they have audit proof
// (and can dispute or retry without re-paying if the failure was ours).
let settled;
try {
settled = await settlePayment({ verified });
} catch (err) {
const receipt = {
success: false,
errorReason: err.message,
network: verified.requirement.network,
transaction: '',
};
return jsonrpcResult(
reqId,
task({
id: taskId,
state: 'failed',
message: agentMessage({
taskId,
text: `Settlement failed: ${err.message}`,
metadata: {
'x402.payment.status': 'payment-failed',
'x402.payment.error': err.code || 'SETTLEMENT_FAILED',
'x402.payment.receipts': [receipt],
},
}),
}),
);
}
let handlerResult;
try {
handlerResult = await handler({
taskId,
payer: verified.payer,
requirement: verified.requirement,
settled: {
transaction: settled.transaction,
network: settled.network,
payer: settled.payer || verified.payer || null,
},
payload,
message,
});
} catch (err) {
// Payment is already settled on-chain — surface the settled receipt
// alongside the handler failure so the payer has proof of charge and
// can replay/dispute. Status is `payment-settled` (not -failed) since
// the payment leg succeeded; the failure is execution-side.
const receipt = {
success: true,
transaction: settled.transaction,
network: settled.network,
payer: settled.payer || verified.payer || null,
};
return jsonrpcResult(
reqId,
task({
id: taskId,
state: 'failed',
message: agentMessage({
taskId,
text: `Skill execution failed after payment settled: ${err.message}`,
metadata: {
'x402.payment.status': 'payment-settled',
'x402.payment.error': err.code || 'HANDLER_FAILED',
'x402.payment.receipts': [receipt],
},
}),
}),
);
}
const receipts = [
{
success: true,
transaction: settled.transaction,
network: settled.network,
payer: settled.payer || verified.payer || null,
},
];
const text =
typeof handlerResult === 'string'
? handlerResult
: handlerResult?.text || 'Payment settled. Skill executed.';
const artifacts =
Array.isArray(handlerResult?.artifacts) && handlerResult.artifacts.length
? handlerResult.artifacts
: undefined;
const completedMessage = agentMessage({
taskId,
text,
metadata: {
'x402.payment.status': 'payment-completed',
'x402.payment.receipts': receipts,
'x402.payment.lifecycle': [
'payment-required',
'payment-submitted',
'payment-verified',
'payment-completed',
],
...(handlerResult?.metadata && typeof handlerResult.metadata === 'object'
? handlerResult.metadata
: {}),
},
});
const completedTask = task({
id: taskId,
state: 'completed',
message: completedMessage,
artifacts,
});
// Cache the completed task against the payment proof so a resubmission of
// the same proof replays this result instead of double-charging / re-running.
if (paymentHash) {
try {
await idemSet(resourceUrl, paymentHash, { task: completedTask }, a2aIdempotencyTtl());
} catch {
/* cache write is best-effort — the payment already settled on-chain */
}
}
return jsonrpcResult(reqId, completedTask);
}
// Compose a Vercel-style HTTP handler around `handleA2ARequest`. POSTs are
// JSON-RPC; GETs return the AgentCard fragment so clients can verify the
// extension declaration without a separate /.well-known fetch.
export function a2aPaidEndpoint(spec) {
const {
route,
description,
priceAtomics = env.X402_MAX_AMOUNT_REQUIRED,
networks = ['base', 'solana'],
mimeType = 'application/json',
payTo,
services,
prompt,
handler,
skill,
} = spec;
if (!route) throw new Error('a2aPaidEndpoint: route is required');
if (!description) throw new Error('a2aPaidEndpoint: description is required');
if (typeof handler !== 'function') {
throw new Error('a2aPaidEndpoint: handler must be a function');
}
return async function a2aHandler(req, res) {
const origin = req.headers.origin;
res.setHeader('access-control-allow-origin', origin || '*');
res.setHeader('access-control-allow-methods', 'GET,POST,OPTIONS');
res.setHeader(
'access-control-allow-headers',
`content-type, authorization, ${A2A_EXTENSIONS_HEADER.toLowerCase()}`,
);
res.setHeader('access-control-expose-headers', A2A_EXTENSIONS_HEADER);
if (req.method === 'OPTIONS') {
res.statusCode = 204;
res.end();
return;
}
activateExtensionHeader(res);
const resourceUrl = `${env.APP_ORIGIN}${route}`;
if (req.method === 'GET') {
// Discovery: emit a minimal AgentCard fragment so a client can confirm
// our extension support before sending a paid message.
res.statusCode = 200;
res.setHeader('content-type', 'application/json; charset=utf-8');
res.setHeader('cache-control', 'public, max-age=300');
res.end(
JSON.stringify({
name: skill?.name || 'three.ws A2A paid skill',
description,
url: resourceUrl,
capabilities: {
streaming: false,
pushNotifications: false,
stateTransitionHistory: false,
extensions: [
{
uri: A2A_X402_EXTENSION_URI,
description: 'Supports payments using the x402 protocol for on-chain settlement.',
required: true,
},
],
},
defaultInputModes: ['application/json'],
defaultOutputModes: [mimeType],
skills: skill ? [skill] : [],
}),
);
return;
}
if (req.method !== 'POST') {
res.setHeader('allow', 'GET,POST,OPTIONS');
res.statusCode = 405;
res.setHeader('content-type', 'application/json; charset=utf-8');
res.end(JSON.stringify({ error: 'method_not_allowed' }));
return;
}
let body;
try {
body = await readJsonBody(req);
} catch (err) {
res.statusCode = err.status || 400;
res.setHeader('content-type', 'application/json; charset=utf-8');
res.end(JSON.stringify({ jsonrpc: '2.0', id: null, error: { code: -32700, message: err.message } }));
return;
}
const rpcReply = await handleA2ARequest({
req,
body,
route,
resourceUrl,
description,
mimeType,
priceAtomics,
networks,
payTo,
services,
prompt,
handler,
});
res.statusCode = 200;
res.setHeader('content-type', 'application/json; charset=utf-8');
res.setHeader('cache-control', 'no-store');
res.end(JSON.stringify(rpcReply));
};
}
// Delegates to the shared readBody (api/_lib/http.js), which prefers the
// pre-parsed req.rawBody/req.body the Cloud Run server already captured —
// re-reading the raw stream here (as this function used to) hangs forever
// once Express has drained it. See http.js readBody for the full rationale;
// this was a live production incident on every A2A JSON-RPC POST.
async function readJsonBody(req) {
const buf = await readBody(req, 1_000_000);
if (!buf.length) return {};
try {
return JSON.parse(buf.toString('utf8'));
} catch (err) {
throw Object.assign(new Error(`invalid JSON: ${err.message}`), { status: 400 });
}
}