Documentation

Everything you need to integrate Toreador into your application.

REST API

Complete HTTP API reference for generating QR codes and creating payment sessions.

TypeScript SDK

The official @toreador/sdk for Node.js, Deno, and edge runtimes.

Webhooks

HMAC-SHA256-signed HTTPS notifications when your sessions change state.

REST API

Authentication & Base URL

All API requests require a Pro plan API key. Include it in the X-API-Key header.

Base URL https://toreador.io/api/v1/public

Rate limit 100 requests per hour per key

Max keys 3 per account

POST

/generate-qr

Public · no key

Generates a QR code image as base64 for native tokens, along with session details.

Free public tier (anonymous). No API key needed for native tokens (BTC, ETH, SOL, POL, USDC on Solana). Anonymous limit: 50 requests/hour, 200/day per IP. With a Pro key: 100/h, no daily cap. The response includes a _meta block with tier and counters.

Parameters

token*	`string` — BTC, ETH, SOL, POL, USDC (Solana)
chainId*	`string` — bitcoin, ethereum, solana, polygon, base
amount*	`string` — Amount in token unit (e.g. "0.001")
recipientAddress*	`string` — Destination wallet address

cURL

curl -X POST https://toreador.io/api/v1/public/generate-qr \
  -H "X-API-Key: tdr_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "BTC",
    "chainId": "bitcoin",
    "amount": "0.001",
    "recipientAddress": "bc1q..."
  }'

Response (200 OK)

{
  "success": true,
  "type": "native",
  "qrData": "bitcoin:bc1q...?amount=0.001",
  "qrCodeURL": "data:image/png;base64,iVBORw0KGgo...",
  "token": { "symbol": "BTC", "name": "Bitcoin", "decimals": 8 },
  "chain": { "id": "bitcoin", "name": "Bitcoin", "symbol": "BTC" },
  "amount": "0.001",
  "recipientAddress": "bc1q..."
}

POST

/create-session

Creates a data session for EVM tokens (USDC, USDT) or DApp integrations.

Parameters

token*	`string` — USDC, USDT, EURC
chainId*	`string` — ethereum, polygon, base
amount*	`string` — Amount in token unit (e.g. "50")
recipientAddress*	`string` — Destination wallet address

cURL

curl -X POST https://toreador.io/api/v1/public/create-session \
  -H "X-API-Key: tdr_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "USDC",
    "chainId": "ethereum",
    "amount": "50",
    "recipientAddress": "0x..."
  }'

Response (200 OK)

{
  "success": true,
  "sessionId": "ses_987654321",
  "securityCode": "4F2A9B",
  "url": "/pay/ses_987654321",
  "expiresAt": 1761123476,
  "expiresIn": 600,
  "token": { "symbol": "USDC", "name": "USD Coin", "decimals": 6 },
  "chain": { "id": "ethereum", "name": "Ethereum", "symbol": "ETH" },
  "amount": "50",
  "recipientAddress": "0x..."
}

GET

/payment/:id/status

Retrieves the current status of an EVM payment session (created via /create-session).

Path Parameters

id*	`string` — The session ID returned by /create-session

cURL

curl https://toreador.io/api/v1/public/payment/ses_987654321/status \
  -H "X-API-Key: tdr_your_key_here"

Response (200 OK)

{
  "success": true,
  "sessionId": "ses_987654321",
  "status": "completed",
  "token": "USDC",
  "chainId": "ethereum",
  "amount": "50",
  "recipientAddress": "0x...",
  "txHash": "0xabc...",
  "confirmations": 3,
  "requiredConfirmations": 3,
  "expiresAt": 1761123476,
  "completedAt": 1761123121
}

Possible statuses: pending, submitted, confirming, completed, expired, failed.

GET

/history

Lists your 50 most recent QR code generations (created via /generate-qr).

cURL

curl https://toreador.io/api/v1/public/history \
  -H "X-API-Key: tdr_your_key_here"

Response (200 OK)

{
  "success": true,
  "payments": [
    {
      "id": "req_123",
      "type": "native",
      "chainId": "bitcoin",
      "token": "BTC",
      "amount": "0.001",
      "recipientAddress": "bc1q...",
      "createdAt": 1761122876
    }
  ]
}

GET

/sessions

Lists your 50 most recent EVM payment sessions (created via /create-session).

cURL

curl https://toreador.io/api/v1/public/sessions \
  -H "X-API-Key: tdr_your_key_here"

Response (200 OK)

{
  "success": true,
  "sessions": [
    {
      "id": "ses_987654321",
      "status": "completed",
      "token": "USDC",
      "chainId": "ethereum",
      "amount": "50",
      "recipientAddress": "0x...",
      "txHash": "0xabc...",
      "confirmations": 3,
      "requiredConfirmations": 3,
      "expiresAt": 1761123476,
      "submittedAt": 1761123000,
      "completedAt": 1761123121,
      "createdAt": 1761122876
    }
  ]
}

Supported Tokens & Chains

Token	Chains	Method
BTC	bitcoin	generate-qr
ETH	ethereum, polygon, base	generate-qr
SOL	solana	generate-qr
POL	polygon	generate-qr
USDC	ethereum, polygon, base, solana	create-session / generate-qr (Solana)
USDT	ethereum, polygon, base	create-session
EURC	ethereum, base	create-session

TypeScript SDK

The official @toreador/sdk provides a type-safe TypeScript interface for the Toreador API. Compatible with Node.js 18+, Deno, and modern browsers.

Installation

Terminal

npm install @toreador/sdk

Quick Start

TypeScript

import Toreador from "@toreador/sdk";

// Initialize the client
const client = new Toreador({ apiKey: "tdr_your_key_here" });

// Generate a Bitcoin QR code
const qr = await client.qrcode.generate({
  token: "BTC",
  chainId: "bitcoin",
  amount: "0.001",
  recipientAddress: "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
});

console.log(qr.qrCodeURL); // data:image/png;base64,...

Available Methods

client.qrcode.generate(params)

Generate a QR code for native tokens (BTC, ETH, SOL, POL) or Solana SPL tokens.

Returns: { success, type, qrData, qrCodeURL, token, chain, amount, recipientAddress }

client.qrcode.history()

List your last 50 QR code generations.

Returns: { payments: PaymentRecord[] }

client.sessions.create(params)

Create a payment session for non-native EVM tokens (USDC, USDT, EURC).

Returns: { sessionId, url, expiresIn, ... }

client.sessions.list()

List your last 50 payment sessions.

Returns: { sessions: SessionRecord[] }

client.sessions.getStatus(sessionId)

Check the status of a payment session.

Returns: { status: 'pending' | 'submitted' | 'confirming' | 'completed' | 'expired' | 'failed', ... }

Example: USDC Payment Session

TypeScript

import Toreador from "@toreador/sdk";

const client = new Toreador({ apiKey: "tdr_your_key_here" });

// Create a USDC payment session on Ethereum
const session = await client.sessions.create({
  token: "USDC",
  chainId: "ethereum",
  amount: "100",
  recipientAddress: "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18",
});

console.log(session.url);       // Payment page URL
console.log(session.expiresIn); // Seconds until expiry

// Check status later
const status = await client.sessions.getStatus(session.sessionId);
console.log(status.status); // 'pending' | 'completed' | ...

Error Handling

TypeScript

import { Toreador, ToreadorError } from "@toreador/sdk";

try {
  await client.qrcode.generate({ /* ... */ });
} catch (err) {
  if (err instanceof ToreadorError) {
    console.error(err.message); // "Missing required fields: ..."
    console.error(err.status);  // 400
    console.error(err.body);    // Full error response
  }
}

Constructor Options

Option	Type	Required	Description
apiKey	string	Yes	Your API key (tdr_xxxx)
baseURL	string	No	API base URL. Defaults to https://toreador.io/api/v1/public
fetch	function	No	Custom fetch implementation. Defaults to globalThis.fetch

Webhooks

Receive HMAC-SHA256-signed events in real time when your sessions change state. Configure endpoints from your dashboard.

Emitted events

Event	Trigger
session.created	When /create-session succeeds
session.submitted	Payer has broadcast the transaction
session.confirming	First on-chain confirmation
session.completed	Required confirmations reached
session.expired	15-minute expiry passed
session.failed	Transaction failed on-chain

Signature verification

Every delivery includes a Toreador-Signature: t=<unix>,v1=<hex> header. The signature is HMAC-SHA256 over <timestamp>.<rawBody> with your endpoint secret. Always verify the signature before processing the event.

Headers sent

Toreador-Signature	t=1761123121,v1=0xabc...
Toreador-Event-Id	evt_xxx — consumer-side idempotency
Toreador-Event-Type	session.completed
Toreador-Delivery-Id	whd_xxx
Toreador-Attempt	attempt number (1, 2, 3, ...)

Example: Express + official SDK

TypeScript

import { webhooks, WebhookSignatureError } from "@toreador/sdk";
import express from "express";

const app = express();

// IMPORTANT : raw body, pas du JSON parsé — la signature porte sur les bytes exacts
app.post("/webhook", express.raw({ type: "application/json" }), async (req, res) => {
  try {
    const event = await webhooks.constructEvent(
      req.body.toString("utf8"),
      req.headers["toreador-signature"] as string,
      process.env.TOREADOR_WEBHOOK_SECRET!
    );

    if (event.type === "session.completed") {
      // fulfill order, update DB, send receipt, etc.
    }

    res.sendStatus(204);
  } catch (err) {
    if (err instanceof WebhookSignatureError) return res.sendStatus(400);
    throw err;
  }
});

Retry policy

If your endpoint returns non-2xx or does not respond within 10 seconds, Toreador retries with exponential backoff: 0s, 5s, 5min, 30min, 2h, 5h, 10h, 24h, 48h (9 attempts total over ~3 days), then status failed. An endpoint is auto-disabled after 50 consecutive failures.

Deliveries can be manually retried from the dashboard. Consumer-side idempotency: use the Toreador-Event-Id header to detect duplicates.

Ready to get started?

Create a Pro account to get your API key and start integrating Toreador.

Go Pro