CLI 参考

@nexus-platon/cli 工具让你可以直接从终端管理支付、Marketplace 注册和托管操作。适用于 DevOps 工作流、CI/CD 管道、Shell 脚本和手动测试。

安装

npm install -g @nexus-platon/cli

或直接运行：

npx @nexus-platon/cli --help

配置

设置签名密钥和 API 端点：

# 方式 A：环境变量
export NEXUS_SIGNER_KEY=0xYourPrivateKey
export NEXUS_API_URL=https://api.nexus.platon.network

# 方式 B：CLI 配置
nexuspay config set api_url https://api.nexus.platon.network

# 方式 C：每次命令指定
nexuspay --api-url https://api.nexus.platon.network --private-key 0x...

验证配置：

nexuspay whoami
nexuspay health

TIP

认证使用基于 NEXUS_SIGNER_KEY 的 EIP-712 请求签名。无需共享 token 或 API 密钥。

注册到 Marketplace

nexuspay agent register \
  --did "did:nexus:20250407:my_agent" \
  --payment-addr "0xYourPaymentAddress" \
  --name "My Agent" \
  --description "航班预订服务" \
  --category "travel.flights" \
  --skill-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"

支付操作

创建支付（从报价）

nexuspay pay \
  --quotes '[{
    "merchant_did": "did:nexus:20250407:demo_flight",
    "merchant_order_ref": "FLT-001",
    "amount": "5000000",
    "currency": "XSGD",
    "chain_id": 20250407,
    "expiry": 9999999999,
    "context": {"summary": "航班 SFO-LAX"},
    "signature": "0x..."
  }]' \
  --payer "0xPayerAddress"

查询支付状态

# 按支付 ID
nexuspay status PAY-xxx

# 按组 ID
nexuspay status GRP-xxx

# 按商户订单号
nexuspay status --order-ref "FLT-001"

确认履约

两步流程：

1. ESCROWED → SETTLED：提交释放到托管合约。
2. SETTLED → COMPLETED：SETTLED 后再次调用以完成最终确认。

nexuspay fulfill PAY-xxx --proof "booking-ref-123"

取消支付 / 订单

nexuspay cancel payment PAY-xxx --reason "缺货"
nexuspay cancel order GRP-xxx --reason "客户要求"

争议与解决

nexuspay dispute PAY-xxx --reason "未交付服务"
nexuspay resolve PAY-xxx --split 5000  # 50% 给商户，50% 退款

释放托管资金

nexuspay release PAY-xxx

Marketplace 与发现

# 搜索 Agent
nexuspay agent list --query "flight" --category "travel"

# 获取 Agent skill
nexuspay agent skill "did:nexus:20250407:demo_flight"

商户查询

# 列出你的支付
nexuspay merchant payments --did "did:nexus:20250407:my_agent" --since "24h"

# 按状态筛选
nexuspay merchant payments --did "did:nexus:20250407:my_agent" --status ESCROWED

开发工具

# 领取测试 XSGD
nexuspay faucet 0xYourAddress

# 检查服务健康状态
nexuspay health

Foundry (cast) 集成

使用 cast 直接与 PlatON Devnet 上的 Nexus 智能合约交互：

# 查询 XSGD 余额
cast call 0x0Fd437613dE3d14F4dDaB8331DC0f2C0C543BdD0 \
  "balanceOf(address)(uint256)" 0xYourAddress \
  --rpc-url https://devnet3openapi.platon.network/rpc

# 查询托管支付状态
cast call 0xeB33a9C2b4c7D3F44Fd5514F90C355AF6bb79236 \
  "getPayment(bytes32)((uint8,address,address,uint256,uint256))" \
  0xPaymentId \
  --rpc-url https://devnet3openapi.platon.network/rpc

WARNING

在 PlatON 上发送交易时务必使用 --legacy 标志：

cast send --legacy --gas-price 20000000000 ...

输出模式

# 人类友好格式（默认）
nexuspay status PAY-xxx

# JSON 模式（用于脚本）
nexuspay --json status PAY-xxx

# 详细模式（显示 HTTP 详情）
nexuspay -v status PAY-xxx

完整命令参考

命令	说明	认证
whoami	显示签名地址和 DID	密钥
config set/get/list	管理本地配置	-
pay	从报价创建支付	-
status	查询支付状态	-
confirm	确认存款交易	-
fulfill	确认履约	密钥
release	释放托管资金	密钥
cancel payment	取消单笔支付	密钥
cancel order	取消订单组	密钥
dispute	发起争议	密钥
resolve	解决争议	密钥
agent list	搜索 Marketplace	-
agent skill	获取 Agent skill	-
agent register	注册到 Marketplace	密钥
merchant payments	商户支付查询	密钥
faucet	领取测试 XSGD	-
health	服务健康检查	-

合约

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

完整参考

• CLI 接入 skill：nexus-cli-integration.md
• REST API：skill-user.md
• MCP 工具：skill.md