API Documentation

Lightning-native AI infrastructure for developers and agents

Quick Start

LightningProx provides pay-per-use access to AI models via Lightning Network micropayments. No accounts. No API keys. Payment authorizes each request.

How It Works (L402 Protocol)

Send a request to the API — no credentials needed
Receive HTTP 402 with a Lightning invoice and macaroon token in WWW-Authenticate
Pay the invoice (any Lightning wallet)
Retry with Authorization: L402 <macaroon>:<preimage>

Also supported: Spend tokens (X-Spend-Token) skip the invoice cycle entirely. Prepay once, make unlimited requests until balance runs out.

Example: Your First Request

Step 1: Send Request (no credentials)

        curl -si -X POST https://lightningprox.com/v1/messages \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-5-20251101",
    "max_tokens": 100,
    "messages": [{"role": "user", "content": "What is Lightning Network?"}]
  }'
    

Response (402 Payment Required)

        HTTP/1.1 402 Payment Required
WWW-Authenticate: L402 macaroon="eyJ...", invoice="lnbc..."
Content-Type: application/json

{
  "error": "payment_required",
  "message": "Pay the Lightning invoice and retry with Authorization: L402 <macaroon>:<preimage>",
  "payment": {
    "charge_id": "abc-123-xyz",
    "payment_request": "lnbc...",
    "amount_sats": 5,
    "amount_usd": 0.005
  }
}
    

Step 2: Pay Invoice — Step 3: Retry with L402 Credential

        # After paying the invoice, use the macaroon + payment preimage:
# macaroon  = value from WWW-Authenticate header
# preimage  = 64-char hex preimage from your Lightning wallet after payment
curl -X POST https://lightningprox.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: L402 <macaroon>:<preimage>" \
  -d '{
    "model": "claude-opus-4-5-20251101",
    "max_tokens": 100,
    "messages": [{"role": "user", "content": "What is Lightning Network?"}]
  }'
    

Spend Tokens

Instead of paying per request, you can prepay with a larger Lightning payment and get a reusable spend token. Use it for multiple requests without generating new invoices each time.

Best for Power Users & Agents
Spend tokens eliminate the invoice-pay-retry cycle. Pay once, then make requests instantly until your balance runs out.

Step 1: Top Up

Choose how many sats you want to load (10 - 100,000):

        curl -X POST https://lightningprox.com/v1/topup \
  -H "Content-Type: application/json" \
  -d '{
    "amount_sats": 500,
    "duration_hours": 72
  }'
    

Response

        {
  "charge_id": "abc-123-xyz",
  "payment_request": "lnbc...",
  "amount_sats": 500,
  "amount_usd": 0.50,
  "duration_hours": 72,
  "next_step": "/v1/tokens"
}
    

Step 2: Pay & Create Token

After paying the invoice, create a spend token:

        curl -X POST https://lightningprox.com/v1/tokens \
  -H "Content-Type: application/json" \
  -d '{
    "charge_id": "YOUR_CHARGE_ID",
    "duration_hours": 72
  }'
    

Response

        {
  "token": "lnpx_a1b2c3d4e5f6...",
  "balance_sats": 500,
  "expires_at": "2026-02-12T19:00:00Z",
  "status": "active"
}
    

Step 3: Use Your Token

Include X-Spend-Token in your requests — no more invoices:

        curl -X POST https://lightningprox.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "X-Spend-Token: lnpx_a1b2c3d4e5f6..." \
  -d '{
    "model": "claude-opus-4-5-20251101",
    "max_tokens": 500,
    "messages": [{"role": "user", "content": "Explain Lightning Network"}]
  }'
# Instant response — cost deducted from token balance
    

Check Balance

        curl https://lightningprox.com/v1/balance \
  -H "X-Spend-Token: lnpx_a1b2c3d4e5f6..."
    

Response

        {
  "balance_sats": 485,
  "balance_usd": 0.485,
  "requests_left_estimate": 97,
  "expires_at": "2026-02-12T19:00:00Z",
  "status": "active"
}
    

MCP Server

The LightningProx MCP Server lets AI agents in Claude Desktop, Claude Code, and Cursor query AI models and pay via Lightning — all through the Model Context Protocol.

Your AI Agent Gets a Lightning Wallet
Install the MCP server and your AI can list models, check pricing, generate invoices, and make AI requests — all with automatic Lightning payments.

Install

go install github.com/unixlamadev-spec/lightningprox-mcp/cmd/mcp-server@latest

Configure Claude Desktop

Add to your claude_desktop_config.json:

        {
  "mcpServers": {
    "lightningprox": {
      "command": "mcp-server",
      "args": []
    }
  }
}
    

Available Tools

Tool	Description
ask_ai	Query an AI model (pay with invoice or spend token)
get_invoice	Generate a Lightning invoice for a request
check_balance	Check spend token balance
list_models	List available models with pricing
get_pricing	Estimate cost before committing

GitHub: github.com/unixlamadev-spec/lightningprox-mcp

Python / LangChain

Use the official LangChain integration for seamless Python development.

Install

pip install langchain-lightningprox

Usage

        from langchain_lightningprox import LightningProxLLM

llm = LightningProxLLM(
    lnbits_url="https://demo.lnbits.com",
    lnbits_admin_key="your_admin_key_here"
)

# Payments are handled automatically
response = llm.invoke("Explain quantum computing in one sentence.")
print(response)
    

GitHub: github.com/unixlamadev-spec/langchain-lightningprox
PyPI: pypi.org/project/langchain-lightningprox

Automatic Payments
The LangChain integration handles invoices and payments automatically via your LNBits wallet. Just call llm.invoke() and it works.

JavaScript / Node.js

For JavaScript agents and bots, use the reference implementation.

Clone the Example

        git clone https://github.com/unixlamadev-spec/lightningprox-agent-example
cd lightningprox-agent-example
npm install
    

Configure

        # .env
LNBITS_URL=https://demo.lnbits.com
LNBITS_ADMIN_KEY=your_admin_key_here
    

Run

node agent.js

GitHub: github.com/unixlamadev-spec/lightningprox-agent-example

OpenAI-Compatible SDK

Drop-in replacement for the OpenAI npm package. Change two lines — everything else stays identical.

Install

npm install lightningprox-openai

Migrate from OpenAI SDK

        // Before:
import OpenAI from 'openai'
const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY })

// After:
import OpenAI from 'lightningprox-openai'
const client = new OpenAI({ apiKey: process.env.LIGHTNINGPROX_SPEND_TOKEN })

// Everything else stays identical:
const response = await client.chat.completions.create({
  model: 'claude-opus-4-5-20251101',
  messages: [{ role: 'user', content: 'Hello' }]
})
console.log(response.choices[0].message.content)
    

Zero migration cost. All models available. Errors surface cleanly: 402 = payment required, 429 = rate limit. No provider API keys required.

npm: npmjs.com/package/lightningprox-openai

Supported Models

Model	Provider	Type	Input Cost	Output Cost
claude-opus-4-5-20251101	Anthropic	Chat	$3/1M tokens	$15/1M tokens
claude-sonnet-4-20250514	Anthropic	Chat	$3/1M tokens	$15/1M tokens
claude-haiku-4-5-20251001	Anthropic	Chat	$0.80/1M tokens	$4/1M tokens
gpt-4o	OpenAI	Chat	$2.50/1M tokens	$10/1M tokens
gpt-4-turbo	OpenAI	Chat	$10/1M tokens	$30/1M tokens
meta-llama/Llama-4-Maverick-17B-128E-Instruct-FP8	Together.ai	Chat	$0.36/1M tokens	$0.36/1M tokens
meta-llama/Llama-3.3-70B-Instruct-Turbo	Together.ai	Chat	$0.88/1M tokens	$0.88/1M tokens
mistralai/Mixtral-8x7B-Instruct-v0.1	Together.ai	Chat	$0.60/1M tokens	$0.60/1M tokens
deepseek-ai/DeepSeek-V3	Together.ai	Chat	$1.25/1M tokens	$1.25/1M tokens
mistral-large-latest	Mistral	Chat	$2/1M tokens	$6/1M tokens
mistral-medium-latest	Mistral	Chat	$0.40/1M tokens	$2/1M tokens
mistral-small-latest	Mistral	Chat	$0.10/1M tokens	$0.30/1M tokens
open-mistral-nemo	Mistral	Chat	$0.15/1M tokens	$0.15/1M tokens
codestral-latest	Mistral	Code	$0.30/1M tokens	$0.90/1M tokens
devstral-latest	Mistral	Agentic Code	$0.40/1M tokens	$1.20/1M tokens
pixtral-large-latest	Mistral	Vision	$2/1M tokens	$6/1M tokens
magistral-medium-latest	Mistral	Reasoning	$2/1M tokens	$5/1M tokens
gemini-2.5-flash	Google	Chat	$0.15/1M tokens	$0.60/1M tokens
gemini-2.5-pro	Google	Chat Requires thinking_config — automatically handled	$1.25/1M tokens	$10/1M tokens
gemini-3-flash-preview	Google	Chat	$0.20/1M tokens	$0.80/1M tokens
gemini-3-pro-preview	Google	Chat	$2/1M tokens	$8/1M tokens

Prices include a 20% markup to cover infrastructure and Lightning fees. All models accessible via spend token — no provider API keys required.

For AI Agents

LightningProx is designed for autonomous agents that need to pay for services programmatically. No human intervention required.

Payment = Authentication
Unlike traditional APIs, there are no API keys to manage. The Lightning payment itself authorizes the request. This makes LightningProx ideal for autonomous systems.

Agent Integration Flow (L402)

Agent sends request with no credentials → receives HTTP 402
Agent parses WWW-Authenticate: L402 macaroon="...", invoice="..."
Agent pays the bolt11 invoice via Lightning wallet (LNbits, Strike, LND, etc.)
Agent retries with Authorization: L402 <macaroon>:<preimage>
Agent receives AI response — macaroon is single-use, cannot be replayed

For high-frequency agents: Use spend tokens instead — pay once, skip the invoice cycle entirely.

Service Discovery

Agents can discover LightningProx capabilities programmatically:

        curl https://lightningprox.com/api/capabilities
    

Returns machine-readable JSON with models, pricing, and integration steps.

Streaming Responses

LightningProx supports streaming responses for real-time token-by-token output. This provides a much better user experience for chat applications.

Why Streaming?
Streaming responses feel 5x faster. Instead of waiting 10 seconds for a complete response, users see text appearing immediately, word by word.

Enable Streaming

Add "stream": true to your request. Use a spend token or L402 credential:

        # With spend token (recommended for streaming):
curl -X POST https://lightningprox.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "X-Spend-Token: lnpx_your_token_here" \
  -d '{
    "model": "claude-opus-4-5-20251101",
    "max_tokens": 500,
    "stream": true,
    "messages": [{"role": "user", "content": "Write a haiku about Bitcoin"}]
  }'

# Or with L402 credential:
# -H "Authorization: L402 <macaroon>:<preimage>"
    

Streaming Response Format

Responses are sent as Server-Sent Events (SSE):

        data: {"type":"content_block_delta","delta":{"text":"Digital"}}

data: {"type":"content_block_delta","delta":{"text":" gold"}}

data: {"type":"content_block_delta","delta":{"text":" flows"}}

data: {"type":"message_stop"}

data: [DONE]

JavaScript Example

        const response = await fetch('https://lightningprox.com/v1/messages', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Spend-Token': spendToken  // or: 'Authorization': `L402 ${macaroon}:${preimage}`
  },
  body: JSON.stringify({
    model: 'claude-opus-4-5-20251101',
    max_tokens: 500,
    stream: true,
    messages: [{ role: 'user', content: prompt }]
  })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  
  const chunk = decoder.decode(value);
  const lines = chunk.split('\n');
  
  for (const line of lines) {
    if (line.startsWith('data: ') && !line.includes('[DONE]')) {
      const data = JSON.parse(line.slice(6));
      if (data.delta?.text) {
        process.stdout.write(data.delta.text);
      }
    }
  }
}
    

Python Example

        import requests

response = requests.post(
    'https://lightningprox.com/v1/messages',
    headers={
        'Content-Type': 'application/json',
        'X-Spend-Token': spend_token  # or: 'Authorization': f'L402 {macaroon}:{preimage}'
    },
    json={
        'model': 'claude-opus-4-5-20251101',
        'max_tokens': 500,
        'stream': True,
        'messages': [{'role': 'user', 'content': prompt}]
    },
    stream=True
)

for line in response.iter_lines():
    if line:
        line = line.decode('utf-8')
        if line.startswith('data: ') and '[DONE]' not in line:
            import json
            data = json.loads(line[6:])
            if 'delta' in data and 'text' in data['delta']:
                print(data['delta']['text'], end='', flush=True)
    

Note: Streaming requests cannot be cached. The 50% cache discount only applies to non-streaming requests with identical queries.

Pricing

Pay per request — no subscriptions or minimums
Cached responses — 50% discount on identical queries
Typical cost — 5-50 sats per request (~$0.005-0.05)

Rate Limits & Safety

Rate limit: 10 requests/minute per IP
Daily spend cap: $20/day (protects you)
Monthly spend cap: $150/month
Max tokens: 4096 per request

Endpoints

Endpoint	Method	Description
/v1/messages	POST	AI completion — Anthropic format. Auth: spend token or L402 credential
/v1/chat/completions	POST	AI completion — OpenAI-compatible format. Same auth as /v1/messages
/v1/models	GET	List available models with pricing (OpenAI-compatible format)
/v1/tokens	POST	Create a prepaid spend token from a paid invoice
/v1/topup	POST	Generate a Lightning invoice for any sats amount (10 - 100,000)
/v1/balance	GET	Check spend token balance (X-Spend-Token header)
/api/capabilities	GET	Service discovery for agents
/health	GET	Service health status