Independent

wdhawkins46@gmail.com

Applications x402 DNS well-known payments discovery x402 is an application-level protocol for internet-native payments built on the HTTP 402 (Payment Required) status code. This document defines how a domain publishes its x402 payment capability out-of-band, so that clients, autonomous agents, and indexers can discover it without prior configuration or a central directory. It specifies a JSON capability manifest served at the well-known URI "/.well-known/x402" and an optional DNS TXT record at the underscored node name "_x402" that points to the manifest. A consumer resolves a bare domain name to verified x402 capability with at most one DNS query and one HTTPS GET. About This Document This document is a successor to the expired individual submission draft-jeftovic-x402-dns-discovery-00, whose author is credited in the Acknowledgments; an offer of co-authorship remains open. Discussion of this document takes place in the x402 Foundation community (https://github.com/x402-foundation/x402), where a corresponding extension specification is under review.

Introduction The x402 protocol makes payment terms self-describing at the moment a client encounters an HTTP 402 response: the response body enumerates acceptable payment schemes, networks, assets, and amounts. What x402 does not define is how a client that has never contacted a host learns that the host participates in x402 at all, in what role, and with what capabilities. In practice this gap has been filled by hand-curated lists and directory sites, which rot, do not scale, and centralize what is naturally edge-published data. Electronic mail solved the same problem with DNS records (MX, SPF , DMARC ), and most directly with MTA-STS , in which an unauthenticated DNS TXT record points to an authenticated HTTPS policy document. This document applies that pattern to x402:

• A JSON capability manifest served over HTTPS at the well-known URI path "/.well-known/x402" is the authoritative, machine-readable record of a host's x402 capability ().
• An optional DNS TXT record at the underscored node name "_x402" is a lightweight pointer that lets a consumer discover x402 capability from DNS alone, before making any HTTP request ().

A consumer resolves a bare domain name to verified capability with at most one DNS query and one HTTPS GET (). Curated directories become optional caches, regenerable by crawling, rather than load-bearing infrastructure.

Conventions and Definitions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here.

Facilitator:

A service that verifies and settles x402 payments on behalf of resource servers, conventionally exposing "supported", "verify", and "settle" endpoints.

Resource server:

An HTTP server that gates resources behind x402 payments.

Manifest:

The JSON document defined in .

Consumer:

Any client, agent, crawler, or indexer that resolves x402 capability using this mechanism.

The x402 Well-Known URI A host participating in x402 SHOULD serve a JSON manifest at: https://<host>/.well-known/x402 The manifest MUST be served over HTTPS with media type "application/json". Cross-origin GET SHOULD be permitted; the manifest is public data. Hosts SHOULD serve the manifest with HTTP caching headers.

Example { "x402Version": 2, "kind": "facilitator", "name": "Example Facilitator", "description": "One-line human description.", "facilitator": { "baseUrl": "https://pay.example.com", "endpoints": { "supported": "/supported", "verify": "/verify", "settle": "/settle" }, "kinds": [ { "x402Version": 2, "scheme": "exact", "network": "eip155:114" } ], "assets": [ { "network": "eip155:114", "address": "0x1F930B6A9F68c91aB23db07a9c4A5Dc166eF8011", "symbol": "EXUSD", "decimals": 6, "standard": "EIP-3009" } ] }, "resources": [ { "url": "https://pay.example.com/demo/card", "method": "POST", "description": "x402-paywalled demo resource" } ], "attestation": { "type": "none" }, "docs": "https://pay.example.com/", "contact": "ops@example.com", "updated": "2026-08-04T00:00:00Z" }

Field Semantics

x402Version (REQUIRED):

Highest x402 protocol version the host speaks.

kind (REQUIRED):

One of "facilitator", "resource-server", or "both".

name, description (RECOMMENDED):

Human-readable identification.

facilitator (REQUIRED when kind includes facilitator):

Capability block for the facilitator role.

facilitator.baseUrl (REQUIRED):

HTTPS base URL of the facilitator API. It MUST be on the same domain as, or a subdomain of, the host serving the manifest, and consumers MUST reject manifests that violate this. Without this rule a host can name someone else's facilitator as its own and turn every conforming crawler into a request amplifier aimed at a third party.

facilitator.endpoints (REQUIRED):

Relative paths for the supported/verify/settle endpoints. Deployments differ; consumers do not guess.

facilitator.kinds (REQUIRED):

A mirror of the live "supported" endpoint. Divergence between the manifest and the live endpoint is a misconfiguration; consumers MUST prefer the live endpoint ().

facilitator.assets (RECOMMENDED):

Settleable assets per network, with the token standard each scheme relies on.

resources (OPTIONAL):

x402-gated resources on this host. Each "url" MUST be HTTPS and on the manifest's own domain or a subdomain. Consumers MUST NOT dereference entries that are not, and SHOULD treat their presence as an abuse signal. Because this document invites indexers to fetch these URLs, an unconstrained field would constitute server-side request forgery by specification: a host listing an internal or link-local address would have every conforming crawler dereference it from inside the crawler's own network.

attestation (OPTIONAL):

Execution-integrity claims, e.g. {"type":"none"} or {"type":"tee","scheme":"...","verifier":"<url>"}. See .

updated (RECOMMENDED):

Timestamp of the last manifest change, used for cache decisions alongside HTTP caching headers.

Unknown fields MUST be ignored, for forward compatibility.

The _x402 DNS TXT Record A domain MAY additionally publish a TXT record at the underscored node name "_x402" : _x402.example.com. IN TXT ( "v=x402-1; " "wk=https://pay.example.com/.well-known/x402; " "k=facilitator; net=eip155:114; scheme=exact" ) The RDATA is a single character-string sequence interpreted as semicolon-separated key=value pairs, order-insensitive:

v (REQUIRED):

The record format version. This document defines "x402-1".

wk (REQUIRED):

Absolute HTTPS URL of the manifest. It MUST be on the publishing domain or a subdomain of it (see ).

k (RECOMMENDED):

"facilitator", "resource-server", or "both" -- a coarse filter so crawlers can skip fetches.

net (OPTIONAL):

Comma-separated network identifiers (coarse filter only).

scheme (OPTIONAL):

Comma-separated scheme names (coarse filter only).

A domain MUST publish at most one record with "v=x402-1" at a given owner name. Consumers that find more than one MUST treat the name as unresolvable rather than choosing between them: "first record wins" is a race that anyone able to add a single TXT record can win by ordering -- a shared DNS control panel, a delegated subdomain, a partial compromise. SPF and DMARC both make duplicate records a hard error for precisely this reason. The TXT record is a pointer, not an authority: all capability data comes from the manifest, which is retrieved over HTTPS. This split -- unauthenticated DNS pointer to authenticated HTTPS policy -- is the MTA-STS pattern, and it keeps the mechanism useful even where DNSSEC is absent. Hosts without control of their DNS (for example, hosts on platform-assigned subdomains) simply publish the manifest alone; resolution step 2 below still finds them.

Resolution Algorithm Given a domain name D, a consumer resolves x402 capability as follows:

1. Query TXT for "_x402.D". If a record with "v=x402-1" exists, fetch the manifest from its "wk" URL, rejecting non-HTTPS or out-of-domain URLs. Consumers MUST re-apply the in-domain constraint to every redirect hop and report the final URL as the manifest source. Checking only the requested URL validates a location the bytes need not have come from: an in-domain "wk" URL that redirects off-domain would otherwise pass, defeating the one control the (unauthenticated) DNS layer has. Redirect chains SHOULD be bounded.
2. Otherwise, attempt GET on "https://D/.well-known/x402".
3. Validate the manifest shape; ignore unknown fields.
4. Before using a facilitator, fetch the live "supported" endpoint given by baseUrl and endpoints.supported, and treat the live response as authoritative over the manifest's "kinds" array.

Steps 1-2 answer "does this domain speak x402, and in what role" with at most one DNS query and one HTTP GET. Indexers crawl the same way and SHOULD periodically re-verify records.

Fetch Bounds Consumers MUST bound the manifest fetch with a request timeout and a maximum response size. An unbounded read is a denial of service handed to anyone who can publish a TXT record: a hostile host serves an arbitrarily large body, or trickles bytes indefinitely, and the crawler exhausts memory or hangs. Size limits MUST be applied to the bytes actually received, not to the Content-Length header, which is the server's claim rather than a measurement. (One deployed implementation uses a 256 KiB size cap, a 10-second deadline, and at most 3 redirect hops.)

Refusing Private Destinations Before every fetch this document invites -- the manifest, each redirect hop, resources[] probes, and the live "supported" cross-check -- a consumer MUST refuse a URL whose host is, or resolves to, a loopback, link-local, or private-range address. The HTTPS and in-domain rules do not cover this case: the publisher controls their own DNS, so an in-domain hostname can resolve to a link-local metadata address or an address inside the crawler's network, and DNS-based certificate issuance grants valid certificates to names that never point anywhere public. The check MUST be re-applied on every redirect hop; a public first hop redirecting to an internal name is the classic bypass. Resolution-time checks remain subject to DNS rebinding between check and connect; consumers needing a stronger guarantee SHOULD pin the resolved address for the connection. Deployments intentionally operating on private networks MAY relax this rule, explicitly.

Security Considerations Discovery is not endorsement. A manifest proves that a host claims a capability; it transfers no trust. Clients MUST validate settlement the way the x402 protocol already requires, and SHOULD apply their own reputation or allowlist policy on top of discovery. DNS spoofing: the TXT record is unauthenticated without DNSSEC. That is why it may only point into the same domain, and why the manifest -- served under the domain's TLS certificate -- is the authority. An attacker who can forge the TXT record but not the domain's HTTPS gains nothing. The same-origin constraint on "wk" prevents a domain from claiming another operator's facilitator as its own, and prevents the record from being used as an open redirect for crawler traffic. This holds only if consumers enforce it on every redirect hop and on facilitator.baseUrl, not on the requested URL alone. Servers MUST NOT derive manifest URLs from request-controlled input. A manifest endpoint that builds its own baseUrl or resource URLs from the Host or X-Forwarded-Host request headers lets any caller make the document -- served under the operator's own TLS certificate -- advertise an attacker's host, and a cacheable response without a matching Vary header can then be replayed to other consumers. The public origin MUST be pinned in configuration. This is the same attack the "wk" rule addresses, arriving on the side this document calls authoritative, and it is easy to introduce precisely because deriving the origin from the request looks like good hygiene. DNSSEC upgrades the TXT record from a hint to an assertion. Unsigned, the record is a convenience that the HTTPS manifest must backstop. Signed, a validating resolver can prove the record was not tampered with. Operators SHOULD sign zones carrying "_x402" records and SHOULD monitor RRSIG expiry: an expired signature fails validation exactly like a forged one, so the record -- and the discovery path -- disappears on a timer. Manifest/live divergence: consumers MUST prefer live "supported" data over the manifest's mirror of it; indexers SHOULD flag divergent hosts. Attestation claims in the manifest are claims like everything else: an execution-integrity attestation is only meaningful if the verifier URL lets the client independently check an attestation token chain against a published, reproducible build. Absent such verification, consumers treat the attestation as absent. Crawler load: manifests are static JSON; hosts SHOULD serve them with cache headers and rate-limit them as any public endpoint.

IANA Considerations

Well-Known URI Registration IANA is requested to register the following entry in the "Well-Known URIs" registry defined by :

URI Suffix:

x402

Change Controller:

IETF

Reference:

This document

Status:

permanent

Underscored Node Name Registration IANA is requested to register the following entry in the "Underscored and Globally Scoped DNS Node Names" registry defined by :

RR Type:

TXT

_NODE NAME:

_x402

Reference:

This document

Implementation Status This section records the status of known implementations per .

• A zero-dependency resolver implementing the full algorithm of , including redirect re-validation, fetch bounds, and private-destination refusal, is deployed and exercises live "_x402" records published on the author's production domains, resolving end-to-end from bare domain name to live capability endpoint.
• A corresponding extension specification is under review in the x402 Foundation repository (x402-foundation/x402, pull request 2979), with a live manifest served by a public facilitator deployment.

Relationship to Prior Proposals DNS-based and well-known-URI-based discovery for x402 has been proposed independently several times in the x402 community, most completely in , which used the same "_x402" TXT label and substantially the same resolution approach. That document expired without revision in May 2026. This document is offered as a successor that consolidates those proposals and adds the manifest schema, duplicate-record rule, redirect and private-destination constraints, and IANA registrations. Co-authorship remains open to the authors of the prior proposals.

References Normative References Informative References x402 Foundation Work in Progress, expired Internet-Draft

Acknowledgments Mark E. Jeftovic proposed "_x402" TXT-record discovery for x402 first, in and in x402 community discussion; this document deliberately builds on that work, and the offer to fold this text into a revision of his draft -- or to add him as co-author here -- stands. The authors of the other independent discovery proposals in the x402 community (repository issues 1348, 2582, and 2831) reached similar designs and are acknowledged likewise. Reviewers on x402 Foundation pull request 2979 materially improved the security considerations, in particular the redirect re-validation and duplicate-record rules.