x402 Surface Check

May 23, 2026 ยท View on GitHub

No-payment CLI for checking x402 launch surfaces before a real agent spends.

It accepts an x402 manifest or OpenAPI URL, derives public endpoints, sends no-payment probes, checks browser preflight behavior, and returns a Markdown patch queue. It never sends payment retry headers, never signs, and never attempts a paid call.

npm: https://www.npmjs.com/package/x402-surface-check Attack-map field note: https://tateprograms.com/x402-attack-map-2026.html Paid re-check or fix sprint: https://tateprograms.com/x402-fix-sprint.html Machine-readable service catalog: https://tateprograms.com/services.json

npx --yes x402-surface-check https://api.example.com/.well-known/x402
npx --yes x402-surface-check https://api.example.com/openapi.json report.md
npx --yes x402-surface-check --endpoint --method POST https://x402.rpc.ankr.com/eth
npx --yes x402-surface-check --endpoint --method POST --body '{"prompt":"price CPI"}' https://api.example.com/paid-post
npx --yes x402-surface-check --strict-cache https://api.example.com/openapi.json
npx --yes x402-surface-check --strict-proof https://api.example.com/openapi.json

What It Checks

  • Manifest endpoint discovery from items[], endpoints[], marketplace skills[] / catalog.skills[], agents[].tools[] resource URLs, object-valued endpoints, string-valued endpoint maps, tools maps, resources[], x402Endpoints, category arrays, raw resource URL strings, method-prefixed resource strings, and OpenAPI paths
  • Streamable HTTP MCP tool catalogs via safe JSON-RPC tools/list probes with Accept: application/json, text/event-stream
  • Object-valued manifest endpoint query examples, public catalog/discovery GETs, and payment-bearing two-phase operations without treating expected public catalog reads as failed payment gates
  • Linked discovery documents via discovery_url, discoveryUrl, resources_url, resourcesUrl, string discovery links, nested discovery.x402_json / OpenAPI links, or manifest-level OpenAPI links
  • OpenAPI servers[] base-path preservation, so /paths are probed through the documented gateway rather than the domain root
  • OpenAPI query/path examples, JSON request-body examples, nested request schemas, local $ref request schemas, and explicit direct-endpoint bodies for safer no-payment probes
  • OpenAPI paid-operation prioritization, so docs and discovery routes do not consume the probe limit before payment-bearing operations
  • 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
  • OpenAPI-declared x-payment-info.price.amount drift versus the live 402 challenge price
  • Placeholder recipients such as zero addresses and Solana system-program values
  • Testnet or staging rails such as Base Sepolia and Solana devnet
  • HTTPS resource URLs and stable resource metadata
  • Resource binding across top-level resource.url; legacy/v1 accept-leg resource echoes; and localhost/private-development resource URLs that should not ship in production
  • Timeout/expiry metadata on challenges, so payment capabilities have an explicit bounded freshness window
  • Payment-metadata privacy checks for sensitive resource query context, email/SSN/token-like values, prompt/private-context strings, and credential-like URLs in body or header-carried challenges
  • Browser CORS allowance for the requesting origin, common x402/MPP retry headers, and exposed challenge/session headers on the actual 402 response
  • Cache-Control posture on no-payment challenge responses, with P1 warnings for explicitly cacheable payment gates and optional strict-cache findings for missing policy headers
  • Optional strict proof/idempotency posture: mutating paid routes that do not advertise payment-identifier idempotency, and payment challenges that do not advertise signed offer/receipt evidence
  • Payment-enforcement headers on 200 responses, so public telemetry/free-trial endpoints do not accidentally advertise enforced x402 while returning content before a challenge
  • Credential-like query params and URL userinfo inside public registry/discovery endpoint URLs, reported with redacted values so provider API keys and tokens are not repeated in scan output
  • Grouped finding summaries for repeated route-wide issues, so large manifests keep the patch order readable
  • Contextual reference guides for CORS, cache policy, Worker gates, resource echo, validation/auth ordering, and the May 2026 x402 attack-control map
  • Over-broad public method surfaces
  • Auth, validation, and free/trial responses that appear before a payment challenge, without piling on missing-field findings when no challenge was actually returned
  • Operational health/status endpoints, without treating expected free health checks as paid-route failures
  • Object-valued document metadata such as facilitator or network objects, without [object Object] report artifacts

Public Proof

Recent public no-payment checks have found and verified real launch fixes:

Field notes and browser version: https://tateprograms.com/x402-surface-check.html

If a public check finds a launch blocker and you want private follow-up, Tate Programs offers fixed-scope help:

  • $49 private re-check for one manifest, endpoint, OpenAPI file, or PR
  • $149 launch review with spend map and patch order
  • $299 small authorized fix sprint for one blocker such as browser-readable 402s, cache headers, canonical resource URLs, discovery docs, registry proof, or idempotency notes

Start with the scope page before paying: https://tateprograms.com/x402-fix-sprint.html

Options

x402-surface-check <manifest-or-openapi-url> [output.md]
x402-surface-check --endpoint --method POST <paid-endpoint-url> [output.md]

--endpoint       Treat the URL as one paid endpoint instead of a discovery document
--method <verb>  HTTP method for direct endpoint mode, default POST
--body <json>    JSON request body for direct endpoint mode
--body-file <p>  Read JSON request body for direct endpoint mode from a file
--origin <url>   Origin to use for browser-style CORS preflight
--limit <n>      Maximum endpoints to probe, default 6
--strict-cache   Flag missing Cache-Control on no-payment 402 responses
--strict-proof   Flag missing idempotency and signed offer/receipt extensions
--json           Print JSON instead of Markdown
--help           Show usage
--version        Show package version

Environment variables are also supported:

X402_CHECK_ORIGIN=https://example.com x402-surface-check https://api.example.com/openapi.json
X402_CHECK_LIMIT=12 x402-surface-check https://api.example.com/.well-known/x402
X402_STRICT_CACHE=1 x402-surface-check https://api.example.com/.well-known/x402
X402_STRICT_PROOF=1 x402-surface-check https://api.example.com/.well-known/x402

Scope

The checker is intentionally external and conservative:

  • no wallet access
  • no payment headers
  • no paid calls
  • no exploit attempts
  • no private endpoint guessing

It is meant for launch-readiness review, spend-policy evidence, and pre-demo patch order.

Web Version

Browser tool: https://tateprograms.com/x402-surface-check.html