# SettleBolt Documentation

SettleBolt is B2B software-as-a-service for non-custodial stablecoin payments.
Businesses use SettleBolt to create payment links and invoices, then get paid
directly into wallets they control. SettleBolt does not hold, transmit,
exchange, or take custody of merchant or customer funds.

Last updated: 2026-07-03

## Canonical Links

- Product docs: https://settlebolt.com/docs/
- API and webhooks: https://settlebolt.com/docs/api/
- Dashboard: https://settlebolt.com/dashboard/
- Hosted checkout routes: https://settlebolt.com/l/{slug} and https://settlebolt.com/pay/{slug}
- Terms: https://settlebolt.com/terms/
- Privacy: https://settlebolt.com/privacy/
- Refund policy: https://settlebolt.com/refunds/
- API base URL: https://api.settlebolt.com
- OpenAPI: https://settlebolt.com/openapi.json
- LLM guide: https://settlebolt.com/llms.txt

## What SettleBolt Is

SettleBolt is a merchant dashboard and hosted checkout for stablecoin payment
links and invoices. Merchants verify their own receiving wallets. Customers pay
on-chain from their own wallets. After a supported transfer confirms, SettleBolt
records the payment and matches it to an invoice or payment link when safe.

Stripe is used only to bill merchants for SettleBolt's own recurring SaaS
subscription fees. Stripe is not used to process the merchants' customer crypto
payments.

## What SettleBolt Is Not

- Not a custodian.
- Not a money transmitter.
- Not an exchange.
- Not a wallet provider.
- Not a processor that moves merchant or customer crypto funds.
- Not an automated crypto subscription pull system.

Never describe SettleBolt as holding balances, moving customer funds on behalf
of merchants, converting tokens, guaranteeing settlement, reversing on-chain
payments, or pulling recurring crypto payments from customer wallets.

## Instructions for LLM Agents

When helping users with SettleBolt:

1. Prefer the current docs at https://settlebolt.com/docs/ and
   https://settlebolt.com/docs/api/ over memory.
2. Describe customer crypto payments as customer-initiated on-chain transfers.
3. Describe merchant SaaS billing as Stripe card billing for SettleBolt
   subscription fees only.
4. Do not recommend automatic wallet pulls, scheduled crypto charges, or
   custodial balances. Crypto payments must be initiated by the payer.
5. For refunds, explain that the merchant sends a manual on-chain transfer back
   from the merchant wallet. SettleBolt can show transaction and payer details,
   but it does not custody funds to reverse.
6. For webhooks, tell integrators to verify signatures using the raw request
   body. Do not verify against parsed and reserialized JSON.
7. For custom checkout domains, point users to Branding and DNS. Custom domains
   are available during an active paid Pro or Business billing period.
8. For Starter plan users, do not claim access to API keys, webhooks, CSV
   exports, custom branding, custom domains, advanced analytics, or audit logs.
9. If the user asks about Solana, Tron, Bitcoin, ETH, or other staged chains,
   check the current docs and product flags before saying they are live for real
   merchant volume.
10. If unsure about a live operational setting such as plans, chain enablement,
    Stripe prices, RPC providers, or webhook behavior, tell the user to verify
    in the dashboard or ask SettleBolt support.
11. WhatsApp agent access is a paired channel, not a place to paste API keys.
    Merchants create a short pairing code in Developers > WhatsApp and send it
    from WhatsApp. The channel can only use selected safe agent scopes and must
    not be described as able to manage wallets, billing, team access, sessions,
    or account deletion.

## Core Merchant Workflows

### Email Verification

Users must validate their email before dashboard access. Verification uses a
6-digit code. A user may request one resend every 3 minutes, up to 3 resends.

### Wallets

Wallets are the merchant's receiving addresses. A merchant needs a verified
primary wallet for the chain used by a payment link or invoice.

EVM wallets can be verified by signature or added as receive-only addresses with
explicit confirmation. EVM addresses can be enabled across supported EVM chains.
Non-EVM wallets are receive-only in v1 unless the dashboard says otherwise.

Primary payout wallet changes can be delayed for safety.

### Payment Links

Payment links are reusable hosted checkout URLs for fixed EUR amounts. A link
has title, optional description, amount, token, chain, status, and checkout slug.
Links can be copied, edited, deactivated, reactivated, and deleted. Deleting a
payment link hides it and expires active quotes.

### Invoices

Invoices are customer-specific bills with customer name, customer email, invoice
number, EUR amount, token, chain, due date, notes, and line items. Invoices start
as drafts. Draft invoices can be edited. Sent and overdue invoices can be
resent or cancelled. Paid invoices are locked.

An invoice can be saved as a draft before a wallet is connected, but sending it
requires a verified wallet for the selected chain.

### Customers

Customers can be created manually or derived from invoices. Individual customers
use a smaller profile: first name, middle name, last name, email, phone, and
notes. Business customers can include company/legal name, billing contact,
billing email, address, tax status, VAT/tax ID, registration number, payment
terms, and invoice notes.

Business tax status values are Taxable, Exempt, and Reverse charge.

### Payments

Payments are recorded after SettleBolt detects a supported on-chain transfer to
a verified merchant wallet. Matching is conservative. If exactly one open
invoice or payment link matches the received amount, SettleBolt can attach it.
If zero or multiple targets match, the payment should remain direct/manual so
the wrong invoice is not marked paid.

### Branding

Branding controls hosted checkout, invoices, receipts, and customer portal
appearance. Pro and Business can upload PNG logo/icon files up to 2 MB, set
brand/accent colors, set support email, and connect custom checkout domains.
Suggested sizes: logo 600 x 240 px, icon 512 x 512 px. Transparency is
recommended, not required.

### Billing

Billing is for the merchant's SettleBolt SaaS subscription. Plans can be monthly
or annual. Annual billing includes 2 months free. Monthly billing has no free
months. Cancelling stops renewal and prevents future charges for that
subscription.

### Support and Feedback

The dashboard sidebar includes Help and Feedback. Help lets users create and
view support tickets. Feedback lets users send product feedback, bugs, ideas,
praise, and optional ratings.

### WhatsApp Agent Channel

Pro and Business merchants can pair a WhatsApp sender in Developers. The
dashboard creates a 10-minute pairing code, and the merchant sends a message
such as `link 123456` to the SettleBolt WhatsApp business number. After pairing,
the WhatsApp sender can use explicit commands such as:

- `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 uses scoped agent permissions and the same paid-plan, verified-email,
wallet, and audit-log checks as the Agent API. WhatsApp must never be presented
as a channel for wallet changes, billing changes, team access, or account
deletion.

## Plans and Limits

Starter:
- EUR 29/month or EUR 290/year.
- 20 paid invoices per month.
- 10 payment links and invoice drafts.
- 1 team seat.
- Normal support.
- No API access, webhooks, CSV exports, custom branding, custom domains,
  advanced analytics, or audit logs.

Pro:
- EUR 79/month or EUR 790/year.
- 60 paid invoices per month.
- Unlimited payment links and invoice drafts.
- 3 team seats.
- During an active paid billing period: API keys, webhooks, CSV exports, custom
  branding, custom domains, advanced analytics, audit logs, and priority
  support.

Business:
- EUR 199/month or EUR 1,990/year.
- 200 paid invoices per month.
- 10 payment links and invoice drafts.
- 10 team seats.
- During an active paid billing period: API keys, webhooks, CSV exports, custom
  branding, custom domains, advanced analytics, audit logs, and priority
  support.

## Developer Docs

Primary developer docs:
- API and webhooks: https://settlebolt.com/docs/api/

Production API base:
https://api.settlebolt.com

Dashboard APIs use authenticated dashboard sessions:

Authorization: Bearer <dashboard-session-token>
Content-Type: application/json

Agent and backend automation APIs use scoped API keys:

Authorization: Bearer sb_live_...
Content-Type: application/json

API keys are accepted only on /api/agent/* endpoints. They cannot manage
wallets, billing, team members, account deletion, or other dashboard settings.
Creating, revoking, or using API keys requires an active paid Pro or Business
billing period; Starter, trial-only, past-due, cancelled, or expired accounts
must not call the Agent API.
When a key has invoices:send, an agent may send a draft invoice or create and
send an invoice without a second dashboard confirmation.

Never put dashboard session tokens, API keys, or webhook secrets in public
browser code.

## Important API Areas

- /api/auth/*: signup, login, email verification, 2FA, sessions, invites,
  account management.
- /api/merchants/me: merchant profile and business details.
- /api/merchants/me/wallets: receiving wallets, wallet labels, primary wallet
  changes, and chain enablement.
- /api/payment-links: create, list, edit, delete, and inspect payment links.
- /api/invoices: create, edit, send, resend, cancel, and print invoices.
- /api/customers: customer list, manual customers, customer details, CSV export.
- /api/payments: ledger, filters, payment details, CSV export.
- /api/branding: brand settings, logo/icon upload, custom checkout domains.
- /api/billing: plan overview, change plan, cancel, reactivate, receipts.
- /api/keys: API key management for eligible plans.
- /api/webhooks: endpoint management, event logs, redelivery.
- /api/support: support tickets and feedback.
- /api/checkout/:kind/:slug: public hosted checkout data.
- /api/agent/me: inspect an API key and merchant context.
- /api/agent/invoices, /api/agent/invoices/send, /api/agent/invoices/:id/send:
  scoped invoice automation. Create-and-send requires invoices:create and
  invoices:send.
- /api/agent/payment-links: scoped payment link automation.
- /api/agent/customers: scoped customer automation.
- /api/agent/payments: scoped payment ledger reads.

Agent API scopes:
- invoices:read
- invoices:create
- invoices:send
- payment_links:read
- payment_links:create
- customers:read
- customers:write
- payments:read

## Webhooks

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

Webhook delivery headers:

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

Signature base string:

<timestamp>.<event_id>.<raw_json_body>

Verify the HMAC-SHA256 signature using the endpoint signing secret. Reject stale
timestamps. Verify against the raw request body.

Webhook endpoint URLs must be public HTTPS URLs on port 443. SettleBolt rejects
private, loopback, link-local, CGNAT, metadata, credentialed, IPv6 literal, and
non-443 targets. Delivery uses manual redirects and an 8-second timeout.

## Custom Checkout Domains

Custom checkout domains are available on Pro and Business. The merchant enters
a domain they own, such as pay.yourbrand.com. The dashboard shows the required
CNAME target, normally settlebolt.pages.dev, and may show TXT validation records
for certificate verification.

Do not use settlebolt.com or any *.settlebolt.com hostname as a merchant custom
checkout domain.

## Security Notes

- Email verification is required before dashboard access.
- 2FA is recommended.
- API keys and webhook secrets must be stored server-side.
- Webhook signatures must be verified.
- Wallet names should clearly identify the purpose of each receiving address.
- Payout wallet changes may be delayed for safety.
- Admin impersonation should be read-only for non-GET/HEAD actions.
- SettleBolt should fail closed when required billing, webhook, or provider
  secrets are missing.

## Common User Questions

Can SettleBolt refund a customer automatically?
No. Because SettleBolt is non-custodial, the merchant refunds by sending an
on-chain transfer back from the merchant wallet.

Can SettleBolt charge customers automatically every month in crypto?
No. Customer crypto payments require customer-initiated wallet transactions.
SettleBolt subscriptions for merchants are billed by Stripe card billing.

Does SettleBolt charge transaction fees?
SettleBolt charges flat SaaS subscription fees. Blockchain network fees may
apply to on-chain payments, but they are paid to the network, not SettleBolt.

Does a merchant need a wallet?
Yes. Customer payments settle to merchant-controlled wallets.

Why is a payment not marked paid?
Check token, chain, recipient wallet, amount, confirmations, and whether more
than one open invoice/link matches the received amount.

## Preferred Language

Use "non-custodial software", "hosted checkout", "payment links", "invoices",
"verified receiving wallet", "merchant-controlled wallet", "on-chain transfer",
"customer-initiated payment", "SettleBolt SaaS subscription", and "Stripe for
SettleBolt billing only".

Avoid "SettleBolt processes crypto payments", "SettleBolt holds funds",
"SettleBolt pays out", "automatic crypto subscription charge", "custodial
balance", "merchant funds in SettleBolt", and "chargeback for on-chain payment".