企业官网建设流程全解析

x402 A2A 传输层实现指南：基于 JSON-RPC 与任务状态的 Agent 间支付协议规范

【免费下载链接】x402A payments protocol for the internet. Built on HTTP.项目地址: https://gitcode.com/GitHub_Trending/x4/x402

x402 是一个构建在 HTTP 之上的互联网支付协议，v2 规范在保持核心传输无关（transport-agnostic）设计的同时，定义了多套传输层实现，其中 A2A（Agent-to-Agent Protocol）传输让 AI Agent 能够以链上加密货币结算的方式相互付费。本篇技术文章以 specs/transports-v2/a2a.md 为核心骨架，完整讲解 A2A 传输的三类支付消息（支付要求、支付载荷、结算回执）、六个支付状态与任务状态的映射关系、错误处理规则以及扩展声明与激活机制；读完后你可以直接按照规范构造 A2A JSON-RPC 消息，理解 x402 v2 各 schema 在 A2A 元数据中的落位方式，并与 HTTP 传输、核心 v2 规范 相互印证。

1. 为什么 A2A 传输需要独立的规范

x402 v2 的核心架构将协议拆分为三层（见 specs/x402-specification-v2.md 的 Architecture 一节）：

1. Types：核心数据结构（PaymentRequired、PaymentPayload、SettlementResponse），与传输机制和支付方案均无关；
2. Logic：依赖支付方案（如exact）与网络（EVM、Solana）的支付构造与验证逻辑；
3. Representation：支付数据如何传输与信令，取决于具体传输机制（HTTP、MCP、A2A）。

A2A 传输正是第三层的实现：它通过 A2A 协议的JSON-RPC 消息和基于任务（task）的状态管理承载 x402 支付流程，使 Agent 能在 A2A 框架内借助任务生命周期（task lifecycle）与元数据（metadata）系统完成支付协调。规范开篇即点明其定位：

The A2A transport implements x402 payment flows over the Agent-to-Agent protocol using JSON-RPC messages and task-based state management.

与 HTTP 传输用 402 状态码和 base64 头部（PAYMENT-REQUIRED/PAYMENT-SIGNATURE/PAYMENT-RESPONSE）做信令不同，A2A 传输把支付信令放进消息元数据字段，并用A2A 任务状态表达支付进展。从源码结构看，当前仓库的 TS / Go / Python SDK 均已实现 HTTP 与 MCP 传输（如 typescript/packages、go/http、python/x402/http），A2A 传输则由外部的 a2a-x402 扩展规范承载——这也解释了为什么本规范以纯协议文档形式给出，而不附带仓库内的 A2A 实现代码。

另外需要注意 v2 与 v1 的差异：本仓库同时收录了 specs/transports-v1/a2a.md，v1 使用network: "base"这类扁平字段并把resource内嵌在accepts的每项中；v2 则采用 CAIP-2 网络标识（eip155:8453）、独立的ResourceInfo对象以及PaymentPayload.accepted结构。下文均以 v2 为准。

2. 支付要求信令：input-required 任务状态 + 元数据

A2A 传输中，服务端 Agent 通过 A2A 任务状态input-required配合支付元数据来指示“需要支付”：

• 信令机制：任务state: "input-required"+ 消息元数据x402.payment.status: "payment-required"；
• 数据格式：PaymentRequiredschema，放在元数据字段x402.payment.required中。

完整的 JSON-RPC 响应示例（规范原文）：

{ "jsonrpc": "2.0", "id": "req-001", "result": { "kind": "task", "id": "task-123", "status": { "state": "input-required", "message": { "kind": "message", "role": "agent", "parts": [ { "kind": "text", "text": "Payment is required to generate the image." } ], "metadata": { "x402.payment.status": "payment-required", "x402.payment.required": { "x402Version": 2, "error": "Payment required to access this resource", "resource": { "url": "https://api.example.com/generate-image", "description": "Generate an image", "mimeType": "image/png" }, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "amount": "48240000", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bda02913", "payTo": "0xServerWalletAddressHere", "maxTimeoutSeconds": 600, "extra": { "name": "USD Coin", "version": "2" } } ] } } } } } }

对照核心规范 5.1 节的PaymentRequired字段表，可以逐字段解读该元数据对象：

其中accepts数组内每个PaymentRequirements对象的关键字段：

ResourceInfo对象包含url（必填，受保护资源 URL）、description（可选）、mimeType（可选，期望响应的 MIME 类型）。示例中mimeType为image/png，与服务端文本部分 "Payment is required to generate the image." 呼应，展示了一个图像生成 Agent 的收费场景。

要点：与 HTTP 传输不同，A2A 不需要任何 base64 编码——PaymentRequired以原生 JSON 形式直接挂在metadata["x402.payment.required"]下，人类可读且便于 Agent 解析；parts中的自然语言文本则面向人类或供上层 LLM 理解。

3. 支付载荷传输：message/send + taskId 关联

客户端使用 A2A 消息元数据携带支付数据，并用taskId与服务端此前的任务做关联：

• 信令机制：消息元数据包含x402.payment.payload字段，并通过taskId关联任务；
• 数据格式：PaymentPayloadschema，放在元数据字段x402.payment.payload中。

客户端通过message/send方法发起 JSON-RPC 请求（规范原文示例）：

{ "jsonrpc": "2.0", "method": "message/send", "id": "req-003", "params": { "message": { "taskId": "task-123", "role": "user", "parts": [ { "kind": "text", "text": "Here is the payment authorization." } ], "metadata": { "x402.payment.status": "payment-submitted", "x402.payment.payload": { "x402Version": 2, "resource": { "url": "https://api.example.com/generate-image", "description": "Generate an image", "mimeType": "image/png" }, "accepted": { "scheme": "exact", "network": "eip155:8453", "amount": "48240000", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bda02913", "payTo": "0xServerWalletAddressHere", "maxTimeoutSeconds": 600, "extra": { "name": "USD Coin", "version": "2" } }, "payload": { "signature": "0x2d6a7588d6acca505cbf0d9a4a227e0c52c6c34008c8e8986a1283259764173608a2ce6496642e377d6da8dbbf5836e9bd15092f9ecab05ded3d6293af148b571c", "authorization": { "from": "0x857b06519E91e3A54538791bDbb0E22373e36b66", "to": "0xServerWalletAddressHere", "value": "48240000", "validAfter": "1740672089", "validBefore": "1740672154", "nonce": "0xf3746613c2d920b5fdabc0856f2aeb2d4f88ee6037b8cc5d04a71a4462f13480" } } } } } } }

结合 v2 规范 5.2 节的PaymentPayload字段表，其结构要点：

• x402Version（必填）：协议版本；
• resource（可选）：ResourceInfo对象，回显所访问资源，便于服务端与支付要求中的资源做一致性核对；
• accepted（必填）：客户端从服务端accepts中选定的一份PaymentRequirements原样回传——这是 A2A 传输与 v1 的关键差异之一，v1 直接在 payload 顶层平铺scheme/network等字段，v2 将其封装为accepted对象；
• payload（必填）：方案特定的支付数据。对于exact+ EVM 组合，按核心规范 5.2.2 字段表包含两个字段：
  • signature：对authorization的 EIP-712 签名；
  • authorization：EIP-3009transferWithAuthorization授权对象，字段为from（付款方地址）、to（收款地址）、value（原子单位金额）、validAfter/validBefore（Unix 时间戳构成的有效时间窗）、nonce（32 字节随机数，防重放）。
• extensions（可选）：客户端回显服务端下发的扩展信息，可按需追加但不可删改既有 info（见核心规范 5.1.2 Extensions 说明）。

taskId（示例中task-123）承担请求-支付关联的职责：A2A 是任务驱动模型，客户端把支付载荷挂回原任务，服务端即可将这笔授权与该任务此前下发的PaymentRequired对应起来。同时元数据中的x402.payment.status: "payment-submitted"声明了当前支付状态，供服务端识别消息语义。

底层原理佐证：authorization各字段的安全作用在核心规范第 10 节（Security Considerations）中给出了系统说明——EIP-3009 的 32 字节nonce防止重放（智能合约层面天然拒绝 nonce 复用）、validAfter/validBefore时间窗限制授权生命周期、签名确保授权由付款方本人发起。Facilitator 在验证时执行六步检查（签名验证、余额检查、金额精确匹配、时间窗检查、参数匹配、交易模拟），这些检查的失败会分别映射为第 5 节所述的不同支付状态与错误码。

4. 结算回执投递：任务状态更新 + receipts 元数据

服务端通过任务状态更新投递结算结果，元数据字段x402.payment.receipts承载SettlementResponseschema 数组。

4.1 成功结算

{ "jsonrpc": "2.0", "id": "req-003", "result": { "kind": "task", "id": "task-123", "status": { "state": "completed", "message": { "kind": "message", "role": "agent", "parts": [ { "kind": "text", "text": "Payment successful. Your image is ready." } ], "metadata": { "x402.payment.status": "payment-completed", "x402.payment.receipts": [ { "success": true, "transaction": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", "network": "eip155:8453", "payer": "0x857b06519E91e3A54538791bDbb0E22373e36b66" } ] } } }, "artifacts": [ { "kind": "image", "name": "generated-image.png", "mimeType": "image/png", "data": "base64-encoded-image-data" } ] } }

对照核心规范 5.3 节SettlementResponse字段表：success（必填，布尔）表示结算是否成功；transaction（必填，失败时为空字符串而非缺省）；network（必填，CAIP-2 格式）；errorReason（失败时给出）；payer（可选）；amount（可选，实际结算金额）；extensions（可选）。

注意result中的artifacts数组：这是 A2A 特有的能力——支付成功后，Agent 直接在任务结果里附带交付物（示例为 base64 编码的 PNG 图像），使“付费 → 交付”在一次任务状态更新中闭环。

4.2 支付失败

{ "jsonrpc": "2.0", "id": "req-003", "result": { "kind": "task", "id": "task-123", "status": { "state": "failed", "message": { "kind": "message", "role": "agent", "parts": [ { "kind": "text", "text": "Payment verification failed: The signature has expired." } ], "metadata": { "x402.payment.status": "payment-failed", "x402.payment.error": "EXPIRED_PAYMENT", "x402.payment.receipts": [ { "success": false, "errorReason": "Payment authorization was submitted after its 'validBefore' timestamp.", "network": "eip155:8453", "transaction": "" } ] } } } } }

失败回执的要点：任务状态转failed；元数据额外携带x402.payment.error机器可读错误码（示例为EXPIRED_PAYMENT，对应授权超出validBefore时间窗）；x402.payment.receipts中success: false、transaction为空字符串并给出errorReason。从源码结构看，这类errorReason文案源自 Facilitator/verify、/settle接口的响应（见核心规范 7.1/7.2 节），A2A 服务端只是将其透传进元数据。

5. 支付状态生命周期与任务状态映射

A2A 传输用x402.payment.status元数据字段跟踪一条细粒度的支付状态推进，每个状态对应 A2A 任务状态（规范原文表格，完整保留）：

这张表揭示了 A2A 传输的设计精髓：支付流程不是独立的 HTTP 往返序列，而是被“织入”了 A2A 任务状态机。任务停在input-required意味着服务端在等待客户端输入——在支付语境下，等待的就是支付授权；客户端提交授权后任务进入working，验证与链上结算完成后任务转为completed并携带artifacts交付结果。payment-verified与payment-completed之间的区分也值得注意：前者表示签名/余额等校验通过（对应 Facilitator/verify成功），后者表示交易已上链（对应/settle成功），两者之间仍存在结算失败的窗口。

6. 错误处理：x402 错误到任务状态与元数据的映射

A2A 传输将 x402 标准错误映射为任务状态 + 支付状态（规范原文表格，完整保留）：

错误响应的具体形态：任务状态转failed，元数据中携带x402.payment.status、机器可读错误码x402.payment.error以及x402.payment.receipts（规范原文示例）：

{ "kind": "task", "id": "task-123", "status": { "state": "failed", "message": { "kind": "message", "role": "agent", "parts": [ { "kind": "text", "text": "Payment verification failed: insufficient funds" } ], "metadata": { "x402.payment.status": "payment-failed", "x402.payment.error": "INSUFFICIENT_FUNDS", "x402.payment.receipts": [ { "success": false, "errorReason": "The client's wallet has insufficient funds to cover the payment.", "network": "eip155:8453", "transaction": "" } ] } } } }

这里体现了 A2A 传输的双通道错误表达：parts中的自然语言文本（"Payment verification failed: insufficient funds"）面向人与 LLM 上下文，而x402.payment.error错误码（如INSUFFICIENT_FUNDS、EXPIRED_PAYMENT）面向程序化决策。核心规范第 9 节定义了 Facilitator 层面的标准错误码（snake_case，如insufficient_funds、invalid_exact_evm_payload_authorization_valid_before等），A2A 层将其归一为 UPPER_SNAKE 风格的传输层错误码；实现时可参照核心规范的错误码表建立映射。客户端据此可以做出可区分的动作：对EXPIRED_PAYMENT重新签名，对INSUFFICIENT_FUNDS提示充值或换用其他accepts项。

7. 扩展声明与激活

A2A 采用扩展（extension）机制实现可选能力协商。支持 x402 支付的 Agent 必须在其AgentCard中声明该扩展：

{ "capabilities": { "extensions": [ { "uri": "https://github.com/google-a2a/a2a-x402/v0.1", "description": "Supports payments using the x402 protocol for on-chain settlement.", "required": true } ] } }

客户端则必须通过X-A2A-ExtensionsHTTP 头部激活该扩展：

X-A2A-Extensions: https://github.com/google-a2a/a2a-x402/v0.1

声明（AgentCard 中的capabilities.extensions）与激活（请求头X-A2A-Extensions）两段式协商的意义在于：AgentCard 是静态能力发现载体，客户端在发起任务前即可判断对端是否支持付费；X-A2A-Extensions头部则在具体请求维度显式激活扩展，使服务端确定性地知道应当启用 x402 支付流程（包括在收费资源上返回payment-required）。required: true表示该扩展为 Agent 正常服务所必需，未激活该扩展的客户端不应预期能完成付费任务。

8. 与 HTTP 传输的对照及实现要点

把 specs/transports-v2/http.md 与 specs/transports-v2/a2a.md 并排阅读，可以清楚看到 x402 传输层抽象的一致性——三个核心 schema 完全相同，变化的只是承载容器：

这一对照对实现者有三点直接启示：

1. schema 复用：A2A 消息元数据中的x402.payment.required/x402.payment.payload/x402.payment.receipts对象，就是核心规范 5.1/5.2/5.3 节定义的PaymentRequired/PaymentPayload/SettlementResponse，可直接复用现有校验逻辑，无需为 A2A 单独定义数据结构。
2. 关联模型不同：HTTP 靠 URL 与请求-响应配对，A2A 靠taskId把支付授权绑定到具体任务，实现多任务并发时的支付隔离。
3. 交付通道不同：HTTP 的交付物是响应体，A2A 的交付物是任务artifacts，天然适配文件、图像等多模态 Agent 输出。

关于适用范围与限制需要说明：本规范描述的是协议报文格式，仓库当前未包含 A2A 传输的 SDK 实现代码（TS/Go/Python 包覆盖 HTTP 与 MCP 传输），A2A 扩展的完整外部规范见文档 References 一节指向的 a2a-x402 项目；核心 v2 规范 12.5 节也列出了客户端库路线图中 A2A 侧对应 python 的x402_a2a。网络标识须用 CAIP-2 格式（如eip155:8453为 Base 主网、eip155:84532为 Base Sepolia 测试网），amount一律为原子单位字符串，这些约束在构造任何 A2A 支付消息时都同样适用。

9. 小结

specs/transports-v2/a2a.md 以 A2A 的 JSON-RPC 消息、任务状态机和元数据系统为容器，将 x402 v2 的三组核心 schema（PaymentRequired、PaymentPayload、SettlementResponse）无缝接入 Agent 间通信：input-required任务承载支付要求，message/send+taskId承载 EIP-3009 支付授权，任务状态更新承载结算回执与artifacts交付。配合六态x402.payment.status生命周期、错误映射表和 AgentCard /X-A2A-Extensions扩展协商，该规范让 AI Agent 之间可以在不脱离 A2A 任务模型的前提下完成链上加密资产结算——这也是 x402 作为“构建在 HTTP 之上的互联网支付协议”向 Agent 通信层自然延伸的样板实现。

【免费下载链接】x402A payments protocol for the internet. Built on HTTP.项目地址: https://gitcode.com/GitHub_Trending/x4/x402