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
// Pay-per-request /api/v1/chat/completions over x402 `upto`, end to end.
//
// Real: the handler, the agent loop, the OpenAI-wire stream reader, the price
// table, the @x402/svm upto client (signs the channel open) and server scheme
// (advertises the offer, signs the claim voucher). Test-controlled: the chain
// (tests/helpers/upto-local-facilitator.js keeps every signature check real and
// replaces only the ledger) and the model upstream, a local HTTP server that
// speaks the real OpenAI chat-completions streaming wire format.
import http from 'node:http';
import { EventEmitter } from 'node:events';
import { Readable } from 'node:stream';
import { generateKeyPairSigner } from '@solana/kit';
import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
import { UptoLocalFacilitator } from './helpers/upto-local-facilitator.js';
vi.mock('@coinbase/x402', () => ({ createCdpAuthHeaders: vi.fn(async () => ({})) }));
let upstreamUrl = '';
vi.mock('../api/_lib/llm-tool-chain.js', async (importOriginal) => {
const actual = await importOriginal();
return { ...actual, providerChain: () => [{ name: 'groq', url: upstreamUrl, key: 'k', model: 'local-model' }] };
});
vi.mock('../api/_lib/rate-limit.js', async (importOriginal) => {
const actual = await importOriginal();
const ok = async () => ({ success: true, limit: 120, remaining: 119, reset: Date.now() + 1000 });
return { ...actual, limits: new Proxy(actual.limits, { get: (t, k) => (k === 'apiV1' || k === 'x402VerifyPenalty' ? ok : t[k]) }) };
});
vi.mock('../api/_lib/auth.js', async (importOriginal) => {
const actual = await importOriginal();
return { ...actual, getSessionUser: async () => null };
});
vi.mock('../api/_lib/x402/audit-log.js', () => ({ logPaymentEvent: vi.fn() }));
vi.mock('../api/_lib/usage.js', () => ({ recordEvent: vi.fn() }));
const USDC_MAINNET = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';
let handler;
let uptoMod;
let metered;
let table;
let facilitator;
let operator;
let payer;
let server;
let upstreamMode = { kind: 'ok', usage: { prompt_tokens: 1200, completion_tokens: 300 }, deltas: ['Hello ', 'from ', 'the model.'] };
let upstreamHold = null;
function startUpstream() {
server = http.createServer((req, res) => {
req.resume();
req.on('end', async () => {
if (upstreamMode.kind === 'down') {
res.writeHead(500, { 'content-type': 'application/json' });
return res.end(JSON.stringify({ error: { message: 'upstream unavailable' } }));
}
res.writeHead(200, { 'content-type': 'text/event-stream' });
const frame = (delta, extra = {}) =>
`data: ${JSON.stringify({ id: 'up-1', object: 'chat.completion.chunk', model: 'local-model', choices: [{ index: 0, delta, finish_reason: null }], ...extra })}\n\n`;
for (const d of upstreamMode.deltas) res.write(frame({ content: d }));
if (upstreamMode.kind === 'hold') {
await new Promise((r) => (upstreamHold = r));
}
res.write(`data: ${JSON.stringify({ id: 'up-1', object: 'chat.completion.chunk', model: 'local-model', choices: [{ index: 0, delta: {}, finish_reason: 'stop' }] })}\n\n`);
res.write(`data: ${JSON.stringify({ id: 'up-1', object: 'chat.completion.chunk', model: 'local-model', choices: [], usage: upstreamMode.usage })}\n\n`);
res.write('data: [DONE]\n\n');
res.end();
});
});
return new Promise((resolve) =>
server.listen(0, '127.0.0.1', () => {
upstreamUrl = `http://127.0.0.1:${server.address().port}/v1/chat/completions`;
resolve();
}),
);
}
function mockReqRes({ headers = {}, body }) {
const lower = { 'content-type': 'application/json' };
for (const [k, v] of Object.entries(headers)) lower[k.toLowerCase()] = v;
const req = Object.assign(new Readable({ read() {} }), {
method: 'POST',
url: '/api/v1/chat/completions',
headers: lower,
connection: { remoteAddress: '127.0.0.1' },
socket: { remoteAddress: '127.0.0.1' },
});
req.push(JSON.stringify(body));
req.push(null);
const chunks = [];
const resHeaders = {};
const res = Object.assign(new EventEmitter(), {
statusCode: 200,
writableEnded: false,
headersSent: false,
setHeader(k, v) {
resHeaders[k.toLowerCase()] = v;
},
getHeader(k) {
return resHeaders[k.toLowerCase()];
},
write(chunk) {
res.headersSent = true;
chunks.push(String(chunk));
return true;
},
end(chunk) {
if (chunk !== undefined) chunks.push(String(chunk));
res.headersSent = true;
res.writableEnded = true;
res.emit('close');
},
});
Object.defineProperties(res, {
body: { get: () => chunks.join('') },
headers: { get: () => resHeaders },
});
return { req, res };
}
async function sign(accept) {
const { UptoSvmScheme } = await import('@x402/svm/upto/client');
const built = await new UptoSvmScheme(payer).createPaymentPayload(2, accept);
return Buffer.from(JSON.stringify({ x402Version: 2, accepted: accept, payload: built.payload })).toString('base64');
}
async function challengeFor(body) {
const { req, res } = mockReqRes({ body });
await handler(req, res);
expect(res.statusCode).toBe(402);
const challenge = JSON.parse(res.body);
return { res, challenge, accept: challenge.accepts.find((a) => a.scheme === 'upto') };
}
const MESSAGES = [{ role: 'user', content: 'Say hello.' }];
beforeAll(async () => {
process.env.X402_ALLOW_MEMORY_FALLBACK = '1';
delete process.env.DATABASE_URL;
operator = await generateKeyPairSigner();
payer = await generateKeyPairSigner();
process.env.X402_PAY_TO_SOLANA = (await generateKeyPairSigner()).address;
process.env.X402_ASSET_MINT_SOLANA = USDC_MAINNET;
process.env.X402_UPTO_ENABLED = 'true';
process.env.X402_FEE_PAYER_SECRET_BASE58 = 'unused-because-the-bundle-is-installed';
const { generatePrivateKey } = await import('viem/accounts');
process.env.OFFER_RECEIPT_SIGNING_PRIVATE_KEY = generatePrivateKey();
await startUpstream();
uptoMod = await import('../api/_lib/x402/upto.js');
metered = await import('../api/_lib/metered-router.js');
table = await import('../api/_lib/pricing/inference-models.js');
const chainState = (await generateKeyPairSigner()).address;
facilitator = new UptoLocalFacilitator({ feePayerAddress: operator.address });
const baseExtra = facilitator.getExtra.bind(facilitator);
facilitator.getExtra = () => ({ ...baseExtra(), recentBlockhash: chainState, lastValidBlockHeight: '1000', recentSlot: '500' });
const { UptoSvmScheme: ServerScheme } = await import('@x402/svm/upto/server');
uptoMod.setUptoBundleForTests({
facilitator,
server: new ServerScheme({ receiverAuthorizerSigner: operator }),
signer: operator,
});
({ default: handler } = await import('../api/v1/chat/completions.js'));
});
afterAll(async () => {
uptoMod?.setUptoBundleForTests(null);
await new Promise((r) => server.close(r));
});
beforeEach(() => {
facilitator.events.length = 0;
upstreamMode = { kind: 'ok', usage: { prompt_tokens: 1200, completion_tokens: 300 }, deltas: ['Hello ', 'from ', 'the model.'] };
});
describe('unauthenticated request', () => {
it('answers a valid 402 with an upto offer sized to the worst case', async () => {
const body = { model: 'three-ws/agent', messages: MESSAGES, stream: false };
const { res, challenge, accept } = await challengeFor(body);
console.log('402 accepts:\n' + JSON.stringify(challenge.accepts, null, 2));
expect(res.headers['payment-required']).toBeTruthy();
expect(challenge.x402Version).toBe(2);
expect(accept.scheme).toBe('upto');
expect(accept.network).toMatch(/^solana:/);
expect(accept.asset).toBe(USDC_MAINNET);
expect(accept.amount).toBe(String(metered.worstCaseAtomics(table.inferenceModelRow('three-ws/agent'), body)));
expect(accept.extra.receiverAuthorizer).toBe(operator.address);
});
it('sizes the cap to the request: a longer prompt asks for a larger cap', async () => {
const small = await challengeFor({ messages: MESSAGES });
const big = await challengeFor({ messages: [{ role: 'user', content: 'x'.repeat(40_000) }] });
expect(BigInt(big.accept.amount)).toBeGreaterThan(BigInt(small.accept.amount));
});
it('refuses naming an agent without an owner', async () => {
const { req, res } = mockReqRes({ body: { messages: MESSAGES, agent_id: '00000000-0000-4000-8000-000000000000' } });
await handler(req, res);
expect(res.statusCode).toBe(401);
expect(JSON.parse(res.body).error).toBe('sign_in_required');
});
});
describe('metered settlement', () => {
it('settles measured tokens times the published price and refunds the rest of the cap', async () => {
const body = { model: 'three-ws/agent', messages: MESSAGES, stream: false };
const { accept } = await challengeFor(body);
const { req, res } = mockReqRes({ body, headers: { 'x-payment': await sign(accept) } });
await handler(req, res);
expect(res.statusCode).toBe(200);
const out = JSON.parse(res.body);
expect(out.usage.prompt_tokens).toBe(1200);
expect(out.usage.completion_tokens).toBe(300);
// 1200 in at 0.5 and 300 out at 2.0 USD per million tokens = 0.0012 USD.
const row = table.inferenceModelRow('three-ws/agent');
const expected = BigInt(Math.round(((1200 * row.input_usd_per_mtok + 300 * row.output_usd_per_mtok) / 1e6) * 1e6));
expect(expected).toBe(1200n);
const [deposit, claim] = facilitator.events;
expect(deposit.kind).toBe('deposit');
expect(deposit.amount).toBe(BigInt(accept.amount));
expect(claim.kind).toBe('claim');
expect(claim.paid).toBe(expected);
console.log('settlement events: ' + JSON.stringify(facilitator.events, (k, v) => (typeof v === 'bigint' ? String(v) : v)));
const settled = JSON.parse(Buffer.from(res.headers['x-payment-response'], 'base64').toString('utf8'));
expect(settled.charged_atomics).toBe('1200');
expect(settled.refunded_atomics).toBe(String(BigInt(accept.amount) - 1200n));
});
it('settles on stream close and reports the charge in the usage chunk', async () => {
const body = { model: 'three-ws/agent', messages: MESSAGES, stream: true, stream_options: { include_usage: true } };
const { accept } = await challengeFor(body);
const { req, res } = mockReqRes({ body, headers: { 'x-payment': await sign(accept) } });
await handler(req, res);
expect(res.statusCode).toBe(200);
expect(res.body).toContain('Hello ');
expect(res.body).toContain('data: [DONE]');
const claim = facilitator.events.find((e) => e.kind === 'claim');
expect(claim.paid).toBe(1200n);
const usageFrame = res.body.split('\n').filter((l) => l.startsWith('data: {')).map((l) => JSON.parse(l.slice(6))).find((f) => f.usage);
expect(usageFrame.billing.charged_atomics).toBe('1200');
expect(usageFrame.billing.paid_via).toBe('x402-upto');
});
it('charges only the tokens already sent when the client drops the stream', async () => {
upstreamMode = { kind: 'hold', usage: { prompt_tokens: 5000, completion_tokens: 5000 }, deltas: ['A'.repeat(40)] };
const body = { model: 'three-ws/agent', messages: MESSAGES, stream: true };
const { accept } = await challengeFor(body);
const { req, res } = mockReqRes({ body, headers: { 'x-payment': await sign(accept) } });
const running = handler(req, res);
await vi.waitFor(() => expect(res.body).toContain('AAAA'));
res.emit('close');
await vi.waitFor(() => expect(facilitator.events.some((e) => e.kind === 'claim')).toBe(true));
const row = table.inferenceModelRow('three-ws/agent');
const expected = metered.chargeAtomics(row, metered.promptTokensOf(body), 10);
const claim = facilitator.events.find((e) => e.kind === 'claim');
expect(claim.paid).toBe(expected);
expect(claim.paid).toBeLessThan(5000n);
upstreamHold?.();
await running;
expect(facilitator.events.filter((e) => e.kind === 'claim')).toHaveLength(1);
});
it('returns the whole deposit when the completion fails before any token', async () => {
upstreamMode = { kind: 'down', deltas: [] };
const body = { model: 'three-ws/agent', messages: MESSAGES, stream: false };
const { accept } = await challengeFor(body);
const { req, res } = mockReqRes({ body, headers: { 'x-payment': await sign(accept) } });
await handler(req, res);
expect(res.statusCode).toBeGreaterThanOrEqual(500);
expect(facilitator.events.map((e) => e.kind)).toEqual(['deposit', 'cancel']);
});
it('never charges above the cap', () => {
const row = table.inferenceModelRow('three-ws/agent');
const cap = metered.worstCaseAtomics(row, { messages: MESSAGES });
expect(uptoMod.normaliseCharge(metered.chargeAtomics(row, 10_000_000, 10_000_000), cap)).toBe(cap);
});
});
describe('deployment without upto', () => {
it('keeps answering 401 missing_api_key when pay-per-request is not enabled', async () => {
const saved = process.env.X402_UPTO_ENABLED;
process.env.X402_UPTO_ENABLED = 'false';
uptoMod.setUptoBundleForTests(null);
try {
const { req, res } = mockReqRes({ body: { messages: MESSAGES } });
await handler(req, res);
expect(res.statusCode).toBe(401);
expect(JSON.parse(res.body).error).toBe('missing_api_key');
} finally {
process.env.X402_UPTO_ENABLED = saved;
}
});
});