Detect nested x402 challenge bodies

Author: TateLyman

README.md

@@ -30,6 +30,7 @@ npx --yes x402-surface-check --strict-proof https://api.example.com/openapi.json
 - No-payment HTTP 402 challenge shape
 - x402 v1 and v2 price fields, including `accepts[]` and `schemes[]` challenge arrays
 - MPP `WWW-Authenticate: Payment` and x402 V2 `WWW-Authenticate: X402 requirements=...` challenges
+- x402 challenges nested inside framework error wrappers such as FastAPI-style `{"detail": {...}}`
 - MPP descriptor-only 402s that advertise discovery headers but do not return a machine-readable payment retry challenge
 - Atomic-unit `amount` / `maxAmountRequired` fields, plus legacy decimal `amount` + `token` x402 v1 challenges
 - `asset` or token metadata, `network`, and `payTo`

bin/x402-surface-check.mjs

@@ -648,6 +648,29 @@ function parseX402Authenticate(value) {
   }
 }
 
+function bodyChallengeJson(value) {
+  if (!value || typeof value !== 'object') return null
+  if (Array.isArray(value.accepts) || Array.isArray(value.schemes)) return value
+
+  const candidates = [
+    value.detail,
+    value.error,
+    value.payment,
+    value.paymentRequired,
+    value.payment_required,
+    value.challenge,
+    value.x402,
+  ]
+
+  for (const candidate of candidates) {
+    if (!candidate || typeof candidate !== 'object') continue
+    const nested = bodyChallengeJson(candidate)
+    if (nested) return nested
+  }
+
+  return null
+}
+
 async function fetchDocument(url) {
   const response = await fetch(url, {
     headers: {
@@ -750,7 +773,11 @@ async function probeEndpoint(entry, origin) {
   const authenticateChallenge = parsePaymentAuthenticate(response.headers.get('www-authenticate'))
     ?? parseX402Authenticate(response.headers.get('www-authenticate'))
 
-  const bodyHasChallenge = Array.isArray(body.json?.accepts) || Array.isArray(body.json?.schemes)
+  const bodyChallenge = bodyChallengeJson(body.json)
+  const bodyHasChallenge = Boolean(bodyChallenge)
+  if (bodyChallenge && body.json !== bodyChallenge) {
+    body.json = bodyChallenge
+  }
   if (!bodyHasChallenge) {
     if (headerChallenge && typeof headerChallenge === 'object') {
       body.json = headerChallenge

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "x402-surface-check",
-  "version": "0.2.36",
+  "version": "0.2.37",
   "description": "No-payment x402 public-surface checker for manifests, OpenAPI specs, and HTTP 402 challenges.",
   "type": "module",
   "bin": {

package.json

@@ -32,6 +32,14 @@ const server = createServer((request, response) => {
     return
   }
 
+  if (request.method === 'OPTIONS' && request.url === '/nested-detail') {
+    response.statusCode = 405
+    response.setHeader('allow', 'POST')
+    response.setHeader('content-type', 'application/json')
+    response.end(JSON.stringify({ detail: 'Method Not Allowed' }))
+    return
+  }
+
   if (request.method === 'OPTIONS') {
     response.statusCode = 204
     response.setHeader('access-control-allow-origin', '*')
@@ -970,6 +978,30 @@ data: ${JSON.stringify({
     return
   }
 
+  if (request.url === '/nested-detail') {
+    response.statusCode = 402
+    response.setHeader('content-type', 'application/json')
+    response.end(JSON.stringify({
+      detail: {
+        x402Version: 1,
+        error: 'Payment Required',
+        accepts: [{
+          scheme: 'exact',
+          network: 'base-mainnet',
+          maxAmountRequired: '500000',
+          resource: `${serverUrl}/nested-detail`,
+          description: 'Nested framework detail challenge',
+          mimeType: 'application/json',
+          payTo: '0xc174A7C8088BF271399CD3E9f88c20D37CAb967D',
+          maxTimeoutSeconds: 300,
+          asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+          extra: { name: 'USD Coin', version: '2' },
+        }],
+      },
+    }))
+    return
+  }
+
   if (request.url === '/mpp/descriptor-only') {
     response.statusCode = 402
     response.setHeader('content-type', 'application/json')
@@ -1510,6 +1542,25 @@ try {
   assert.match(strictCache.stdout, /Cloudflare x402 Worker Starter/)
   assert.match(strictCache.stdout, /x402 Attack Map 2026/)
 
+  const nestedDetail = await execFileAsync('node', [
+    'bin/x402-surface-check.mjs',
+    '--endpoint',
+    '--method',
+    'POST',
+    `${serverUrl}/nested-detail`,
+    '--origin',
+    'https://example.com',
+    '--strict-cache',
+  ], { cwd: new URL('..', import.meta.url) })
+
+  assert.match(nestedDetail.stdout, /direct endpoint/)
+  assert.match(nestedDetail.stdout, /base-mainnet/)
+  assert.match(nestedDetail.stdout, /\$0\.50/)
+  assert.match(nestedDetail.stdout, /402 challenge response does not allow the requesting origin/)
+  assert.match(nestedDetail.stdout, /CORS preflight does not allow the requesting origin/)
+  assert.match(nestedDetail.stdout, /CORS preflight does not allow a known x402 retry header/)
+  assert.match(nestedDetail.stdout, /payment challenge response did not expose Cache-Control/)
+
   const schemes = await execFileAsync('node', [
     'bin/x402-surface-check.mjs',
     '--endpoint',