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
/**
* Work order 03: the decomposed 3D studio on OKX.AI
* (/api/okx/3d/<service>, catalog rows in api/_lib/okx-catalog.js, engines in
* api/_okx3d/rest-services.js).
*
* Covers, for EVERY paid REST service (no sampling): the catalog contract and
* price points, the per-service 402 (OKX dialect, X Layer accept first, the
* service's own amount), the free GET descriptor, the paid dispatch to the
* real engine seam, settle-only-after-success, and the failure paths that
* must never charge (invalid input, humanoid gate, engine 5xx, rejected
* payment).
*/
import { describe, it, expect, vi, beforeEach } from 'vitest';
import { Readable } from 'node:stream';
import Ajv from 'ajv';
import addFormats from 'ajv-formats';
process.env.PUBLIC_APP_ORIGIN = 'https://three.ws';
process.env.X402_PAY_TO_XLAYER ||= '0x75d00a2713565171f33216e5aa2a375e076ecf69';
process.env.X402_XLAYER_RELAYER_KEY ||=
'0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d';
process.env.X402_PAY_TO_BASE ||= '0x0000000000000000000000000000000000000001';
process.env.JWT_SECRET ||= 'okx-3d-test-secret';
vi.mock('../../api/_lib/rate-limit.js', () => ({
limits: {
publicIp: vi.fn(async () => ({ success: true, reset: Date.now() + 1000 })),
mcpIp: vi.fn(async () => ({ success: true, reset: Date.now() + 1000 })),
mcpUser: vi.fn(async () => ({ success: true, reset: Date.now() + 1000 })),
mcpOptimize: vi.fn(async () => ({ success: true, reset: Date.now() + 1000 })),
},
clientIp: vi.fn(() => '203.0.113.9'),
}));
vi.mock('../../api/_lib/usage.js', () => ({
recordEvent: vi.fn(),
logger: () => ({ info: () => {}, warn: () => {}, error: () => {} }),
}));
// Idempotency plumbing is DB-backed in prod; stub it to always-miss so the
// paid path runs the engine (replay caching has its own suite).
vi.mock('../../api/_lib/x402/payment-identifier-server.js', () => ({
PAYMENT_IDENTIFIER: 'payment-identifier',
extractIdFromHeader: vi.fn(() => null),
hashPaymentProof: vi.fn(() => null),
hashRequestPayload: vi.fn(() => 'payload-hash'),
paymentIdentifierExtension: vi.fn(() => ({})),
checkCache: vi.fn(async () => ({ kind: 'miss' })),
storeResponse: vi.fn(async () => {}),
writeCachedResponse: vi.fn(),
writeConflict: vi.fn(),
reservePaymentProof: vi.fn(async () => ({ ok: true, release: async () => {} })),
}));
// Payment verification/settlement are exercised against the live rail in the
// WO-04 gauntlet; here they are seams: the suite asserts WHEN they run
// (verify before engine, settle only after success), not chain mechanics.
const verifyPaymentMock = vi.fn();
const settlePaymentMock = vi.fn();
vi.mock('../../api/_lib/x402-spec.js', async (importOriginal) => {
const real = await importOriginal();
return {
...real,
verifyPayment: (...args) => verifyPaymentMock(...args),
settlePayment: (...args) => settlePaymentMock(...args),
};
});
vi.mock('../../api/_lib/r2.js', () => ({
putObject: vi.fn(async () => {}),
getObjectBuffer: vi.fn(async () => Buffer.alloc(0)),
headObject: vi.fn(async () => ({ ContentLength: 1 })),
publicUrl: (key) => `https://cdn.test/${key}`,
}));
// Programmable fetch router over the engine's HTTP surfaces (/api/forge).
const fetchRoutes = {};
function jsonResponse(status, body) {
return new Response(JSON.stringify(body), {
status,
headers: { 'content-type': 'application/json' },
});
}
const realFetch = globalThis.fetch;
beforeEach(() => {
verifyPaymentMock.mockReset();
settlePaymentMock.mockReset();
verifyPaymentMock.mockImplementation(async ({ requirements }) => ({
paymentPayload: { x402Version: 2 },
requirement: Array.isArray(requirements) ? requirements[0] : requirements,
payer: '0x75d00a2713565171f33216e5aa2a375e076ecf69',
}));
settlePaymentMock.mockResolvedValue({
success: true,
transaction: '0xsettled',
network: 'eip155:196',
payer: '0x75d00a2713565171f33216e5aa2a375e076ecf69',
});
fetchRoutes.forgeSubmit = () => jsonResponse(200, { job_id: 'forge-gen-1', status: 'queued' });
fetchRoutes.rig = () => jsonResponse(200, { job_id: 'forge-rig-1', status: 'queued' });
fetchRoutes.forgePoll = () => jsonResponse(200, { status: 'running' });
fetchRoutes.chat = () => new Response(null, { status: 503 }); // director down → fail-soft
fetchRoutes.other = () => new Response('not found', { status: 404 });
globalThis.fetch = vi.fn(async (url, init = {}) => {
const u = String(url);
if (u.includes('/api/chat')) return fetchRoutes.chat(u, init);
if (u.includes('/api/forge?action=rig')) return fetchRoutes.rig(u, init);
if (u.includes('/api/forge?job=')) return fetchRoutes.forgePoll(u, init);
if (u.includes('/api/forge')) return fetchRoutes.forgeSubmit(u, init);
return fetchRoutes.other(u, init);
});
return () => {
globalThis.fetch = realFetch;
};
});
const {
OKX_CATALOG,
catalogEntry,
catalogIndex,
displayWidth,
listedCatalog,
listingDescription,
parameterSpec,
requestMethod,
validateCatalog,
} = await import('../../api/_lib/okx-catalog.js');
const studioCatalog = await import('../../api/_mcp3d/catalog.js');
const { default: handler } = await import('../../api/okx/3d/[service].js');
const PAID_REST_IDS = [
'text-to-3d',
'text-to-3d-pro',
'image-to-3d',
'rig',
'avatar',
'retarget',
'pose-seed',
'fbx-export',
];
// Valid POST bodies per service, used by both the 402 and the paid tests.
const VALID_INPUT = {
'text-to-3d': { prompt: 'a brass steampunk owl' },
'text-to-3d-pro': { prompt: 'a brass steampunk owl', tier: 'high' },
'image-to-3d': { image_urls: ['https://example.com/owl-front.jpg'] },
rig: { glb_url: 'https://cdn.test/owl.glb' },
avatar: { prompt: 'a heroic knight character, full body' },
retarget: { model_url: 'https://cdn.test/knight-rigged.glb', animation: 'idle' },
'pose-seed': { prompt: 'confident standing pose, arms crossed' },
'fbx-export': { model_url: 'https://cdn.test/knight-rigged.glb' },
};
function makeRes() {
return {
statusCode: 200,
headers: {},
body: null,
setHeader(name, value) {
this.headers[String(name).toLowerCase()] = value;
},
end(body) {
this.body = body ?? null;
},
};
}
function makeReq({ method = 'POST', service, headers = {}, body = null } = {}) {
const payload = body == null ? '' : JSON.stringify(body);
const req = Readable.from(payload ? [Buffer.from(payload, 'utf8')] : []);
req.method = method;
req.url = `/api/okx/3d/${service}`;
req.query = { service };
req.headers = {
'content-type': 'application/json',
host: 'three.ws',
'x-forwarded-proto': 'https',
...headers,
};
return req;
}
const decode402Header = (res) =>
JSON.parse(Buffer.from(res.headers['payment-required'], 'base64').toString('utf8'));
describe('okx catalog, work order 03 rows', () => {
it('all eight decomposed services exist at the work-order price points', () => {
expect(validateCatalog()).toBe(true);
const prices = Object.fromEntries(
OKX_CATALOG.map((e) => [e.id, [e.priceUsd, e.amountAtomics]]),
);
expect(prices['text-to-3d']).toEqual(['0.01', '10000']);
expect(prices['text-to-3d-pro']).toEqual(['0.30', '300000']);
expect(prices['image-to-3d']).toEqual(['0.30', '300000']);
expect(prices.rig).toEqual(['0.25', '250000']);
expect(prices.avatar).toEqual(['0.50', '500000']);
expect(prices.retarget).toEqual(['0.10', '100000']);
expect(prices['pose-seed']).toEqual(['0.02', '20000']);
expect(prices['fbx-export']).toEqual(['0.10', '100000']);
});
it('every paid row routes /api/okx/3d/<id> and is POST-documented', () => {
for (const id of PAID_REST_IDS) {
const e = catalogEntry(id);
expect(e.endpoint).toBe(`https://three.ws/api/okx/3d/${id}`);
expect(e.inputSchema).toBeTruthy();
}
});
// OKX listing QA requires FOUR parts on an A2MCP service and rejects a
// listing missing any of them (`onchainos agent update --help`). Submitting
// two parts is what earned the 2026-09-02 rejection: "The service you
// submitted is missing a complete description, parameter details, and usage
// examples."
it('every listed row submits four parts: capability, parameters, method, example', () => {
for (const e of listedCatalog()) {
const parts = listingDescription(e).split('\n');
expect(parts, `${e.id} part count`).toHaveLength(4);
expect(parts[0], `${e.id} capability`).toBe(e.describes.capability);
expect(parts[1], `${e.id} parameters`).toBe(parameterSpec(e));
expect(parts[2], `${e.id} method`).toBe(requestMethod(e));
expect(parts[3], `${e.id} example`).toMatch(/^curl /);
expect(parts[3], `${e.id} example hits the real endpoint`).toContain(e.endpoint);
expect(displayWidth(listingDescription(e)), `${e.id} width`).toBeLessThanOrEqual(2000);
}
});
// Part 2 is generated from the schema, so it names every argument the
// endpoint accepts, with the type and required flag the endpoint enforces.
it('the parameter spec names every schema property with its real type and requiredness', () => {
for (const e of listedCatalog()) {
const props = Object.entries(e.inputSchema?.properties || {});
const spec = parameterSpec(e);
if (!props.length) {
expect(spec).toBe('No parameters. Send an empty request.');
continue;
}
const required = new Set(e.inputSchema.required || []);
for (const [name, prop] of props) {
const type = prop.type === 'array' ? `${prop.items?.type}[]` : prop.type;
expect(spec, `${e.id}.${name}`).toContain(
`${name} (${type}, ${required.has(name) ? 'required' : 'optional'}):`,
);
}
}
});
// A published usage example the endpoint would reject is worse than none:
// the buyer copies it, gets a 400, and leaves. Validate each example against
// the row's own schema with the same Ajv the endpoints use.
it('every listed usage example validates against its own endpoint schema', async () => {
const { default: Ajv } = await import('ajv');
const { default: addFormats } = await import('ajv-formats');
const ajv = addFormats(new Ajv({ strict: false }));
for (const e of listedCatalog()) {
if (!Object.keys(e.inputSchema?.properties || {}).length) continue;
const validate = ajv.compile(e.inputSchema);
const ok = validate(e.describes.example);
expect(ok, `${e.id} example: ${ajv.errorsText(validate.errors)}`).toBe(true);
}
});
// OKX rejected the listing on 2026-07-26 for "missing a complete description,
// parameter details, and usage examples". Every row states its capability and
// what the caller must provide, and this guard keeps that from regressing.
it('every row states its capability and its parameters', () => {
for (const e of OKX_CATALOG) {
expect(e.describes.capability.length, `${e.id} capability`).toBeGreaterThan(40);
// Parameter details: the "Provide..." sentence OKX's format asks for.
expect(e.describes.input, `${e.id} input`).toMatch(/^Provide/);
}
});
// The listing invariants (.agents/skills/okx-agent-identity/references/
// invariants.md) forbid example prompts, links and tech-stack names inside a
// service description. The back-burner rows predate that reading and are not
// submitted; every LISTED row must be clean, since those are the strings a
// reviewer actually reads.
it('listed rows carry no example prompt, link, or tech-stack name', () => {
for (const e of listedCatalog()) {
for (const part of [e.describes.capability, e.describes.input]) {
expect(part, `${e.id}`).not.toMatch(/Example:/i);
expect(part, `${e.id}`).not.toMatch(/https?:\/\//);
expect(part, `${e.id}`).not.toMatch(/\b(TRELLIS|Hunyuan|NVIDIA|GPU|MCP|x402|JSON-RPC)\b/);
}
}
});
// The back burner is a listing decision, not a deletion: those endpoints stay
// deployed and payable, so the free index still publishes them under
// `unlisted` rather than pretending they are gone.
it('the free catalog index splits listed from back-burner rows, losing none', () => {
const index = catalogIndex();
const listedIds = index.services.map((s) => s.id);
const unlistedIds = index.unlisted.map((s) => s.id);
for (const id of PAID_REST_IDS) expect(unlistedIds).toContain(id);
expect([...listedIds, ...unlistedIds].sort()).toEqual(OKX_CATALOG.map((e) => e.id).sort());
expect(listedIds).toEqual(listedCatalog().map((e) => e.id));
});
it('the paid MCP tools each service maps to exist on the studio engine', () => {
for (const tool of ['apply_animation', 'pose_model', 'remesh_model']) {
expect(studioCatalog.TOOLS[tool]?.handler).toBeTypeOf('function');
}
});
});
describe('per-service 402 (unpaid POST)', () => {
for (const id of PAID_REST_IDS) {
it(`${id}: OKX-dialect 402, X Layer accept first, its own amount`, async () => {
const res = makeRes();
await handler(makeReq({ service: id, body: VALID_INPUT[id] }), res);
expect(res.statusCode).toBe(402);
const entry = catalogEntry(id);
const header = decode402Header(res);
const body = JSON.parse(res.body);
expect(body).toEqual(header); // header and body carry the same envelope
expect(body.x402Version).toBe(2);
expect(body.resource.url).toBe(`https://three.ws/api/okx/3d/${id}`);
expect(body.resource.mimeType).toBe('application/json');
const first = body.accepts[0];
expect(first.scheme).toBe('exact');
expect(first.network).toBe('eip155:196');
expect(first.amount).toBe(entry.amountAtomics);
expect(first.payTo.toLowerCase()).toBe('0x75d00a2713565171f33216e5aa2a375e076ecf69');
expect(first.asset.toLowerCase()).toBe('0x779ded0c9e1022225f8e0630b35a9b54be713736');
expect(first.maxTimeoutSeconds).toBe(86400);
expect(first.extra).toMatchObject({
symbol: 'USDT',
name: 'USD₮0',
version: '1',
transferMethod: 'eip3009',
});
// One service, one price: every advertised rail quotes the same amount.
for (const a of body.accepts) expect(a.amount).toBe(entry.amountAtomics);
expect(settlePaymentMock).not.toHaveBeenCalled();
});
}
it('GET is the free per-service descriptor (price + schema, no payment)', async () => {
const res = makeRes();
await handler(makeReq({ method: 'GET', service: 'rig' }), res);
expect(res.statusCode).toBe(200);
const body = JSON.parse(res.body);
expect(body.price_usd).toBe('0.25');
expect(body.input_schema.required).toEqual(['glb_url']);
expect(body.method).toBe('POST');
});
});
describe('paid dispatch: verify → engine → settle', () => {
function paidReq(service, body) {
return makeReq({ service, body, headers: { 'payment-signature': 'c2ln' } });
}
it('text-to-3d runs the free draft-tier lane (no backend pin) and returns a pollable job', async () => {
const res = makeRes();
await handler(paidReq('text-to-3d', VALID_INPUT['text-to-3d']), res);
expect(res.statusCode).toBe(200);
const body = JSON.parse(res.body);
expect(body).toMatchObject({ service: 'text-to-3d', price_usd: '0.01', status: 'queued', job_id: 'forge-gen-1' });
expect(body.poll_url).toContain('/api/forge?job=');
const submit = globalThis.fetch.mock.calls.find(([u]) => String(u).endsWith('/api/forge'));
// No backend pin: the draft default now resolves to the photoreal
// image-intermediate pipeline (see forge-tiers.js FREE_DEFAULT_FOR_TIERS)
// instead of forcing NVIDIA's native text-only preview.
expect(JSON.parse(submit[1].body)).toMatchObject({ path: 'image' });
expect(JSON.parse(submit[1].body).backend).toBeUndefined();
expect(settlePaymentMock).toHaveBeenCalledTimes(1);
expect(res.headers['payment-response']).toBeTruthy();
expect(res.headers['x-payment-response']).toBe(res.headers['payment-response']);
});
// The paid 200 is the ONLY response that carries a settlement receipt, and a
// browser-side x402 client can read a response header only if it is in the
// expose list. The success path used to overwrite cors()'s list with just
// the two v2 names, so it set x-payment-response and then hid it from every
// cross-origin reader.
it('the paid 200 exposes both receipt header names to cross-origin readers', async () => {
const res = makeRes();
await handler(paidReq('text-to-3d', VALID_INPUT['text-to-3d']), res);
expect(res.statusCode).toBe(200);
const exposed = String(res.headers['access-control-expose-headers'])
.split(',')
.map((h) => h.trim().toLowerCase());
expect(exposed).toContain('payment-response');
expect(exposed).toContain('x-payment-response');
});
it('text-to-3d-pro survives a downed art director (fail-soft) and submits the original prompt', async () => {
const res = makeRes();
await handler(paidReq('text-to-3d-pro', VALID_INPUT['text-to-3d-pro']), res);
expect(res.statusCode).toBe(200);
const submit = globalThis.fetch.mock.calls.find(([u]) => String(u).endsWith('/api/forge'));
expect(JSON.parse(submit[1].body).prompt).toBe('a brass steampunk owl');
expect(settlePaymentMock).toHaveBeenCalledTimes(1);
});
it('image-to-3d forwards the reference views to the reconstruct lane', async () => {
const res = makeRes();
await handler(paidReq('image-to-3d', VALID_INPUT['image-to-3d']), res);
expect(res.statusCode).toBe(200);
const submit = globalThis.fetch.mock.calls.find(([u]) => String(u).endsWith('/api/forge'));
expect(JSON.parse(submit[1].body).image_urls).toEqual(VALID_INPUT['image-to-3d'].image_urls);
expect(settlePaymentMock).toHaveBeenCalledTimes(1);
});
it('rig submits the auto-rig job and returns it pollable', async () => {
const res = makeRes();
await handler(paidReq('rig', VALID_INPUT.rig), res);
expect(res.statusCode).toBe(200);
expect(JSON.parse(res.body)).toMatchObject({ status: 'queued', job_id: 'forge-rig-1', mode: 'rig' });
expect(settlePaymentMock).toHaveBeenCalledTimes(1);
});
it('avatar chains generate → rig and returns the mesh even while the rig job polls', async () => {
fetchRoutes.forgeSubmit = () =>
jsonResponse(200, { status: 'done', glb_url: 'https://cdn.test/knight.glb' });
const res = makeRes();
await handler(paidReq('avatar', VALID_INPUT.avatar), res);
expect(res.statusCode).toBe(200);
const body = JSON.parse(res.body);
expect(body).toMatchObject({
service: 'avatar',
status: 'queued',
job_id: 'forge-rig-1',
mode: 'avatar',
mesh_glb_url: 'https://cdn.test/knight.glb',
});
expect(settlePaymentMock).toHaveBeenCalledTimes(1);
});
it('pose-seed resolves deterministically in-process: same prompt, same seed, real engine', async () => {
const res1 = makeRes();
await handler(paidReq('pose-seed', VALID_INPUT['pose-seed']), res1);
expect(res1.statusCode).toBe(200);
const first = JSON.parse(res1.body);
expect(first.status).toBe('done');
expect(first.seed ?? first.pose ?? first.rotations ?? first.preset).toBeDefined();
const res2 = makeRes();
await handler(paidReq('pose-seed', VALID_INPUT['pose-seed']), res2);
expect(JSON.parse(res2.body)).toEqual(first);
expect(settlePaymentMock).toHaveBeenCalledTimes(2);
});
it('retarget routes to the apply_animation engine and settles only on success', async () => {
const original = studioCatalog.TOOLS.apply_animation.handler;
studioCatalog.TOOLS.apply_animation.handler = vi.fn(async (args) => ({
content: [{ type: 'text', text: 'ok' }],
structuredContent: { animation: args.animation, coverage: 0.97, clip: { tracks: 12 } },
}));
try {
const res = makeRes();
await handler(paidReq('retarget', VALID_INPUT.retarget), res);
expect(res.statusCode).toBe(200);
expect(JSON.parse(res.body)).toMatchObject({ status: 'done', animation: 'idle', coverage: 0.97 });
expect(studioCatalog.TOOLS.apply_animation.handler).toHaveBeenCalledTimes(1);
expect(settlePaymentMock).toHaveBeenCalledTimes(1);
} finally {
studioCatalog.TOOLS.apply_animation.handler = original;
}
});
it('fbx-export routes to remesh_model convert with rig-preserving fbx default', async () => {
const original = studioCatalog.TOOLS.remesh_model.handler;
studioCatalog.TOOLS.remesh_model.handler = vi.fn(async (args) => {
// remesh_model speaks mesh_url/output_format, NOT the catalog row's
// model_url/format. Passing the OKX names made every paid fbx-export
// call 400 on "mesh_url must be a public https URL" and silently drop
// the requested format.
expect(args).toMatchObject({
mesh_url: VALID_INPUT['fbx-export'].model_url,
operation: 'convert',
output_format: 'fbx',
});
return { content: [{ type: 'text', text: 'ok' }], structuredContent: { job_id: 'remesh-1' } };
});
try {
const res = makeRes();
await handler(paidReq('fbx-export', VALID_INPUT['fbx-export']), res);
expect(res.statusCode).toBe(200);
expect(JSON.parse(res.body)).toMatchObject({ status: 'queued', job_id: 'remesh-1', format: 'fbx' });
expect(settlePaymentMock).toHaveBeenCalledTimes(1);
} finally {
studioCatalog.TOOLS.remesh_model.handler = original;
}
});
});
// The three tool-backed rows call an MCP tool handler DIRECTLY, bypassing the
// studio dispatcher that would normally validate arguments, so a renamed key
// fails at runtime, on a paid call, with nothing catching it in between. This
// holds each adapter to the engine tool's own published schema.
describe('engine argument contract', () => {
const ENGINE_FOR = {
retarget: 'apply_animation',
'pose-seed': 'pose_model',
'fbx-export': 'remesh_model',
};
const schemaAjv = new Ajv({ allErrors: true, strict: false });
addFormats(schemaAjv);
for (const [service, tool] of Object.entries(ENGINE_FOR)) {
it(`${service} passes arguments ${tool} actually accepts`, async () => {
const schema = studioCatalog.TOOL_CATALOG.find((t) => t.name === tool)?.inputSchema;
expect(schema, `${tool} publishes an inputSchema`).toBeTruthy();
const validate = schemaAjv.compile(schema);
const original = studioCatalog.TOOLS[tool].handler;
let seen = null;
studioCatalog.TOOLS[tool].handler = vi.fn(async (args) => {
seen = args;
return { content: [{ type: 'text', text: 'ok' }], structuredContent: {} };
});
try {
const res = makeRes();
await handler(
makeReq({ service, body: VALID_INPUT[service], headers: { 'payment-signature': 'c2ln' } }),
res,
);
expect(res.statusCode).toBe(200);
} finally {
studioCatalog.TOOLS[tool].handler = original;
}
expect(seen, `${service} never reached ${tool}`).toBeTruthy();
expect(validate(seen) ? [] : validate.errors).toEqual([]);
});
}
});
describe('failure paths never charge', () => {
function paidReq(service, body) {
return makeReq({ service, body, headers: { 'payment-signature': 'c2ln' } });
}
it('invalid input → 400 before any engine call, no settle', async () => {
const res = makeRes();
await handler(paidReq('text-to-3d', { prompt: 'x' }), res); // below minLength 3
expect(res.statusCode).toBe(400);
expect(settlePaymentMock).not.toHaveBeenCalled();
expect(globalThis.fetch.mock.calls.find(([u]) => String(u).includes('/api/forge'))).toBeUndefined();
});
it('avatar humanoid gate steers objects away without charging', async () => {
const res = makeRes();
await handler(paidReq('avatar', { prompt: 'a wooden chair' }), res);
expect(res.statusCode).toBe(400);
expect(JSON.parse(res.body).error_description || JSON.parse(res.body).message).toMatch(/humanoid/i);
expect(settlePaymentMock).not.toHaveBeenCalled();
});
it('engine 5xx → 502, explicit "payment was not taken", no settle', async () => {
fetchRoutes.forgeSubmit = () => jsonResponse(500, { message: 'kaboom' });
const res = makeRes();
await handler(paidReq('text-to-3d', VALID_INPUT['text-to-3d']), res);
expect(res.statusCode).toBeGreaterThanOrEqual(500);
expect(res.body).toMatch(/payment was not taken/);
expect(settlePaymentMock).not.toHaveBeenCalled();
});
it('rejected payment → fresh OKX 402 with the error surfaced, engine never runs', async () => {
const { X402Error } = await import('../../api/_lib/x402-errors.js');
verifyPaymentMock.mockRejectedValueOnce(new X402Error('invalid_payment', 'insufficient_balance', 402));
const res = makeRes();
await handler(paidReq('rig', VALID_INPUT.rig), res);
expect(res.statusCode).toBe(402);
const body = JSON.parse(res.body);
expect(body.error).toBe('insufficient_balance');
expect(body.accepts[0].network).toBe('eip155:196');
expect(globalThis.fetch.mock.calls.find(([u]) => String(u).includes('action=rig'))).toBeUndefined();
expect(settlePaymentMock).not.toHaveBeenCalled();
});
// The decode failure used to be the one rejection on the paid path that
// answered without a quotation (a bare 400 carrying no accepts[]), which a
// marketplace validator replaying a payment reads as an unparseable x402
// quotation. OKX's own seller SDK re-issues the 402 here.
it('an undecodable payment header re-issues the quotation, never a bare 400', async () => {
const { X402Error } = await import('../../api/_lib/x402-errors.js');
verifyPaymentMock.mockRejectedValueOnce(
new X402Error('invalid_payment', 'X-PAYMENT JSON parse failed: Unexpected token', 400),
);
const res = makeRes();
await handler(paidReq('rig', VALID_INPUT.rig), res);
expect(res.statusCode).toBe(402);
const body = JSON.parse(res.body);
expect(body).toEqual(decode402Header(res));
expect(body.accepts[0].network).toBe('eip155:196');
expect(body.error).toMatch(/parse failed/);
expect(settlePaymentMock).not.toHaveBeenCalled();
});
it('settle failure after delivered work surfaces the x402 error path', async () => {
const { X402Error } = await import('../../api/_lib/x402-errors.js');
settlePaymentMock.mockRejectedValueOnce(new X402Error('settle_failed', 'facilitator down', 502));
const res = makeRes();
await handler(paidReq('text-to-3d', VALID_INPUT['text-to-3d']), res);
expect(res.statusCode).toBe(502);
expect(res.body).toMatch(/settle|facilitator/i);
});
});