Discovering x402 Resources via DNS TXT Records

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 11 May 2026.¶

Copyright Notice

Copyright (c) 2025 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 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 [RFC1034] [RFC1035], 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).¶

2. 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 [RFC2119] [RFC8174] 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").¶

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

4. 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 [RFC3986].¶

  • 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" ¶

5. 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 [RFC9110] 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 [X402]. 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.¶

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

7. 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 [RFC9110].¶

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

8. IANA Considerations

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

9. References

Appendix A. 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.¶

Appendix B. 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. ¶

Author's Address