x402 1.0.0

X402 Check v1.0.0

Status

• Version: 1.0.0
• Check identifier: x402
• Input contract: [email protected]
• Output contract: [email protected]
• Scope: site
• Maturity: emerging recommendation

Abstract

This check validates x402 V2 discovery for origins that expose programmable paid HTTP resources. It looks for public x402 or paid-resource signals, discovers safe candidate GET routes, probes those routes without sending payment, and validates observable 402 Payment Required responses that carry a V2 PAYMENT-REQUIRED header.

The check does not execute payments, sign payloads, call facilitator settlement endpoints, or verify blockchain transactions.

Motivation

x402 lets agents discover payable HTTP resources through ordinary HTTP responses. A server can return 402 Payment Required with machine-readable payment requirements, allowing a capable client to understand price, network, scheme, and payee before retrying with a signed payment payload.

Without clear x402 runtime evidence or metadata, agents cannot reliably distinguish a paid programmable resource from a human checkout flow, generic pricing page, or unavailable endpoint.

Normative Model

This version follows:

• RFC 9110 for the 402 Payment Required status code.
• The IANA HTTP field registry to distinguish registered fields from x402

ecosystem header conventions.

• The IANA well-known URI registry to distinguish registered well-known URIs

from community conventions.

• Current x402 V2 documentation for PAYMENT-REQUIRED,

PAYMENT-SIGNATURE, PAYMENT-RESPONSE, Base64 JSON payloads, CAIP-2 network identifiers, and V1-to-V2 migration guidance.

• CAIP-2 for network identifier shape.

Normative expectations used by the check:

• A payable resource should return HTTP 402 before payment.
• A current x402 V2 402 response should include PAYMENT-REQUIRED.
• PAYMENT-REQUIRED should be Base64-encoded JSON.
• The decoded requirement should identify current x402 behavior, preferably

x402Version: 2.

• Payment requirements should include accepted payment options with scheme,

CAIP-2 network, payee or destination, and price or amount.

• Legacy V1 headers such as X-PAYMENT and X-PAYMENT-RESPONSE are

compatibility evidence, not current pass criteria by themselves.

• /.well-known/x402 is treated as a community discovery signal, not as a

registered well-known URI requirement.

Applicability

The check applies when public evidence suggests the origin exposes programmable paid resources or x402 support:

• A sampled route or homepage returns 402 Payment Required.
• A response contains PAYMENT-REQUIRED, PAYMENT-SIGNATURE,

PAYMENT-RESPONSE, or legacy x402 payment headers.

• OpenAPI, Swagger, community metadata, or page content mentions x402, HTTP 402,

machine payments, paid API calls, paid endpoints, pay-per-use resources, or payment headers and also exposes a payable-looking machine route to probe.

• /.well-known/x402 exists.

The check is not applicable when:

• No programmable paid-resource or x402 signal is visible.
• The site only offers ordinary human ecommerce checkout with no paid

machine-readable HTTP resource evidence.

• The scanned origin is a marketing site for a payment product but does not

expose payable resources itself.

• The scanned origin merely describes x402, scanner capabilities, or generic

APIs without exposing an x402 payment header, HTTP 402, /.well-known/x402, or a payable-looking route.

Pass Criteria

The check passes when applicability is established and the strongest observable runtime evidence is valid:

• A discovered or sampled payable resource returns HTTP 402.
• The response includes PAYMENT-REQUIRED.
• PAYMENT-REQUIRED decodes as Base64 JSON.
• The decoded payment requirement indicates current x402 behavior, preferably

x402Version: 2.

• At least one accepted payment option includes:
• scheme
• CAIP-2 network identifier
• payee or destination
• price or amount
• OpenAPI or community metadata, when present, is consistent with observed

runtime behavior.

• No unsafe public metadata is detected.

Warning Criteria

Warnings include:

• x402 or paid-resource signals exist, but no safe payable candidate route is

discoverable.

• Candidate route probing is inconclusive because one or more routes are

unreachable.

• x402 metadata exists, but no probed candidate returns HTTP 402.
• Only legacy or adjacent payment headers are visible.
• /.well-known/x402 is absent while other valid x402 signals exist.
• A payment requirement is mostly valid but omits optional helpful metadata such

as resource description or MIME type.

• An unknown payment scheme is present with otherwise well-formed requirements.

Failure Criteria

Failures include:

• The origin clearly claims x402 support, but discovered candidate routes do not

return HTTP 402.

• A payable candidate returns 402 without PAYMENT-REQUIRED.
• PAYMENT-REQUIRED is not Base64 JSON.
• The decoded payment requirement omits accepted payment options.
• Accepted payment options omit scheme, network, payee or destination, or

price or amount.

• Network identifiers are not CAIP-2 formatted.
• Public metadata exposes localhost, private-network, credential-bearing, or

secret-like values.

Evidence Model

The check emits step-level evidence:

• Applicability signals from homepage status, homepage headers, homepage HTML,

OpenAPI/Swagger, and /.well-known/x402.

• Applicability gating details showing whether the signal came from runtime

status/headers, a payable homepage candidate, or metadata discovery.

• Candidate resources discovered from public metadata.
• Safe candidate probe results:
• path
• source
• status code
• content type
• final URL
• payment header names with redacted values
• bounded text sample where useful
• PAYMENT-REQUIRED validation summary:
• Base64 decode status
• JSON parse status
• version marker
• accepted option count
• schemes
• networks
• invalid network identifiers
• payee/destination presence
• amount presence
• description or MIME type presence
• Metadata consistency summary.
• Safety flags for private/internal URLs, credential-bearing URLs, and concrete

secret-like values. Ordinary OpenAPI authorization descriptions, OAuth authorization endpoints, and placeholder examples such as Authorization: Bearer <key> are not secret exposure by themselves.

Detailed logs must not include full payment payloads, signatures, credentials, cookies, API keys, private keys, full payment addresses, or full fetched metadata bodies.

Validation/Scoring Steps

The check uses these validation steps:

• applicability (0.10): decide whether the origin exposes programmable paid

resources or x402 evidence.

• discover-candidates (0.15): discover safe candidate payable routes from

homepage signals, API docs, and community x402 metadata.

• runtime-402 (0.20): probe candidate GET routes and look for HTTP 402.
• v2-headers (0.15): validate PAYMENT-REQUIRED on 402 responses and

record V2 or legacy payment header evidence.

• payload-shape (0.20): Base64-decode and JSON-parse payment requirements;

validate version and accepted payment option shape.

• network-scheme (0.10): classify schemes and validate CAIP-2 network

identifiers.

• metadata-consistency (0.05): compare OpenAPI and community metadata with

observed runtime behavior.

• security-review (0.05): flag unsafe URLs, credentials, internal targets,

and secret-like public metadata.

Standard Behavior

If no programmable paid-resource signal is visible, the result is not_applicable.

If x402 or paid-resource signals are visible but no safe candidate payable route is discoverable, the result is warning.

If a payable candidate returns valid x402 V2 402 payment requirements, the result is pass.

If a site claims x402 support but emits malformed V2 headers, malformed payment requirements, non-CAIP-2 networks, or unsafe public metadata, the result is fail.

Non-Standard and Real-World Behavior

x402 implementations often protect API routes, MCP tool routes, download URLs, or content resources rather than the homepage. This check therefore uses public metadata to discover candidate routes, but it only sends safe unauthenticated GET probes.

OpenAPI descriptions and community /.well-known/x402 documents can help agents find payable routes. This version treats those as discovery evidence, not as substitutes for a valid runtime 402 response.

Some deployments still expose V1 headers, older package names, or legacy network aliases. This version records those signals as compatibility evidence, but V2 behavior is the preferred pass path.

Non-Goals and Limitations

This check does not:

• Execute payments.
• Sign payloads.
• Send PAYMENT-SIGNATURE.
• Call facilitator /verify or /settle endpoints.
• Verify blockchain settlement, token balances, token decimals, nonces,

deadlines, replay protection, or signatures.

• Crawl every API route looking for paid resources.
• Treat ordinary human checkout ecommerce as x402 support.
• Treat /.well-known/x402 as an IANA-registered well-known URI.

References

• www.rfc-editor.org/rfc/rfc9110#status.402
• www.iana.org/assignments/http-fields/http-fields.xhtml
• www.iana.org/assignments/well-known-uris/well-known-uris.xhtml
• docs.x402.org/
• docs.x402.org/core-concepts/http-402
• docs.x402.org/guides/migration-v1-to-v2
• docs.x402.org/schemes/overview
• docs.x402.org/core-concepts/network-and-token-support
• github.com/x402-foundation/x402
• chainagnostic.org/CAIPs/caip-2
• www.rfc-editor.org/rfc/rfc9110

x402 v1.0.0 Changelog

• Validates observable 402 responses with PAYMENT-REQUIRED Base64 JSON payloads, x402 version markers, accepted payment options, and CAIP-2 network identifiers.
• Treats /.well-known/x402 as community discovery evidence rather than a registered well-known URI requirement.
• Records legacy V1 payment headers as compatibility signals instead of current pass criteria.
• Tightens applicability so generic x402/scanner copy and ordinary API routes do not make the check applicable without runtime payment signals, discovery metadata, or payable-looking machine routes.
• Avoids flagging ordinary OpenAPI authorization descriptions as secret exposure unless concrete secret-like values are published.