llm402.ai API

Pay-per-request LLM inference. No accounts. No API keys. Just pay and prompt.

llm402.ai provides OpenAI-compatible endpoints gated by HTTP 402 micropayments. Send a request, get an invoice, pay it, re-send with proof of payment. Your prompt is processed by one of 400+ models across multiple providers.

Four payment rails are supported. Every 402 response includes all available options -- pick whichever works for your client:

Model Naming

Short names work for all models -- no provider prefix needed:

• deepseek-v3.2, claude-sonnet-4.6, gpt-5.4
• Full IDs also work: deepseek/deepseek-v3.2, anthropic/claude-sonnet-4.6
• For auto-routing: use "model": "auto" and read X-Route-Model header from the 402 response

Model in URL Path

All inference endpoints support specifying the model in the URL path instead of the request body:

• /v1/chat/completions/deepseek-v3.2
• /v1/images/generations/FLUX.1-schnell
• /v1/videos/generations/kling-2.1-master

If both URL path and body contain a model, the body model takes priority. The /v1/models endpoint returns all available model IDs.

Quick Start

x402 (USDC on Base)

Pay with USDC stablecoins. No BTC needed. No gas for the payer.

L402 (Bitcoin Lightning)

Pay with Bitcoin over the Lightning Network. Instant settlement, 21-sat minimum.

Endpoints

All inference endpoints are OpenAI-compatible. Base URL: https://llm402.ai

OpenAI-Compatible

Ollama-Compatible

Ollama Examples

# Chat via Ollama-compatible endpoint (model in path)
curl -s -X POST https://llm402.ai/api/chat/deepseek-v3.2 \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"hello"}],"stream":false}'

# Text generation via Ollama-compatible endpoint
curl -s -X POST https://llm402.ai/api/generate/deepseek-v3.2 \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Explain Bitcoin in one sentence","stream":false}'

# List all models with pricing and endpoints
curl -s https://llm402.ai/api/tags | jq '.models[] | {name, price_sats}'

Utility

Estimate Cost

Pre-authorize requests by checking the cost before paying. This endpoint is free and requires no authentication. Useful for MCP clients, agents, and budgeting.

curl -s -X POST https://llm402.ai/v1/estimate-cost \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "Explain quantum computing"}],
    "max_tokens": 500,
    "pref": "balanced"
  }'

Response:

{
  "model": "deepseek-v3.2",
  "shortName": "deepseek-v3.2",
  "category": "general_knowledge",
  "confidence": 0.82,
  "rc": 100,
  "estimatedInputTokens": 8,
  "estimatedOutputTokens": 500,
  "costSats": 21,
  "costUsd": 0.000152,
  "btcPrice": 68000
}

Parameters

Response fields

Invoice Status

Poll the payment status of a Lightning invoice. Useful for wallet integrations that need to confirm payment before re-sending with the L402 header.

curl -s -X POST https://llm402.ai/api/invoice/status \
  -H "Content-Type: application/json" \
  -d '{
    "payment_hash": "a1b2c3d4...64hex",
    "macaroon": "AgEJ..."
  }'

# Before payment: { "paid": false }
# After payment:  { "paid": true, "preimage": "e5f6a7b8...64hex" }

x402 Protocol (USDC)

x402 uses EIP-3009 TransferWithAuthorization for gasless USDC payments on Base. The payer signs an off-chain authorization; the server settles it on-chain.

Network and Asset

Payment Flow

Send a normal inference request with no auth headers:

curl -s -D- -X POST https://llm402.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4.6",
    "messages": [{"role": "user", "content": "Say hello."}],
    "max_tokens": 50
  }'

The server responds with HTTP 402. The response body contains all payment information:

{
  "error": "Payment Required",
  "description": "claude-sonnet-4.6 inference, pay-per-request over Lightning, USDC, or Cashu",
  "price": 42,
  "model": "claude-sonnet-4.6",
  "provider": "llm402.ai",
  "max_tokens": 50,
  "estimated_input_tokens": 12,
  "invoice": "lnbc420n...",
  "macaroon": "AgEJ...",
  "paymentHash": "a1b2c3d4e5f6...64hex",
  "x402": {
    "price_usd": "0.000305",
    "network": "eip155:8453",
    "address": "0xe05cf38...",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "scheme": "exact"
  },
  "cashu": {
    "price_sats": 42,
    "unit": "sat",
    "description": "Send sat-denominated Cashu tokens in X-Cashu header. Server-configured mint allowlist — see /llms.txt for the current list."
  }
}

The response headers include all payment options:

HTTP/2 402
WWW-Authenticate: L402 macaroon="...", invoice="lnbc..."
Payment-Required: eyJzY2hlbWUiOiJleGFjdCIsIm5ldH...
Cache-Control: no-store

Payment-Required Header

Base64-encoded JSON in x402 v2 envelope format. Decode it and use accepts[0] for payment details:

{
  "x402Version": 2,
  "error": "Payment required",
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "amount": "3150",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "payTo": "0x...",
      "maxTimeoutSeconds": 120,
      "extra": {
        "name": "USD Coin",
        "version": "2"
      }
    }
  ],
  "resource": {
    "url": "https://llm402.ai/v1/chat/completions",
    "description": "LLM inference",
    "mimeType": "application/json"
  },
  "price": "$0.003150"
}

Build a TransferWithAuthorization signature using EIP-712 typed data.

EIP-712 Domain

const domain = {
  name: "USD Coin",        // from extra.name
  version: "2",            // from extra.version
  chainId: 8453,           // Base mainnet
  verifyingContract: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
};

EIP-712 Types

const types = {
  TransferWithAuthorization: [
    { name: "from",        type: "address" },
    { name: "to",          type: "address" },
    { name: "value",       type: "uint256" },
    { name: "validAfter",  type: "uint256" },
    { name: "validBefore", type: "uint256" },
    { name: "nonce",       type: "bytes32" },
  ]
};

Authorization Message

const now = Math.floor(Date.now() / 1000);
const nonce = "0x" + crypto.randomBytes(32).toString("hex");
const opt = paymentRequired.accepts[0];  // always use accepts[0]

const message = {
  from:        walletAddress,             // your address (payer)
  to:          opt.payTo,                 // from accepts[0]
  value:       BigInt(opt.amount),
  validAfter:  BigInt(now - 600),         // 10 min ago (clock skew buffer)
  validBefore: BigInt(now + 120),         // 2 min from now
  nonce:       nonce,
};

Construct the V2 payment payload and base64-encode it:

const opt = paymentRequired.accepts[0];  // always use accepts[0]
const payload = {
  x402Version: 2,
  resource: paymentRequired.resource,
  accepted: {
    scheme: opt.scheme,
    network: opt.network,
    amount: opt.amount,
    asset: opt.asset,
    payTo: opt.payTo,
    maxTimeoutSeconds: opt.maxTimeoutSeconds,
    extra: opt.extra
  },
  payload: {
    signature: signature,
    authorization: {
      from: walletAddress,
      to: opt.payTo,
      value: opt.amount,
      validAfter: (now - 600).toString(),
      validBefore: (now + 120).toString(),
      nonce: nonce
    }
  }
};

const paymentSignature = Buffer.from(JSON.stringify(payload)).toString("base64");

Re-send the same inference request with the Payment-Signature header:

curl -s -X POST https://llm402.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Payment-Signature: eyJ4NDAyVmVyc2lvbiI6Mix..." \
  -d '{
    "model": "claude-sonnet-4.6",
    "messages": [{"role": "user", "content": "Say hello."}],
    "max_tokens": 50
  }'

Response (HTTP 200):

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1712345678,
  "model": "claude-sonnet-4.6",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "Hello! How can I help you today?"
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 4,
    "completion_tokens": 10,
    "total_tokens": 14
  }
}

CORS

The server allows cross-origin x402 requests:

Access-Control-Allow-Headers: Content-Type, Authorization, Payment-Signature, X-Cashu, Mcp-Session-Id
Access-Control-Expose-Headers: X-Route-Model, X-Route-Category, Payment-Required, WWW-Authenticate, X-Cashu-Change

Nonce Replay Protection

Each signed authorization can only be used once. Replay protection is enforced both server-side and on-chain via EIP-3009 nonces.

L402 Protocol (Lightning)

L402 (formerly LSAT) combines HTTP 402 status codes with Lightning Network payments and macaroon-based authentication. It is the original payment protocol supported by llm402.ai.

Payment Flow

Curl Example

# Send a request with no auth -- get back a 402 with an invoice
curl -s -D- -X POST https://llm402.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v3.2",
    "messages": [{"role": "user", "content": "hi"}],
    "max_tokens": 50
  }'

# Response includes:
#   WWW-Authenticate: L402 macaroon="AgEJ...", invoice="lnbc210n1pn..."
#   Body: { "error": "Payment Required", "price": 21, "invoice": "lnbc...", "macaroon": "AgEJ...", ... }

# Pay the Lightning invoice with your wallet and get the preimage.
# Then resend the exact same request with the L402 Authorization header:

curl -s -X POST https://llm402.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: L402 AgEJbGxtNDAyLmFp...:a1b2c3d4e5f67890..." \
  -d '{
    "model": "deepseek-v3.2",
    "messages": [{"role": "user", "content": "hi"}],
    "max_tokens": 50
  }'

# Response: HTTP 200 with chat completion

WWW-Authenticate Header

The 402 response includes a WWW-Authenticate header with two components:

WWW-Authenticate: L402 macaroon="AgELbGxt...", invoice="lnbc50n1pn..."

Macaroon Caveats

Each macaroon is bound with first-party caveats that restrict its use. The server verifies all caveats on the paid request and rejects any that fail (fail-closed):

Authorization Header

After paying the Lightning invoice and receiving the preimage, send the authorization:

Authorization: L402 AgELbGxt...:abc123def456...

Format: L402 {base64_macaroon}:{hex_preimage}

The server verifies:

• The macaroon signature against the root key
• All caveats pass (path, expiry, tokens, model, etc.)
• The preimage hashes to the payment hash embedded in the macaroon identifier
• The preimage has not been used before (atomic Redis SET NX, burned before inference begins)

Balance Tokens (Prepaid)

Balance tokens let you prepay for multiple requests with a single Lightning payment or USDC transfer. Fund a balance once, then use Authorization: Bearer bal_... on any gated endpoint without per-request payment flows.

How It Works

Endpoints

Request a Lightning invoice to fund a new balance:

# Step 1: Request an invoice for 1000 sats
curl -s -X POST https://llm402.ai/v1/balance \
  -H "Content-Type: application/json" \
  -d '{"sats": 1000}'

# Response (402):
# { "payment_hash": "a1b2c3...", "invoice": "lnbc10u...", "sats": 1000, "expires_in": 600 }

After paying the invoice, poll with the payment hash to get your token. (An unknown payment_hash returns 404 Unknown payment_hash; pending invoices return 200 {"paid": false}.)

# Step 2: Poll until paid
curl -s -X POST https://llm402.ai/v1/balance \
  -H "Content-Type: application/json" \
  -d '{"payment_hash": "a1b2c3d4e5f6...64hex"}'

# Before payment: { "paid": false }
# After payment:  { "paid": true, "token": "bal_xxxx...", "sats": 1000, "expires_at": "2026-05-03T..." }

curl -s -X POST https://llm402.ai/v1/balance \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer bal_xxxx..." \
  -d '{"action": "status"}'

# Response:
# { "sats": 850, "expires_at": "2026-05-03T...", "total_spent": 150, "requests": 7 }

Add sats to an existing balance:

# Get a top-up invoice
curl -s -X POST https://llm402.ai/v1/balance \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer bal_xxxx..." \
  -d '{"sats": 500}'

# Returns 402 with a new invoice. Pay it, then poll with payment_hash as above.

Fund with USDC (x402)

Fund a balance using USDC on Base instead of Lightning. Send a single POST with a Payment-Signature header carrying an EIP-3009 TransferWithAuthorization envelope — no 402 challenge flow is required from this endpoint. The server settles the USDC on-chain via the CDP facilitator, derives the sats to credit from the signed amount at its current BTC price, and returns the balance token in one round trip.

Decide how many sats you want to buy and convert to USDC atomic units (6 decimals) at a BTC price you are willing to pay. The server will re-derive sats from the signed USDC amount at its own BTC price — your body.sats hint is advisory and never authoritative.

Sign an off-chain authorization to transfer USDC on Base from your wallet to the server’s receiving address. The signing domain, asset, network, and payTo are identical to the values served in Payment-Required envelopes on other llm402 endpoints.

// Illustrative. Uses viem. Install: npm install viem
import { createWalletClient, http, parseSignature } from 'viem';
import { base } from 'viem/chains';
import { privateKeyToAccount } from 'viem/accounts';

const account = privateKeyToAccount(process.env.PRIV_KEY);
const client = createWalletClient({ account, chain: base, transport: http() });

// USDC on Base, 6 decimals. Example: $0.50 => 500000 atomic units.
const amountAtomic = '500000';
const payTo = '0x...';                     // llm402 receiving address (from any x402 envelope)
const usdc = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913';

// Random 32-byte nonce (hex). Must not be reused.
const nonce = '0x' + crypto.randomBytes(32).toString('hex');
const validAfter = 0n;
const validBefore = BigInt(Math.floor(Date.now() / 1000) + 120);

const signature = await client.signTypedData({
  domain: { name: 'USD Coin', version: '2', chainId: 8453, verifyingContract: usdc },
  types: {
    TransferWithAuthorization: [
      { name: 'from', type: 'address' },
      { name: 'to', type: 'address' },
      { name: 'value', type: 'uint256' },
      { name: 'validAfter', type: 'uint256' },
      { name: 'validBefore', type: 'uint256' },
      { name: 'nonce', type: 'bytes32' },
    ],
  },
  primaryType: 'TransferWithAuthorization',
  message: {
    from: account.address, to: payTo, value: BigInt(amountAtomic),
    validAfter, validBefore, nonce,
  },
});

// x402 v2 envelope — base64(JSON) for the Payment-Signature header
const envelope = {
  x402Version: 2,
  scheme: 'exact',
  network: 'eip155:8453',
  payload: {
    signature,
    authorization: {
      from: account.address, to: payTo, value: amountAtomic,
      validAfter: validAfter.toString(), validBefore: validBefore.toString(),
      nonce,
    },
  },
};
const paymentSignature = Buffer.from(JSON.stringify(envelope)).toString('base64');

The body may be omitted entirely, or may contain {"sats": N} as a hint for your own UX. The server ignores body.sats for accounting and derives sats from the signed USDC amount.

curl -s -X POST https://llm402.ai/v1/balance \
  -H "Content-Type: application/json" \
  -H "Payment-Signature: $PAYMENT_SIG" \
  -d '{"sats": 500}'

# 200 OK on success:
# { "paid": true, "token": "bal_xxxx...", "sats": 500, "credited": 500 }

To top up an existing balance, add Authorization: Bearer bal_... to the same request. The server caps the top-up at 50000 sats total and returns 400 if the signed amount would exceed the cap.

Once you have a bal_ token (from either the Lightning flow above or the USDC funding flow), include it as a Bearer auth on any gated endpoint:

curl -s -X POST https://llm402.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer bal_xxxx..." \
  -d '{
    "model": "deepseek-v3.2",
    "messages": [{"role": "user", "content": "Explain Lightning Network"}],
    "max_tokens": 200
  }'

Token Lifecycle

Cashu Tokens (Ecash)

Pay with Cashu ecash tokens -- instant, private Bitcoin micropayments with no Lightning channel required. Send tokens directly in the request header. If you overpay, the server returns change tokens.

How It Works

Request

Send a cashuB (v4) token in the X-Cashu header:

curl -s -X POST https://llm402.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "X-Cashu: cashuBo2F0gaJha..." \
  -d '{
    "model": "deepseek-v3.2",
    "messages": [{"role": "user", "content": "hello"}],
    "max_tokens": 100
  }'

Response Headers

Every successful Cashu-paid call emits the same pair of response headers, and the server always lists them in Access-Control-Expose-Headers so browser clients can read them:

These headers appear on every endpoint that accepts X-Cashu payment — /v1/chat/completions, /v1/embeddings, /v1/images/generations, and /v1/videos.

HTTP/2 200
Content-Type: application/json
X-Cashu-Consumed: true
X-Cashu-Change: cashuBo2F0gaJha...
Access-Control-Expose-Headers: X-Cashu-Consumed, X-Cashu-Change

The change token is a standard cashuB token. Import it with any Cashu wallet or present it on a subsequent request.

Constraints

MCP Server

llm402.ai provides a hosted Model Context Protocol (MCP) server. Connect from any MCP client — Claude Code, Claude Desktop, Cursor, or any tool that supports MCP. Six tools are available: text inference, image generation, video generation, model discovery, balance management, and funding.

Setup

Claude Code (~/.claude.json):

{
  "mcpServers": {
    "llm402": {
      "url": "https://llm402.ai/mcp",
      "headers": {
        "Authorization": "Bearer bal_YOUR_TOKEN_HERE"
      }
    }
  }
}

Claude Desktop (claude_desktop_config.json) — Claude Desktop only supports stdio MCP transport, so use the third-party mcp-remote bridge:

{
  "mcpServers": {
    "llm402": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://llm402.ai/mcp",
        "--header",
        "Authorization:Bearer bal_YOUR_TOKEN_HERE"
      ]
    }
  }
}

Replace bal_YOUR_TOKEN_HERE with your actual balance token. That’s it — the MCP client discovers all tools automatically. (mcp-remote is a community npm package; pin the version with [email protected] in production.)

Available Tools

Example: Text Inference

# Using curl against the MCP endpoint directly (JSON-RPC format)
curl -X POST https://llm402.ai/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer bal_YOUR_TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "llm402_inference",
      "arguments": {
        "prompt": "Explain quantum computing in one sentence.",
        "max_tokens": 100
      }
    },
    "id": 1
  }'

Example: Image Generation

curl -X POST https://llm402.ai/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer bal_YOUR_TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "llm402_image",
      "arguments": {
        "prompt": "A cyberpunk cityscape at night with neon lights",
        "model": "black-forest-labs/FLUX.1-schnell"
      }
    },
    "id": 1
  }'

OpenAI-Compatible Alternative

If your tool doesn't support MCP but accepts OPENAI_BASE_URL, the same balance token works directly:

export OPENAI_BASE_URL=https://llm402.ai/v1
export OPENAI_API_KEY=bal_YOUR_TOKEN

This works with Cursor, Aider, LangChain, the OpenAI Python SDK, and any tool that accepts a custom base URL.

Endpoint

MCP endpoint: https://llm402.ai/mcp

Protocol: Streamable HTTP (POST only). Each request is independently authenticated via the Authorization: Bearer bal_ header — no server-side session state is persisted between calls. (The Mcp-Session-Id CORS header is allowed for spec-compliant clients that send it, but the server doesn’t require or track it.) Responses are Server-Sent Events containing JSON-RPC results.

OpenClaw Plugin

Use llm402.ai from inside OpenClaw via the official @llm402/openclaw-provider plugin. All four payment rails supported: prepaid balance, Cashu ecash, USDC on Base, and Lightning. 400+ models.

npm install @llm402/openclaw-provider

Requires Node.js 22+. Includes a wallet CLI and the OpenClaw plugin.

The package ships a CLI for wallet management. Skip this step if you only need balance mode (Bearer token).

# Create a wallet (generates Nostr nsec + EVM keypair)
npx llm402-openclaw init

# Fund it with Lightning (prints a BOLT11 invoice — pay from any wallet)
npx llm402-openclaw fund 5000

# Check balance
npx llm402-openclaw balance

Your sats are stored locally as Cashu ecash proofs at ~/.llm402/wallet.json. From your perspective: you pay a Lightning invoice, your inference calls deduct from the Cashu balance. Run npx llm402-openclaw --help for all commands.

Pick a payment mode:

Balance mode (simplest — Bearer token, zero latency, no wallet):

{
  "paymentMode": "balance",
  "balanceToken": "bal_YOUR_TOKEN_HERE"
}

Cashu mode (pay with ecash — requires wallet from step 2):

# Reveal your nsec for the config below
LLM402_SHOW_SECRETS=1 npx llm402-openclaw init

{
  "paymentMode": "cashu",
  "cashuNsec": "nsec1..."
}

x402 mode (pay with USDC on Base — gasless, no ETH needed):

{
  "paymentMode": "x402",
  "evmPrivateKey": "0x..."
}

Lightning mode (pay L402 invoices by melting Cashu proofs):

{
  "paymentMode": "lightning",
  "cashuNsec": "nsec1..."
}

Wallet modes (cashu / x402 / lightning) start a local HTTP proxy on 127.0.0.1 that transparently handles the 402-and-pay cycle. OpenClaw only ever sees the final 200 response. See the plugin README for all modes.

CLI commands

Budget controls

Runaway cost protection. Both sats and USDC are tracked independently; either rail can reject a request before signing.

Security

This plugin runs locally and handles wallet keys. Do not install on shared systems, CI runners, or Codespaces. Wallet lives at ~/.llm402/wallet.json with 0600 permissions. Full threat model in the SECURITY.md.

Streaming

Add "stream": true to your request body to receive Server-Sent Events (SSE) as tokens are generated. The format follows the OpenAI streaming specification.

Request

curl -s -N -X POST https://llm402.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer bal_xxxx..." \
  -d '{
    "model": "deepseek-v3.2",
    "messages": [{"role": "user", "content": "Count to 5"}],
    "max_tokens": 100,
    "stream": true
  }'

Response Format

The server sends a series of data: lines. Each line is a JSON chunk with a delta object containing the next token(s):

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":1712345678,"model":"deepseek-v3.2","choices":[{"index":0,"delta":{"role":"assistant","content":"1"},"finish_reason":null}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":1712345678,"model":"deepseek-v3.2","choices":[{"index":0,"delta":{"content":", "},"finish_reason":null}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":1712345678,"model":"deepseek-v3.2","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":12,"completion_tokens":24,"total_tokens":36}}

data: [DONE]

Consuming the Stream

# Stream tokens to stdout (use -N to disable buffering)
curl -s -N -X POST https://llm402.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer bal_xxxx..." \
  -d '{"model":"deepseek-v3.2","messages":[{"role":"user","content":"hello"}],"max_tokens":100,"stream":true}' \
  | while IFS= read -r line; do
      echo "$line"
    done

const res = await fetch('https://llm402.ai/v1/chat/completions', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer bal_xxxx...' },
  body: JSON.stringify({
    model: 'deepseek-v3.2', messages: [{ role: 'user', content: 'hello' }],
    max_tokens: 100, stream: true
  })
});
const reader = res.body.getReader();
const decoder = new TextDecoder();
let buf = '';
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  buf += decoder.decode(value, { stream: true });
  const lines = buf.split('\n');
  buf = lines.pop() || ''; // keep partial trailing line for the next read
  for (const line of lines) {
    if (line.startsWith('data: ') && line !== 'data: [DONE]') {
      const chunk = JSON.parse(line.slice(6));
      const token = chunk.choices[0]?.delta?.content || '';
      process.stdout.write(token);
    }
  }
}

import requests, json

res = requests.post('https://llm402.ai/v1/chat/completions',
    headers={'Content-Type': 'application/json', 'Authorization': 'Bearer bal_xxxx...'},
    json={'model': 'deepseek-v3.2', 'messages': [{'role': 'user', 'content': 'hello'}],
          'max_tokens': 100, 'stream': True},
    stream=True)

for line in res.iter_lines():
    line = line.decode('utf-8')
    if line.startswith('data: ') and line != 'data: [DONE]':
        chunk = json.loads(line[6:])
        token = chunk['choices'][0].get('delta', {}).get('content', '')
        print(token, end='', flush=True)

Request Deduplication

Non-streaming responses are cached for 30 seconds. If you retry an identical request (same model, messages, max_tokens, and IP), the server returns the cached response immediately without re-running inference or re-charging you.

The response includes an X-Dedup header indicating whether the response was served from cache:

X-Dedup: hit    # served from cache (no charge)
X-Dedup: miss   # fresh inference

To bypass the cache, send the X-No-Cache: true request header. (Streaming responses and cache-bypassed requests omit the X-Dedup header entirely — the absence of the header should be treated the same as miss.)

Web Search

Ground model responses with real-time web data. When enabled, the model searches the web before responding and includes citations to sources. Available on most models via auto-routing.

Usage

Add web_search: true to any /v1/chat/completions request:

curl -X POST https://llm402.ai/v1/chat/completions \
  -H "Authorization: Bearer bal_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [{"role": "user", "content": "What is the current price of Bitcoin?"}],
    "web_search": true,
    "stream": true
  }'

Parameters

Response

The model embeds citation markers (e.g. [1]) in its response text with links to sources. When the upstream provider returns structured citations, llm402 forwards them unmodified as an annotations array attached to the assistant message.

Non-streaming schema

The annotations array is attached to choices[0].message:

{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "Some answer with citations [1].",
      "annotations": [
        {
          "type": "url_citation",
          "url_citation": {
            "url": "https://example.com/article",
            "title": "Example article",
            "content": "optional snippet",
            "start_index": 14,
            "end_index": 17
          }
        }
      ]
    }
  }]
}

Streaming

During an SSE stream with web_search: true, annotations do not arrive progressively. They are attached to the final stop chunk (the same chunk that carries finish_reason: "stop"), as a top-level annotations array on that chunk.

data: {"id":"...","choices":[{"index":0,"delta":{"content":"answer"}}]}

data: {"id":"...","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"annotations":[{"type":"url_citation","url_citation":{"url":"https://example.com","title":"..."}}]}

data: [DONE]

Pricing

Web search adds a small surcharge per request on top of the base inference cost. The surcharge varies with model and current rates — query POST /v1/estimate-cost with web_search: true for the exact number, or read the price field on the 402 challenge. Default coverage is up to 5 web page lookups per request.

Compatibility

• model: "auto" — always supported. The router selects a search-capable model.
• Explicit model — supported on most models. Returns 400 if the model does not support web search.
• The tools parameter is not supported. Use web_search: true instead.

Estimate Cost

Use /v1/estimate-cost with web_search: true to see the price before sending a paid request:

curl -X POST https://llm402.ai/v1/estimate-cost \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [{"role": "user", "content": "Latest AI news"}],
    "web_search": true
  }'

The response includes webSearchEnabled: true and the total cost with the search surcharge included.

Image Generation

Generate images from text prompts. 40+ models across multiple providers, all behind a unified OpenAI-compatible endpoint. All four payment rails are supported (L402, x402, Balance, Cashu).

Endpoint

POST /v1/images/generations or /v1/images/generations/{model}

Request Body

Response

{
  "created": 1234567890,
  "model": "black-forest-labs/FLUX.1-schnell",
  "data": [
    { "url": "/v1/media/img_abc123..." }
  ]
}

The url field can take three forms:

• Relative proxy path (e.g. /v1/media/img_abc123...) — the most common form. The image is served from llm402.ai with a 24h TTL and provider-agnostic CSP. Prepend https://llm402.ai to fetch.
• data: URI (e.g. data:image/png;base64,...) — inline base64 for providers that return raw bytes (the image is embedded; no extra fetch).
• Direct HTTPS URL — only as a fallback when the media-proxy token can't be created. HTTPS URLs from upstream providers may expire (~7 days).

Each data[i] entry may also include provider-specific extras: revised_prompt (image-prompt rewriting), or timings/index (provider diagnostics). These are pass-through — treat them as best-effort and code defensively.

Key Differences from Chat Completions

• No streaming — response is synchronous
• model is required (no auto-routing)
• One image per request (n is always 1)
• Pricing is per-image, not per-token
• All image payments are non-refundable on backend failure — intentional per pentester finding (eliminates refund oracle). This diverges from chat where Balance refunds on upstream failure. Use /v1/estimate-cost + the /v1/models health signal before paying.
• Request deduplication is disabled
• Generation time varies: 1–10s for FLUX/diffusion models, 30–90s for GPT-5 Image models
• Dimensions are automatically rounded to the nearest multiple of 16 for compatibility
• Both size string and width/height integer formats are accepted

Example

curl -X POST https://llm402.ai/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer bal_your_token_here" \
  -d '{
    "model": "black-forest-labs/FLUX.1-schnell",
    "prompt": "A serene mountain landscape at sunset"
  }'

Available Models

40+ image models from multiple providers. Use /v1/models or the Models page for the full live list with current sat prices. Selected highlights:

Video Generation

Generate videos from text prompts. Unlike image generation, video generation is asynchronous: you create a job, then poll for completion. All four payment rails are supported (L402, x402, Balance, Cashu). Payment is collected when the job is created.

Workflow

1. Create job — POST /v1/videos with your prompt and model. Returns 202 Accepted with a job ID and poll URL.
2. Poll for status — GET /v1/videos/{job_id} (no auth required). Returns queued, processing, completed, or failed.
3. Download — When status is completed, the response includes a video_url.

Create Job

POST /v1/videos or /v1/videos/generations/{model}

Request Body

Pricing

Video pricing varies by provider and model:

• Together.ai models (Kling, MiniMax, Seedance, etc.) — flat per-video pricing. The price is the same regardless of duration or resolution.
• OpenRouter models (Veo 3.1) — per-second pricing that scales with duration and resolution. Longer videos and higher resolutions cost more.

The 402 challenge always shows the exact price for the specific parameters you requested. If no optional parameters are specified (duration, resolution), the minimum price for that model is shown.

Model Capabilities

Each video model supports specific durations, sizes, and fps values. Sending unsupported parameters returns 400 Bad Request with the list of supported values for that model. Use GET /v1/models to discover per-model capabilities.

Video models in the /v1/models response include these additional fields:

# Discover video model capabilities
curl -s https://llm402.ai/v1/models | jq '.data[] | select(.model_type=="video") | {id, capabilities}'

Response (202 Accepted)

{
  "id": "vj_abc123...",
  "status": "queued",
  "model": "minimax/video-01-director",
  "poll_url": "/v1/videos/vj_abc123...",
  "poll_interval_ms": 5000,
  "created_at": 1234567890
}

Poll Job Status

GET /v1/videos/{job_id}

Response (completed)

{
  "id": "vj_abc123...",
  "status": "completed",
  "model": "minimax/video-01-director",
  "video_url": "/v1/videos/vj_abc123.../content",
  "done_at": 1234567890,
  "created_at": 1234567000,
  "poll_interval_ms": 5000
}

Response (failed)

{
  "id": "vj_abc123...",
  "status": "failed",
  "model": "minimax/video-01-director",
  "error": "upstream provider timeout",
  "poll_interval_ms": 5000
}

Key Differences from Image Generation

• Asynchronous — returns immediately with a job ID, not a finished result
• Polling required — use poll_url to check status; respect poll_interval_ms
• URL-only — no b64_json response format; videos are always returned as URLs
• Longer generation times — expect 30s–5min depending on model and duration
• Non-refundable — payment is collected at job creation, not on completion
• model is required (no auto-routing)
• One video per request
• Request deduplication is disabled

Example

# Create video job
curl -X POST https://llm402.ai/v1/videos \
  -H "Authorization: Bearer bal_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model": "minimax/video-01-director", "prompt": "A cat walking through a garden", "seconds": 5}'

# Response (202 Accepted):
# {"id":"vj_abc...","status":"queued","model":"minimax/video-01-director","poll_url":"/v1/videos/vj_abc...","poll_interval_ms":5000}

# Poll for completion
curl https://llm402.ai/v1/videos/vj_abc123...

# Response (completed):
# {"id":"vj_abc...","status":"completed","model":"minimax/video-01-director","video_url":"/v1/videos/vj_abc.../content","done_at":1234567890,"created_at":1234567000,"poll_interval_ms":5000}

# Generate a 16:9 HD video with specific duration
curl -X POST https://llm402.ai/v1/videos \
  -H "Authorization: Bearer bal_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model": "google/veo-3.0", "prompt": "cat walking on beach", "seconds": 8, "width": 1920, "height": 1080}'

Available Models

Video models from multiple providers. Use /v1/models or the Models page for the full live list with pricing and per-model capabilities. Available models include Sora 2, Veo 3.0, Veo 3.1 (via OpenRouter, per-second pricing), Kling 2.1, Seedance, PixVerse, MiniMax, Vidu, and Wan.

Fetching Generated Video

GET /v1/videos/{job_id}/content

Completed video jobs expose their binary through an opaque proxy endpoint. When the poll response of GET /v1/videos/{job_id} returns status: "completed", the accompanying video_url field is a relative path of the form /v1/videos/vj_…/content pointing at this endpoint. The provider’s actual CDN URL is never exposed to the client.

No additional authentication is required — the job_id itself is a 128-bit capability token (vj_ + 32 hex characters).

End-to-end flow

curl -s -L -o out.mp4 "https://llm402.ai/v1/videos/vj_aaaaaaaabbbbbbbbccccccccdddddddd/content"

The placeholder job ID above will return 404 Video not available — that is expected, and documents the shape of the "unknown or expired job" error.

Response

On success the server streams the binary with the following headers:

Status codes

Rate limit: this endpoint shares the video-polling class at 60 requests / minute per IP.

Code Examples

Complete examples for each payment method and language.

const API_URL = 'https://llm402.ai/v1/chat/completions';
const body = JSON.stringify({
  model: 'claude-sonnet-4.6',
  messages: [{ role: 'user', content: 'Say hello.' }],
  max_tokens: 50
});

// 1. Get 402 -- parse Payment-Required header (x402 v2 envelope)
const res402 = await fetch(API_URL, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body });
const envelope = JSON.parse(Buffer.from(res402.headers.get('Payment-Required'), 'base64').toString());
const req = envelope.accepts[0];  // always use accepts[0]
const routedModel = res402.headers.get('X-Route-Model') || 'claude-sonnet-4.6';

// 2. Sign EIP-3009 TransferWithAuthorization (off-chain, no gas)
const signature = await walletClient.signTypedData({
  domain: { name: req.extra.name, version: req.extra.version, chainId: 8453, verifyingContract: req.asset },
  types: { TransferWithAuthorization: [
    { name: 'from', type: 'address' }, { name: 'to', type: 'address' },
    { name: 'value', type: 'uint256' }, { name: 'validAfter', type: 'uint256' },
    { name: 'validBefore', type: 'uint256' }, { name: 'nonce', type: 'bytes32' },
  ]},
  primaryType: 'TransferWithAuthorization',
  message: { from: address, to: req.payTo, value: BigInt(req.amount),
             validAfter: BigInt(now - 600), validBefore: BigInt(now + 120), nonce },
});

// 3. Send with Payment-Signature header (base64-encoded JSON payload)
const res = await fetch(API_URL, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'Payment-Signature': paymentB64 },
  body: JSON.stringify({ model: routedModel, messages, max_tokens: 50 }),
});

API_URL = 'https://llm402.ai/v1/chat/completions'
body = {'model': 'claude-sonnet-4.6', 'messages': [{'role': 'user', 'content': 'Say hello.'}], 'max_tokens': 50}

# 1. Get 402 -- parse Payment-Required header (x402 v2 envelope)
res402 = requests.post(API_URL, json=body)
envelope = json.loads(base64.b64decode(res402.headers["Payment-Required"]).decode())
req = envelope["accepts"][0]  # always use accepts[0]
routed_model = res402.headers.get("X-Route-Model", "claude-sonnet-4.6")

# 2. Sign EIP-3009 TransferWithAuthorization (off-chain, no gas)
domain = {"name": req["extra"]["name"], "version": req["extra"]["version"],
          "chainId": 8453, "verifyingContract": req["asset"]}
message = {"from": address, "to": req["payTo"], "value": int(req["amount"]),
           "validAfter": now - 600, "validBefore": now + 120,
           "nonce": bytes.fromhex(nonce[2:])}
signable = encode_typed_data(domain, types, "TransferWithAuthorization", message)
signed = account.sign_message(signable)

# 3. Send with Payment-Signature header (base64-encoded JSON payload)
res = requests.post(API_URL, json={**body, "model": routed_model},
                    headers={"Payment-Signature": payment_b64})

# 1. Get 402 challenge
curl -s -D- -X POST https://llm402.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-sonnet-4.6","messages":[{"role":"user","content":"hi"}],"max_tokens":50}'
# Response: HTTP 402 with Payment-Required header (base64 JSON) and WWW-Authenticate (L402)

# 2. Decode the Payment-Required header (x402 v2 envelope)
echo "$PAYMENT_REQ_HEADER" | base64 -d | jq .
# Returns: { x402Version: 2, accepts: [{ scheme, network, amount, asset, payTo, extra }], resource, price }
# Use accepts[0] for payment details: jq '.accepts[0]'

# 3. Sign EIP-3009 with cast, build payload, base64 encode (see x402 docs above for full flow)

# 4. Send with payment
curl -s -X POST https://llm402.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Payment-Signature: $PAYMENT_B64" \
  -d '{"model":"claude-sonnet-4.6","messages":[{"role":"user","content":"hi"}],"max_tokens":50}'

// 1. Connect wallet + switch to Base
const provider = new ethers.BrowserProvider(window.ethereum);
const signer = await provider.getSigner();
await window.ethereum.request({ method: 'wallet_switchEthereumChain', params: [{ chainId: '0x2105' }] });

// 2. Get 402, parse Payment-Required header (x402 v2 envelope)
const res402 = await fetch(API_URL, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body });
const envelope = JSON.parse(atob(res402.headers.get('Payment-Required')));
const req = envelope.accepts[0];  // always use accepts[0]

// 3. Sign EIP-3009 (wallet popup -- no gas, no approval tx)
const signature = await signer.signTypedData(
  { name: req.extra.name, version: req.extra.version, chainId: 8453, verifyingContract: req.asset },
  { TransferWithAuthorization: [/* from, to, value, validAfter, validBefore, nonce */] },
  { from: address, to: req.payTo, value: BigInt(req.amount), validAfter: BigInt(now-600), validBefore: BigInt(now+120), nonce }
);

// 4. Send with Payment-Signature header
const res = await fetch(API_URL, {
  headers: { 'Content-Type': 'application/json', 'Payment-Signature': btoa(JSON.stringify(payload)) },
  method: 'POST', body: JSON.stringify({ model: routedModel, messages, max_tokens: 50 }),
});

# Step 1: Get 402 challenge with Lightning invoice
curl -s -D- -X POST https://llm402.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-v3.2","messages":[{"role":"user","content":"hi"}],"max_tokens":50}'

# Response body includes:
#   "invoice": "lnbc210n1pn..."   (pay this with your Lightning wallet)
#   "macaroon": "AgEJbGxt..."     (send this back with the preimage)
#   "price": 21                   (cost in sats)

# Step 2: Pay the Lightning invoice with your wallet.
# Your wallet will give you the preimage (64-char hex).

# Step 3: Resend the request with L402 authorization
curl -s -X POST https://llm402.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: L402 AgEJbGxt...:a1b2c3d4e5f67890..." \
  -d '{"model":"deepseek-v3.2","messages":[{"role":"user","content":"hi"}],"max_tokens":50}'

# Response: HTTP 200 with the chat completion

# Step 1: Create a prepaid balance (get Lightning invoice)
curl -s -X POST https://llm402.ai/v1/balance \
  -H "Content-Type: application/json" \
  -d '{"sats": 1000}'
# Response: { "payment_hash": "abc...", "invoice": "lnbc10u...", "sats": 1000, "expires_in": 600 }

# Step 2: Pay the invoice, then poll for the token
curl -s -X POST https://llm402.ai/v1/balance \
  -H "Content-Type: application/json" \
  -d '{"payment_hash": "abc..."}'
# Response: { "paid": true, "token": "bal_xxxx...", "sats": 1000, "expires_at": "..." }

# Step 3: Use the token for requests (no per-request payment needed)
curl -s -X POST https://llm402.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer bal_xxxx..." \
  -d '{"model":"gpt-5.4","messages":[{"role":"user","content":"hello"}],"max_tokens":100}'

# Step 4: Check remaining balance
curl -s -X POST https://llm402.ai/v1/balance \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer bal_xxxx..." \
  -d '{"action": "status"}'
# Response: { "sats": 850, "expires_at": "...", "total_spent": 150, "requests": 3 }

Pricing

Prices are computed dynamically per-request based on the model, your estimated input tokens, and your requested max_tokens. Cheaper models cost as little as 21 sats. The exact price is returned in the 402 response.

A uniform 10% markup is applied over upstream provider cost across every modality — chat, embeddings, images, video, and web search. Same markup regardless of which payment rail you use (L402, x402, Cashu, or prepaid balance). The 21-sat floor applies to all sats-denominated requests.

How max_tokens affects your bill

We charge upfront, once per request, based on input size plus your max_tokens cap — not on actual tokens returned. A 50-word answer at max_tokens: 16384 costs the same as a 5,000-word answer at the same cap. Sizing the cap tightly is the single biggest lever on your invoice.

Guidance for larger outputs:

Per-model upper bounds apply — check max_tokens in /v1/models (which returns each model's context_length along with per-token pricing in USD and sats). Requests that exceed a model's context window are rejected before payment with a 400, so you never pay for an impossible request.

Denomination by Protocol

Errors

All errors on /v1/* endpoints follow the OpenAI error format:

{
  "error": {
    "message": "description",
    "type": "error_type",
    "code": "error_code"
  }
}

x402-Specific Errors

Cashu-Specific Errors

L402-Specific Errors

General Errors

Rate Limits

Rate limits apply per IP address (via cf-connecting-ip). Limits differ by endpoint class.

Concurrent Stream Limits

When rate limited, the response includes a Retry-After header indicating how many seconds to wait before retrying.

Models & Auto-Routing

llm402.ai serves 400+ models across multiple providers. The full model list with pricing is available at the /v1/models endpoint:

curl -s https://llm402.ai/v1/models | jq '.data[].id'

Model Naming

You can use either short names or full provider-prefixed IDs:

Auto-Routing

Send model: "auto" and an embedding-based classifier picks the best model across 8 task categories: code, reasoning, creative, summarization, multilingual, general_knowledge, agents, chat. Vision is supported via explicit "task": "vision" in the request body (the auto-classifier itself doesn't infer vision — provide images and set the task hint).

• code -- programming, debugging, code generation
• reasoning -- logic, math, step-by-step analysis
• general_knowledge -- factual questions, definitions, Q&A
• creative -- writing, storytelling, brainstorming
• summarization -- condensing content, TL;DR
• chat -- casual conversation, general chat
• multilingual -- translation, cross-language tasks
• agents -- function calling, tool integration, structured output
• vision -- image understanding (multimodal models)

To skip the classifier and route within a specific category, use the task body parameter with model: "auto":

curl -s -X POST https://llm402.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"auto","task":"code","messages":[{"role":"user","content":"Sort a list in Python"}],"max_tokens":200}'