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
// Hosted agent-wallet x402 bridge — the production equivalent of
// scripts/agent-wallet-x402-bridge.mjs, so the /play/agent-wallet page works
// for real visitors instead of dead-ending on "bridge offline".
//
// GET /api/agent-wallet-bridge?status=1 → wallet + balances
// GET /api/agent-wallet-bridge?quote=1&endpoint=<url>&... → parsed 402 challenge
// POST /api/agent-wallet-bridge?pay=1 {endpoint,method,body} → SSE real payment
//
// The platform-held A2A payer keypair (A2A_PAYER_SOLANA_SECRET) signs a real SPL
// USDC TransferChecked on Solana mainnet against three.ws's own x402 endpoints
// (standard x402 v2 `exact` scheme via @x402/svm — the same flow the local
// bridge runs). Settlement happens at the paid endpoint's facilitator; real
// USDC moves.
//
// Because the payer wallet is shared, the spend path is protected:
// • status / quote are read-only and public.
// • pay requires a signed-in session (or bearer) — anonymous visitors get a
// clear "sign in" error instead of draining the wallet.
// • per-IP rate limit + per-payment cap + per-wallet daily USDC cap.
// • target endpoints must be on an allowlisted origin (three.ws + local dev).
import { cors, wrap, error, serverError, setRateLimitHeaders } from './_lib/http.js';
import { getSessionUser, authenticateBearer, extractBearer } from './_lib/auth.js';
import { assertBearerMaySpend } from './_lib/spend-scope.js';
import { requireCsrf } from './_lib/csrf.js';
import { limits, clientIp } from './_lib/rate-limit.js';
import { createSolanaSigner } from './_lib/x402/a2a-client.js';
import { enforceCap, commit, rollbackReservation } from './_lib/x402-spending-cap.js';
import { env } from './_lib/env.js';
import { fetchUpstream } from './_lib/upstream-fetch.js';
const SOLANA_RPC_URL = env.SOLANA_RPC_URL || 'https://api.mainnet-beta.solana.com';
const USDC_MINT_SOLANA = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';
const PAYER_SECRET = env.A2A_PAYER_SOLANA_SECRET || '';
// Caps (micro-USDC == micro-USD for USDC). Per-payment default $0.10, matching
// the local bridge; per-wallet daily default $2.00. Both env-overridable.
const MAX_PER_CALL_MICROS = Number(process.env.AGENT_WALLET_MAX_USDC_MICROS || 100_000);
const MAX_PER_DAY_MICROS = Number(process.env.AGENT_WALLET_DAILY_USDC_MICROS || 2_000_000);
// Loopback origins are a development convenience only: in production the
// container itself listens on loopback, so leaving them in the default let an
// unauthenticated quote call reach the instance's own internal port.
const DEFAULT_ENDPOINT_ORIGINS = env.isProduction
? 'https://three.ws'
: 'https://three.ws,http://localhost:3000,http://127.0.0.1:3000';
const ALLOWED_ENDPOINT_ORIGINS = (process.env.AGENT_WALLET_ALLOWED_ORIGINS || DEFAULT_ENDPOINT_ORIGINS)
.split(',')
.map((s) => s.trim())
.filter(Boolean);
const BUILDER_CODE_PATTERN = /^[a-z0-9_]{1,32}$/;
function fmtUsdc(micros) {
return '$' + (Number(micros) / 1e6).toFixed(2);
}
function endpointAllowed(endpoint) {
try {
return ALLOWED_ENDPOINT_ORIGINS.includes(new URL(endpoint).origin);
} catch {
return false;
}
}
// A payable Solana accept: exact scheme on a Solana CAIP-2 network.
//
// `extra.feePayer` is OPTIONAL and picks the signing mode, it is not an
// admission test. When the endpoint advertises a fee payer the facilitator
// co-signs it (sponsored mode, built by @x402/svm). When it does not, that is
// the x402 self-pay contract: the buyer signs as its own fee payer and the
// facilitator only broadcasts. Requiring feePayer here is what made every quote
// 502 the moment three.ws's own paid endpoints started advertising self-pay
// accepts (x402-paid-endpoint.js drops the fee payer whenever the sponsor
// wallet cannot co-sign), which took /play/agent-wallet down end to end.
export function isSolanaExactAccept(a) {
return Boolean(a && a.scheme === 'exact' && String(a.network || '').startsWith('solana:'));
}
// Pick the accept this bridge pays: USDC first, so a challenge that also
// advertises a $THREE Solana entry can never settle in the platform token off a
// USDC-denominated cap.
export function pickSolanaAccept(accepts) {
const solana = accepts.filter(isSolanaExactAccept);
return solana.find((a) => a.asset === USDC_MINT_SOLANA) || solana[0] || null;
}
let signerPromise = null;
function agentSigner() {
if (!PAYER_SECRET) {
return Promise.reject(new Error('agent wallet not configured on the server'));
}
if (!signerPromise) {
signerPromise = createSolanaSigner(PAYER_SECRET);
signerPromise.catch(() => { signerPromise = null; });
}
return signerPromise;
}
let statusCache = null; // { at, payload }
async function walletStatus() {
if (statusCache && Date.now() - statusCache.at < 10_000) return statusCache.payload;
const signer = await agentSigner();
const [{ PublicKey }, { getAssociatedTokenAddressSync }, { solanaConnection }] = await Promise.all([
import('@solana/web3.js'),
import('@solana/spl-token'),
import('./_lib/solana/connection.js'),
]);
// Multi-endpoint failover: a quota-dead or garbage-returning primary is skipped
// transparently instead of stalling this handler to the 30s Vercel ceiling
// (the source of the "[agent-wallet-bridge] Task timed out" errors) or throwing
// a StructError on a poison RPC body.
const conn = solanaConnection({ url: SOLANA_RPC_URL, commitment: 'confirmed' });
const owner = new PublicKey(signer.address);
let sol = null;
let usdc = 0;
try {
sol = (await conn.getBalance(owner)) / 1e9;
const ata = getAssociatedTokenAddressSync(new PublicKey(USDC_MINT_SOLANA), owner);
const bal = await conn.getTokenAccountBalance(ata).catch(() => null);
usdc = bal?.value?.uiAmount ?? 0;
} catch {
// RPC hiccup — report the wallet without live balances rather than fail.
}
const payload = {
ok: true,
wallet: { address: signer.address, mode: 'solana', chainNamespace: 'solana' },
balance: {
currency: 'USD',
totalValue: usdc.toFixed(2),
chains: [{ network: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp', sol, usdc }],
},
};
statusCache = { at: Date.now(), payload };
return payload;
}
async function fetch402(endpoint, method, body) {
// Any status is a legitimate answer here (we are probing for a 402), so the
// wrapper only adds the timeout and a retry on a dropped connection.
const res = await fetchUpstream(endpoint, {
method,
headers: { accept: 'application/json', ...(body ? { 'content-type': 'application/json' } : {}) },
body: body ? JSON.stringify(body) : undefined,
}, { timeoutMs: 15_000, attempts: 2, okWhen: () => true });
if (res.status !== 402) {
const text = (await res.text()).slice(0, 300);
throw new Error(`expected a 402 challenge from ${endpoint}, got ${res.status}: ${text}`);
}
const challenge = await res.json();
if (!Array.isArray(challenge?.accepts) || !challenge.accepts.length) {
throw new Error('402 challenge has no accepts[] entries');
}
const accept = pickSolanaAccept(challenge.accepts);
if (!accept) throw new Error('endpoint does not accept exact-scheme USDC on Solana');
return { challenge, accept };
}
// Build the signed SPL TransferChecked for a SELF-PAY accept (no advertised
// facilitator fee payer): the agent wallet is both the token authority and the
// transaction fee payer, so the transaction carries one signature and the
// facilitator broadcasts it without co-signing. Reuses the ring's own builder so
// the compute-budget nonce, the idempotent receiver-ATA create and the fee
// sizing are byte-for-byte what the self-facilitator validates on /settle.
async function buildSelfPayPayload(accept) {
const [web3, splToken, { solanaConnection }, { mintDecimals, getRecentBlockhash, blockhashKey }, pay] = await Promise.all([
import('@solana/web3.js'),
import('@solana/spl-token'),
import('./_lib/solana/connection.js'),
import('./_lib/solana/read-guards.js'),
import('./_lib/x402/pay.js'),
]);
const secretBytes = pay.decodeSeedSecret(PAYER_SECRET);
if (!secretBytes) {
throw new Error('agent wallet secret is not a decodable 64-byte Solana key');
}
const buyer = web3.Keypair.fromSecretKey(secretBytes);
const conn = solanaConnection({ url: SOLANA_RPC_URL, commitment: 'confirmed' });
const mint = new web3.PublicKey(accept.asset);
const [decimals, blockhash] = await Promise.all([
mintDecimals(conn, mint),
getRecentBlockhash(conn, blockhashKey({ network: accept.network })),
]);
const receiverAta = splToken.getAssociatedTokenAddressSync(
mint, new web3.PublicKey(accept.payTo), false,
splToken.TOKEN_PROGRAM_ID, splToken.ASSOCIATED_TOKEN_PROGRAM_ID,
);
const receiverAtaInfo = await conn.getAccountInfo(receiverAta).catch(() => null);
const transaction = pay.buildPaymentTx({
accept,
buyer,
blockhash,
mintInfo: { decimals },
receiverAtaExists: receiverAtaInfo !== null,
nonce: pay.nextAutoNonce(),
selfPay: true,
});
return { x402Version: 2, payload: { transaction } };
}
// ERC-8021 builder-code echo — the server rejects payments that don't echo the
// declared app code. Self-attribute as the wallet/service pair.
function builderCodeEcho(challenge) {
const declaredA = challenge?.extensions?.['builder-code']?.info?.a;
if (!declaredA || !BUILDER_CODE_PATTERN.test(declaredA)) return null;
return {
a: declaredA,
w: env.X402_BUILDER_CODE_WALLET || 'threews_agent',
s: ['agent_wallet_x402_bridge'],
};
}
async function executePayment({ endpoint, method, body, payerAddress, emit }) {
// 1. Real 402 challenge from the paid endpoint.
const { challenge, accept } = await fetch402(endpoint, method, body);
const amount = BigInt(accept.amount);
if (amount > BigInt(MAX_PER_CALL_MICROS)) {
throw new Error(
`endpoint asks for ${fmtUsdc(accept.amount)} USDC, above the per-payment cap of ${fmtUsdc(MAX_PER_CALL_MICROS)}`,
);
}
// 2. Spending-cap admission (per-payment already checked; this enforces the
// per-wallet daily ceiling and records the spend).
const cap = await enforceCap({
requirement: accept,
opts: {
address: payerAddress,
maxPerCall: MAX_PER_CALL_MICROS,
maxPerDay: MAX_PER_DAY_MICROS,
strict: true,
},
});
if (cap.abort) throw new Error(cap.reason || 'spending cap exceeded');
let committed = false;
try {
emit({
stage: 'challenge',
amount: accept.amount,
payTo: accept.payTo,
asset: accept.asset,
network: accept.network,
resource: challenge.resource || null,
});
// 3. The agent wallet builds + signs the SPL TransferChecked. Sponsored
// accepts go through @x402/svm (which hard-requires extra.feePayer);
// self-pay accepts go through the ring builder with the agent wallet as
// its own fee payer.
const signer = await agentSigner();
const sponsored = Boolean(accept.extra?.feePayer);
emit({
stage: 'signing',
signer: signer.address,
network: accept.network,
mint: accept.asset,
to: accept.payTo,
value: accept.amount,
feePayer: sponsored ? accept.extra.feePayer : signer.address,
selfPay: !sponsored,
});
let built;
if (sponsored) {
const { ExactSvmScheme } = await import('@x402/svm');
const scheme = new ExactSvmScheme(signer, { rpcUrl: SOLANA_RPC_URL });
built = await scheme.createPaymentPayload(2, accept);
} else {
built = await buildSelfPayPayload(accept);
}
emit({ stage: 'signed', signer: signer.address, selfPay: !sponsored });
// 4. Retry with the X-PAYMENT header — the endpoint verifies, settles via
// its facilitator, then does the paid work.
const paymentPayload = {
x402Version: built.x402Version || 2,
scheme: 'exact',
network: accept.network,
resource: { url: endpoint, mimeType: 'application/json' },
accepted: accept,
payload: built.payload,
};
const echo = builderCodeEcho(challenge);
if (echo) paymentPayload.extensions = { 'builder-code': echo };
emit({ stage: 'submitting' });
// A signed payment must never be re-sent (a retry could double-spend), so
// this is a single attempt: timeout only.
const paidRes = await fetchUpstream(endpoint, {
method,
headers: {
accept: 'application/json',
'x-payment': Buffer.from(JSON.stringify(paymentPayload), 'utf8').toString('base64'),
...(body ? { 'content-type': 'application/json' } : {}),
},
body: body ? JSON.stringify(body) : undefined,
}, { timeoutMs: 30_000, attempts: 1, okWhen: () => true });
const resultText = await paidRes.text();
let result = null;
try { result = JSON.parse(resultText); } catch { result = { raw: resultText.slice(0, 1000) }; }
if (!paidRes.ok) {
throw new Error(
`payment rejected by endpoint (HTTP ${paidRes.status}): ${result?.error?.message || result?.error || resultText.slice(0, 300)}`,
);
}
let settlement = null;
const settleHeader = paidRes.headers.get('x-payment-response');
if (settleHeader) {
try { settlement = JSON.parse(Buffer.from(settleHeader, 'base64').toString('utf8')); } catch { settlement = null; }
}
await commit(cap.reservation, { endpoint, tx: settlement?.transaction || null });
committed = true;
statusCache = null; // balance just changed
emit({
stage: 'done',
amount: accept.amount,
payer: signer.address,
payTo: accept.payTo,
settlement,
result,
});
} finally {
if (!committed) await rollbackReservation(cap.reservation).catch(() => {});
}
}
export default wrap(async (req, res) => {
if (cors(req, res, { methods: 'GET,POST,OPTIONS', origins: '*' })) return;
const url = new URL(req.url, 'http://x');
// ── STATUS (public, read-only) ────────────────────────────────────────
if (req.method === 'GET' && url.searchParams.get('status') === '1') {
try {
// Resolve the async payload BEFORE committing headers — writing the head
// first and awaiting inside res.end() means a rejected walletStatus() lands
// in the catch with headers already sent, turning a clean 503 into an
// ERR_HTTP_HEADERS_SENT crash.
const status = await walletStatus();
res.writeHead(200, { 'content-type': 'application/json', 'access-control-allow-origin': '*' });
res.end(JSON.stringify(status));
} catch (err) {
// A 503 here means the signer/RPC layer faulted — sanitize so a keyed
// RPC URL or signer internal can't ride out in the error body.
serverError(res, 503, 'wallet_unavailable', err);
}
return;
}
// ── QUOTE (public, read-only) ─────────────────────────────────────────
if (req.method === 'GET' && url.searchParams.get('quote') === '1') {
const endpoint = url.searchParams.get('endpoint') || '';
const method = (url.searchParams.get('method') || 'POST').toUpperCase();
if (!endpointAllowed(endpoint)) {
return error(res, 400, 'endpoint_not_allowed', `endpoint origin not allowed (allowed: ${ALLOWED_ENDPOINT_ORIGINS.join(', ')})`);
}
try {
const bodyParam = url.searchParams.get('body');
const probeBody = bodyParam ? JSON.parse(bodyParam) : undefined;
const { challenge, accept } = await fetch402(endpoint, method, probeBody);
res.writeHead(200, { 'content-type': 'application/json', 'access-control-allow-origin': '*' });
res.end(JSON.stringify({
ok: true,
amount: accept.amount,
payTo: accept.payTo,
asset: accept.asset,
network: accept.network,
feePayer: accept.extra?.feePayer || null,
selfPay: !accept.extra?.feePayer,
maxTimeoutSeconds: accept.maxTimeoutSeconds,
resource: challenge.resource || null,
}));
} catch (err) {
// Don't echo upstream endpoint URLs / response bodies to the caller —
// fetch402 errors embed both. Log server-side, return a stable message.
console.error('[agent-wallet-bridge] quote_failed:', err?.message || err);
error(res, 502, 'quote_failed', 'Unable to retrieve a payment quote right now. Try again shortly.');
}
return;
}
// ── PAY (real on-chain spend — auth + rate limit + caps) ──────────────
if (req.method !== 'POST') {
return error(res, 405, 'method_not_allowed', 'use ?status=1, ?quote=1, or POST ?pay=1');
}
// Real USDC leaves the shared platform wallet — require a signed-in caller.
const sessionUser = await getSessionUser(req).catch(() => null);
// Pays real USDC from the shared platform wallet: a bearer needs wallet:write.
const bearerUser = sessionUser ? null : assertBearerMaySpend(await authenticateBearer(extractBearer(req)).catch(() => null), req);
if (!sessionUser && !bearerUser) {
return error(res, 401, 'unauthorized', 'Sign in to let your agent wallet make a real payment.');
}
const callerUserId = (sessionUser || bearerUser).userId ?? (sessionUser || bearerUser).id;
if (!(await requireCsrf(req, res, callerUserId))) return;
const rl = await limits.publicIp(clientIp(req));
if (!rl.success) {
const retryAfter = Math.max(1, setRateLimitHeaders(res, rl));
res.setHeader('retry-after', String(retryAfter));
return error(res, 429, 'rate_limited', 'Too many payment attempts — try again shortly.');
}
let parsed;
try {
parsed = typeof req.body === 'object' && req.body ? req.body : JSON.parse(await readRawBody(req) || '{}');
} catch {
return error(res, 400, 'invalid_body', 'invalid JSON body');
}
const endpoint = String(parsed.endpoint || '');
const payMethod = String(parsed.method || 'POST').toUpperCase();
if (!['GET', 'POST'].includes(payMethod)) {
return error(res, 400, 'invalid_method', 'method must be GET or POST');
}
if (!endpointAllowed(endpoint)) {
return error(res, 400, 'endpoint_not_allowed', `endpoint origin not allowed (allowed: ${ALLOWED_ENDPOINT_ORIGINS.join(', ')})`);
}
res.writeHead(200, {
'content-type': 'text/event-stream; charset=utf-8',
'cache-control': 'no-cache, no-store',
connection: 'keep-alive',
'x-accel-buffering': 'no',
'access-control-allow-origin': '*',
});
res.flushHeaders?.();
let lastStage = 'challenge';
const emit = (evt) => {
lastStage = evt.stage || lastStage;
res.write(`data: ${JSON.stringify(evt)}\n\n`);
};
try {
const signer = await agentSigner();
await executePayment({ endpoint, method: payMethod, body: parsed.body, payerAddress: signer.address, emit });
} catch (err) {
emit({ stage: 'error', failedStage: lastStage, message: err.message });
}
res.end();
});
function readRawBody(req) {
return new Promise((resolve, reject) => {
let data = '';
req.on('data', (c) => {
data += c;
if (data.length > 64 * 1024) reject(new Error('request body too large'));
});
req.on('end', () => resolve(data));
req.on('error', reject);
});
}
export const maxDuration = 30;