Docs / MCP

MCP.

Hosted at mcp.settle.xxx. OAuth-style auth, streamable HTTP transport. Your agent gets a scoped token and the full Settle surface as MCP tools.

Connect.

Add the server to your MCP-aware client (Claude Desktop, Cursor, Windsurf, Continue, custom). The first call opens a browser tab where you authorize the agent against your Settle account; the agent gets a scoped token bound to your merchant_id and current mode (test or live).

claude_desktop_config.json

{
  "mcpServers": {
    "settle": {
      "url": "https://mcp.settle.xxx",
      "transport": "streamable-http"
    }
  }
}

Always start with get_started. It returns the exact next tool the agent should call for the merchant’s current state, so the agent doesn’t have to guess.

Orientation.

Three tools that tell the agent who it’s talking to and what to do next.

get_started

Args

none

Returns

Onboarding checklist for the current merchant: what's done, what's next, exact next tool to call. The single most important tool — call it first.

whoami

Args

none

Returns

merchant_id, display_name, mode (test | live), enabled chains, verified domain.

get_integration_pattern

Args

framework: nextjs | hono | fastapi | express

Returns

Working snippet — server route that creates an invoice + redirects, webhook handler, env vars needed, install command. The same code lives at /docs/integration-patterns.

Example output of get_started:

> get_started()

{
  "merchant": "acme",
  "mode": "test",
  "checklist": [
    { "step": "register_payout_address", "done": false, "chain": "base" },
    { "step": "register_webhook",        "done": false },
    { "step": "create_invoice",          "done": false }
  ],
  "next": "register_payout_address"
}

Onboarding.

The merchant has to register and verify a payout address per chain before any invoice can settle. Domains and branding are optional.

register_payout_address

Args

chain, address

Returns

Challenge string for the merchant to sign with the same wallet.

confirm_payout_address

Args

chain, address, signature

Returns

{ verified: boolean }.

list_payout_addresses

Args

none

Returns

Registered addresses with verification status, per chain.

verify_domain

Args

domain

Returns

{ record_type: 'TXT', name, value } to add to DNS, plus polling instructions.

enable_usdt_ethereum

Args

min_invoice_usd? (default 1000, floor 500)

Returns

Confirmation. USDT-Ethereum is hidden from checkout below this amount.

get_branding

Args

none

Returns

logo_url, accent_hex, auto-extracted preview.

set_branding

Args

logo_url, accent_hex

Returns

Confirmation.

Invoices.

An invoice is the only payable thing in Settle. The MCP server computes payment_options server-side from merchant config, so the agent doesn’t have to know which chains apply.

create_invoice

Args

amount_usd, accepted_currencies?, customer_email?, description?, metadata?, return_url?, cancel_url?, expires_in?, idempotency_key?

Returns

{ id, checkout_url, status, expires_at, payment_options[] }.

get_invoice

Args

invoice_id

Returns

Full invoice with status; payment_tx if paid.

list_invoices

Args

filters: status, date range, customer_email, metadata key

Returns

Array of invoices.

void_invoice

Args

invoice_id

Returns

Confirmation. No-op if already paid.

simulate_payment

Args

invoice_id (test mode only)

Returns

Marks invoice paid and fires the webhook. The fastest way to test your invoice.paid handler.

Example call:

> create_invoice({
    amount_usd: 49.00,
    customer_email: "buyer@example.com",
    metadata: { order_id: "ord_123" },
    return_url: "https://acme.com/orders/success",
    cancel_url: "https://acme.com/cart"
  })

{
  "id": "inv_01HZX9V0K1Q3Y2T7M3N4D5R8S0",
  "checkout_url": "https://pay.settle.xxx/c/inv_01HZX9V0K1Q3Y2T7M3N4D5R8S0",
  "status": "open",
  "expires_at": "2026-04-27T12:30:00Z",
  "payment_options": [ /* see below */ ]
}

Webhooks.

Register a URL, choose events, get a signing secret back. Use the secret to verify the HMAC-SHA256 signature on each delivery — see Webhooks.

register_webhook

Args

url, events[]

Returns

Signing secret. Store this — it does not appear again.

list_webhooks

Args

none

Returns

Array.

update_webhook

Args

id, optional fields

Returns

Confirmation.

delete_webhook

Args

Returns

Confirmation.

list_webhook_events

Args

filters

Returns

Recent deliveries with status, response code, and payload snapshot.

replay_webhook_event

Args

event_id

Returns

Confirmation. Re-delivers as a new attempt.

API keys.

Stripe-style split between secret and publishable keys. sk_live_… / sk_test_… are server-side only and full-power. pk_live_… / pk_test_… are client-safe, origin-bound to your verified domain, and limited to create_invoice + get_invoice.

create_api_key

Args

name, mode: test | live

Returns

Key value (shown once).

list_api_keys

Args

none

Returns

Array (no values).

revoke_api_key

Args

key_id

Returns

Confirmation.

Webhook events.

The full event list. Most integrations only need invoice.paid.

Event	Fires when
`invoice.created`	An invoice is created. Useful for analytics, not required.
`invoice.paid`	The router event is finalized on chain. Most important.
`invoice.expired`	The invoice ttl elapsed without a settled payment.
`invoice.voided`	The merchant called `void_invoice`.
`invoice.underpaid`	v2 only — for the forwarder pattern.
`payout.completed`	Settlement finalized to the merchant’s wallet.
`domain.verified`	DNS TXT record was found and matched.
`address.verified`	A payout address signature challenge was completed.
`key.rotated`	A 90-day key rotation just happened.
`key.suspicious_use`	An unusual call pattern triggered the heuristic.

Payment options shape.

Every create_invoice response includes the chains and amounts that will be displayed to the customer.

{
  "payment_options": [
    { "currency": "USDC", "chain": "base", "amount": "100.000000", "network_fee_estimate_usd": 0.01 }
  ]
}

Was this helpful?

PreviousFees NextREST API