---
name: nexus-cli-integration
version: "1.0.0"
description: Integrate your merchant agent with NexusPay via the CLI tool
protocol: NUPS/1.5
category: finance.payment.integration
interface: cli
currencies: [XSGD]
chain_id: 20250407
---

# NexusPay Merchant Integration — CLI

Manage payments and marketplace operations from the command line using **@nexus-platon/cli**. Best for DevOps workflows, CI/CD pipelines, shell scripts, and manual testing.

## When to Use CLI

- You're testing payment flows during development
- You need to script payment operations in CI/CD
- You prefer command-line tools over code
- You want to manage marketplace registration without writing code

## Prerequisites

1. Node.js 18+ installed
2. An EVM private key for signing (`NEXUS_SIGNER_KEY` env var)
3. Network access to the NexusPay API

## Step 1 — Install

```bash
npm install -g @nexus-platon/cli
```

Or run directly:
```bash
npx @nexus-platon/cli --help
```

## Step 2 — Configure

Set your signer key and API endpoint:

```bash
# 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:
```bash
nexuspay whoami
nexuspay health
```

## Step 3 — Register to Marketplace

```bash
nexuspay agent register \
  --did "did:nexus:20250407:my_agent" \
  --payment-addr "0xYourPaymentAddress" \
  --name "My Agent" \
  --webhook-url "https://my-agent.example.com/webhooks/nexus"
```

## Step 4 — Payment Operations

### Create Payment (from quotes)

```bash
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

```bash
# 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

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

### Cancel Payment / Order

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

### Dispute & Resolve

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

### Release Escrowed Funds

```bash
nexuspay release PAY-xxx
```

## Step 5 — Marketplace & Discovery

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

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

## Step 6 — Merchant Queries

```bash
# 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

# List groups
nexuspay group list
nexuspay group detail GRP-xxx
```

## Step 7 — Development Tools

```bash
# Claim test XSGD
nexuspay faucet 0xYourAddress

# Check service health
nexuspay health

# View statistics
nexuspay stats
```

## Output Modes

```bash
# 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 |
| `group list` | List payment groups | - |
| `group detail` | Group with child payments | - |
| `faucet` | Claim test XSGD | - |
| `health` | Service health check | - |
| `stats` | Payment statistics | - |

## Full Reference

- REST API: [skill-user.md](https://api.nexus.platon.network/skill-user.md)
- MCP tools: [skill.md](https://api.nexus.platon.network/skill.md)