Documentation

Tout ce dont vous avez besoin pour intégrer Toreador dans votre application.

REST API

Référence complète de l'API HTTP pour générer des QR codes et créer des sessions de paiement.

TypeScript SDK

Le SDK officiel @toreador/sdk pour Node.js, Deno et les runtimes edge.

Webhooks

Notifications HTTPS signées HMAC-SHA256 quand vos sessions changent d'état.

REST API

Authentification & URL de base

Toutes les requêtes API nécessitent une clé API Pro. Ajoutez-la dans le header X-API-Key.

URL de base https://toreador.io/api/v1/public

Limite de débit 100 requêtes par heure par clé

Clés maximum 3 par compte

POST

/generate-qr

Public · sans clé

Génère une image QR code en base64 pour les tokens natifs, avec les détails de session.

Tier public gratuit (anonyme). Cet endpoint ne nécessite pas de clé API pour les tokens natifs (BTC, ETH, SOL, POL, USDC sur Solana). Limite anonyme : 50 requêtes/heure et 200/jour par IP. Avec une clé Pro : 100/h, pas de cap quotidien. La réponse inclut un bloc _meta avec le tier et les compteurs.

Parameters

token*	`string` — BTC, ETH, SOL, POL, USDC (Solana)
chainId*	`string` — bitcoin, ethereum, solana, polygon, base
amount*	`string` — Montant en unité du token (ex: "0.001")
recipientAddress*	`string` — Adresse du wallet destinataire

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

Crée une session de données pour les tokens EVM (USDC, USDT) ou les intégrations DApp.

Parameters

token*	`string` — USDC, USDT, EURC
chainId*	`string` — ethereum, polygon, base
amount*	`string` — Montant en unité du token (ex: "50")
recipientAddress*	`string` — Adresse du wallet destinataire

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

Récupère le statut courant d'une session de paiement EVM (créée via /create-session).

Path Parameters

id*	`string` — L'ID de session retourné par /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
}

Statuts possibles : pending, submitted, confirming, completed, expired, failed.

GET

/history

Liste les 50 dernières générations de QR codes (créés 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

Liste les 50 dernières sessions de paiement EVM (créées 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
    }
  ]
}

Tokens & Blockchains supportés

Token	Blockchains	Méthode
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

Le SDK officiel @toreador/sdk fournit une interface TypeScript type-safe pour l'API Toreador. Compatible avec Node.js 18+, Deno et les navigateurs modernes.

Installation

Terminal

npm install @toreador/sdk

Démarrage rapide

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,...

Méthodes disponibles

client.qrcode.generate(params)

Génère un QR code pour les tokens natifs (BTC, ETH, SOL, POL) ou les tokens SPL Solana.

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

client.qrcode.history()

Liste les 50 dernières générations de QR codes.

Retourne: { payments: PaymentRecord[] }

client.sessions.create(params)

Crée une session de paiement pour les tokens EVM non-natifs (USDC, USDT, EURC).

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

client.sessions.list()

Liste les 50 dernières sessions de paiement.

Retourne: { sessions: SessionRecord[] }

client.sessions.getStatus(sessionId)

Récupère le statut d'une session de paiement.

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

Exemple : Session de paiement USDC

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' | ...

Gestion des erreurs

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
  }
}

Options du constructeur

Option	Type	Requis	Description
apiKey	string	Oui	Votre clé API (tdr_xxxx)
baseURL	string	No	URL de base de l'API. Par défaut : https://toreador.io/api/v1/public
fetch	function	No	Implémentation fetch custom. Par défaut : globalThis.fetch

Webhooks

Recevez en temps réel des événements signés HMAC-SHA256 quand vos sessions changent d'état. Configurez vos endpoints depuis le dashboard.

Évènements émis

Event	Déclenchement
session.created	Quand /create-session réussit
session.submitted	Le payeur a diffusé la transaction
session.confirming	Première confirmation on-chain
session.completed	Confirmations requises atteintes
session.expired	Délai de 15 minutes dépassé
session.failed	Transaction échouée on-chain

Vérification de signature

Chaque livraison inclut un header Toreador-Signature: t=<unix>,v1=<hex>. La signature est un HMAC-SHA256 sur la chaîne <timestamp>.<rawBody> avec le secret de votre endpoint. Toujours vérifier la signature avant de traiter l'évènement.

Headers envoyés

Toreador-Signature	t=1761123121,v1=0xabc...
Toreador-Event-Id	evt_xxx — idempotence côté consommateur
Toreador-Event-Type	session.completed
Toreador-Delivery-Id	whd_xxx
Toreador-Attempt	numéro de tentative (1, 2, 3, ...)

Exemple : Express + SDK officiel

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;
  }
});

Politique de retry

Si votre endpoint répond autre chose qu'un 2xx ou ne répond pas dans les 10 secondes, Toreador rejoue avec un backoff exponentiel : 0s, 5s, 5min, 30min, 2h, 5h, 10h, 24h, 48h (9 tentatives au total sur ~3 jours), puis statut failed. Un endpoint est désactivé automatiquement après 50 échecs consécutifs.

Les livraisons sont retentables manuellement depuis le dashboard. Idempotence côté consommateur : utilisez le header Toreador-Event-Id pour détecter les doublons.

Prêt à commencer ?

Créez un compte Pro pour obtenir votre clé API et commencer à intégrer Toreador.

Passer Pro