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

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

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

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

Step 1: Get the 402 Challenge

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. Any public mint accepted."
  }
}

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": "/v1/chat/completions",
    "description": "LLM inference",
    "mimeType": "application/json"
  },
  "price": "$0.003150"
}

Step 2: Sign the EIP-3009 Authorization

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

Step 3: Build the Payment Payload

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

Step 4: Send the Paid Request

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",
  "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
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 (burn-on-success: preimage is only burned after successful inference)

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

Create Balance (Lightning)

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 }

Poll for Payment

After paying the invoice, poll with the payment hash to get your token:

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

Check 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": "2026-05-03T...", "total_spent": 150, "requests": 7 }

Top Up (Lightning)

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 instead of Lightning. Include a Payment-Signature header with the signed x402 payload:

# Fund with USDC (sign an x402 payment for the equivalent USD amount)
curl -s -X POST https://llm402.ai/v1/balance \
  -H "Content-Type: application/json" \
  -H "Payment-Signature: eyJ4NDAyVmVyc2lvbiI6Mix..." \
  -d '{"sats": 500}'

# Response: { "paid": true, "token": "bal_xxxx...", "sats": 500 }

Use Balance Token

Include the token 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
  }'

Change Tokens

If the token value exceeds the model's price by 2 or more sats, the server returns change in the X-Cashu-Change response header:

HTTP/2 200
X-Cashu-Consumed: true
X-Cashu-Change: cashuBo2F0gaJha...  # remaining sats as ecash token

The change token is a cashuB token you can use for future requests.

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):

{
  "mcpServers": {
    "llm402": {
      "url": "https://llm402.ai/mcp",
      "headers": {
        "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.

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, stateless). Responses are Server-Sent Events containing JSON-RPC results.

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"},"finish_reason":null}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":1712345678,"model":"deepseek-v3.2","choices":[{"index":0,"delta":{"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"}]}

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();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  const text = decoder.decode(value, { stream: true });
  for (const line of text.split('\n')) {
    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.

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. Structured annotations may also be included in the response as annotations on the message object.

Pricing

Web search adds a small surcharge per request (approximately 35–50 sats) on top of the base inference cost. The surcharge covers up to 5 web page lookups per request. The exact cost is included in the 402 challenge invoice or deducted from your balance.

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 three providers, all behind a unified OpenAI-compatible endpoint. All five payment rails are supported (L402, x402, Balance, Cashu, 402 challenge).

Endpoint

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

Request Body

Response

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

The url field contains either an HTTPS URL or a data: URI depending on the model. Both are valid image sources for <img> tags. HTTPS URLs expire after ~7 days.

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 payments are non-refundable
• 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 three providers. Use /v1/models or the Models page for the full live list. 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 including supported durations, resolutions, and fps options.

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": "https://...",
  "done_at": 1234567890
}

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":"https://...","done_at":1234567890}

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.

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.

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 are applied per IP address across three tiers:

Limits per Tier

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 the server picks the best model for your prompt, routing across 9 task categories:

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