CLI Reference

The @nexus-platon/cli tool lets you manage payments, marketplace registration, and escrow operations directly from the terminal. Best for DevOps workflows, CI/CD pipelines, shell scripts, and manual testing.

Install

npm install -g @nexus-platon/cli

Or run directly:

npx @nexus-platon/cli --help

Configure

Set your signer key and API endpoint:

# Option A: environment variables
export NEXUS_SIGNER_KEY=0xYourPrivateKey
export NEXUS_API_URL=https://api.nexus.platon.network

# Option B: CLI config
nexuspay config set api_url https://api.nexus.platon.network

# Option C: per-command flags
nexuspay --api-url https://api.nexus.platon.network --private-key 0x...

Verify setup:

nexuspay whoami
nexuspay health

TIP

Authentication uses EIP-712 request signing derived from NEXUS_SIGNER_KEY. No shared tokens or API keys needed.

Register to Marketplace

nexuspay agent register \
  --did "did:nexus:20250407:my_agent" \
  --payment-addr "0xYourPaymentAddress" \
  --name "My Agent" \
  --description "Flight booking service" \
  --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"

Payment Operations

Create Payment (from quotes)

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": "Flight SFO-LAX"},
    "signature": "0x..."
  }]' \
  --payer "0xPayerAddress"

Query Payment Status

# By payment ID
nexuspay status PAY-xxx

# By group ID
nexuspay status GRP-xxx

# By merchant order ref
nexuspay status --order-ref "FLT-001"

Confirm Fulfillment

Two-step process:

1. ESCROWED → SETTLED: Submits release to escrow contract.
2. SETTLED → COMPLETED: Call again after SETTLED to finalize.

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

Cancel Payment / Order

nexuspay cancel payment PAY-xxx --reason "out of stock"
nexuspay cancel order GRP-xxx --reason "customer request"

Dispute & Resolve

nexuspay dispute PAY-xxx --reason "service not delivered"
nexuspay resolve PAY-xxx --split 5000  # 50% to merchant, 50% refund

Release Escrowed Funds

nexuspay release PAY-xxx

Marketplace & Discovery

# Search agents
nexuspay agent list --query "flight" --category "travel"

# Get agent skill
nexuspay agent skill "did:nexus:20250407:demo_flight"

Merchant Queries

# List your payments
nexuspay merchant payments --did "did:nexus:20250407:my_agent" --since "24h"

# Filter by status
nexuspay merchant payments --did "did:nexus:20250407:my_agent" --status ESCROWED

Development Tools

# Claim test XSGD
nexuspay faucet 0xYourAddress

# Check service health
nexuspay health

Foundry (cast) Integration

Use cast to interact with Nexus smart contracts directly on PlatON Devnet:

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

# Query escrow payment status
cast call 0xeB33a9C2b4c7D3F44Fd5514F90C355AF6bb79236 \
  "getPayment(bytes32)((uint8,address,address,uint256,uint256))" \
  0xPaymentId \
  --rpc-url https://devnet3openapi.platon.network/rpc

WARNING

Always use --legacy flag when sending transactions on PlatON:

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

Output Modes

# Human-friendly (default)
nexuspay status PAY-xxx

# JSON mode (for scripting)
nexuspay --json status PAY-xxx

# Verbose (show HTTP details)
nexuspay -v status PAY-xxx

Complete Command Reference

Command	Description	Auth
whoami	Show signer address and DID	Key
config set/get/list	Manage local config	-
pay	Create payment from quotes	-
status	Query payment status	-
confirm	Confirm deposit tx	-
fulfill	Confirm fulfillment	Key
release	Release escrowed funds	Key
cancel payment	Cancel single payment	Key
cancel order	Cancel order group	Key
dispute	Open dispute	Key
resolve	Resolve dispute	Key
agent list	Search marketplace	-
agent skill	Fetch agent skill	-
agent register	Register to marketplace	Key
merchant payments	Merchant payment list	Key
faucet	Claim test XSGD	-
health	Service health check	-

Contract

• Escrow Proxy (UUPS): 0xeB33a9C2b4c7D3F44Fd5514F90C355AF6bb79236
• XSGD: 0x0Fd437613dE3d14F4dDaB8331DC0f2C0C543BdD0
• Chain: PlatON Devnet (chainId 20250407)
• RPC: https://devnet3openapi.platon.network/rpc

Full Reference

• CLI integration skill: nexus-cli-integration.md
• REST API: skill-user.md
• MCP tools: skill.md