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
fix(x402): answer a validator's bare probe with the 402 challenge instead of a 400
nirholas02ab5a15601d
diff --git a/api/x402/pay-by-name.js b/api/x402/pay-by-name.jsindex 6dc808978..2cbd633ba 100644--- a/api/x402/pay-by-name.js+++ b/api/x402/pay-by-name.js@@ -97,7 +97,6 @@ function isOnCurveAddress(addr) {async function handlePaidNameResolve(req, res, body) {const name = String(body?.name || '').trim();- if (!name) return error(res, 400, 'validation_error', 'name required');const resourceUrl = resolveResourceUrl(req, PAID_RESOLVE_ROUTE);const accepts = buildSolanaAccepts(PAID_RESOLVE_PRICE_ATOMIC, resourceUrl);@@ -116,6 +115,14 @@ async function handlePaidNameResolve(req, res, body) {});}+ // The `name` check lives BELOW the challenge on purpose. A bare POST with no+ // body is how every listing validator probes a paid row (x402scan's "Add API"+ // registration flow, the A2MCP compliance self-check), and a 400 tells it this+ // route sells nothing. The probe now reads the 402 it looks for, and a buyer+ // who actually pays without naming anything still gets the validation error,+ // before anything is settled.+ if (!name) return error(res, 400, 'validation_error', 'name required');+let verified;try {verified = await verifyPayment({ paymentHeader, requirements: accepts });@@ -437,8 +444,18 @@ export default wrap(async (req, res) => {// Paid name resolution — body has `name` but no payer_wallet/amount_usdc and// no explicit prep/send mode. Returns 402 challenge; on payment resolves the// name and returns { data: { name, address, verified, source } }.- if (body?.name && !body?.payer_wallet && !body?.amount_usdc &&- body?.mode !== 'send' && body?.mode !== 'prep') {+ //+ // A body-less POST lands here too. That is the paid capability this route is+ // cataloged under, and a bare `curl -X POST` is exactly how a directory+ // validates a paid row: it fell through to the free prep branch and answered+ // 400, so the row read as selling nothing. mode=prep still reaches prep, it+ // just has to say so (or carry the wallet/amount fields prep needs anyway).+ const paidResolveLane =+ !body?.payer_wallet &&+ !body?.amount_usdc &&+ body?.mode !== 'send' &&+ body?.mode !== 'prep';+ if (paidResolveLane) {return handlePaidNameResolve(req, res, body);}diff --git a/api/x402/pipeline.js b/api/x402/pipeline.jsindex d5a43a3f1..27df0b6e0 100644--- a/api/x402/pipeline.js+++ b/api/x402/pipeline.js@@ -277,17 +277,29 @@ export default wrap(async (req, res) => {const chunks = [await readBody(req, 1_000_000)];const rawBody = Buffer.concat(chunks).toString('utf8');- let plan;+ // A body that never becomes a plan must NOT short-circuit the paywall. Every+ // validator that indexes this route probes it with a bare POST and no body+ // (x402scan's "Add API" registration flow, the A2MCP compliance self-check),+ // and reads anything other than 402 as a row that sells nothing. Answering+ // the probe with a 400 is why this route stayed unlistable while quoting a+ // spec-valid 402 to real buyers. The probe now gets the challenge, priced at+ // the catalog's example chain (the same amount /.well-known/x402.json and+ // /openapi.json advertise for this route), and the validation error is+ // re-raised below for any caller that actually crosses the paywall.+ let plan = null;+ let planError = null;try {const bodyObj = rawBody ? JSON.parse(rawBody) : {};plan = parsePlan(bodyObj);} catch (err) {- if (err.status) return error(res, err.status, err.code, err.message);- return error(res, 400, 'invalid_json', 'Request body must be valid JSON.');+ planError = err.status+ ? { status: err.status, code: err.code, message: err.message }+ : { status: 400, code: 'invalid_json', message: 'Request body must be valid JSON.' };}- // The 402 quote is the EXACT sum of the requested stages' prices.- const price = priceForChain(plan.stages);+ // The 402 quote is the EXACT sum of the requested stages' prices; an+ // unpriceable probe body quotes the catalog's example chain instead.+ const price = priceForChain(plan ? plan.stages : INPUT_EXAMPLE.stages);const resourceUrl = resolveResourceUrl(req, ROUTE);const requirements = buildRequirements(resourceUrl, price.atomics);const service = withService({@@ -316,6 +328,10 @@ export default wrap(async (req, res) => {const paymentHeader = req.headers['x-payment'] || req.headers['payment-signature'];if (!bypass && !paymentHeader) return send402(res, challenge);+ // Past the paywall with a body we could not turn into a plan: answer the+ // validation error it earned. Nothing settles, because nothing ran.+ if (planError) return error(res, planError.status, planError.code, planError.message);+// Guard the input GLB against SSRF before any lane fetches it.if (plan.glbUrl) {try {diff --git a/scripts/okx-compliance-probe.mjs b/scripts/okx-compliance-probe.mjsindex 72b9c8866..6ef25b64f 100644--- a/scripts/okx-compliance-probe.mjs+++ b/scripts/okx-compliance-probe.mjs@@ -123,6 +123,10 @@ const failures = [];for (const [service, listPrice] of PAID_ROWS) {const shapes = [+ [+ 'GET, the SSE transport a streaming MCP client opens with',+ { method: 'GET', headers: { accept: 'text/event-stream' } },+ ],['docs self-check: POST, no body, no content-type', {}],['POST {} with content-type application/json',diff --git a/tests/x402-probe-challenge.test.js b/tests/x402-probe-challenge.test.jsindex 30cb39fd1..cb452868e 100644--- a/tests/x402-probe-challenge.test.js+++ b/tests/x402-probe-challenge.test.js@@ -24,6 +24,12 @@ beforeAll(async () => {X402_PAY_TO_BASE: '0x4022de2d36c334e73c7a108805cea11c0564f402',X402_ASSET_ADDRESS_BASE: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',X402_ADVERTISE_BASE: 'true',+ // pay-by-name builds its own Solana-only accept list and answers 503+ // not_configured without these three, so the probe would never reach+ // the challenge the test below asserts.+ X402_PAY_TO_SOLANA: 'wwwwwDxFWRn7grgr3Esrsg5C6NvDoDHSA4gaCffccrU',+ X402_FEE_PAYER_SOLANA: 'WwwuGbqHrwF5RG89KhUbmRWEvjnRH9k5kVM5p7T3WwW',+ X402_ASSET_MINT_SOLANA: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',},timeoutMs: 60_000,});@@ -46,6 +52,8 @@ beforeAll(async () => {'/api/x402/cosmetic-purchase','/api/x402/animation-download','/api/x402/fact-check',+ '/api/x402/pipeline',+ '/api/x402/pay-by-name','/api/v1/x/openai/chat','/api/v1/x/coingecko/price',].map((route) => fetch(`${BASE}${route}`).catch(() => {})),@@ -132,4 +140,51 @@ describe('credential-less probes always reach the 402 challenge', () => {});await expectChallenge(res);}, 15000);++ // pipeline and pay-by-name validated the request body BEFORE pricing it, so a+ // bare `POST` with no body answered 400 (`invalid_stages`, `payer_wallet must+ // be a base58 Solana public key`). Measured against production 2026-09-04:+ // they were the only two of the 60 paid routes absent from the x402scan+ // origin listing that answered a bodyless probe with anything other than a+ // 402 or an honest 503, which is exactly the shape that fails registration.++ it('bodyless POST on pipeline serves the challenge, not the stage-validation 400', async () => {+ const res = await fetch(`${BASE}/api/x402/pipeline`, { method: 'POST' });+ await expectChallenge(res);+ }, 15000);++ it('pipeline prices a probe at the catalog example chain (generate + rig)', async () => {+ // The catalog advertises the example chain's price for this route, so an+ // unpriceable probe body must quote that same amount or the directory+ // lists a price no buyer is ever shown. The child server inherits this+ // process's env, so the stage prices behind both are identical.+ const { priceForChain } = await import('../api/_lib/pipeline.js');+ const res = await fetch(`${BASE}/api/x402/pipeline`, { method: 'POST' });+ const body = await expectChallenge(res);+ expect(body.accepts[0].amount).toBe(priceForChain(['generate', 'rig']).atomics);+ }, 15000);++ it('a body naming an unknown stage still reaches the challenge, not a 400', async () => {+ const res = await fetch(`${BASE}/api/x402/pipeline`, {+ method: 'POST',+ headers: { 'content-type': 'application/json' },+ body: JSON.stringify({ stages: ['not-a-stage'] }),+ });+ await expectChallenge(res);+ }, 15000);++ it('bodyless POST on pay-by-name serves the paid-resolve challenge, not the prep 400', async () => {+ const res = await fetch(`${BASE}/api/x402/pay-by-name`, { method: 'POST' });+ const body = await expectChallenge(res);+ expect(body.resource?.url ?? body.resourceUrl ?? '').toContain('/api/x402/pay-by-name');+ }, 15000);++ it('pay-by-name still routes an explicit mode=prep to prep validation', async () => {+ const res = await fetch(`${BASE}/api/x402/pay-by-name`, {+ method: 'POST',+ headers: { 'content-type': 'application/json' },+ body: JSON.stringify({ mode: 'prep' }),+ });+ expect(res.status).toBe(400);+ }, 15000);});