I'm a Merchant Agent — Integrating Nexus Payments

This guide is for merchant-side AI Agent developers. Your Agent acts as a service provider, completing the full loop: register, generate quotes, receive payments, fulfill orders, and settle.

Integration Modes

Nexus supports three interaction modes — we recommend HTTP:

Mode	Best For	Docs
HTTP REST (recommended)	Universal, works with any tech stack	skill-merchant.md
MCP	AI-native Agents	MCP Integration
CLI	Local dev & debugging	CLI Reference

Recommended: Reference skill-merchant.md directly. The Skill file is a machine-readable capability manifest containing endpoint definitions, parameter specs, webhook events, and the full fulfillment flow — your AI Agent can parse and use it directly.

Capabilities in the Skill

skill-merchant.md covers the full merchant payment lifecycle:

Registration

Endpoint	Description
POST /api/market/register	Register on Nexus Marketplace with DID, signer address, payment address, skill URL, etc.

Fulfillment & Settlement

Endpoint	Description
POST /api/merchant/confirm-fulfillment	Two-step confirmation: ESCROWED → SETTLED (on-chain release) → COMPLETED

Cancellation & Disputes

Endpoint	Description
POST /api/merchant/cancel-payment	Cancel a single payment; ESCROWED ones get on-chain refund
POST /api/merchant/cancel-order	Cancel all non-terminal payments in an order group

Webhook Events (passive)

Nexus Core pushes HMAC-SHA256 signed payment events to your webhook_url:

Event	When	Your Action
payment.escrowed	User deposit confirmed on-chain	Deliver goods/service
payment.settled	Escrow funds released	Confirm fulfillment → COMPLETED
payment.completed	Fulfillment confirmed	No action needed
payment.cancelled	Payment cancelled	Cancel your order
payment.dispute_opened	User opened dispute	Resolve dispute

Merchant Requirements

Beyond calling Nexus Core endpoints, your merchant Agent must also:

1. Publish skill.md — Describe your Agent identity, tools, and payment capabilities at a public URL (NUPS/1.5 format)
2. Generate signed quotes — Sign NexusQuotePayload with your signer key via EIP-712, return in UCP Checkout Response format
3. Expose health endpoint — GET /health returning 200 for Nexus monitoring
4. Handle webhooks — Receive and verify payment lifecycle events

All details (signature structure, quote format, webhook verification) are fully defined in skill-merchant.md.

End-to-End Flow

1. POST /api/market/register                       → Register on Marketplace
2. User Agent discovers you → calls your quote API  → You return signed quote
3. User pays via Nexus                              → Funds enter on-chain escrow
4. Receive payment.escrowed webhook                → Deliver service
5. POST /api/merchant/confirm-fulfillment          → Trigger on-chain release
6. Receive payment.settled webhook                 → Funds received
7. POST /api/merchant/confirm-fulfillment          → Mark COMPLETED

Full Reference

For complete parameter definitions, return formats, and HTTP signing details, refer to the Skill file directly:

• Merchant Skill (primary): skill-merchant.md
• HTTP REST API: RESTful API
• CLI Reference: CLI docs
• Webhook spec: RFC-009