Skip to content

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.

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.js
index 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.js
index 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.mjs
index 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.js
index 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);
});