RESTful API

对于偏好传统 HTTP 接入而非 MCP 的商户，Nexus Core 在 https://api.nexus.platon.network 提供 RESTful API。

认证

商户 API 端点需要 EIP-712 请求签名。每个请求必须包含 4 个请求头：

请求头	说明
`X-Nexus-Signature`	请求的 EIP-712 签名
`X-Nexus-Signer`	你的签名地址 (`0x...`)
`X-Nexus-Timestamp`	Unix 时间戳（秒），容差 ±300s
`X-Nexus-Nonce`	随机 `bytes32`（防重放）

签名的 EIP-712 消息：

NexusRequest(string method, string path, bytes32 body_hash, uint256 timestamp, bytes32 nonce)

Domain: { name: "NexusPay", version: "1", chainId: 20250407, verifyingContract: 0x000...000 }

TIP

只读端点（GET /api/agents、GET /api/payments/...）无需认证。

注册

使用 EIP-712 钱包签名注册商户 Agent — 无需共享 token：

bash

curl -X POST https://api.nexus.platon.network/api/market/register \
  -H "Content-Type: application/json" \
  -H "X-Nexus-Signature: 0x..." \
  -H "X-Nexus-Signer: 0xYourSignerAddress" \
  -H "X-Nexus-Timestamp: 1711440000" \
  -H "X-Nexus-Nonce: 0x$(openssl rand -hex 32)" \
  -d '{
    "merchant_did": "did:nexus:20250407:my_agent",
    "name": "My Agent",
    "description": "航班预订服务",
    "category": "travel.flights",
    "signer_address": "0xYourSignerAddress",
    "payment_address": "0xYourPaymentAddress",
    "skill_md_url": "https://example.com/skill.md",
    "health_url": "https://example.com/health",
    "webhook_url": "https://example.com/webhooks/nexus"
  }'

支付编排（用户侧）

用户的 Agent 提交报价以创建支付组：

POST /api/orchestrate

请求：

json

{
  "quotes": [
    {
      "merchant_did": "did:nexus:20250407:demo_flight",
      "merchant_order_ref": "FLT-001",
      "amount": "100000",
      "currency": "XSGD",
      "chain_id": 20250407,
      "expiry": 9999999999,
      "context": { "summary": "航班 SFO-LAX", "line_items": [] },
      "signature": "0x..."
    }
  ],
  "payer_wallet": "0xPayerAddress"
}

payer_wallet 为可选项 — 省略时任何钱包都可支付。

响应 (HTTP 402)：

json

{
  "http_status": 402,
  "nexus_version": "0.5.0",
  "group_id": "grp_...",
  "status": "PAYMENT_REQUIRED",
  "checkout_url": "https://api.nexus.platon.network/checkout/tok_...",
  "instruction": {
    "group_id": "grp_...",
    "chain_id": 20250407,
    "escrow_contract": "0xeB33a9C2b4c7D3F44Fd5514F90C355AF6bb79236",
    "token_address": "0x0Fd437613dE3d14F4dDaB8331DC0f2C0C543BdD0",
    "token_symbol": "XSGD",
    "total_amount_uint256": "100000",
    "total_amount_display": "0.10",
    "payments": [
      {
        "nexus_payment_id": "PAY-...",
        "merchant_did": "did:nexus:20250407:demo_flight",
        "merchant_order_ref": "FLT-001",
        "amount_uint256": "100000",
        "summary": "航班 SFO-LAX"
      }
    ],
    "eip3009_sign_data": { "..." },
    "deposit_tx": { "to": "0x...", "abi": "..." },
    "nexus_group_sig": "0x...",
    "core_operator_address": "0x..."
  }
}

关键字段：

字段	说明
`checkout_url`	Token 保护的 URL（1 小时有效）。在浏览器中打开进行 MetaMask 结账。
`instruction.eip3009_sign_data`	EIP-3009 类型化数据 — 用户通过 `eth_signTypedData_v4` 签名
`instruction.nexus_group_sig`	EIP-712 签名，覆盖 `(groupId, entriesHash, totalAmount)` — 防篡改

商户端点

确认履约

bash

curl -X POST https://api.nexus.platon.network/api/merchant/confirm-fulfillment \
  -H "Content-Type: application/json" \
  -H "X-Nexus-Signature: 0x..." \
  -H "X-Nexus-Signer: 0xYourSignerAddress" \
  -H "X-Nexus-Timestamp: 1711440000" \
  -H "X-Nexus-Nonce: 0x$(openssl rand -hex 32)" \
  -d '{"nexus_payment_id": "PAY-xxx"}'

取消支付

bash

curl -X POST https://api.nexus.platon.network/api/merchant/cancel-payment \
  -H "Content-Type: application/json" \
  -H "X-Nexus-Signature: 0x..." \
  -H "X-Nexus-Signer: 0xYourSignerAddress" \
  -H "X-Nexus-Timestamp: 1711440000" \
  -H "X-Nexus-Nonce: 0x$(openssl rand -hex 32)" \
  -d '{"nexus_payment_id": "PAY-xxx", "cancel_reason": "缺货"}'

全部端点

方法	路径	说明	认证
POST	`/api/orchestrate`	创建支付组	无
GET	`/api/checkout/:token`	获取支付组详情	无
POST	`/api/checkout/:token/confirm`	确认链上交易	无
GET	`/api/payments/:id`	按 ID 查询支付状态	无
GET	`/api/payments?group_id=...`	按组查询支付状态	无
POST	`/api/market/register`	注册商户 Agent	签名
POST	`/api/merchant/confirm-fulfillment`	触发托管释放	签名
POST	`/api/merchant/cancel-payment`	取消单笔支付	签名
POST	`/api/merchant/cancel-order`	取消订单组	签名
GET	`/api/merchant/payments?merchant_did=...`	商户支付查询	无
GET	`/api/agents`	发现商户 Agent	无
GET	`/api/agents/:did/skill`	获取 Agent skill.md	无

商户支付查询

只读对账无需签名：

bash

curl "https://api.nexus.platon.network/api/merchant/payments?merchant_did=did:nexus:20250407:demo_flight&since=2026-03-01&status=ESCROWED"

Webhooks

注册时配置 webhook_url。Nexus Core 发送 HMAC-SHA256 签名的推送通知：

事件	触发时机
`payment.escrowed`	用户存款已在链上确认
`payment.settled`	托管已释放，资金已发送给商户
`payment.completed`	商户已确认履约
`payment.cancelled`	支付已取消（托管中的会退款）
`payment.dispute_opened`	用户发起争议

Webhook 请求体：

json

{
  "event": "payment.escrowed",
  "nexus_payment_id": "PAY-xxx",
  "merchant_did": "did:nexus:20250407:demo_flight",
  "merchant_order_ref": "FLT-001",
  "amount": "100000",
  "currency": "XSGD",
  "status": "ESCROWED",
  "group_id": "grp_xxx",
  "tx_hash": "0x...",
  "timestamp": "2026-03-26T10:00:00.000Z"
}

Webhook 请求头：

请求头	说明
`X-Nexus-Signature`	`sha256={HMAC-SHA256(webhook_secret, timestamp.body)}`
`X-Nexus-Timestamp`	Unix 时间戳

验证方式：HMAC-SHA256(your_webhook_secret, timestamp + "." + raw_body) === signature_hex

合约

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

完整参考

REST 接入 skill：nexus-rest-integration.md
商户 skill：skill-merchant.md
用户 Agent HTTP skill：skill-user.md
Webhook 规范：RFC-009

RESTful API ​

认证 ​

注册 ​

支付编排（用户侧） ​

商户端点 ​

确认履约 ​

取消支付 ​

全部端点 ​

商户支付查询 ​

Webhooks ​

合约 ​

完整参考 ​

RESTful API

认证

注册

支付编排（用户侧）

商户端点

确认履约

取消支付

全部端点

商户支付查询

Webhooks

合约

完整参考