规范文档
核心协议规范

核心协议规范

AP2 的核心对象在 src/ap2/types 中给出了参考实现，主要包括 智能体身份、支付意图、结算凭证 以及三类 Mandate。本节概述关键字段以及围绕它们的 REST 接口。

数据模型

智能体身份 (agent_identity.py)

字段类型说明
didstring控制平面签发的去中心化标识
public_keys[]array验证密钥（Ed25519、P-256）及其 key id
policy_claimsobject策略声明（限额、司法辖区、审批阈值等）
metadataobject基本信息、风险等级、联系方式
delegations[]array可选的人工监督者及其授权范围

支付意图 (payment_request.py)

关键部分：

  • amount：金额与币种（当前支持 USDC、USDC.e、USDT）。
  • participants：引用买卖双方的 DID。
  • terms：结算方式、托管规则、争议窗口、轨道标识等。
  • line_items：SKU 级明细，可附带税率等元数据。
  • evidence：合同、验收单等证据的 CID。
  • policy_trace：策略评估记录（规则 ID、结果、说明）。

结算凭证 (settlement-proof.json)

字段说明
intentId关联的支付意图 ID
rail结算适配器标识（x402、sepa、card…）
ledgerEntries借贷明细，记录钱包或账户的增减
hash基于 payload 的内容寻址哈希
signatures[]结算轨道与控制平面的签名（JWS）
compliance旅行规则、制裁校验、司法辖区等合规模块的摘要

Mandate（mandate.py）

AP2 将用户意图与支付上下文封装为三类可验证凭证：

  • IntentMandate —— 描述授权范围，可限制商家、SKU、可退款要求及过期时间。
  • CartMandate —— 商家签名的购物车，绑定价格、支付方式、有效期与是否需要用户确认。
  • PaymentMandate —— 凭证提供方/支付处理方出具，记录最终支付方式、金额、Cart 哈希与必要签名。

Mandate 与结算凭证共同构成不可抵赖的流水，有助于责任划分、争议处理与审计。

REST 接口

基路径：/v1/ap2

方法路径说明
POST/payment-intents创建或更新支付意图
GET/payment-intents/{id}查询支付意图状态
POST/payment-intents/{id}/confirm商家接受并触发策略评估
POST/payment-intents/{id}/cancel取消待处理的意图
POST/payment-intents/{id}/release授权释放托管资金
POST/refunds创建退款意图
GET/settlement-proofs/{id}获取签名结算凭证
GET/events (SSE)订阅生命周期事件
POST/evidence上传补充证据（返回带签名的 CID）
GET/identities/{did}查询公开的智能体身份信息

认证采用主体之间的 mTLS + 策略令牌（JWT）。示例：

{
  "iss": "https://control.ap2",
  "sub": "did:ap2:buyer-bot-9f32",
  "aud": "https://control.ap2/v1/ap2",
  "claims": {
    "maxSinglePayment": "1000 USDC",
    "allowedRails": ["x402"],
    "jurisdictions": ["US", "CA"]
  }
}

事件流

事件通过 Server-Sent Events (text/event-stream) 推送：

event: payment.authorized
data: {
  "id": "ap2_pi_7f0cf3",
  "status": "authorized",
  "policyTrace": [
    {"ruleId": "limit.max_single", "outcome": "pass"},
    {"ruleId": "kyc.check", "outcome": "pass"}
  ],
  "rail": "x402",
  "timestamp": "2025-09-17T12:04:12Z"
}

客户端应处理网络中断，可使用 Last-Event-ID 续传。

错误模型

基于 RFC 7807，附带 AP2 自定义错误码：

{
  "type": "https://agentpaymentsprotocol.info/errors/policy-threshold-exceeded",
  "title": "Policy threshold exceeded",
  "status": 422,
  "detail": "Amount 15000 USDC exceeds policy limit 1000 USDC",
  "instance": "ap2_pi_1c9f8",
  "extra": {
    "ruleId": "limit.max_single",
    "allowed": "1000 USDC",
    "requested": "15000 USDC"
  }
}

推荐的客户端处理策略：

  • 400 —— 修复请求格式后重试。
  • 409 —— 意图状态冲突，需重新获取状态。
  • 422 —— 策略失败，调整条款或升级为人工审批。
  • 5xx —— 轨道或控制平面异常，指数退避重试。

安全要求

  • 所有请求需使用 HTTP Message Signatures（draft-ietf-httpbis-message-signatures-19）。
  • 大于 512 KiB 的 payload 应通过证据端点上传，使用预签名 URL。
  • 策略令牌等敏感凭证应至少每 30 天轮换一次，沙盒会自动完成轮换。

版本管理

协议版本遵循 YYYY.MINOR（如 2025.0）。兼容性变更会同步更新路线图与迁移说明。客户端需在 AP2-Schema-Version 头部声明支持的版本，控制平面会协商双方兼容的最高版本。

如需完整字段定义，请查看官方仓库的 src/ap2/types 模块，或使用样例中的可视化工具探索对象结构。

发现与能力宣告