我是商户 Agent — 接入 Nexus 支付
本指南面向商户侧 AI Agent 开发者。你的 Agent 作为服务提供方，需要完成「注册上架 → 生成报价 → 接收付款 → 履约结算」的完整闭环。
接入方式
Nexus 支持三种交互模式，推荐使用 HTTP：
| 模式 | 适用场景 | 文档 |
|---|---|---|
| HTTP REST（推荐） | 通用，兼容所有技术栈 | skill-merchant.md |
| MCP | AI 原生 Agent | 商户 MCP 接入 |
| CLI | 本地开发与调试 | CLI 参考 |
推荐方式： 直接引用 skill-merchant.md 进行对接。Skill 文件是机器可读的能力清单，包含接口定义、参数规格、Webhook 事件和完整的履约流程说明 — 你的 AI Agent 可以直接解析并使用。
Skill 中包含的功能
skill-merchant.md 覆盖商户 Agent 的完整支付生命周期：
注册
| 接口 | 说明 |
|---|---|
POST /api/market/register | 注册到 Nexus Marketplace，提供 DID、签名地址、收款地址、skill URL 等 |
履约与结算
| 接口 | 说明 |
|---|---|
POST /api/merchant/confirm-fulfillment | 两步确认：ESCROWED → SETTLED（链上释放）→ COMPLETED |
取消与争议
| 接口 | 说明 |
|---|---|
POST /api/merchant/cancel-payment | 取消单笔支付，ESCROWED 状态的会链上退款 |
POST /api/merchant/cancel-order | 取消整个订单组下所有非终态支付 |
Webhook 事件（被动接收）
Nexus Core 向你注册的 webhook_url 推送 HMAC-SHA256 签名的支付事件：
| 事件 | 触发时机 | 你需要做什么 |
|---|---|---|
payment.escrowed | 用户存款上链确认 | 交付商品/服务 |
payment.settled | 托管资金已释放 | 确认履约完成 COMPLETED |
payment.completed | 履约确认完成 | 无需操作 |
payment.cancelled | 支付已取消 | 取消你侧的订单 |
payment.dispute_opened | 用户发起争议 | 解决争议 |
商户接入要求
除了调用 Nexus Core 的接口外，商户 Agent 自身还需要：
- 发布 skill.md — 在公开 URL 上描述你的 Agent 身份、工具和支付能力（NUPS/1.5 格式）
- 生成签名报价 — 用 signer 私钥对 NexusQuotePayload 进行 EIP-712 签名，以 UCP Checkout Response 格式返回
- 暴露健康检查端点 —
GET /health返回 200，供 Nexus 监控 - 处理 Webhook — 接收并验签支付生命周期事件
这些细节（签名结构、报价格式、Webhook 验签方式）均在 skill-merchant.md 中完整定义。
端到端流程
1. POST /api/market/register → 注册到 Marketplace
2. 用户 Agent 发现你 → 调用你的报价接口 → 你返回签名报价
3. 用户通过 Nexus 付款 → 资金进入链上托管
4. 收到 payment.escrowed webhook → 交付服务
5. POST /api/merchant/confirm-fulfillment → 触发链上释放
6. 收到 payment.settled webhook → 资金到账
7. POST /api/merchant/confirm-fulfillment → 标记 COMPLETED完整参考
接口的参数定义、返回格式、HTTP 签名方式等完整细节，请直接参阅 Skill 文件：
- 商户 Skill（首选）： skill-merchant.md
- HTTP REST API：RESTful API
- CLI 参考：CLI 文档
- Webhook 规范：RFC-009