---
name: nexus-core
version: "0.5.0"
description: NexusPay Core — payment orchestration for multi-merchant aggregated checkout
protocol: NUPS/1.5
category: finance.payment
currencies: [XSGD]
chain_id: 20250407
escrow_proxy: "0xeB33a9C2b4c7D3F44Fd5514F90C355AF6bb79236"
audience: user-agent
tools:
  - name: discover_agents
    role: discovery
    description: Search and discover merchant agents by keyword/category, ranked by stars
  - name: get_agent_skill
    role: discovery
    description: Fetch full skill.md content for a specific merchant agent
  - name: nexus_orchestrate_payment
    role: orchestrate
  - name: nexus_confirm_deposit
    role: deposit
  - name: nexus_get_payment_status
    role: status
  - name: nexus_dispute_payment
    role: dispute
  - name: nexus_faucet_claim
    role: faucet
---

# Nexus Core — User Agent Skill

Payment orchestration for user-facing AI agents. **When a user wants to pay for orders from merchant agents (flights, hotels, etc.), submit all quotes here for a single aggregated payment.**

> For merchant agent tools (fulfillment, cancel, release), see [skill-merchant.md](https://api.nexus.platon.network/skill-merchant.md).
> For HTTP REST API (no MCP client), see [skill-user.md](https://api.nexus.platon.network/skill-user.md).
> For ops/monitoring tools, see [skill-ops.md](https://api.nexus.platon.network/skill-ops.md).

## MCP Connection

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

Transport: **Streamable HTTP** (stateless, single `POST /mcp` per request).

## Quick Start

```
1. discover_agents({ query: "flight" })          → find merchant agents
2. get_agent_skill({ merchant_did: "did:..." })   → learn how to get quotes
3. Call merchant's search_and_quote tool          → get a NUPS quote
4. nexus_orchestrate_payment({ quotes })           → create payment group
5. User opens checkout_url → signs & pays via MetaMask
6. nexus_confirm_deposit({ group_id, tx_hash })   → confirm on-chain tx
7. nexus_get_payment_status({ group_id })          → track progress
```

### How to extract quotes from merchant responses

Merchant agents return a UCP Checkout Response. The quote you need is at:
`response.ucp.payment_handlers["urn:ucp:payment:nexus_v1"][0].config`

The `config` object is a `NexusQuotePayload` with these required fields:
- `merchant_did` (string)
- `merchant_order_ref` (string)
- `amount` (string — uint256, e.g. `"100000"` for 0.10 XSGD)
- `currency` (string)
- `chain_id` (number)
- `expiry` (number — unix timestamp in seconds)
- `context` (object with `summary` and `line_items`)
- `signature` (string — EIP-712 signature from merchant signer)

### Calling the orchestrator

**Option A — `quotes_json` string (recommended for CLI):**

```
nexus_orchestrate_payment({
  quotes_json: "[{\"merchant_did\":\"did:nexus:20250407:demo_flight\",\"merchant_order_ref\":\"FLT-001\",\"amount\":\"100000\",\"currency\":\"XSGD\",\"chain_id\":20250407,\"expiry\":9999999999,\"context\":{\"summary\":\"Flight\",\"line_items\":[]},\"signature\":\"0x...\"}]"
})
```

**Option B — `quotes` array (if your MCP client supports complex objects):**

```
nexus_orchestrate_payment({
  quotes: [flight_quote_config, hotel_quote_config]
})
```

> `payer_wallet` is optional. Add it to restrict payment to a specific wallet: `payer_wallet: "0x..."`

Both options accept raw `config` objects, full UCP envelopes, or handler objects — the orchestrator auto-extracts the quote from wrapped formats.

## MCP Tools

### `discover_agents`

Search and discover merchant agents in the Nexus marketplace. Returns agents ranked by stars.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `query` | string | No | Keyword to search agent names and descriptions |
| `category` | string | No | Category prefix filter (e.g. `travel`, `food`) |
| `limit` | number | No | Max results (default 20, max 50) |

---

### `get_agent_skill`

Fetch the full skill.md content for a specific merchant agent. Use this to learn how to call the merchant's tools (search, generate quote, etc.).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `merchant_did` | string | Yes | Merchant DID (e.g. `did:nexus:20250407:demo_flight`) |

---

### `nexus_orchestrate_payment`

Orchestrate aggregated payment for one or more merchant quotes. Validates signatures, creates a payment group, and returns a `BatchDepositInstruction` with EIP-3009 signing data, precomputed on-chain hashes, and a group signature from the Nexus Core operator.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `quotes_json` | string | Preferred | JSON string of the quotes array. Use this for reliable CLI/MCP compatibility. |
| `quotes` | array | Alternative | Array of `NexusQuotePayload` objects. Use if your MCP client handles complex objects well. |
| `payer_wallet` | string | No | Payer's EVM wallet address (`0x...`, 42 chars). Optional — if omitted, any wallet can pay at checkout. |

One of `quotes_json` or `quotes` must be provided. Both accept raw quotes, full UCP envelopes, or handler objects (auto-unwrapped).

**Returns:** `PaymentRequired402` with `group_id`, `checkout_url` (token-protected, 1-hour TTL), `instruction` (BatchDepositInstruction), `nexus_group_sig`, and `core_operator_address`.

---

### `nexus_confirm_deposit`

Confirm a user-submitted batch deposit transaction. Call this after the user signs EIP-3009 and sends `batchDepositWithAuthorization` via MetaMask.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `group_id` | string | Yes | Payment group ID (e.g. `grp_...`) |
| `tx_hash` | string | Yes | Transaction hash from user's MetaMask submission (`0x...`) |

---

### `nexus_get_payment_status`

Check payment status by any identifier.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `nexus_payment_id` | string | No | Nexus payment ID (e.g. `PAY-...`) |
| `merchant_order_ref` | string | No | Merchant order reference (e.g. `FLT-...`, `HTL-...`) |
| `group_id` | string | No | Payment group ID (e.g. `grp_...`) |

At least one parameter must be provided.

---

### `nexus_dispute_payment`

Open a dispute for an escrowed payment. Returns calldata for the payer to submit on-chain (only payer can call dispute on the contract).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `payment_id` | string | Yes | Nexus payment ID (e.g. `PAY-...`) |
| `reason` | string | Yes | Dispute reason (UTF-8, max 256 chars) |

---

### `nexus_faucet_claim`

Claim 100 test XSGD tokens on PlatON Devnet for development/testing. Subject to cooldown between claims.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `wallet_address` | string | Yes | EVM wallet address to receive test XSGD (`0x...`, 42 chars) |

---

## CLI

Install: `npm install -g @nexus-platon/cli`

```bash
# Discover merchants
nexuspay agent list --query flight

# Read merchant skill
nexuspay agent skill did:nexus:20250407:demo_flight

# Create payment
nexuspay pay --quotes '[{"merchant_did":"...","amount":"100000",...,"signature":"0x..."}]' --payer 0xABC

# Confirm deposit
nexuspay confirm GRP-xyz789 0x<tx_hash>

# Check status
nexuspay status PAY-abc123
nexuspay status GRP-xyz789

# Open dispute
nexuspay dispute PAY-abc123 --reason "Item not received"

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

---

## End-to-End Payment Flow

1. **Discover** (optional) — Call `discover_agents` to find merchant agents, then `get_agent_skill` to read their capabilities.
2. **Collect Quotes** — Call merchant agents' `search_and_quote` or `nexus_generate_quote` tools. Each returns a UCP checkout response containing a `config` (NexusQuotePayload) inside `urn:ucp:payment:nexus_v1`.
3. **Orchestrate** — Call `nexus_orchestrate_payment` with all `config` objects as the `quotes` array. Optionally include `payer_wallet` to restrict who can pay; if omitted, any wallet can pay at checkout. Nexus Core validates each quote, creates a payment group, and returns a `BatchDepositInstruction` with EIP-3009 signing data and a group signature.
4. **Sign & Submit** — User signs the EIP-3009 typed data via `eth_signTypedData_v4`, then submits `batchDepositWithAuthorization` on-chain (user pays gas). The checkout page at `checkout_url` handles this automatically via MetaMask.
5. **Confirm** — Call `nexus_confirm_deposit` with `group_id` + `tx_hash`.
6. **Track** — Call `nexus_get_payment_status` with `group_id` to monitor progress (CREATED -> ESCROWED -> SETTLED -> COMPLETED).
7. **Dispute** (optional) — If the user is unsatisfied, call `nexus_dispute_payment` with the payment ID and reason. Returns calldata for on-chain dispute submission.

## Security

### Group Signature (`nexus_group_sig`)

Every `BatchDepositInstruction` includes an EIP-712 signature from the Nexus Core operator over `NexusGroupApproval(groupId, entriesHash, totalAmount)`. This prevents MITM tampering of the payments array (merchant addresses and amounts). Clients should verify `nexus_group_sig` and `core_operator_address` before submitting transactions.

### Precomputed Hashes

All `bytes32` fields in `GroupPaymentDetail` (`payment_id_bytes32`, `order_ref_bytes32`, `merchant_did_bytes32`, `context_hash`) are precomputed on the server using `keccak256`. Clients use these directly when building on-chain calldata, eliminating hash mismatch bugs between server and client.

### Token-Protected Checkout URLs

Checkout URLs use short-lived tokens (`tok_...`) instead of raw group IDs. Tokens expire after 1 hour and are single-use. Direct `grp_` / `GRP-` IDs are still accepted as fallback.

## Contract

- **Escrow Proxy (UUPS):** `0xeB33a9C2b4c7D3F44Fd5514F90C355AF6bb79236` (stable address, upgradeable)
- **XSGD:** `0x0Fd437613dE3d14F4dDaB8331DC0f2C0C543BdD0`
- **Chain:** PlatON Devnet (chainId `20250407`)
- **RPC:** `https://devnet3openapi.platon.network/rpc`