]> easyDNS Technologies Inc.

markjr@easydns.com

Applications and Real-Time Independent Submission x402 DNS TXT payment discovery This document defines a DNS-based discovery mechanism for locating x402 payment resources associated with a domain. Domains publish one or more _x402 TXT records containing URLs where x402-compatible clients can obtain resource manifests and metadata over HTTPS. The goal is to provide a lightweight, cache-friendly discovery vector that enables automated payment negotiation using the x402 protocol while keeping DNS records static and non-sensitive.

Introduction The x402 protocol reactivates HTTP status code 402 ("Payment Required") as a mechanism for metered and token-based access control. In this model, clients interact directly with an origin server or a designated facilitator to complete small, machine-to-machine payments before accessing a protected resource. This draft defines a complementary DNS discovery mechanism for x402. By publishing a _x402 TXT record as defined in the Domain Name System , a domain can advertise one or more URLs where clients may retrieve x402 resource manifests and related metadata. This allows agents and applications to locate payment gateways before making application requests, reducing latency and enabling autonomous client behavior. The TXT layer is a pointer-only facility; all dynamic data (prices, nonces, credentials) are obtained via HTTPS from the discovered URL(s).

Conventions and Terminology 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.

Origin

The HTTP host (and optional port) that serves content or APIs protected by x402.

x402 Resource

Any endpoint implementing the x402 payment protocol.

Manifest URL

An HTTPS URL published via _x402 TXT that, when fetched, returns a structured manifest describing available x402 resources.

Descriptor

A short, optional free-text token that semantically identifies the service (e.g., "api", "shop", "tshirt").

Overview To enable discovery, an origin publishes one or more TXT records under the underscored node name _x402 at the specific hostname where x402 resources are served: dns _x402.example.com. 300 IN TXT "v=x4021;url=https://example.com/.well-known/x402" _x402.shop.example.com. 300 IN TXT "v=x4021;descriptor=tshirt;url=https://shop.example.com/x402-discovery" Clients perform a DNS TXT lookup on _x402.<host> using the exact hostname from their intended HTTP request and obtain one or more URLs. x402-protected resources SHOULD be served over HTTPS. While the x402 protocol operates at the HTTP layer, encrypted transport is strongly recommended for payment-related communications. Each URL represents an HTTPS endpoint where further x402 metadata can be retrieved using a simple GET request. The DNS record itself is static and only intended to point to discovery locations. All dynamic data - such as pricing, currency, or facilitator credentials - are obtained over HTTPS from the URL(s) indicated.

Discovery Scope

Each hostname requiring x402 discovery MUST publish its own _x402 TXT record. There is no inheritance from parent domains. Clients MUST query _x402.<exact-request-host> to discover payment resources for that specific hostname.

Record Format Each _x402 TXT record MUST contain a single string formatted as semicolon-separated key/value pairs: abnf record = "v=" version ";" [ descriptor ] "url=" https_url version = "x4021" descriptor = "descriptor=" desc_value ";" desc_value = 1*(%x20-21 / %x23-3A / %x3C-7E) ; printable ASCII excluding quote (0x22) and semicolon (0x3B) https_url = "https://" 1*(VCHAR)

• The optional descriptor provides a short, human-readable identifier for the service (e.g., "api", "shop", "tshirt").
  • Values SHOULD NOT contain semicolons or double quotes; if needed, publishers MAY percent-encode reserved characters per .
  • The descriptor is informational only and MUST NOT be relied upon for authorization or routing decisions.
  • Clients MAY display the descriptor to users to help identify the service.
• Implementations MUST ignore any keys they do not understand.
• Multiple TXT records at the same node are permitted and indicate multiple discovery URLs.

Examples: dns _x402.api.example.com. 300 IN TXT "v=x4021;descriptor=api;url=https://api.example.com/.well-known/x402" _x402.shop.example.com. 300 IN TXT "v=x4021;descriptor=tshirt;url=https://shop.example.com/payment-info" _x402.example.com. 300 IN TXT "v=x4021;url=https://pay.example.com/x402"

Client Processing

1. Lookup - The client performs a DNS TXT query for _x402.<host> using the exact hostname from the intended HTTPS origin.
2. Parse - For each TXT record beginning with v=x4021;, extract the url and, if present, the descriptor.
3. Fetch - Issue an HTTPS GET to each discovered URL. Clients MUST validate TLS certificates per and SHOULD require TLS 1.2 or higher.
4. Interpret - Parse the returned manifest. The manifest format and required fields are defined by the x402 core protocol specification . Implementations MUST support JSON format for manifests.
5. Negotiate - Proceed with the x402 payment handshake as defined by the x402 protocol, using the information obtained via HTTPS.

Multiple Record Handling

If multiple _x402 TXT records exist for a hostname, clients SHOULD attempt to fetch all discovered URLs unless local policy dictates otherwise. The order of TXT records in DNS responses is undefined; clients MUST NOT assume any preference based on record order. Clients MAY use the descriptor field to select among multiple options, or MAY present choices to users.

Caching

Clients SHOULD respect DNS TTL values for _x402 records and HTTP cache headers (Cache-Control, Expires) from manifest URLs. When manifest content changes more frequently than DNS records, operators SHOULD use appropriate HTTP cache directives rather than short DNS TTLs.

Operational Considerations

• The _x402 TXT record is expected to change infrequently and MAY have long TTLs (hours or days).
• Records MUST be published under each subdomain hostname where x402 resources are served (e.g., _x402.api.example.com for resources at api.example.com).
• Operators SHOULD sign their DNS zones with DNSSEC to prevent spoofing.
• Clients SHOULD prefer DNSSEC-validated responses when available.
• Only HTTPS URLs are permitted; clients MUST reject plain HTTP endpoints.

URL Path Conventions (Informative) While this specification does not mandate any particular URL structure, operators MAY choose to follow the well-known URI convention defined in by hosting discovery manifests at: /.well-known/x402 This path aligns with similar discovery mechanisms in other protocols (e.g., Nostr NIP-05, Lightning Address LUD-16) and may aid in automated discovery tools. However, any HTTPS URL specified in the TXT record is valid, and clients MUST NOT assume any particular path structure. Examples of valid discovery URLs include:

• https://example.com/.well-known/x402 (well-known convention)
• https://api.example.com/x402-manifest (custom path)
• https://cdn.example.com/payment-discovery (CDN-hosted)
• https://us.example.com/x402 (geographic routing)

Note: Use of /.well-known/x402 does not require IANA registration unless it becomes a widely-adopted convention requiring standardization.

Security Considerations The TXT discovery mechanism does not convey any sensitive or dynamic payment data. However, compromise of DNS responses could redirect clients to malicious payment endpoints. To mitigate this, clients SHOULD verify DNSSEC signatures and servers SHOULD serve discovery manifests over HTTPS with valid certificates per . Because TXT records are publicly visible, operators MUST NOT embed user-specific, time-sensitive, or confidential data in DNS records. The optional descriptor is informational only and MUST NOT be relied upon for authorization or routing.

Privacy Considerations DNS queries for _x402 records may reveal which services a client intends to use. This information may be logged by recursive resolvers and other DNS infrastructure. Privacy-conscious clients SHOULD consider using DNS-over-HTTPS or DNS-over-TLS to prevent disclosure of discovery queries to network observers. Operators should be aware that publishing _x402 TXT records publicly announces the availability of payment-required resources.

TLS Requirements Clients MUST validate TLS certificates when fetching manifest URLs. Certificate validation MUST follow and . Clients SHOULD require TLS version 1.2 or higher and SHOULD prefer TLS 1.3 when available. Clients MUST NOT proceed with payment negotiation if certificate validation fails.

IANA Considerations IANA is requested to add the following entry to the "Underscored and Globally Scoped DNS Node Names" registry defined in :

Node Name	RR Type	Reference
_x402	TXT	This document

References Normative References This RFC is the revised basic definition of The Domain Name System. It obsoletes RFC-882. This memo describes the domain style names and their used for host address look up and electronic mail forwarding. It discusses the clients and servers in the domain name system and the protocol used between them. This RFC is the revised specification of the protocol and format used in the implementation of the Domain Name System. It obsoletes RFC-883. This memo documents the details of the domain name client - server communication. In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. A Uniform Resource Identifier (URI) is a compact sequence of characters that identifies an abstract or physical resource. This specification defines the generic URI syntax and a process for resolving URI references that might be in relative form, along with guidelines and security considerations for the use of URIs on the Internet. The URI syntax defines a grammar that is a superset of all valid URIs, allowing an implementation to parse the common components of a URI reference without knowing the scheme-specific requirements of every possible identifier. This specification does not define a generative grammar for URIs; that task is performed by the individual specifications of each URI scheme. [STANDARDS-TRACK] RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. Formally, any DNS Resource Record (RR) may occur under any domain name. However, some services use an operational convention for defining specific interpretations of an RRset by locating the records in a DNS branch under the parent domain to which the RRset actually applies. The top of this subordinate branch is defined by a naming convention that uses a reserved node name, which begins with the underscore character (e.g., "_name"). The underscored naming construct defines a semantic scope for DNS record types that are associated with the parent domain above the underscored branch. This specification explores the nature of this DNS usage and defines the "Underscored and Globally Scoped DNS Node Names" registry with IANA. The purpose of this registry is to avoid collisions resulting from the use of the same underscored name for different services. The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. This document describes the overall architecture of HTTP, establishes common terminology, and defines aspects of the protocol that are shared by all versions. In this definition are core protocol elements, extensibility mechanisms, and the "http" and "https" Uniform Resource Identifier (URI) schemes. This document updates RFC 3864 and obsoletes RFCs 2818, 7231, 7232, 7233, 7235, 7538, 7615, 7694, and portions of 7230. Many application technologies enable secure communication between two entities by means of Transport Layer Security (TLS) with Internet Public Key Infrastructure using X.509 (PKIX) certificates. This document specifies procedures for representing and verifying the identity of application services in such interactions. This document obsoletes RFC 6125. Informative References This document describes the use of Transport Layer Security (TLS) to provide privacy for DNS. Encryption provided by TLS eliminates opportunities for eavesdropping and on-path tampering with DNS queries in the network, such as discussed in RFC 7626. In addition, this document specifies two usage profiles for DNS over TLS and provides advice on performance considerations to minimize overhead from using TCP and TLS with DNS. This document focuses on securing stub-to-recursive traffic, as per the charter of the DPRIVE Working Group. It does not prevent future applications of the protocol to recursive-to-authoritative traffic. This document defines a protocol for sending DNS queries and getting DNS responses over HTTPS. Each DNS query-response pair is mapped into an HTTP exchange. This memo defines a path prefix for "well-known locations", "/.well-known/", in selected Uniform Resource Identifier (URI) schemes. In doing so, it obsoletes RFC 5785 and updates the URI schemes defined in RFC 7230 to reserve that space. It also updates RFC 7595 to track URI schemes that support well-known URIs in their registry. Coinbase Developer Platform

Acknowledgments The author gratefully acknowledges the architects of the original Hypertext Transfer Protocol, including Tim Berners-Lee, Roy Fielding, and the early contributors to the HTTP/1.0 and HTTP/1.1 specifications, whose design of the status code system (1xx-5xx) provided the long-dormant foundation for "Payment Required" (HTTP 402). Recognition is also extended to Erik Reppel, Coinbase, and the broader x402.org team for their pioneering work in implementing and open-sourcing the modern x402 protocol, and for advancing the idea of agentic micropayments on the web. Their efforts to operationalize HTTP 402 payments have provided the context and inspiration for this DNS-based discovery mechanism.

Example Flow text 1. A client wishes to access https://api.example.com/data 2. It queries DNS for _x402.api.example.com TXT 3. DNS responds with: "v=x4021;descriptor=api;url=https://api.example.com/.well-known/x402" 4. Client performs GET https://api.example.com/.well-known/x402 and receives a JSON manifest enumerating payable API endpoints. 5. Client follows x402 negotiation per core spec, receives 402 Payment Required, completes settlement, and retries successfully.