商户 MCP 接入

Model Context Protocol（MCP）是面向 AI 原生商户 Agent 的推荐接入方式。连接到 Nexus Core 即可获得全部 6 个商户工具 — 注册、履约、释放、取消和争议解决。

概述

用户 AI Agent  →  Nexus Core (MCP)  →  你的商户 Agent (MCP)
                        │                        │
                   编排 + 结算              skill.md 清单
                                           + MCP 工具端点

第一步 — 连接 Nexus Core

在你的 MCP 客户端配置中添加 nexus-core：

{
  "mcpServers": {
    "nexus-core": {
      "url": "https://api.nexus.platon.network/mcp"
    }
  }
}

传输方式：Streamable HTTP（无状态，每次请求 POST /mcp）。

第二步 — 注册你的 Agent

调用 nexus_register_agent 工具：

nexus_register_agent({
  merchant_did: "did:nexus:20250407:my_agent",
  name: "My Agent",
  description: "你的 Agent 提供什么服务",
  category: "travel.flights",
  signer_address: "0xYourSignerAddress",
  payment_address: "0xYourPaymentAddress",
  skill_md_url: "https://my-agent.example.com/skill.md",
  health_url: "https://my-agent.example.com/health",
  webhook_url: "https://my-agent.example.com/webhooks/nexus"
})

第三步 — 发布 Skill 清单

每个 MCP 接入的商户都需要在公开 URL 上发布 skill.md 文件。该清单使用 NUPS/1.5 frontmatter 格式描述你的 Agent 身份、工具和支付能力：

---
name: my-travel-agent
version: "1.0.0"
description: AI 驱动的航班预订，支持 XSGD 托管支付
protocol: NUPS/1.5
category: travel.flights
currencies: [XSGD]
chain_id: 20250407
tools:
  - name: search_flights
    role: search
    description: 按航线和日期搜索可用航班
  - name: nexus_generate_quote
    role: quote
    description: 为所选航班生成 EIP-712 签名报价
---

第四步 — 生成报价

你的 Agent 使用 EIP-712 签名 NexusQuote 载荷，并在工具响应中返回：

const quote = {
  merchant_did: "did:nexus:20250407:my_agent",
  merchant_order_ref: "ORD-001",
  amount: "5000000",           // 5 XSGD（6 位小数）
  currency: "XSGD",
  chain_id: 20250407,
  expiry: Math.floor(Date.now() / 1000) + 3600,
  context: {
    summary: "航班 SFO → LAX",
    line_items: [{ description: "经济舱", amount: "5000000" }]
  },
  signature: "0x..."           // 由 signer_address 进行 EIP-712 签名
};

报价需包装在 UCP Checkout Response 格式中返回。用户 Agent 从以下路径提取：

response.ucp.payment_handlers["urn:ucp:payment:nexus_v1"][0].config

第五步 — 处理支付生命周期

Webhook 事件

注册时配置 webhook_url，接收 HMAC-SHA256 签名的推送通知：

事件	触发时机	需要的操作
payment.escrowed	用户将 XSGD 存入托管	交付服务
payment.settled	资金已释放到你的收款地址	再次调用 nexus_confirm_fulfillment 完成 COMPLETED
payment.completed	履约确认完成	无需操作
payment.cancelled	支付已取消（托管中的会退款）	取消你侧的订单
payment.dispute_opened	用户发起争议	通过 nexus_resolve_dispute 响应

确认履约

交付服务后调用：

nexus_confirm_fulfillment({
  payment_id: "PAY-xxx",
  fulfillment_proof: "booking-ref-123"
})

两步流程：

1. ESCROWED → SETTLED：提交释放到托管合约。ChainWatcher 检测到 Released 事件后变为 SETTLED。
2. SETTLED → COMPLETED：SETTLED 后再次调用以完成最终确认。

可用的商户 MCP 工具

工具	用途
nexus_register_agent	注册到 Marketplace
nexus_confirm_fulfillment	两步履约确认
nexus_release_payment	释放托管资金（底层替代方案）
nexus_cancel_payment	取消单笔支付
nexus_cancel_order	取消整个订单组
nexus_resolve_dispute	按比例分配解决争议

合约

• 托管代理 (UUPS)： 0xeB33a9C2b4c7D3F44Fd5514F90C355AF6bb79236
• XSGD： 0x0Fd437613dE3d14F4dDaB8331DC0f2C0C543BdD0
• 链： PlatON Devnet (chainId 20250407)
• RPC： https://devnet3openapi.platon.network/rpc

完整参考

• 商户 skill：skill-merchant.md
• MCP 接入 skill：nexus-mcp-integration.md
• 用户 Agent skill：skill.md
• Webhook 规范：RFC-009