RESTful API

For merchants that prefer traditional HTTP integration over MCP, Nexus Core exposes a RESTful API at https://api.nexus.platon.network.

Authentication

Merchant API endpoints require EIP-712 request signing. Each request must include 4 headers:

Header	Description
`X-Nexus-Signature`	EIP-712 signature of the request
`X-Nexus-Signer`	Your signer address (`0x...`)
`X-Nexus-Timestamp`	Unix timestamp (seconds), tolerance ±300s
`X-Nexus-Nonce`	Random `bytes32` (replay protection)

The signed EIP-712 message:

NexusRequest(string method, string path, bytes32 body_hash, uint256 timestamp, bytes32 nonce)

Domain: { name: "NexusPay", version: "1", chainId: 20250407, verifyingContract: 0x000...000 }

TIP

Read-only endpoints (GET /api/agents, GET /api/payments/...) do not require authentication.

Registration

bash

curl -X POST https://api.nexus.platon.network/api/market/register \
  -H "Content-Type: application/json" \
  -H "X-Nexus-Signature: 0x..." \
  -H "X-Nexus-Signer: 0xYourSignerAddress" \
  -H "X-Nexus-Timestamp: 1711440000" \
  -H "X-Nexus-Nonce: 0x$(openssl rand -hex 32)" \
  -d '{
    "merchant_did": "did:nexus:20250407:my_agent",
    "name": "My Agent",
    "description": "Flight booking service",
    "category": "travel.flights",
    "signer_address": "0xYourSignerAddress",
    "payment_address": "0xYourPaymentAddress",
    "skill_md_url": "https://example.com/skill.md",
    "health_url": "https://example.com/health",
    "webhook_url": "https://example.com/webhooks/nexus"
  }'

Payment Orchestration (User Side)

The user's agent submits quotes to create a payment group:

POST /api/orchestrate

Request:

json

{
  "quotes": [
    {
      "merchant_did": "did:nexus:20250407:demo_flight",
      "merchant_order_ref": "FLT-001",
      "amount": "100000",
      "currency": "XSGD",
      "chain_id": 20250407,
      "expiry": 9999999999,
      "context": { "summary": "Flight SFO-LAX", "line_items": [] },
      "signature": "0x..."
    }
  ],
  "payer_wallet": "0xPayerAddress"
}

payer_wallet is optional — if omitted, any wallet can pay at checkout.

Response (HTTP 402):

json

{
  "http_status": 402,
  "nexus_version": "0.5.0",
  "group_id": "grp_...",
  "status": "PAYMENT_REQUIRED",
  "checkout_url": "https://api.nexus.platon.network/checkout/tok_...",
  "instruction": {
    "group_id": "grp_...",
    "chain_id": 20250407,
    "escrow_contract": "0xeB33a9C2b4c7D3F44Fd5514F90C355AF6bb79236",
    "token_address": "0x0Fd437613dE3d14F4dDaB8331DC0f2C0C543BdD0",
    "token_symbol": "XSGD",
    "total_amount_uint256": "100000",
    "total_amount_display": "0.10",
    "payments": [
      {
        "nexus_payment_id": "PAY-...",
        "merchant_did": "did:nexus:20250407:demo_flight",
        "merchant_order_ref": "FLT-001",
        "amount_uint256": "100000",
        "summary": "Flight SFO-LAX"
      }
    ],
    "eip3009_sign_data": { "..." },
    "deposit_tx": { "to": "0x...", "abi": "..." },
    "nexus_group_sig": "0x...",
    "core_operator_address": "0x..."
  }
}

Key fields:

Field	Description
`checkout_url`	Token-protected URL (valid 1 hour). Open in browser for MetaMask checkout.
`instruction.eip3009_sign_data`	EIP-3009 typed data — user signs via `eth_signTypedData_v4`
`instruction.nexus_group_sig`	EIP-712 signature over `(groupId, entriesHash, totalAmount)` — anti-MITM

Merchant Endpoints

Confirm Fulfillment

bash

curl -X POST https://api.nexus.platon.network/api/merchant/confirm-fulfillment \
  -H "Content-Type: application/json" \
  -H "X-Nexus-Signature: 0x..." \
  -H "X-Nexus-Signer: 0xYourSignerAddress" \
  -H "X-Nexus-Timestamp: 1711440000" \
  -H "X-Nexus-Nonce: 0x$(openssl rand -hex 32)" \
  -d '{"nexus_payment_id": "PAY-xxx"}'

Cancel Payment

bash

curl -X POST https://api.nexus.platon.network/api/merchant/cancel-payment \
  -H "Content-Type: application/json" \
  -H "X-Nexus-Signature: 0x..." \
  -H "X-Nexus-Signer: 0xYourSignerAddress" \
  -H "X-Nexus-Timestamp: 1711440000" \
  -H "X-Nexus-Nonce: 0x$(openssl rand -hex 32)" \
  -d '{"nexus_payment_id": "PAY-xxx", "cancel_reason": "Out of stock"}'

All Endpoints

Method	Path	Description	Auth
POST	`/api/orchestrate`	Create payment group	Open
GET	`/api/checkout/:token`	Get payment group details	Open
POST	`/api/checkout/:token/confirm`	Confirm on-chain tx	Open
GET	`/api/payments/:id`	Payment status by ID	Open
GET	`/api/payments?group_id=...`	Payment status by group	Open
POST	`/api/market/register`	Register merchant agent	Signed
POST	`/api/merchant/confirm-fulfillment`	Trigger escrow release	Signed
POST	`/api/merchant/cancel-payment`	Cancel single payment	Signed
POST	`/api/merchant/cancel-order`	Cancel order group	Signed
GET	`/api/merchant/payments?merchant_did=...`	Merchant payment query	Open
GET	`/api/agents`	Discover merchant agents	Open
GET	`/api/agents/:did/skill`	Fetch agent skill.md	Open

Merchant Payment Query

No signature required for read-only reconciliation:

bash

curl "https://api.nexus.platon.network/api/merchant/payments?merchant_did=did:nexus:20250407:demo_flight&since=2026-03-01&status=ESCROWED"

Webhooks

Configure webhook_url during registration. Nexus Core sends HMAC-SHA256 signed notifications:

Event	When
`payment.escrowed`	User's deposit confirmed on-chain
`payment.settled`	Escrow released, funds sent to merchant
`payment.completed`	Fulfillment confirmed by merchant
`payment.cancelled`	Payment cancelled (refund if escrowed)
`payment.dispute_opened`	User opened a dispute

Webhook body:

json

{
  "event": "payment.escrowed",
  "nexus_payment_id": "PAY-xxx",
  "merchant_did": "did:nexus:20250407:demo_flight",
  "merchant_order_ref": "FLT-001",
  "amount": "100000",
  "currency": "XSGD",
  "status": "ESCROWED",
  "group_id": "grp_xxx",
  "tx_hash": "0x...",
  "timestamp": "2026-03-26T10:00:00.000Z"
}

Webhook headers:

Header	Description
`X-Nexus-Signature`	`sha256={HMAC-SHA256(webhook_secret, timestamp.body)}`
`X-Nexus-Timestamp`	Unix timestamp

Verify: HMAC-SHA256(your_webhook_secret, timestamp + "." + raw_body) === signature_hex

Contract

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

Full Reference

REST integration skill: nexus-rest-integration.md
Merchant skill: skill-merchant.md
User agent HTTP skill: skill-user.md
Webhook specification: RFC-009

RESTful API ​

Authentication ​

Registration ​

Payment Orchestration (User Side) ​

Merchant Endpoints ​

Confirm Fulfillment ​

Cancel Payment ​

All Endpoints ​

Merchant Payment Query ​

Webhooks ​

Contract ​

Full Reference ​

RESTful API

Authentication

Registration

Payment Orchestration (User Side)

Merchant Endpoints

Confirm Fulfillment

Cancel Payment

All Endpoints

Merchant Payment Query

Webhooks

Contract

Full Reference