Merchant MCP Integration

The Model Context Protocol (MCP) is the recommended integration path for AI-native merchant agents. Connect your agent to Nexus Core and gain access to all 6 merchant tools — registration, fulfillment, release, cancellation, and dispute resolution.

Overview

User's AI Agent  →  Nexus Core (MCP)  →  Your Merchant Agent (MCP)
                          │                        │
                    Orchestration             skill.md manifest
                    + Settlement              + MCP tool endpoints

Step 1 — Connect to Nexus Core

Add nexus-core as an MCP server in your client configuration:

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

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

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",
  webhook_url: "https://my-agent.example.com/webhooks/nexus"
})

Step 3 — Publish Your Skill Manifest

Every MCP-integrated merchant must publish a skill.md file at a public URL. This manifest describes your agent's identity, tools, and payment capabilities using the NUPS/1.5 frontmatter format:

---
name: my-travel-agent
version: "1.0.0"
description: AI-powered flight booking with XSGD escrow payments
protocol: NUPS/1.5
category: travel.flights
currencies: [XSGD]
chain_id: 20250407
tools:
  - name: search_flights
    role: search
    description: Search available flights by route and date
  - name: nexus_generate_quote
    role: quote
    description: Generate an EIP-712 signed quote for selected flights
---

Step 4 — Generate Quotes

Your agent signs NexusQuote payloads using EIP-712 and returns them in tool responses:

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 wrapped in the UCP Checkout Response format. The user's agent extracts it from:

response.ucp.payment_handlers["urn:ucp:payment:nexus_v1"][0].config

Step 5 — Handle Payment Lifecycle

Webhook Events

Configure webhook_url during registration to receive HMAC-SHA256 signed notifications:

Event	When	Action
payment.escrowed	User deposited XSGD into escrow	Deliver the service
payment.settled	Funds released to your payment address	Call nexus_confirm_fulfillment again for COMPLETED
payment.completed	Fulfillment confirmed	No action needed
payment.cancelled	Payment was cancelled (refund if escrowed)	Cancel the order on your side
payment.dispute_opened	User opened a dispute	Respond via nexus_resolve_dispute

Confirm Fulfillment

After delivering the service:

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

Two-step process:

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

Available Merchant MCP Tools

Tool	Purpose
nexus_register_agent	Register to marketplace
nexus_confirm_fulfillment	Two-step fulfillment confirmation
nexus_release_payment	Release escrowed funds (lower-level alternative)
nexus_cancel_payment	Cancel a single payment
nexus_cancel_order	Cancel an entire order group
nexus_resolve_dispute	Resolve dispute with merchant/payer split

Contract

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

Full Reference

• Merchant skill: skill-merchant.md
• MCP integration skill: nexus-mcp-integration.md
• User agent skill: skill.md
• Webhook specification: RFC-009