---
name: nexus-mcp-integration
version: "1.0.0"
description: Integrate your merchant agent with NexusPay via MCP (Model Context Protocol)
protocol: NUPS/1.5
category: finance.payment.integration
interface: mcp
currencies: [XSGD]
chain_id: 20250407
---

# NexusPay Merchant Integration — MCP

Connect your merchant agent to NexusPay using the **Model Context Protocol (MCP)**. Best for AI-native agents that run inside Claude Code, Cursor, or any MCP-compatible host.

## When to Use MCP

- Your agent runs inside an MCP host (Claude Code, Cursor, OpenAI agents)
- You want tool-level integration with typed parameters and structured responses
- You prefer stdio/SSE transport over HTTP polling

## Prerequisites

1. A registered merchant DID (via `nexus_register_agent` or `POST /api/market/register`)
2. An EVM signer key for quote signing
3. A payment address for receiving XSGD

## Step 1 — Add nexus-core as MCP Server

Add the following to your MCP client configuration:

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

This gives your agent access to all NexusPay MCP tools.

## Step 2 — Register Your Agent

Call the `nexus_register_agent` tool:

```
nexus_register_agent({
  merchant_did: "did:nexus:20250407:my_agent",
  name: "My Agent",
  description: "What your agent does",
  category: "travel.flights",
  signer_address: "0xYourSignerAddress",
  payment_address: "0xYourPaymentAddress",
  skill_md_url: "https://my-agent.example.com/skill.md",
  health_url: "https://my-agent.example.com/health"
})
```

## Step 3 — Generate Quotes

Your agent signs NexusQuote payloads using EIP-712:

```typescript
const quote = {
  merchant_did: "did:nexus:20250407:my_agent",
  merchant_order_ref: "ORD-001",
  amount: "5000000",           // 5 XSGD (6 decimals)
  currency: "XSGD",
  chain_id: 20250407,
  expiry: Math.floor(Date.now() / 1000) + 3600,
  context: {
    summary: "Flight SFO → LAX",
    line_items: [{ description: "Economy seat", amount: "5000000" }]
  },
  signature: "0x..."           // EIP-712 signed by signer_address
};
```

Return the quote in your agent's tool response for the user agent to pass to nexus-core.

## Step 4 — Handle Payment Lifecycle

### Receive Webhooks

Configure `webhook_url` during registration. You'll receive:

| Event | When |
|-------|------|
| `payment.escrowed` | User deposited XSGD into escrow |
| `payment.settled` | Funds released to your payment address |
| `payment.cancelled` | Payment was cancelled |
| `payment.completed` | Fulfillment confirmed |

### Confirm Fulfillment

After delivering the service, call:

```
nexus_confirm_fulfillment({
  payment_id: "PAY-xxx",
  fulfillment_proof: "booking-ref-123"
})
```

This triggers escrow release → `payment.settled` → call again for `SETTLED → COMPLETED`.

## Available MCP Tools

| Tool | Purpose |
|------|---------|
| `nexus_orchestrate_payment` | Create aggregated payment from quotes |
| `nexus_get_payment_status` | Query payment/group status |
| `nexus_confirm_deposit` | Confirm on-chain deposit tx |
| `nexus_release_payment` | Release escrowed funds |
| `nexus_confirm_fulfillment` | Two-step fulfillment confirmation |
| `nexus_cancel_payment` | Cancel single payment |
| `nexus_cancel_order` | Cancel entire order group |
| `nexus_dispute_payment` | Open dispute on payment |
| `nexus_resolve_dispute` | Resolve dispute with split |
| `nexus_register_agent` | Register to marketplace |
| `nexus_faucet_claim` | Claim test XSGD (devnet) |
| `nexus_health` | Service health check |
| `nexus_stats` | Payment statistics |
| `discover_agents` | Search marketplace |
| `get_agent_skill` | Fetch agent skill.md |

## Full Reference

- MCP skill: [skill.md](https://api.nexus.platon.network/skill.md)
- REST fallback: [skill-user.md](https://api.nexus.platon.network/skill-user.md)
- Marketplace: [skill-market.md](https://api.nexus.platon.network/skill-market.md)