Using the API

Routstr is OpenAI-compatible. Almost any AI application, SDK, or tool that supports custom endpoints will work out of the box. Just change two things:

BASE_URL  →  https://api.routstr.com/v1
API_KEY   →  sk-... or cashuA...

Both work as API keys: - sk-7f8e9d... — Session key (from Lightning invoice or Cashu import) - cashuA3s8j... — Raw Cashu token (use directly from your wallet)

If the app lets you set a base URL and API key, you're good to go.

---

Quick Setup Examples

OpenAI SDK (Python/JS)

client = OpenAI(base_url="https://api.routstr.com/v1", api_key="sk-...")  # or any provider's URL

Claude Code

export ANTHROPIC_BASE_URL=https://api.routstr.com/v1
export ANTHROPIC_AUTH_TOKEN=sk-...

Any OpenAI-compatible app

Look for "Custom API endpoint", "Base URL", or "OpenAI-compatible" in settings. Paste the URL and key.

---

Detailed Examples

Python (Official SDK)

from openai import OpenAI

# 1. Initialize with Routstr URL and your funded key
client = OpenAI(
    base_url="https://api.routstr.com/v1",
    api_key="sk-7f8e9d..." 
)

# 2. Call the API normally
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
    stream=True
)

for chunk in response:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

Node.js

import OpenAI from 'openai';

// You can use a session key OR a raw Cashu token directly
const openai = new OpenAI({
  baseURL: 'https://api.routstr.com/v1',
  apiKey: 'cashuA3s8jKx9...', // or 'sk-7f8e9d...'
});

async function main() {
  const completion = await openai.chat.completions.create({
    messages: [{ role: 'user', content: 'Say this is a test' }],
    model: 'gpt-3.5-turbo',
  });

  console.log(completion.choices[0]);
}

main();

cURL

# Works with session key or raw Cashu token
curl https://api.routstr.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer cashuA3s8jKx9..." \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

---

Error Handling

Insufficient Balance (402 Payment Required)

If your session runs out of funds, the API will return a 402 error.

{
  "error": {
    "message": "Insufficient balance. Current: 1000 msat, Required: 5000 msat",
    "type": "insufficient_balance",
    "code": 402
  }
}

Action: Top up your key using the /lightning/invoice (topup purpose) or /v1/balance/topup endpoints.

Rate Limiting

Routstr passes through rate limits from the upstream provider. Handle 429 Too Many Requests with standard exponential backoff.

---

Advanced: Tor Access

If the node is running as a hidden service, use a SOCKS5 proxy (like 127.0.0.1:9050).

Python:

import httpx
from openai import OpenAI

proxy_mounts = {
    "http://": httpx.HTTPTransport(proxy="socks5://127.0.0.1:9050"),
    "https://": httpx.HTTPTransport(proxy="socks5://127.0.0.1:9050"),
}

client = OpenAI(
    base_url="http://verylongonionaddress.onion/v1",
    api_key="sk-...",
    http_client=httpx.Client(mounts=proxy_mounts),
)