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
#!/usr/bin/env node
// agent-wallet-x402-bridge — local bridge between the /play/agent-wallet demo
// page and the three.ws agent wallet (a local Solana payer keypair).
//
// The payer secret lives in the developer's environment (A2A_PAYER_SOLANA_SECRET,
// the same convention the A2A payer uses), so a browser page can't reach it
// directly. This bridge exposes the three operations the demo needs over
// localhost HTTP:
//
// GET /status → wallet address + live SOL/USDC balances (Solana RPC)
// GET /quote?endpoint=<url> → the endpoint's real 402 challenge, parsed
// POST /pay {endpoint,method,body} → SSE stream of a REAL x402 payment:
// challenge → signing → signed → submitting → done|error
//
// The payment is the standard x402 v2 `exact` scheme on Solana mainnet
// (solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp): the bridge fetches the 402
// challenge, builds an SPL TransferChecked via the official @x402/svm scheme
// with the endpoint-advertised facilitator as fee payer, partially signs it
// with the agent wallet, then retries the request with the X-PAYMENT header.
// Settlement happens server-side at the paid endpoint via its facilitator —
// real USDC moves on Solana.
//
// Safety rails (this listens on localhost, where any local page could reach it):
// • Target endpoints must be on an allowlisted origin (three.ws + local dev).
// • Per-payment cap, default $0.10 USDC (X402_BRIDGE_MAX_USDC_MICROS).
// • CORS restricted to local dev origins + *.app.github.dev.
//
// Run: node scripts/agent-wallet-x402-bridge.mjs (or: npm run demo:agent-wallet-bridge)
import { createServer } from 'node:http';
import { readFileSync } from 'node:fs';
// Pick up A2A_PAYER_SOLANA_SECRET / SOLANA_RPC_URL from the repo .env when
// present, without overriding anything already exported in the shell.
try {
const raw = readFileSync(new URL('../.env', import.meta.url), 'utf8');
for (const line of raw.split('\n')) {
const m = line.match(/^([A-Z0-9_]+)=(.*)$/);
if (m && !(m[1] in process.env)) process.env[m[1]] = m[2];
}
} catch {
/* no .env — rely on the shell environment */
}
const PORT = Number(process.env.X402_BRIDGE_PORT) || 4402;
const MAX_USDC_MICROS = BigInt(process.env.X402_BRIDGE_MAX_USDC_MICROS || '100000'); // $0.10
const SOLANA_RPC_URL = process.env.SOLANA_RPC_URL || 'https://api.mainnet-beta.solana.com';
const PAYER_SECRET =
process.env.A2A_PAYER_SOLANA_SECRET || process.env.A2A_PAYER_SOLANA_PRIVATE_KEY || '';
const USDC_MINT_SOLANA = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';
// Origins a target paid endpoint may live on. The demo pays three.ws's own
// x402 endpoints; local dev lets you point at `vercel dev`/vite proxies.
const ALLOWED_ENDPOINT_ORIGINS = (
process.env.X402_BRIDGE_ALLOWED_ENDPOINT_ORIGINS ||
'https://three.ws,http://localhost:3000,http://127.0.0.1:3000'
)
.split(',')
.map((s) => s.trim())
.filter(Boolean);
// Browser origins allowed to call the bridge (the demo page).
function corsOriginAllowed(origin) {
if (!origin) return false;
try {
const u = new URL(origin);
if (u.hostname === 'localhost' || u.hostname === '127.0.0.1') return true;
if (u.hostname.endsWith('.app.github.dev')) return true;
if (origin === 'https://three.ws') return true;
return false;
} catch {
return false;
}
}
// ── agent wallet (Solana payer keypair) ────────────────────────────────────
// Decode a Solana secret key from any of the encodings used across this
// codebase: a JSON byte array (solana-keygen), base58 (Phantom export), or
// base64. Returns the 64-byte expanded secret key.
async function decodeSolanaSecret(secret) {
const trimmed = String(secret).trim();
if (trimmed.startsWith('[')) {
const bytes = Uint8Array.from(JSON.parse(trimmed));
if (bytes.length === 64) return bytes;
throw new Error('Solana secret: malformed 64-byte JSON array');
}
const { default: bs58 } = await import('bs58');
for (const decode of [() => bs58.decode(trimmed), () => new Uint8Array(Buffer.from(trimmed, 'base64'))]) {
try {
const bytes = decode();
if (bytes.length === 64) return bytes;
} catch {
/* try the next encoding */
}
}
throw new Error('Solana secret must be a 64-byte key encoded as base58, base64, or a JSON array');
}
let signerPromise = null;
function agentSigner() {
if (!PAYER_SECRET) {
return Promise.reject(
new Error('agent wallet not configured — set A2A_PAYER_SOLANA_SECRET in .env or the shell'),
);
}
if (!signerPromise) {
signerPromise = (async () => {
const { createKeyPairSignerFromBytes } = await import('@solana/kit');
return createKeyPairSignerFromBytes(await decodeSolanaSecret(PAYER_SECRET));
})();
signerPromise.catch(() => {
signerPromise = null; // let a corrected env value retry on next call
});
}
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 [{ Connection, PublicKey }, { getAssociatedTokenAddressSync }] = await Promise.all([
import('@solana/web3.js'),
import('@solana/spl-token'),
]);
const conn = new Connection(SOLANA_RPC_URL, '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; // no ATA yet → zero USDC
} 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;
}
// ── x402 client flow (Solana exact scheme, official @x402/svm) ─────────────
function endpointAllowed(endpoint) {
try {
const u = new URL(endpoint);
return ALLOWED_ENDPOINT_ORIGINS.includes(u.origin);
} catch {
return false;
}
}
// A co-signable Solana accept: exact scheme, Solana CAIP-2 network, and the
// facilitator fee payer the @x402/svm scheme needs to build the transaction.
function isSolanaExactAccept(a) {
return a && a.scheme === 'exact' && String(a.network || '').startsWith('solana:') && a.extra?.feePayer;
}
async function fetch402(endpoint, method, body) {
const res = await fetch(endpoint, {
method,
headers: { accept: 'application/json', ...(body ? { 'content-type': 'application/json' } : {}) },
body: body ? JSON.stringify(body) : undefined,
});
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 = challenge.accepts.find(isSolanaExactAccept);
if (!accept) {
throw new Error('endpoint does not accept exact-scheme USDC on Solana');
}
return { challenge, accept };
}
// ERC-8021 builder-code echo — the server rejects payments that don't echo the
// declared app code. Self-attribute this bridge as the wallet/service pair.
const BUILDER_CODE_PATTERN = /^[a-z0-9_]{1,32}$/;
function builderCodeEcho(challenge) {
const declaredA = challenge?.extensions?.['builder-code']?.info?.a;
if (!declaredA || !BUILDER_CODE_PATTERN.test(declaredA)) return null;
return { a: declaredA, w: 'threews_agent', s: ['agent_wallet_x402_bridge'] };
}
function fmtUsdc(micros) {
return '$' + (Number(micros) / 1e6).toFixed(2);
}
async function executePayment({ endpoint, method, body, emit }) {
// 1. Real 402 challenge from the paid endpoint.
const { challenge, accept } = await fetch402(endpoint, method, body);
const amount = BigInt(accept.amount);
if (amount > MAX_USDC_MICROS) {
throw new Error(
`endpoint asks for ${fmtUsdc(accept.amount)} USDC, above the bridge cap of ${fmtUsdc(MAX_USDC_MICROS.toString())} (raise X402_BRIDGE_MAX_USDC_MICROS to allow)`,
);
}
emit({
stage: 'challenge',
amount: accept.amount,
payTo: accept.payTo,
asset: accept.asset,
network: accept.network,
resource: challenge.resource || null,
});
// 2. The agent wallet builds + partially signs the SPL TransferChecked.
// The endpoint-advertised extra.feePayer pays the transaction fee and is
// co-signed by the facilitator on /settle — the agent only signs the
// transfer authority.
const signer = await agentSigner();
emit({
stage: 'signing',
signer: signer.address,
network: accept.network,
mint: accept.asset,
to: accept.payTo,
value: accept.amount,
feePayer: accept.extra.feePayer,
});
const { ExactSvmScheme } = await import('@x402/svm');
const scheme = new ExactSvmScheme(signer, { rpcUrl: SOLANA_RPC_URL });
const built = await scheme.createPaymentPayload(2, accept);
emit({ stage: 'signed', signer: signer.address });
// 3. Retry the request with the X-PAYMENT header — the endpoint verifies and
// 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' });
const paidRes = await fetch(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,
});
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;
}
}
statusCache = null; // balance just changed
emit({
stage: 'done',
amount: accept.amount,
payer: signer.address,
payTo: accept.payTo,
settlement,
result,
});
}
// ── HTTP server ───────────────────────────────────────────────────────────
function readBody(req) {
return new Promise((resolvePromise, reject) => {
let data = '';
req.on('data', (c) => {
data += c;
if (data.length > 64 * 1024) reject(new Error('request body too large'));
});
req.on('end', () => resolvePromise(data));
req.on('error', reject);
});
}
function sendJson(res, status, obj) {
res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' });
res.end(JSON.stringify(obj));
}
const server = createServer(async (req, res) => {
const origin = req.headers.origin;
if (origin && corsOriginAllowed(origin)) {
res.setHeader('access-control-allow-origin', origin);
res.setHeader('vary', 'origin');
res.setHeader('access-control-allow-methods', 'GET,POST,OPTIONS');
res.setHeader('access-control-allow-headers', 'content-type');
}
if (req.method === 'OPTIONS') {
res.writeHead(204);
return res.end();
}
const url = new URL(req.url, `http://localhost:${PORT}`);
try {
if (req.method === 'GET' && url.pathname === '/status') {
return sendJson(res, 200, await walletStatus());
}
if (req.method === 'GET' && url.pathname === '/quote') {
const endpoint = url.searchParams.get('endpoint') || '';
const method = (url.searchParams.get('method') || 'POST').toUpperCase();
if (!endpointAllowed(endpoint)) {
return sendJson(res, 400, { ok: false, error: `endpoint origin not allowed (allowed: ${ALLOWED_ENDPOINT_ORIGINS.join(', ')})` });
}
const bodyParam = url.searchParams.get('body');
const probeBody = bodyParam ? JSON.parse(bodyParam) : undefined;
const { challenge, accept } = await fetch402(endpoint, method, probeBody);
return sendJson(res, 200, {
ok: true,
amount: accept.amount,
payTo: accept.payTo,
asset: accept.asset,
network: accept.network,
feePayer: accept.extra?.feePayer || null,
maxTimeoutSeconds: accept.maxTimeoutSeconds,
resource: challenge.resource || null,
});
}
if (req.method === 'POST' && url.pathname === '/pay') {
const raw = await readBody(req);
let parsed;
try {
parsed = JSON.parse(raw || '{}');
} catch {
return sendJson(res, 400, { ok: false, error: 'invalid JSON body' });
}
const endpoint = String(parsed.endpoint || '');
const method = String(parsed.method || 'POST').toUpperCase();
if (!['GET', 'POST'].includes(method)) {
return sendJson(res, 400, { ok: false, error: 'method must be GET or POST' });
}
if (!endpointAllowed(endpoint)) {
return sendJson(res, 400, { ok: false, error: `endpoint origin not allowed (allowed: ${ALLOWED_ENDPOINT_ORIGINS.join(', ')})` });
}
res.writeHead(200, {
'content-type': 'text/event-stream; charset=utf-8',
'cache-control': 'no-store',
connection: 'keep-alive',
});
let lastStage = 'challenge';
const emit = (evt) => {
lastStage = evt.stage || lastStage;
res.write(`data: ${JSON.stringify(evt)}\n\n`);
};
try {
await executePayment({ endpoint, method, body: parsed.body, emit });
} catch (err) {
emit({ stage: 'error', failedStage: lastStage, message: err.message });
}
return res.end();
}
sendJson(res, 404, { ok: false, error: 'not found' });
} catch (err) {
if (!res.headersSent) sendJson(res, 500, { ok: false, error: err.message });
else res.end();
}
});
server.listen(PORT, '127.0.0.1', () => {
console.log(`agent-wallet x402 bridge listening on http://127.0.0.1:${PORT}`);
console.log(` settlement rail: USDC on Solana mainnet (solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp)`);
console.log(` allowed endpoint origins: ${ALLOWED_ENDPOINT_ORIGINS.join(', ')}`);
console.log(` per-payment cap: ${fmtUsdc(MAX_USDC_MICROS.toString())} USDC`);
walletStatus()
.then((s) =>
console.log(
` agent wallet: ${s.wallet.address} (${s.balance.chains[0]?.usdc ?? 0} USDC, ${s.balance.chains[0]?.sol ?? '?'} SOL)`,
),
)
.catch((e) => console.warn(` wallet unavailable: ${e.message}`));
});