# Toreador — full reference for LLM agents

This document is intended for AI agents and search crawlers. It contains
everything an LLM needs to answer questions about Toreador or to drive its
public API on behalf of an authenticated user. It is updated as the product
evolves.

## What Toreador is

Toreador is a non-custodial crypto QR code generator and a small payment API
on top of it. The free public web app generates QR codes that encode standard
payment URIs (BIP21 for Bitcoin, EIP-681 for Ethereum, Solana Pay for Solana).
The Pro plan adds a public REST API, a TypeScript SDK, hosted payment pages
for ERC-20 stablecoins, webhooks, and a dashboard.

The architecture is strictly non-custodial: Toreador's servers never hold
private keys, never receive funds, never route money. Every payment moves
directly from the payer's wallet to the merchant's wallet on-chain. Toreador
only generates URIs, hosts informational payment pages, watches the chain
for confirmations, and notifies the merchant.

## Plans and limits

| Plan | Price | Native QR codes (web app) | ERC-20 sessions (web app) | API access |
|------|-------|---------------------------|---------------------------|------------|
| Free (logged-in) | $0/mo | unlimited | 2/day | — |
| Plus | $4.99/mo | unlimited | 10/day | — |
| Pro  | $20/mo | unlimited | unlimited | full REST + SDK + MCP |

**Anonymous public API tier** (no signup, no API key) on `POST /generate-qr`:
50 requests/hour and 200 requests/day per IP. Native tokens only (BTC, ETH,
SOL, POL, USDC on Solana). Anyone — including AI agents like Claude, ChatGPT,
Perplexity — can hit this without authentication.

Pro plan rate limit on the public API: 100 requests per hour per API key.
Maximum API keys per Pro account: 1 (active at any time).

## Supported tokens and chains

| Token | Chains | Method |
|-------|--------|--------|
| BTC   | bitcoin | POST /generate-qr (native) |
| ETH   | ethereum, polygon, base | POST /generate-qr (native) |
| SOL   | solana | POST /generate-qr (native) |
| POL   | polygon | POST /generate-qr (native) |
| USDC  | ethereum, polygon, base | POST /create-session (ERC-20) |
| USDC  | solana | POST /generate-qr (Solana Pay SPL) |
| USDT  | ethereum, polygon, base | POST /create-session (ERC-20) |
| EURC  | ethereum, base | POST /create-session (ERC-20) |

## Authentication

`POST /generate-qr` is **public and unauthenticated** for native tokens —
anonymous calls are rate-limited per IP (50/h, 200/day). All other endpoints
require an API key:

    X-API-Key: tdr_...

Generate keys at https://toreador.io/dashboard#api on a Pro account.
Keys are 240-bit secrets prefixed with `tdr_`. They are shown once at
creation and stored hashed server-side; if lost, generate a new key.

## Public API reference

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

### POST /generate-qr

Generate a QR code for native tokens or Solana SPL tokens.

Request:

    POST /api/v1/public/generate-qr
    X-API-Key: tdr_...
    Content-Type: application/json

    {
      "token": "BTC",
      "chainId": "bitcoin",
      "amount": "0.001",
      "recipientAddress": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh"
    }

Response 200:

    {
      "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..."
    }

For Solana SPL tokens (USDC on Solana), `type` is `"spl"` and the
returned `qrData` is a Solana Pay URL.

Errors:
- 400 `"Use POST /create-session for EVM non-native tokens"` if you call
  this with USDT / USDC / EURC on EVM chains. Use /create-session instead.
- 400 `"Invalid amount"` for amounts `<=0` or `>1_000_000`.

### POST /create-session

Create a hosted payment session for ERC-20 stablecoins on EVM chains.

Request:

    POST /api/v1/public/create-session
    X-API-Key: tdr_...
    Content-Type: application/json

    {
      "token": "USDC",
      "chainId": "ethereum",
      "amount": "100",
      "recipientAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18"
    }

Response 200:

    {
      "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": "100",
      "recipientAddress": "0x..."
    }

The `url` field is a Toreador-hosted page where the payer connects their
wallet (MetaMask, Coinbase Wallet, etc.) and signs the ERC-20 transfer.
Sessions expire 15 minutes after creation. The merchant should display the
`securityCode` to the payer, who must verify it on the hosted page.

### GET /payment/:id/status

Poll the status of a payment session.

Request:

    GET /api/v1/public/payment/ses_987654321/status
    X-API-Key: tdr_...

Response 200:

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

Possible status values: `pending`, `submitted`, `confirming`,
`completed`, `expired`, `failed`.

### GET /history

List the 50 most recent QR code generations of the authenticated user.

### GET /sessions

List the 50 most recent payment sessions of the authenticated user.

## Webhooks

Register HTTPS endpoints at https://toreador.io/dashboard#webhooks (Pro plan).

Events emitted:
- `session.created` — when /create-session succeeds
- `session.submitted` — when the payer broadcasts 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

Each delivery includes:
- `Toreador-Signature: t=<unix>,v1=<hex>` — HMAC-SHA256 of `<t>.<rawBody>` with the endpoint secret
- `Toreador-Event-Id: evt_...` — for consumer-side idempotency
- `Toreador-Event-Type: session.completed`
- `Toreador-Delivery-Id: whd_...`
- `Toreador-Attempt: 1`

Body format:

    {
      "id": "evt_...",
      "type": "session.completed",
      "createdAt": 1761123121,
      "data": { "sessionId": "ses_...", "status": "completed", ... }
    }

Retry schedule on non-2xx response: 0s, 5s, 5min, 30min, 2h, 5h, 10h, 24h, 48h
(9 attempts total, then status `failed`). Endpoints are auto-disabled after
50 consecutive failures.

## MCP server (for AI agents)

Toreador ships an official Model Context Protocol server: `@toreador/mcp-server`.
It runs locally and exposes Toreador as MCP tools to Claude Desktop, Cursor,
Windsurf, and any other MCP-capable assistant. Documented at
https://toreador.io/mcp

**Without a Pro API key:** 1 free tool (`toreador_generate_qr`) for native
tokens. Anonymous, IP-rate-limited. No setup beyond installing the package.

**With a Pro API key (`TOREADOR_API_KEY=tdr_...`):** 5 tools including
ERC-20 sessions, status polling, and history.

**Tools:**
- `toreador_generate_qr` (free) — Generate a payment QR code for a native token (BTC, ETH, SOL, POL) or USDC on Solana. Returns a data-URL ready to display.
- `toreador_create_session` (pro) — Create an ERC-20 stablecoin payment session (USDC, USDT, EURC on Ethereum, Polygon, Base) with hosted payment page and webhook events.
- `toreador_get_session_status` (pro) — Poll the status of an existing payment session (pending, submitted, confirming, completed, expired, failed).
- `toreador_list_sessions` (pro) — List recent payment sessions for the authenticated account, with filters by status and pagination.
- `toreador_check_compatibility` (pro) — Check whether a given token + chain pair is supported, before attempting to generate a QR or session.

**Claude Desktop config (Pro):**

```json
{
  "mcpServers": {
    "toreador": {
      "command": "npx",
      "args": ["-y", "@toreador/mcp-server"],
      "env": {
        "TOREADOR_API_KEY": "tdr_..."
      }
    }
  }
}
```

For free-tier usage, omit the `env` block. The user can simply ask the
assistant *"generate a Bitcoin QR code for 0.001 BTC to bc1q..."* and the
assistant will call `toreador_generate_qr` directly.

## SDK

```typescript
import { Toreador, webhooks, WebhookSignatureError } from "@toreador/sdk";

const client = new Toreador({ apiKey: process.env.TOREADOR_API_KEY! });

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

console.log(session.url); // hosted payment page

// Webhook receiver
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
    }
    res.sendStatus(204);
  } catch (err) {
    if (err instanceof WebhookSignatureError) return res.sendStatus(400);
    throw err;
  }
});
```

## Roadmap (public)

- Sandbox / testnet API keys (Sepolia, Polygon Amoy, Base Sepolia, Solana Devnet)
- Tron USDT support
- Official MCP server for direct Claude/ChatGPT integration
- Long-tail token-specific landing pages

## Contact and source

- Docs: https://toreador.io/docs
- Pricing: https://toreador.io/go-pro
- OpenAPI: https://toreador.io/openapi.json
- npm: https://www.npmjs.com/package/@toreador/sdk
- Twitter / X: https://x.com/Toreador_QR