From 2d2d419b25620a3aa868ddfe6439459d731baea8 Mon Sep 17 00:00:00 2001 From: EfeDurmaz16 Date: Fri, 15 May 2026 21:03:12 +0300 Subject: [PATCH] docs(spec): clarify HTTP payment required header --- specs/transports-v2/http.md | 5 +++++ specs/x402-specification-v2.md | 4 +++- 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/specs/transports-v2/http.md b/specs/transports-v2/http.md index a735f80032..ddba4c9425 100644 --- a/specs/transports-v2/http.md +++ b/specs/transports-v2/http.md @@ -11,6 +11,11 @@ The server indicates payment is required using the HTTP 402 "Payment Required" s **Mechanism**: HTTP 402 status code with `PAYMENT-REQUIRED` header **Data Format**: Base64-encoded `PaymentRequired` schema in header +The `PAYMENT-REQUIRED` header is the canonical HTTP transport location for the +`PaymentRequired` object. A response body may duplicate the same information +for humans or backward compatibility, but clients and crawlers must not depend +on the body alone for x402 protocol data. + **Example:** ```http diff --git a/specs/x402-specification-v2.md b/specs/x402-specification-v2.md index 470bb9a9ca..b3727597a5 100644 --- a/specs/x402-specification-v2.md +++ b/specs/x402-specification-v2.md @@ -69,7 +69,9 @@ This section defines the core data structures used in the x402 protocol. These a **5.1.1 JSON Payload** -When a resource server requires payment, it responds with a payment required signal and a JSON payload containing payment requirements. Example: +When a resource server requires payment, it responds with a payment required signal containing the `PaymentRequired` object. The transport defines where this object is carried. For HTTP, the canonical wire location is the base64-encoded `PAYMENT-REQUIRED` response header, not only the response body. See [HTTP Payment Required Signaling](./transports-v2/http.md#payment-required-signaling). + +Example `PaymentRequired` object: ```json {