HTTP 402 支付协议详解x402 如何激活预留状态码完成互联网原生支付【免费下载链接】x402A payments protocol for the internet. Built on HTTP.项目地址: https://gitcode.com/GitHub_Trending/x4/x402HTTP 402 Payment Required 是 HTTP 标准中一个被预定了近三十年却极少被真正使用的状态码。x402 协议将其激活作为互联网原生支付协议的核心信令服务器用 402 声明此资源需要付费并通过标准化请求头向客户端传递支付金额、币种、网络与收款地址。读完本文你将掌握 402 在 x402 V2 中的完整语义、PAYMENT-REQUIRED/PAYMENT-SIGNATURE/PAYMENT-RESPONSE三个核心请求头的格式与编解码方式以及客户端与服务器两端在实际源码中如何落地这一交互。HTTP 402 是什么为支付预留的标准状态码HTTP 402 是 RFC 7231 中定义的标准 HTTP 响应状态码语义为 Payment Required需要付款用于指示访问某个资源需要先完成支付。尽管它从 HTTP 协议诞生之初就被预留但由于缺乏统一的支付协议承载方在实际互联网服务中长期处于有名无实的状态。x402 正是围绕这一状态码构建的开放支付标准。在 x402 中HTTP 402 被激活后承担三项职责告知客户端买家或 AI Agent需要支付以标准状态码而非私有错误码发出信号任何 HTTP 客户端都能识别传达支付细节包括金额amount、币种/资产asset、网络标识network以及收款地址payTo等结构化信息提供程序化完成支付所需的信息客户端无需人工干预即可根据响应中的支付要求Payment Requirements自动构造支付载荷并重试请求。在 x402 协议架构中HTTP 只是众多传输层之一另有 MCP、A2A 等而 HTTP 402 正是 HTTP 传输层实现支付必需信令的载体。协议的 核心规范 将整个协议抽象为三个层次Types与传输层和支付方案无关的核心数据结构、Logic依赖具体支付方案与链的支付构造/校验逻辑、Representation支付数据如何通过具体传输层表达。HTTP 402 与三个请求头就是 HTTP 传输层中 Representation 的具体形态。为什么 x402 选择 HTTP 402x402 选择 HTTP 402 作为支付信令首要目的是实现免摩擦、API 原生的网络资源支付尤其面向以下场景机器对机器M2M支付例如 AI Agent 自主调用付费 API无需人工介入下单或转账流程按使用付费Pay-per-use模式例如按次计费的 API 调用、付费墙paywall保护的内容无账户、无传统支付轨道的小额支付客户端只需持有加密钱包不需要注册账号、管理凭证或建立会话。使用 402 状态码让 x402 协议天然保持Web 兼容性任何基于 HTTP 的服务Express.js、FastAPI、Hono、Next.js、Go net/http 等都可以在现有请求-响应模型上直接集成无需改造传输机制。正如 官方文档 所述x402 让任意 Web 服务可以在返回响应之前要求支付利用加密原生支付实现速度、隐私与效率上的优势。从完整流程看402 只是支付链路的起点。在 客户端/服务器交互 中一次典型交互包含六步客户端向服务器发起资源请求服务器以402 Payment Required响应并在PAYMENT-REQUIRED请求头中携带支付要求客户端根据支付要求构造支付载荷以 Base64 编码放入PAYMENT-SIGNATURE请求头后重试服务器本地校验或通过 facilitator 校验支付载荷服务器完成链上结算服务器返回资源成功或错误响应失败两种情况都通过PAYMENT-RESPONSE请求头返回结算详情。V2 的三个支付头协议的核心词汇表x402 V2 通过三个标准化 HTTP 请求头完成支付信息的全部通信HeaderDirectionDescriptionPAYMENT-REQUIREDServer → ClientBase64-encodedPaymentRequiredobjectPAYMENT-SIGNATUREClient → ServerBase64-encodedPaymentPayloadobjectPAYMENT-RESPONSEServer → ClientBase64-encodedSettlementResponseobjectPAYMENT-REQUIRED服务器声明支付要求该请求头由服务器在返回 402 状态码时附带内容是 Base64 编码的PaymentRequired对象包含可接受的支付方案scheme、价格price/amount、网络标识network与收款地址payTo等支付要求。客户端解码后即可知晓该资源如何付费。PAYMENT-SIGNATURE客户端证明已授权支付该请求头由客户端在收到 402 响应后、重试原请求时附带内容是 Base64 编码的PaymentPayload对象包含客户端选定的支付方式accepted字段、方案特定的支付数据payload字段如 EIP-3009 授权与 EIP-712 签名以此证明其已授权付款。PAYMENT-RESPONSE服务器回传结算结果该请求头由服务器在尝试结算后返回无论成功或失败都会附带内容是 Base64 编码的SettlementResponse对象。它向客户端提供关于支付结果的结构化反馈——例如success布尔值、交易哈希transaction、网络与付款人地址失败时则包含errorReason。为什么所有头部都使用 Base64 编码三个请求头的值都是有效的 Base64 编码 JSON 字符串。这一编码选择有两方面原因兼容性HTTP 头部的值不允许包含换行、引号等字符而 JSON 载荷中天然包含引号与花括号Base64 可将任意 JSON 字节安全地放入单个头部值健壮性避免不同 HTTP 实现、代理与中间件对 JSON 特殊字符的处理差异导致头部分割或转义问题。在 Python 实现的 HTTP 常量定义 中可以看到这三个头名的官方常量声明# HTTP Header Names PAYMENT_SIGNATURE_HEADER PAYMENT-SIGNATURE PAYMENT_REQUIRED_HEADER PAYMENT-REQUIRED PAYMENT_RESPONSE_HEADER PAYMENT-RESPONSE SETTLEMENT_OVERRIDES_HEADER Settlement-Overrides X_PAYMENT_HEADER X-PAYMENT # V1 legacy X_PAYMENT_RESPONSE_HEADER X-PAYMENT-RESPONSE # V1 legacy ACCESS_CONTROL_EXPOSE_HEADERS Access-Control-Expose-Headers # HTTP Status Codes HTTP_STATUS_PAYMENT_REQUIRED 402 # Default Facilitator URL DEFAULT_FACILITATOR_URL https://x402.org/facilitator同一文件中还定义了 V1 的旧请求头X-PAYMENT与X-PAYMENT-RESPONSE以及Access-Control-Expose-Headers——后者用于浏览器跨域场景下让前端 JavaScript 能够读取到这些自定义响应头。在 Go 实现的 HTTP 客户端 中请求头的编解码逻辑按协议版本自动分派func (c *x402HTTPClient) EncodePaymentSignatureHeader(payloadBytes []byte) (map[string]string, error) { // Detect version from bytes version, err : types.DetectVersion(payloadBytes) ... // Base64 encode the payload bytes encoded : base64.StdEncoding.EncodeToString(payloadBytes) switch version { case 2: return map[string]string{ PAYMENT-SIGNATURE: encoded, }, nil case 1: return map[string]string{ X-PAYMENT: encoded, }, nil ... }注意 Go 客户端对请求头名做了大写归一化后再读取strings.ToUpper(k)以兼容不同 HTTP 实现可能产生的大小写差异解析PAYMENT-REQUIRED时优先读取 V2 头部找不到时才回退到 V1 的响应体 JSON 格式。一次完整的 402 支付交互请求-响应示例下面基于 HTTP 传输规范 中的完整示例逐步还原一次支付交互的字节级细节。第 1 步服务器返回 402 与 PAYMENT-REQUIRED客户端请求受保护资源服务器判定未携带有效支付返回 402 状态码与PAYMENT-REQUIRED请求头HTTP/1.1 402 Payment Required Content-Type: application/json PAYMENT-REQUIRED: eyJ4NDAyVmVyc2lvbiI6MiwiZXJyb3IiOiJQQVlNRU5ULVNJR05BVFVSRSBoZWFkZXIgaXMgcmVxdWlyZWQiLCJyZXNvdXJjZSI6eyJ1cmwiOiJodHRwczovL2FwaS5leGFtcGxlLmNvbS9wcmVtaXVtLWRhdGEiLCJkZXNjcmlwdGlvbiI6IkFjY2VzcyB0byBwcmVtaXVtIG1hcmtldCBkYXRhIiwibWltZVR5cGUiOiJhcHBsaWNhdGlvbi9qc29uIn0sImFjY2VwdHMiOlt7InNjaGVtZSI6ImV4YWN0IiwibmV0d29yayI6ImVpcDE1NTo4NDUzMiIsImFtb3VudCI6IjEwMDAwIiwiYXNzZXQiOiIweDAzNkNiRDUzODQyYzU0MjY2MzRlNzkyOTU0MWVDMjMxOGYzZENGN2UiLCJwYXlUbyI6IjB4MjA5NjkzQmM2YWZjMEM1MzI4YkEzNkZhRjAzQzUxNEVGMzEyMjg3QyIsIm1heFRpbWVvdXRTZWNvbmRzIjo2MCwiZXh0cmEiOnsibmFtZSI6IlVTREMiLCJ2ZXJzaW9uIjoiMiJ9fV19 {}将该 Base64 字符串解码后得到结构化的PaymentRequired对象{ x402Version: 2, error: PAYMENT-SIGNATURE header is required, resource: { url: https://api.example.com/premium-data, description: Access to premium market data, mimeType: application/json }, accepts: [ { scheme: exact, network: eip155:84532, amount: 10000, asset: 0x036CbD53842c5426634e7929541eC2318f3dCF7e, payTo: 0x209693Bc6afc0C5328bA36FaF03C514EF312287C, maxTimeoutSeconds: 60, extra: { name: USDC, version: 2 } } ] }该 JSON 中各字段语义详见 核心规范 5.1 节字段类型说明x402Versionnumber协议版本标识V2 必须为 2errorstring解释为何要求支付的错误消息可选resourceobject描述受保护资源的ResourceInfo对象url、description、mimeTypeacceptsarray可接受的支付方式数组每个元素为一个PaymentRequirements对象extensionsobject协议扩展数据可选其中每个PaymentRequirements对象包含scheme支付方案标识如exact、networkCAIP-2 格式链标识如eip155:84532表示 Base Sepolia、amount以代币原子单位为计价的金额、asset代币合约地址或法币 ISO 4217 代码、payTo收款钱包地址或角色常量、maxTimeoutSeconds支付完成允许的最大时间、extra方案特定附加信息。第 2 步客户端携带 PAYMENT-SIGNATURE 重试客户端解码支付要求后构造支付载荷Base64 编码后放入PAYMENT-SIGNATURE请求头重试原请求POST /premium-data HTTP/1.1 Host: api.example.com PAYMENT-SIGNATURE: eyJ4NDAyVmVyc2lvbiI6MiwicmVzb3VyY2UiOnsidXJsIjoiaHR0cHM6Ly9hcGkuZXhhbXBsZS5jb20vcHJlbWl1bS1kYXRhIiwiZGVzY3JpcHRpb24iOiJBY2Nlc3MgdG8gcHJlbWl1bSBtYXJrZXQgZGF0YSIsIm1pbWVUeXBlIjoiYXBwbGljYXRpb24vanNvbiJ9LCJhY2NlcHRlZCI6eyJzY2hlbWUiOiJleGFjdCIsIm5ldHdvcmsiOiJlaXAxNTU6ODQ1MzIiLCJhbW91bnQiOiIxMDAwMCIsImFzc2V0IjoiMHgwMzZDYkQ1Mzg0MmM1NDI2NjM0ZTc5Mjk1NDFlQzIzMThmM2RDRjdlIiwicGF5VG8iOiIweDIwOTY5M0JjNmFmYzBDNTMyOGJBMzZGYUYwM0M1MTRFRjMxMjI4N0MiLCJtYXhUaW1lb3V0U2Vjb25kcyI6NjAsImV4dHJhIjp7Im5hbWUiOiJVU0RDIiwidmVyc2lvbiI6IjIifX0sInBheWxvYWQiOnsic2lnbmF0dXJlIjoiMHgyZDZhNzU4OGQ2YWNjYTUwNWNiZjBkOWE0YTIyN2UwYzUyYzZjMzQwMDhjOGU4OTg2YTEyODMyNTk3NjQxNzM2MDhhMmNlNjQ5NjY0MmUzNzdkNmRhOGRiYmY1ODM2ZTliZDE1MDkyZjllY2FiMDVkZWQzZDYyOTNhZjE0OGI1NzFjIiwiYXV0aG9yaXphdGlvbiI6eyJmcm9tIjoiMHg4NTdiMDY1MTlFOTFlM0E1NDUzODc5MWJEYmIwRTIyMzczZTM2YjY2IiwidG8iOiIweDIwOTY5M0JjNmFmYzBDNTMyOGJBMzZGYUYwM0M1MTRFRjMxMjI4N0MiLCJ2YWx1ZSI6IjEwMDAwIiwidmFsaWRBZnRlciI6IjE3NDA2NzIwODkiLCJ2YWxpZEJlZm9yZSI6IjE3NDA2NzIxNTQiLCJub25jZSI6IjB4ZjM3NDY2MTNjMmQ5MjBiNWZkYWJjMDg1NmYyYWViMmQ0Zjg4ZWU2MDM3YjhjYzVkMDRhNzFhNDQ2MmYxMzQ4MCJ9fX0 Content-Type: application/json { query: latest market data }解码后为PaymentPayload对象payload字段内含signatureEIP-712 签名与authorizationEIP-3009 授权参数from、to、value、validAfter、validBefore、nonce。validAfter/validBefore定义了授权的有效时间窗nonce是 32 字节随机数用于防重放攻击。第 3 步服务器返回 PAYMENT-RESPONSE 结算结果支付校验并完成链上结算后服务器返回资源内容并附带PAYMENT-RESPONSE请求头HTTP/1.1 200 OK Content-Type: application/json PAYMENT-RESPONSE: eyJzdWNjZXNzIjp0cnVlLCJ0cmFuc2FjdGlvbiI6IjB4MTIzNDU2Nzg5MGFiY2RlZjEyMzQ1Njc4OTBhYmNkZWYxMjM0NTY3ODkwYWJjZGVmMTIzNDU2Nzg5MGFiY2RlZiIsIm5ldHdvcmsiOiJlaXAxNTU6ODQ1MzIiLCJwYXllciI6IjB4ODU3YjA2NTE5RTkxZTNBNTQ1Mzg3OTFiRGJiMEUyMjM3M2UzNmI2NiJ9 { data: premium market data response, timestamp: 2024-01-15T10:30:00Z }解码后为SettlementResponsesuccess: true、transaction交易哈希、network、payer。若结算失败服务器仍返回PAYMENT-RESPONSE此时success: false且errorReason携带失败原因如insufficient_fundstransaction为空字符串。上图来自仓库 static/flow.png完整呈现了上述流程Client 发起请求 → Server 返回402 PAYMENT-REQUIRED→ Client 构造支付载荷并携带PAYMENT-SIGNATURE重试 → Server 通过可选的 Facilitator 调用POST /verify与POST /settle→ 交易上链确认后 Server 返回200 Settled。Facilitator 为可选组件所有逻辑步骤校验、结算也可由服务器自行完成facilitator.md 中详细描述了这一 12 步交互。客户端如何自动完成支付从 402 到重试对于普通 HTTP 客户端而言收到 402 后解码头部、构造载荷、重试请求这套流程应该被透明封装。Go 实现通过PaymentRoundTripper将支付处理嵌入 HTTP 传输层go/http/client.go// RoundTrip implements http.RoundTripper with V1/V2 version detection func (t *PaymentRoundTripper) RoundTrip(req *http.Request) (*http.Response, error) { // Get or initialize retry count for this request ... // Prevent infinite retry loops if retries 1 { t.retryCount.Delete(requestID) return nil, fmt.Errorf(payment retry limit exceeded) } // Make initial request resp, err : t.Transport.RoundTrip(req) ... // If not 402, return as-is if resp.StatusCode ! http.StatusPaymentRequired { t.retryCount.Delete(requestID) return resp, nil } ... }其核心逻辑是先发送原始请求若响应不是 402 则原样返回若收到 402则解析PAYMENT-REQUIRED头部 → 构造并签名支付载荷 → 通过PAYMENT-SIGNATURE头部重试。retryCount以请求为粒度限制重试次数防止意外进入无限重试循环。整个处理对上层业务代码透明开发者可以直接使用WrapHTTPClientWithPayment包装标准http.Client或以GetWithPayment、PostWithPayment、DoWithPayment等便捷方法发起带支付能力的请求go/http/http.go。服务器端如何发出 402框架集成实现服务器端负责在请求未携带有效支付时构造 402 响应。在 Python HTTP 服务实现 中x402HTTPResourceServer.process_http_request是异步框架FastAPI/Starlette的中间件入口其处理结果有三种语义no-payment-required路由无需支付直接放行payment-verified支付有效继续处理请求payment-error返回 402 响应。服务器支持动态定价与动态收款地址PaymentOption中的price与pay_to既可以是静态值也可以是回调函数异步框架同时支持 sync/async 回调每次请求时动态解析并构建PaymentRequirements。这是 402 语义落地的关键——同一个 402 响应中的金额与收款地址完全由服务器按请求上下文实时决定。对于浏览器场景Go 实现还提供了付费墙paywallHTML生成能力go/http/paywall.go当请求的Accept头为text/html时服务器不再返回纯 JSON 的 402而是返回一个内嵌 EVM/SVM 模板的 HTML 付费墙页面让人类用户可以通过钱包完成支付。PaywallBuilder将多个网络处理器EVMPaywallHandler、SVMPaywallHandler组合为统一的PaywallProvider按支付要求的网络类型分派到对应模板。错误处理402/400/500/200 的状态码映射HTTP 传输层将 x402 的协议级错误映射为标准的 HTTP 状态码见 HTTP 传输规范x402 ErrorHTTP StatusDescriptionPayment Required402访问资源需要支付Invalid Payment400支付载荷或支付要求格式错误Payment Failed402支付校验或结算失败Server Error500支付处理过程中的服务器内部错误Success200支付校验并结算成功值得注意的细节是支付失败如余额不足同样以 402 返回但会携带PAYMENT-RESPONSE请求头说明失败原因如insufficient_funds从而与首次请求未携带支付的 402携带PAYMENT-REQUIRED在语义上区分开。协议还定义了细粒度的错误码例如invalid_exact_evm_payload_signature签名无效、invalid_exact_evm_payload_authorization_valid_before授权已过期、invalid_network网络不支持等帮助客户端精确诊断失败原因详见 核心规范第 9 节。从 V1 到 V2 的演化头部命名与兼容在协议 V1 时代支付信息通过X-PAYMENT与X-PAYMENT-RESPONSE请求头传递且部分信息承载于响应体 JSON 中。V2 将其重构为语义化的三个标准化头部PAYMENT-REQUIRED、PAYMENT-SIGNATURE、PAYMENT-RESPONSE并引入了 CAIP-2 网络标识如eip155:8453表示 Base 主网、PaymentRequired/PaymentPayload结构拆分以及扩展extensions支持。从实现角度看各语言 SDK 都保留了向后兼容能力Go 客户端的头部编码按载荷版本自动选择PAYMENT-SIGNATURE或X-PAYMENT解析PAYMENT-REQUIRED失败时回退到 V1 响应体格式Python 常量定义中同样保留X-PAYMENT/X-PAYMENT-RESPONSE作为 V1 legacy。这意味着同一套客户端库可以同时服务 V1 与 V2 服务器。总结HTTP 402 是 x402 协议的基石。它在 x402 中被赋予了三重职责信号以标准状态码告知客户端需要支付沟通通过PAYMENT-REQUIRED请求头传达金额、币种、网络与收款地址等必要支付细节集成无缝融入标准 HTTP 工作流客户端收到 402 后携带PAYMENT-SIGNATURE重试服务器结算后以PAYMENT-RESPONSE回传结果。三个 Base64 编码的 JSON 请求头构成了 x402 V2 在 HTTP 传输层的完整词汇表配合 核心规范 定义的PaymentRequired、PaymentPayload、SettlementResponse数据结构以及 客户端/服务器职责、Facilitator 校验与结算接口/verify、/settlex402 实现了免账户、免凭证、机器可读的互联网原生支付。无论你是想为自己的 API 增加按次付费能力还是让 AI Agent 具备自主支付能力HTTP 402 都是理解与接入 x402 的第一站。【免费下载链接】x402A payments protocol for the internet. Built on HTTP.项目地址: https://gitcode.com/GitHub_Trending/x4/x402创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
HTTP 402 支付协议详解：x402 如何激活“预留状态码“完成互联网原生支付
HTTP 402 支付协议详解x402 如何激活预留状态码完成互联网原生支付【免费下载链接】x402A payments protocol for the internet. Built on HTTP.项目地址: https://gitcode.com/GitHub_Trending/x4/x402HTTP 402 Payment Required 是 HTTP 标准中一个被预定了近三十年却极少被真正使用的状态码。x402 协议将其激活作为互联网原生支付协议的核心信令服务器用 402 声明此资源需要付费并通过标准化请求头向客户端传递支付金额、币种、网络与收款地址。读完本文你将掌握 402 在 x402 V2 中的完整语义、PAYMENT-REQUIRED/PAYMENT-SIGNATURE/PAYMENT-RESPONSE三个核心请求头的格式与编解码方式以及客户端与服务器两端在实际源码中如何落地这一交互。HTTP 402 是什么为支付预留的标准状态码HTTP 402 是 RFC 7231 中定义的标准 HTTP 响应状态码语义为 Payment Required需要付款用于指示访问某个资源需要先完成支付。尽管它从 HTTP 协议诞生之初就被预留但由于缺乏统一的支付协议承载方在实际互联网服务中长期处于有名无实的状态。x402 正是围绕这一状态码构建的开放支付标准。在 x402 中HTTP 402 被激活后承担三项职责告知客户端买家或 AI Agent需要支付以标准状态码而非私有错误码发出信号任何 HTTP 客户端都能识别传达支付细节包括金额amount、币种/资产asset、网络标识network以及收款地址payTo等结构化信息提供程序化完成支付所需的信息客户端无需人工干预即可根据响应中的支付要求Payment Requirements自动构造支付载荷并重试请求。在 x402 协议架构中HTTP 只是众多传输层之一另有 MCP、A2A 等而 HTTP 402 正是 HTTP 传输层实现支付必需信令的载体。协议的 核心规范 将整个协议抽象为三个层次Types与传输层和支付方案无关的核心数据结构、Logic依赖具体支付方案与链的支付构造/校验逻辑、Representation支付数据如何通过具体传输层表达。HTTP 402 与三个请求头就是 HTTP 传输层中 Representation 的具体形态。为什么 x402 选择 HTTP 402x402 选择 HTTP 402 作为支付信令首要目的是实现免摩擦、API 原生的网络资源支付尤其面向以下场景机器对机器M2M支付例如 AI Agent 自主调用付费 API无需人工介入下单或转账流程按使用付费Pay-per-use模式例如按次计费的 API 调用、付费墙paywall保护的内容无账户、无传统支付轨道的小额支付客户端只需持有加密钱包不需要注册账号、管理凭证或建立会话。使用 402 状态码让 x402 协议天然保持Web 兼容性任何基于 HTTP 的服务Express.js、FastAPI、Hono、Next.js、Go net/http 等都可以在现有请求-响应模型上直接集成无需改造传输机制。正如 官方文档 所述x402 让任意 Web 服务可以在返回响应之前要求支付利用加密原生支付实现速度、隐私与效率上的优势。从完整流程看402 只是支付链路的起点。在 客户端/服务器交互 中一次典型交互包含六步客户端向服务器发起资源请求服务器以402 Payment Required响应并在PAYMENT-REQUIRED请求头中携带支付要求客户端根据支付要求构造支付载荷以 Base64 编码放入PAYMENT-SIGNATURE请求头后重试服务器本地校验或通过 facilitator 校验支付载荷服务器完成链上结算服务器返回资源成功或错误响应失败两种情况都通过PAYMENT-RESPONSE请求头返回结算详情。V2 的三个支付头协议的核心词汇表x402 V2 通过三个标准化 HTTP 请求头完成支付信息的全部通信HeaderDirectionDescriptionPAYMENT-REQUIREDServer → ClientBase64-encodedPaymentRequiredobjectPAYMENT-SIGNATUREClient → ServerBase64-encodedPaymentPayloadobjectPAYMENT-RESPONSEServer → ClientBase64-encodedSettlementResponseobjectPAYMENT-REQUIRED服务器声明支付要求该请求头由服务器在返回 402 状态码时附带内容是 Base64 编码的PaymentRequired对象包含可接受的支付方案scheme、价格price/amount、网络标识network与收款地址payTo等支付要求。客户端解码后即可知晓该资源如何付费。PAYMENT-SIGNATURE客户端证明已授权支付该请求头由客户端在收到 402 响应后、重试原请求时附带内容是 Base64 编码的PaymentPayload对象包含客户端选定的支付方式accepted字段、方案特定的支付数据payload字段如 EIP-3009 授权与 EIP-712 签名以此证明其已授权付款。PAYMENT-RESPONSE服务器回传结算结果该请求头由服务器在尝试结算后返回无论成功或失败都会附带内容是 Base64 编码的SettlementResponse对象。它向客户端提供关于支付结果的结构化反馈——例如success布尔值、交易哈希transaction、网络与付款人地址失败时则包含errorReason。为什么所有头部都使用 Base64 编码三个请求头的值都是有效的 Base64 编码 JSON 字符串。这一编码选择有两方面原因兼容性HTTP 头部的值不允许包含换行、引号等字符而 JSON 载荷中天然包含引号与花括号Base64 可将任意 JSON 字节安全地放入单个头部值健壮性避免不同 HTTP 实现、代理与中间件对 JSON 特殊字符的处理差异导致头部分割或转义问题。在 Python 实现的 HTTP 常量定义 中可以看到这三个头名的官方常量声明# HTTP Header Names PAYMENT_SIGNATURE_HEADER PAYMENT-SIGNATURE PAYMENT_REQUIRED_HEADER PAYMENT-REQUIRED PAYMENT_RESPONSE_HEADER PAYMENT-RESPONSE SETTLEMENT_OVERRIDES_HEADER Settlement-Overrides X_PAYMENT_HEADER X-PAYMENT # V1 legacy X_PAYMENT_RESPONSE_HEADER X-PAYMENT-RESPONSE # V1 legacy ACCESS_CONTROL_EXPOSE_HEADERS Access-Control-Expose-Headers # HTTP Status Codes HTTP_STATUS_PAYMENT_REQUIRED 402 # Default Facilitator URL DEFAULT_FACILITATOR_URL https://x402.org/facilitator同一文件中还定义了 V1 的旧请求头X-PAYMENT与X-PAYMENT-RESPONSE以及Access-Control-Expose-Headers——后者用于浏览器跨域场景下让前端 JavaScript 能够读取到这些自定义响应头。在 Go 实现的 HTTP 客户端 中请求头的编解码逻辑按协议版本自动分派func (c *x402HTTPClient) EncodePaymentSignatureHeader(payloadBytes []byte) (map[string]string, error) { // Detect version from bytes version, err : types.DetectVersion(payloadBytes) ... // Base64 encode the payload bytes encoded : base64.StdEncoding.EncodeToString(payloadBytes) switch version { case 2: return map[string]string{ PAYMENT-SIGNATURE: encoded, }, nil case 1: return map[string]string{ X-PAYMENT: encoded, }, nil ... }注意 Go 客户端对请求头名做了大写归一化后再读取strings.ToUpper(k)以兼容不同 HTTP 实现可能产生的大小写差异解析PAYMENT-REQUIRED时优先读取 V2 头部找不到时才回退到 V1 的响应体 JSON 格式。一次完整的 402 支付交互请求-响应示例下面基于 HTTP 传输规范 中的完整示例逐步还原一次支付交互的字节级细节。第 1 步服务器返回 402 与 PAYMENT-REQUIRED客户端请求受保护资源服务器判定未携带有效支付返回 402 状态码与PAYMENT-REQUIRED请求头HTTP/1.1 402 Payment Required Content-Type: application/json PAYMENT-REQUIRED: eyJ4NDAyVmVyc2lvbiI6MiwiZXJyb3IiOiJQQVlNRU5ULVNJR05BVFVSRSBoZWFkZXIgaXMgcmVxdWlyZWQiLCJyZXNvdXJjZSI6eyJ1cmwiOiJodHRwczovL2FwaS5leGFtcGxlLmNvbS9wcmVtaXVtLWRhdGEiLCJkZXNjcmlwdGlvbiI6IkFjY2VzcyB0byBwcmVtaXVtIG1hcmtldCBkYXRhIiwibWltZVR5cGUiOiJhcHBsaWNhdGlvbi9qc29uIn0sImFjY2VwdHMiOlt7InNjaGVtZSI6ImV4YWN0IiwibmV0d29yayI6ImVpcDE1NTo4NDUzMiIsImFtb3VudCI6IjEwMDAwIiwiYXNzZXQiOiIweDAzNkNiRDUzODQyYzU0MjY2MzRlNzkyOTU0MWVDMjMxOGYzZENGN2UiLCJwYXlUbyI6IjB4MjA5NjkzQmM2YWZjMEM1MzI4YkEzNkZhRjAzQzUxNEVGMzEyMjg3QyIsIm1heFRpbWVvdXRTZWNvbmRzIjo2MCwiZXh0cmEiOnsibmFtZSI6IlVTREMiLCJ2ZXJzaW9uIjoiMiJ9fV19 {}将该 Base64 字符串解码后得到结构化的PaymentRequired对象{ x402Version: 2, error: PAYMENT-SIGNATURE header is required, resource: { url: https://api.example.com/premium-data, description: Access to premium market data, mimeType: application/json }, accepts: [ { scheme: exact, network: eip155:84532, amount: 10000, asset: 0x036CbD53842c5426634e7929541eC2318f3dCF7e, payTo: 0x209693Bc6afc0C5328bA36FaF03C514EF312287C, maxTimeoutSeconds: 60, extra: { name: USDC, version: 2 } } ] }该 JSON 中各字段语义详见 核心规范 5.1 节字段类型说明x402Versionnumber协议版本标识V2 必须为 2errorstring解释为何要求支付的错误消息可选resourceobject描述受保护资源的ResourceInfo对象url、description、mimeTypeacceptsarray可接受的支付方式数组每个元素为一个PaymentRequirements对象extensionsobject协议扩展数据可选其中每个PaymentRequirements对象包含scheme支付方案标识如exact、networkCAIP-2 格式链标识如eip155:84532表示 Base Sepolia、amount以代币原子单位为计价的金额、asset代币合约地址或法币 ISO 4217 代码、payTo收款钱包地址或角色常量、maxTimeoutSeconds支付完成允许的最大时间、extra方案特定附加信息。第 2 步客户端携带 PAYMENT-SIGNATURE 重试客户端解码支付要求后构造支付载荷Base64 编码后放入PAYMENT-SIGNATURE请求头重试原请求POST /premium-data HTTP/1.1 Host: api.example.com PAYMENT-SIGNATURE: eyJ4NDAyVmVyc2lvbiI6MiwicmVzb3VyY2UiOnsidXJsIjoiaHR0cHM6Ly9hcGkuZXhhbXBsZS5jb20vcHJlbWl1bS1kYXRhIiwiZGVzY3JpcHRpb24iOiJBY2Nlc3MgdG8gcHJlbWl1bSBtYXJrZXQgZGF0YSIsIm1pbWVUeXBlIjoiYXBwbGljYXRpb24vanNvbiJ9LCJhY2NlcHRlZCI6eyJzY2hlbWUiOiJleGFjdCIsIm5ldHdvcmsiOiJlaXAxNTU6ODQ1MzIiLCJhbW91bnQiOiIxMDAwMCIsImFzc2V0IjoiMHgwMzZDYkQ1Mzg0MmM1NDI2NjM0ZTc5Mjk1NDFlQzIzMThmM2RDRjdlIiwicGF5VG8iOiIweDIwOTY5M0JjNmFmYzBDNTMyOGJBMzZGYUYwM0M1MTRFRjMxMjI4N0MiLCJtYXhUaW1lb3V0U2Vjb25kcyI6NjAsImV4dHJhIjp7Im5hbWUiOiJVU0RDIiwidmVyc2lvbiI6IjIifX0sInBheWxvYWQiOnsic2lnbmF0dXJlIjoiMHgyZDZhNzU4OGQ2YWNjYTUwNWNiZjBkOWE0YTIyN2UwYzUyYzZjMzQwMDhjOGU4OTg2YTEyODMyNTk3NjQxNzM2MDhhMmNlNjQ5NjY0MmUzNzdkNmRhOGRiYmY1ODM2ZTliZDE1MDkyZjllY2FiMDVkZWQzZDYyOTNhZjE0OGI1NzFjIiwiYXV0aG9yaXphdGlvbiI6eyJmcm9tIjoiMHg4NTdiMDY1MTlFOTFlM0E1NDUzODc5MWJEYmIwRTIyMzczZTM2YjY2IiwidG8iOiIweDIwOTY5M0JjNmFmYzBDNTMyOGJBMzZGYUYwM0M1MTRFRjMxMjI4N0MiLCJ2YWx1ZSI6IjEwMDAwIiwidmFsaWRBZnRlciI6IjE3NDA2NzIwODkiLCJ2YWxpZEJlZm9yZSI6IjE3NDA2NzIxNTQiLCJub25jZSI6IjB4ZjM3NDY2MTNjMmQ5MjBiNWZkYWJjMDg1NmYyYWViMmQ0Zjg4ZWU2MDM3YjhjYzVkMDRhNzFhNDQ2MmYxMzQ4MCJ9fX0 Content-Type: application/json { query: latest market data }解码后为PaymentPayload对象payload字段内含signatureEIP-712 签名与authorizationEIP-3009 授权参数from、to、value、validAfter、validBefore、nonce。validAfter/validBefore定义了授权的有效时间窗nonce是 32 字节随机数用于防重放攻击。第 3 步服务器返回 PAYMENT-RESPONSE 结算结果支付校验并完成链上结算后服务器返回资源内容并附带PAYMENT-RESPONSE请求头HTTP/1.1 200 OK Content-Type: application/json PAYMENT-RESPONSE: eyJzdWNjZXNzIjp0cnVlLCJ0cmFuc2FjdGlvbiI6IjB4MTIzNDU2Nzg5MGFiY2RlZjEyMzQ1Njc4OTBhYmNkZWYxMjM0NTY3ODkwYWJjZGVmMTIzNDU2Nzg5MGFiY2RlZiIsIm5ldHdvcmsiOiJlaXAxNTU6ODQ1MzIiLCJwYXllciI6IjB4ODU3YjA2NTE5RTkxZTNBNTQ1Mzg3OTFiRGJiMEUyMjM3M2UzNmI2NiJ9 { data: premium market data response, timestamp: 2024-01-15T10:30:00Z }解码后为SettlementResponsesuccess: true、transaction交易哈希、network、payer。若结算失败服务器仍返回PAYMENT-RESPONSE此时success: false且errorReason携带失败原因如insufficient_fundstransaction为空字符串。上图来自仓库 static/flow.png完整呈现了上述流程Client 发起请求 → Server 返回402 PAYMENT-REQUIRED→ Client 构造支付载荷并携带PAYMENT-SIGNATURE重试 → Server 通过可选的 Facilitator 调用POST /verify与POST /settle→ 交易上链确认后 Server 返回200 Settled。Facilitator 为可选组件所有逻辑步骤校验、结算也可由服务器自行完成facilitator.md 中详细描述了这一 12 步交互。客户端如何自动完成支付从 402 到重试对于普通 HTTP 客户端而言收到 402 后解码头部、构造载荷、重试请求这套流程应该被透明封装。Go 实现通过PaymentRoundTripper将支付处理嵌入 HTTP 传输层go/http/client.go// RoundTrip implements http.RoundTripper with V1/V2 version detection func (t *PaymentRoundTripper) RoundTrip(req *http.Request) (*http.Response, error) { // Get or initialize retry count for this request ... // Prevent infinite retry loops if retries 1 { t.retryCount.Delete(requestID) return nil, fmt.Errorf(payment retry limit exceeded) } // Make initial request resp, err : t.Transport.RoundTrip(req) ... // If not 402, return as-is if resp.StatusCode ! http.StatusPaymentRequired { t.retryCount.Delete(requestID) return resp, nil } ... }其核心逻辑是先发送原始请求若响应不是 402 则原样返回若收到 402则解析PAYMENT-REQUIRED头部 → 构造并签名支付载荷 → 通过PAYMENT-SIGNATURE头部重试。retryCount以请求为粒度限制重试次数防止意外进入无限重试循环。整个处理对上层业务代码透明开发者可以直接使用WrapHTTPClientWithPayment包装标准http.Client或以GetWithPayment、PostWithPayment、DoWithPayment等便捷方法发起带支付能力的请求go/http/http.go。服务器端如何发出 402框架集成实现服务器端负责在请求未携带有效支付时构造 402 响应。在 Python HTTP 服务实现 中x402HTTPResourceServer.process_http_request是异步框架FastAPI/Starlette的中间件入口其处理结果有三种语义no-payment-required路由无需支付直接放行payment-verified支付有效继续处理请求payment-error返回 402 响应。服务器支持动态定价与动态收款地址PaymentOption中的price与pay_to既可以是静态值也可以是回调函数异步框架同时支持 sync/async 回调每次请求时动态解析并构建PaymentRequirements。这是 402 语义落地的关键——同一个 402 响应中的金额与收款地址完全由服务器按请求上下文实时决定。对于浏览器场景Go 实现还提供了付费墙paywallHTML生成能力go/http/paywall.go当请求的Accept头为text/html时服务器不再返回纯 JSON 的 402而是返回一个内嵌 EVM/SVM 模板的 HTML 付费墙页面让人类用户可以通过钱包完成支付。PaywallBuilder将多个网络处理器EVMPaywallHandler、SVMPaywallHandler组合为统一的PaywallProvider按支付要求的网络类型分派到对应模板。错误处理402/400/500/200 的状态码映射HTTP 传输层将 x402 的协议级错误映射为标准的 HTTP 状态码见 HTTP 传输规范x402 ErrorHTTP StatusDescriptionPayment Required402访问资源需要支付Invalid Payment400支付载荷或支付要求格式错误Payment Failed402支付校验或结算失败Server Error500支付处理过程中的服务器内部错误Success200支付校验并结算成功值得注意的细节是支付失败如余额不足同样以 402 返回但会携带PAYMENT-RESPONSE请求头说明失败原因如insufficient_funds从而与首次请求未携带支付的 402携带PAYMENT-REQUIRED在语义上区分开。协议还定义了细粒度的错误码例如invalid_exact_evm_payload_signature签名无效、invalid_exact_evm_payload_authorization_valid_before授权已过期、invalid_network网络不支持等帮助客户端精确诊断失败原因详见 核心规范第 9 节。从 V1 到 V2 的演化头部命名与兼容在协议 V1 时代支付信息通过X-PAYMENT与X-PAYMENT-RESPONSE请求头传递且部分信息承载于响应体 JSON 中。V2 将其重构为语义化的三个标准化头部PAYMENT-REQUIRED、PAYMENT-SIGNATURE、PAYMENT-RESPONSE并引入了 CAIP-2 网络标识如eip155:8453表示 Base 主网、PaymentRequired/PaymentPayload结构拆分以及扩展extensions支持。从实现角度看各语言 SDK 都保留了向后兼容能力Go 客户端的头部编码按载荷版本自动选择PAYMENT-SIGNATURE或X-PAYMENT解析PAYMENT-REQUIRED失败时回退到 V1 响应体格式Python 常量定义中同样保留X-PAYMENT/X-PAYMENT-RESPONSE作为 V1 legacy。这意味着同一套客户端库可以同时服务 V1 与 V2 服务器。总结HTTP 402 是 x402 协议的基石。它在 x402 中被赋予了三重职责信号以标准状态码告知客户端需要支付沟通通过PAYMENT-REQUIRED请求头传达金额、币种、网络与收款地址等必要支付细节集成无缝融入标准 HTTP 工作流客户端收到 402 后携带PAYMENT-SIGNATURE重试服务器结算后以PAYMENT-RESPONSE回传结果。三个 Base64 编码的 JSON 请求头构成了 x402 V2 在 HTTP 传输层的完整词汇表配合 核心规范 定义的PaymentRequired、PaymentPayload、SettlementResponse数据结构以及 客户端/服务器职责、Facilitator 校验与结算接口/verify、/settlex402 实现了免账户、免凭证、机器可读的互联网原生支付。无论你是想为自己的 API 增加按次付费能力还是让 AI Agent 具备自主支付能力HTTP 402 都是理解与接入 x402 的第一站。【免费下载链接】x402A payments protocol for the internet. Built on HTTP.项目地址: https://gitcode.com/GitHub_Trending/x4/x402创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考