REST API
Toreador's public HTTP API: generate crypto QR codes and create non-custodial payment sessions. Toreador never holds funds — every payment moves directly from payer to merchant wallet, on-chain.
https://toreador.io/api/v1/public
Machine-readable spec: openapi.json (OpenAPI 3.1).
Authentication
Most endpoints require an API key, passed in the X-API-Key header. The key identifies your account; your entitlements (plan, quota) are evaluated on every request. Generate keys from your dashboard.
tor_test_…
Testnet sandbox, open to everyone, outside quota. For development and testing.
tor_live_…
Production (mainnet). Subject to plan and on-chain-confirmed payment quota.
Rate limits
Rate limiting is per account (not per key). Exceeding it returns 429 with a Retry-After header. Every endpoint requires a key (the free plan includes one).
- Per-minute rate by plan (
X-RateLimit-*headers on every response).
| Plan | API rate | API keys | On-chain-confirmed payments / mo |
|---|---|---|---|
| Free | 10/min | 1 | Unlimited |
| Starter | 30/min | 1 | 150 |
| Pro | 120/min | 3 | 1000 |
| Plus | 600/min | 10 | 5000 |
| Entreprise | Unlimited | Unlimited | Unlimited |
Default grid values; your exact limit may vary by region and is shown in your dashboard. The keyed rate is per account (creating multiple keys does not multiply it).
Idempotency
For POST requests, add an Idempotency-Key header: replaying with the same key returns the original response (Idempotent-Replayed: true header), without re-creating a session. Same key + different body → 409.
Errors
Errors use a dual-shape envelope: error stays a string (back-compat) and error_details carries the typed detail (code, type, message, request_id, doc_url).
Error codes
| code | HTTP | When |
|---|---|---|
| missing_field | 400 | A required field is missing (token, chainId, amount, recipientAddress). |
| invalid_parameter | 400 | Unknown token, chain or format. |
| invalid_address | 400 | The recipient address is not valid for this chain. |
| invalid_amount | 400 | Amount not a decimal or out of range (0–1,000,000). |
| incompatible_token_chain | 400 | This token does not exist on this chain (e.g. BTC on Ethereum). |
| wrong_endpoint | 400 | Wrong endpoint: native ↔ ERC-20 (use the other one). |
| missing_api_key | 401 | API key missing. |
| invalid_api_key | 401 | API key invalid or revoked. |
| quota_exceeded | 402 | Monthly on-chain-confirmed payment quota exhausted (carries used/limit/upgrade_url). |
| forbidden | 403 | The key is not allowed to access this resource. |
| recipient_blocked | 403 | The recipient address is on a sanctions list: no QR code or payment page is created. |
| session_not_found | 404 | Session not found (or expired/purged). |
| payment_not_found | 404 | Payment not found. |
| idempotency_conflict | 409 | Same Idempotency-Key reused with a different body. |
| no_rail | 409 | No usable rail for this payment: the token/network pair is not creditable by the connected exchange wallet, or the issuer of the stablecoin has frozen the receiving address on that network. |
| rate_limited | 429 | Rate exceeded (Retry-After header). |
| internal_error | 500 | Unexpected server error — retry, then contact support. |
Pagination
List endpoints (/history, /sessions) are cursor-paginated: pass limit (1–100, default 20) and cursor. The response carries has_more and next_cursor — feed the latter back for the next page.
Endpoints
Endpoint reference
/ping
Key requiredVerifies connectivity and the API key. Returns the environment (test/live), plan and API version. Ideal for a 'Test connection' button.
No parameters.
Response codes
Request
Response
Try this endpoint
The request goes to the live API, on your behalf. Use a test key (tor_test_…) — a live call creates real data. The key is never stored or sent elsewhere.
/account
Key requiredAccount status: effective plan, environment, subscription (trial vs paid), monthly quota (used/limit/remaining) and limits (rate, keys, wallets). The subscription field (status trialing/active, realPlan, trialEndsAt as epoch s, trialDaysRemaining) should drive the plan badge — not plan alone, which is 'plus' during the trial.
No parameters.
Response codes
Request
Response
Try this endpoint
The request goes to the live API, on your behalf. Use a test key (tor_test_…) — a live call creates real data. The key is never stored or sent elsewhere.
/tokens
Key requiredSupported payment matrix (tokens × chains), derived from config (single source of truth, contracts verified on-chain). Fetch it instead of hardcoding the list → stays in sync when chains/tokens are added. Only PAYABLE pairs are returned (native, or ERC-20/SPL with a contract). Contracts depend on the key's env (test/live).
No parameters.
Response codes
Request
Response
Try this endpoint
The request goes to the live API, on your behalf. Use a test key (tor_test_…) — a live call creates real data. The key is never stored or sent elsewhere.
/screen
Key requiredChecks whether a crypto address is on the SANCTIONS lists we consult (OFAC, EU, UK and Swiss lists downloaded by us; plus the Chainalysis on-chain oracle for EVM addresses). Returns sanctioned (true/false), or null when the address can't be verified (invalid, unsupported chain, oracle unavailable). Call it before sending or receiving funds. Result is cached (~24h freshness).
sanctioned: null = could not verify (invalid address, stale list, oracle unavailable). Compliance information, not legal advice.address (query, required) — the address to check.
Response codes
Request
Response
Try this endpoint
The request goes to the live API, on your behalf. Use a test key (tor_test_…) — a live call creates real data. The key is never stored or sent elsewhere.
/generate-qr
Key requiredGenerates a QR code (base64 PNG) encoding a standard payment URI (BIP-21, EIP-681, Solana Pay). For native tokens (BTC, ETH, SOL, POL) and USDC on Solana. For ERC-20 stablecoins on EVM, use /create-session.
X-RateLimit-* headers on every response.Body
| token* | string — BTC, ETH, SOL, POL, USDC (Solana) |
| chainId* | string — bitcoin, ethereum, polygon, base, solana |
| amount* | string — Canonical decimal (e.g. "0.001") |
| recipientAddress* | string — Recipient address (validated for the chain) |
| format | string — Output format: png (default, base64 data-URI), svg (vector markup) or text (block characters to print in a terminal; returned as qrCodeText). |
| textBackground | string — For format: text: background of the terminal the text will be shown in, dark (default) or light. A wrong background gives an inverted QR code many phones cannot read. |
Response codes
Request
Response
Try this endpoint
The request goes to the live API, on your behalf. Use a test key (tor_test_…) — a live call creates real data. The key is never stored or sent elsewhere.
/create-session
Key requiredCreates a hosted payment session (wallet-to-wallet payment, directly to the merchant's address) for ERC-20 stablecoins (USDC, USDT, EURC) on Ethereum, Polygon and Base. Returns a /pay URL to share with the payer. The session expires 15 minutes after creation.
tor_test_…) creates a testnet sandbox session, outside quota — ideal for plugin development. A live key (tor_live_…) counts toward the monthly on-chain-confirmed payment quota (402 when exhausted).Body
| token* | string — USDC, USDT, EURC, PYUSD, USDG, RLUSD, USAT, OUSD |
| chainId* | string — ethereum, polygon, base |
| amount* | string — Canonical decimal (e.g. "100") |
| recipientAddress* | string — Recipient EVM address (validated at the core) |
Response codes
Request
Response
Try this endpoint
The request goes to the live API, on your behalf. Use a test key (tor_test_…) — a live call creates real data. The key is never stored or sent elsewhere.
/wallets
Key requiredLists (READ-ONLY) the account's receiving addresses. Each wallet returns address, family, label, source, ownershipProven (true = ownership proven by a signed message, or address read from a connected exchange), custodial (true = deposit address of the MERCHANT's own exchange account, e.g. Binance/Coinbase, held by the exchange, never by Toreador) and acceptedRails: null = no restriction (self-hosted, all networks of the family); otherwise the (token, chain) pairs the custodial source credits TO THIS address. IMPORTANT: for a custodial wallet, restrict your payment matrix to acceptedRails — an uncredited pair is not offered to the payer (the exchange would not credit it and the funds would be lost). Adding/removing wallets is done in the authenticated dashboard (passkey) — never via the API.
No parameters.
Response codes
Request
Response
Try this endpoint
The request goes to the live API, on your behalf. Use a test key (tor_test_…) — a live call creates real data. The key is never stored or sent elsewhere.
/checkout
Key requiredCreates a FIAT-denominated checkout (USD/EUR): the merchant sets a fiat amount, the payer connects a wallet on the hosted /pay page (wallet-to-wallet payment, directly to the merchant's address) and picks the stablecoin and chain. Preferred for integrations (the merchant needn't understand 'USDC on Base').
conversion:"off" (default) offers only same-currency stablecoins (USD→USDC/USDT). conversion:"on" also offers stablecoins of the other currency: the amount due is computed from an indicative reference rate (source and timestamp recorded), fixed when the rail is picked. Toreador performs no conversion: the payer sends that stablecoin directly to the merchant's wallet.Body
| amount* | number — Amount in CURRENCY (e.g. 50), not in token |
| currency* | string — USD, EUR |
| recipientAddress* | string — Receiving address (EVM 0x… or Solana). Supplied by YOUR system — handles rotation. |
| description | string — Label shown to the payer (≤ 500 chars) |
| conversion | string — "off" (default) or "on" |
| acceptNative | boolean — Also offer NATIVE crypto payment (ETH/POL); amount computed at the current rate (indicative reference). The merchant bears the volatility. |
| reference | string — Free reference (e.g. order id), echoed on the checkout, /payment/{id} and /sessions — to correlate the payment on your side (≤ 255 chars). |
Response codes
Request
Response
Try this endpoint
The request goes to the live API, on your behalf. Use a test key (tor_test_…) — a live call creates real data. The key is never stored or sent elsewhere.
/webhooks
Key requiredRegisters (or updates, IDEMPOTENT by URL) the account's webhook endpoint to receive events via PUSH. An integration calls it automatically after Connect. Returns the HMAC secret ONCE — store it encrypted. The URL must be public HTTPS and, if the key was issued via Connect, on the key's domain.
Body
| url* | string — Public HTTPS endpoint (on the key's domain) |
| events | string[] — Subscribed events (default: session.completed/failed/expired) |
| description | string — Label (≤ 200 chars) |
Response codes
Request
Response
Try this endpoint
The request goes to the live API, on your behalf. Use a test key (tor_test_…) — a live call creates real data. The key is never stored or sent elsewhere.
/payment/{id}
Key requiredRetrieves a unified Payment object — native QR (type: native) or ERC-20 session (type: session) — with its event timeline. ALSO accepts a checkout id (co_…): it resolves to that checkout's payment (ideal for tracking an order by its checkoutId, without knowing the session id).
Path parameter
| id* | string — Payment / session id, OR a checkout id (co_…) |
Response codes
Request
Response
Try this endpoint
The request goes to the live API, on your behalf. Use a test key (tor_test_…) — a live call creates real data. The key is never stored or sent elsewhere.
/payment/{id}/status
Key requiredReturns the current status of a payment session. For real-time payer-side tracking, the /pay page uses an SSE stream; server-side, prefer signed webhooks (see below).
Path parameter
| id* | string — Session id (returned by /create-session) |
Response codes
Request
Response
Try this endpoint
The request goes to the live API, on your behalf. Use a test key (tor_test_…) — a live call creates real data. The key is never stored or sent elsewhere.
/establishments
Key requiredLists (READ-ONLY) the establishments of the key: id, name, isDefault. An id is used as establishment_id, when creating a payment request as well as to filter /sessions, /history and /export.
No parameters.
Response codes
Request
Response
Try this endpoint
The request goes to the live API, on your behalf. Use a test key (tor_test_…) — a live call creates real data. The key is never stored or sent elsewhere.
/history
Key requiredPaginated list of QR codes generated by the key's organization and its team (most recent first). Each item carries establishmentId and establishmentName. A key only returns the payments of its own environment: a live key never returns test payments, a test key returns only test payments.
Query
| limit | integer — 1–100, default 20 |
| cursor | string — Opaque cursor (next_cursor from the previous page) |
| establishment_id | string — Only the payments of this establishment (an id from GET /establishments) |
Response codes
Request
Response
Try this endpoint
The request goes to the live API, on your behalf. Use a test key (tor_test_…) — a live call creates real data. The key is never stored or sent elsewhere.
/sessions
Key requiredPaginated list of the payment sessions of the key's organization and its team (most recent first). Each item carries establishmentId and establishmentName. A key only returns the payments of its own environment: a live key never returns test payments, a test key returns only test payments.
fxRate, fxSource and fxQuotedAt describe the indicative reference rate used to compute the token amount (value, source, timestamp). Toreador performs no conversion: token and amount are what the payer sent on-chain, from their own wallet, to the merchant's wallet.Query
| limit | integer — 1–100, default 20 |
| cursor | string — Opaque pagination cursor |
| establishment_id | string — Only the payments of this establishment (an id from GET /establishments) |
Response codes
Request
Response
Try this endpoint
The request goes to the live API, on your behalf. Use a test key (tor_test_…) — a live call creates real data. The key is never stored or sent elsewhere.
/export
Key requiredACCOUNTING export of on-chain-confirmed payments, with the reference rate (invoiced amount ↔ amount paid on-chain + indicative rate + source + timestamp + tx). As CSV (default, downloadable) or JSON. Optional period (from/to). With format=quickbooks, xero, odoo or pennylane: the bank-transaction import file of that software, one currency per file. A key only returns the payments of its own environment: a live key never returns test payments, a test key returns only test payments.
settlementToken, settlementChain and settlementAmount = token, network and amount actually paid on-chain by the payer, from their own wallet, to the merchant's wallet (Toreador settles nothing); fxRate, fxSource and fxQuotedAt = the indicative reference rate used to compute that amount, its source and timestamp (informational, no conversion performed); invoiceAmount / invoiceCurrency = the amount invoiced by the merchant.Query
| format | string — "csv" (default) or "json": the full export. "quickbooks", "xero", "odoo" or "pennylane": a file for the bank-transaction import of that accounting software |
| currency | string — Import files only: the currency of the file. Optional when the period holds a single currency |
| from | integer — Period start (epoch s, on completed_at) |
| to | integer — Period end (epoch s) |
| establishment_id | string — Only the payments of this establishment (an id from GET /establishments) |
Response codes
Request
Response
Try this endpoint
The request goes to the live API, on your behalf. Use a test key (tor_test_…) — a live call creates real data. The key is never stored or sent elsewhere.
Webhooks
To be notified of status changes server-side (no polling), register a webhook endpoint. Toreador POSTs an HMAC-SHA256-signed event (Toreador-Signature: t=…,v1=… header) on every transition.
session.createdsession.submittedsession.confirmingsession.completedsession.expiredsession.failedcheckout.created
Changelog
v1.0.0The major version lives in the URL (/v1/). Backward-compatible changes (new fields, optional params, endpoints) are listed here and never break v1; a breaking change would ship as /v2/. Every response carries the API-Version header.
- AddedPublic API v1: QR generation (native + Solana SPL), hosted ERC-20 payment sessions (wallet-to-wallet, directly to the merchant's address), payment & status retrieval, paginated history and sessions.
- AddedHMAC-SHA256 signed webhooks (session.created/submitted/confirming/completed/expired/failed).
- AddedTest/live keys (testnet sandbox, outside quota); QR output as
pngorsvgvia theformatparam. - Added
API-Versionheader on every response; typed error envelope + idempotency (Idempotency-Key). - AddedEstablishments:
GET /establishments,establishmentIdandestablishmentNameon payments,establishment_idfilter on lists and export; a key reads the payments created by the whole team. - AddedAccounting import files:
GET /export?format=quickbooks|xero|odoo|pennylane, one currency per file. - AddedEnvironments are separate: a live key only reads live payments, a test key only reads test payments (lists, export, read by id).