Discovering x402 Payment Capability via DNS and a Well-Known URI

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶

This Internet-Draft will expire on 2 February 2027.¶

Copyright Notice

Copyright (c) 2026 IETF Trust and the persons identified as the document authors. All rights reserved.¶

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶

Table of Contents

1. Introduction

The x402 protocol [X402] 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 [RFC7208], DMARC [RFC7489]), and most directly with MTA-STS [RFC8461], 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 [RFC8615] path "/.well-known/x402" is the authoritative, machine-readable record of a host's x402 capability (Section 3).¶
• An optional DNS TXT record at the underscored node name [RFC8552] "_x402" is a lightweight pointer that lets a consumer discover x402 capability from DNS alone, before making any HTTP request (Section 4).¶

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

2. 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 [RFC2119] [RFC8174] 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 Section 3.¶

Consumer:

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

3. The x402 Well-Known URI

A host participating in x402 SHOULD serve a JSON [RFC8259] 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.¶

{
  "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"
}

4. The _x402 DNS TXT Record

A domain MAY additionally publish a TXT record [RFC1035] at the underscored node name "_x402" [RFC8552]:¶

_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 Section 6).¶

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 [RFC7208] and DMARC [RFC7489] 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 [RFC8461] pattern, and it keeps the mechanism useful even where DNSSEC [RFC4033] 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.¶

5. 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.¶

6. 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.¶

7. IANA Considerations

8. Implementation Status

This section is to be removed before publishing as an RFC.¶

This section records the status of known implementations per [RFC7942].¶

• A zero-dependency resolver implementing the full algorithm of Section 5, 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.¶

9. 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 [JEFTOVIC], 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.¶

Acknowledgments

Mark E. Jeftovic proposed "_x402" TXT-record discovery for x402 first, in [JEFTOVIC] 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.¶

Author's Address