API and webhooks

Production API base:

https://api.settlebolt.com

Send JSON with Content-Type: application/json. Write requests with JSON bodies are capped at 5 MiB, with smaller caps on support ticket and feedback routes.

Dashboard APIs use the logged-in dashboard session token:

Authorization: Bearer <dashboard-session-token>

Only verified-email accounts can access the dashboard API. Mutating requests made through admin impersonation are rejected unless they are read-only.

The Agent API is the supported surface for AI agents and backend automations. It requires an active paid Pro or Business subscription, uses scoped API keys from Developers, and is limited to merchant operations that are safe to automate. Agent keys are not accepted on dashboard endpoints and cannot manage wallets, billing, team members, or account deletion.

Required header:

Authorization: Bearer sb_live_...

Machine-readable OpenAPI:

https://settlebolt.com/openapi.json

The WhatsApp channel lets a merchant pair a WhatsApp sender to a scoped SettleBolt agent. It uses the same paid Pro/Business, verified-email, plan-current, scope, wallet, and audit-log checks as the Agent API, but no API key is shown in WhatsApp.

Supported WhatsApp commands include:

send invoice to FPSHEAVEN info@example.com for EUR 1200 due July 16 using USDC on Base
create payment link Website deposit for EUR 500 using USDC on Base
add customer FPSHEAVEN info@example.com
payments
customers
status

WhatsApp cannot manage wallets, billing, team members, account deletion, dashboard sessions, or other high-risk settings.

Custom checkout domains may call only public checkout and public asset APIs. The public checkout response intentionally returns public RPC fallbacks only, never configured provider secrets.

Create and send an invoice with an agent key:

curl -X POST "$API/api/agent/invoices/send" \
  -H "Authorization: Bearer $SETTLEBOLT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customerName": "FPSHEAVEN",
    "customerEmail": "billing@example.com",
    "invoiceNumber": "INV-0008",
    "amount": 120000,
    "currency": "EUR",
    "token": "USDC",
    "chain": "base",
    "dueDate": "2026-07-16",
    "lineItems": [
      { "description": "Brand and website design", "qty": 1, "unitPrice": 90000 },
      { "description": "Hosting setup", "qty": 1, "unitPrice": 30000 }
    ]
  }'

Create a payment link:

curl -X POST "$API/api/payment-links" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Website design",
    "description": "Deposit",
    "amount": 120000,
    "currency": "EUR",
    "token": "USDC",
    "chain": "base"
  }'

Create a draft invoice:

curl -X POST "$API/api/invoices" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customerName": "FPSHEAVEN",
    "customerEmail": "billing@example.com",
    "invoiceNumber": "INV-0008",
    "amount": 120000,
    "currency": "EUR",
    "token": "USDC",
    "chain": "base",
    "dueDate": "2026-07-16",
    "lineItems": [
      { "description": "Brand and website design", "qty": 1, "unitPrice": 90000 },
      { "description": "Hosting setup", "qty": 1, "unitPrice": 30000 }
    ]
  }'

List payments with filters:

curl "$API/api/payments?status=confirmed,overpaid&chain=base&source=invoices" \
  -H "Authorization: Bearer $TOKEN"

Webhook management is available only during an active paid Pro or Business billing period.

Event headers:

X-SettleBolt-Event: payment.confirmed
X-SettleBolt-Event-Id: <event-id>
X-SettleBolt-Timestamp: 1783100000
X-SettleBolt-Signature: t=1783100000,v1=<hmac>

Signature base string:

<timestamp>.<event_id>.<raw_json_body>

Node verification shape:

import crypto from "node:crypto";

function verifySettleBoltWebhook(rawBody, headers, secret) {
  const eventId = headers["x-settlebolt-event-id"];
  const timestamp = headers["x-settlebolt-timestamp"];
  const sig = headers["x-settlebolt-signature"];
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${eventId}.${rawBody}`)
    .digest("hex");
  return sig && sig.includes(`v1=${expected}`);
}

Request body:

{
  "type": "payment.confirmed",
  "created_at": "2026-07-03T12:00:00.000Z",
  "data": {
    "payment_id": "…",
    "merchant_id": "…",
    "status": "confirmed",        // confirmed | underpaid | overpaid
    "chain": "base",
    "token": "USDC",
    "amount": "1200000000",       // raw on-chain units, as a string
    "amount_eur_cents": 120000,   // null for unmatched priced-native (BTC/SOL/TRX)
    "tx_hash": "0x…",
    "invoice_id": null,
    "payment_link_id": "…",
    "payer_address": "0x…",
    "merchant_address": "0x…"
  }
}

• Webhook endpoints must be public HTTPS URLs on port 443.
• Private, loopback, link-local, CGNAT, metadata, credentialed, IPv6 literal, and redirect-following webhook targets are rejected.
• Webhook delivery fetches use manual redirects and an 8 second timeout.
• Webhook secrets are encrypted at rest and the raw secret is only shown once.
• Payment recording validates chain, token, recipient wallet, and idempotency before crediting.
• Do not put dashboard session tokens, API keys, or webhook secrets in browser code.

Most errors return JSON with an error string and an appropriate HTTP status.

{ "error": "Unsupported chain or token" }