📖 API Guide

1. Overview — What Is LightPhon?

LightPhon is an OpenAI-compatible proxy that sits between your application and a decentralized network of GPU nodes running open-source LLMs.

Think of it like this: instead of sending requests to api.openai.com, you send them to lightphon.com. The API format is identical — same endpoints, same JSON structure, same SDKs. LightPhon takes your request, picks the best available GPU node, and returns the response.

2. Quick Start (5 minutes)

Get up and running in 3 steps:

from openai import OpenAI

client = OpenAI(
    base_url="https://lightphon.com/v1",
    api_key="your-api-key-here"
)

response = client.chat.completions.create(
    model="auto",                       # router picks the best model
    messages=[{"role": "user", "content": "Hello!"}]
)
print(response.choices[0].message.content)

That's it. The model: "auto" setting tells the router to pick the best available model automatically.

3. Authentication

There are two ways to authenticate with the LightPhon API:

Option A — API Key (recommended)

Generate an API Key from the Model Router → Step 1 in the web app. This key never expires and works like a standard OpenAI API key.

# Use as a Bearer token in the Authorization header:
Authorization: Bearer lp_abc123def456...

# Or pass it as apiKey in any OpenAI SDK:
client = OpenAI(base_url="https://lightphon.com/v1", api_key="lp_abc123def456...")

Option B — Agent Token (URL-based)

The Agent Token embeds authentication directly in the URL. Useful for tools that don't support custom headers (some IDE plugins, automation scripts, etc.).

# Base URL with embedded token:
https://lightphon.com/api/agent/<your-token>

# The apiKey field can be anything (token is in the URL):
client = OpenAI(
    base_url="https://lightphon.com/api/agent/<your-token>",
    api_key="x"
)

4. API Endpoints

All endpoints follow the OpenAI convention under /v1/:

5. Chat Completions

The main endpoint. Send a conversation and get a response — identical to OpenAI's chat completions API.

Request

POST /v1/chat/completions
Authorization: Bearer <api-key>
Content-Type: application/json

{
  "model": "auto",
  "messages": [
    { "role": "system", "content": "You are a helpful assistant." },
    { "role": "user",   "content": "Explain Bitcoin Lightning in 3 lines." }
  ],
  "max_tokens": 512,
  "temperature": 0.7,
  "stream": false
}

Response

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1717171200,
  "model": "Qwen/Qwen2.5-Coder-14B-Instruct-GGUF",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Bitcoin Lightning is a Layer 2 payment protocol..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 86,
    "total_tokens": 110
  }
}

Supported parameters

• model — model ID from /v1/models, or "auto" for automatic routing
• messages — array of { role, content } objects
• max_tokens — maximum tokens to generate (default: 4096)
• temperature — sampling temperature 0–2 (default: 0.7)
• stream — true for Server-Sent Events streaming
• top_p, frequency_penalty, presence_penalty — standard OpenAI params

6. Streaming (SSE)

Set "stream": true to receive tokens as they are generated, in real-time.

Event format

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":" world"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

Python streaming example

from openai import OpenAI

client = OpenAI(base_url="https://lightphon.com/v1", api_key="your-key")

stream = client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "Hello!"}],
    stream=True
)
for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

curl streaming example

curl -N https://lightphon.com/v1/chat/completions \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{"model":"auto","messages":[{"role":"user","content":"Hi"}],"stream":true}'

7. Model Router & Auto Selection

The Model Router automatically selects the best available node and model for your request. You don't have to hardcode a model name — just use "auto".

How "auto" works

When you set "model": "auto", the router:

1. Checks all online GPU nodes and OpenClaw models
2. Scores them based on availability, speed, and capabilities
3. Picks the best match and forwards your request

The response includes a routing_info field showing which node and model were used.

Advanced — direct routing query

You can query the router directly to find models matching specific criteria:

POST /api/models/route
Authorization: Bearer <api-key>
Content-Type: application/json

{
  "providers": ["meta", "mistral", "deepseek"],
  "min_params_b": 7,
  "max_params_b": 72,
  "capabilities": ["code", "reasoning"],
  "prefer_size": "balanced",
  "limit": 5
}

Filter options

• providers — meta, mistral, deepseek, google, microsoft, alibaba…
• min_params_b / max_params_b — parameter range in billions
• size_classes — tiny, small, medium, large, xlarge
• capabilities — chat, code, reasoning, math, vision, tool_use, rag, agent…
• families — llama, qwen, mistral, gemma…
• min_context_length — minimum context window
• prefer_size — smallest | largest | balanced
• known_only — true to only return cataloged models

8. Where Models Come From

When you call GET /v1/models, you'll see models from two types of sources:

🖥️ Local GPU Nodes

These are real hardware machines running open-source LLMs (LLaMA, Qwen, Mistral, DeepSeek, etc.) via the LightPhon node software. They connect to the server over WebSocket and serve inference requests in real-time. Anyone can run a GPU node — see the Download page.

🐾 OpenClaw

OpenClaw is an external OpenAI-compatible AI platform that the LightPhon server can integrate as a virtual node. When OpenClaw is enabled, the server queries its /v1/models endpoint at startup and makes those models available in the network alongside real GPU nodes.

The router treats both sources equally when selecting the best model. If an OpenClaw model is the best match for your request, the server forwards to OpenClaw directly via HTTP (no WebSocket needed). The response format is always the same regardless of source.

9. OpenClaw Integration

OpenClaw and LightPhon can work together in two directions:

A) Use LightPhon from OpenClaw

If you use OpenClaw as your AI assistant, you can add LightPhon as one of its model providers. This way, OpenClaw sends inference requests to the LightPhon network.

# In your OpenClaw models configuration:
models:
  providers:
    - name: lightphon
      api: openai-completions
      baseUrl: https://lightphon.com/v1
      apiKey: "your-api-key"
      models:
        - name: auto               # router picks best model
        - name: Qwen/Qwen2.5-Coder-14B-Instruct-GGUF  # or a specific model

B) Use OpenClaw as a backend for LightPhon

Server administrators can configure LightPhon to pull models from an OpenClaw instance, making them available alongside local GPU nodes.

Server environment variables

OPENCLAW_ENABLED=true
OPENCLAW_BASE_URL=http://<openclaw-host>:<port>
OPENCLAW_API_KEY=          # optional, if OpenClaw requires auth
OPENCLAW_NODE_NAME=OpenClaw
OPENCLAW_PRICE=0           # cost in sats/min (0 = free)
OPENCLAW_TIMEOUT=120       # request timeout in seconds

How it works

10. Use With Any Client

LightPhon works with any tool or library that supports the OpenAI chat completions API. Just change the base URL and API key.

Python (openai SDK)

from openai import OpenAI

client = OpenAI(
    base_url="https://lightphon.com/v1",
    api_key="your-api-key"
)

resp = client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "Hello!"}]
)
print(resp.choices[0].message.content)

Node.js (openai SDK)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://lightphon.com/v1",
  apiKey: "your-api-key"
});

const resp = await client.chat.completions.create({
  model: "auto",
  messages: [{ role: "user", content: "Hello!" }]
});
console.log(resp.choices[0].message.content);

curl

curl https://lightphon.com/v1/chat/completions \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [{"role":"user","content":"Hello!"}]
  }'

LangChain

from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    base_url="https://lightphon.com/v1",
    api_key="your-api-key",
    model="auto"
)
print(llm.invoke("Explain Lightning in 2 lines").content)

Aider / Continue.dev / Cursor / any IDE plugin

Most AI coding tools let you configure a custom OpenAI endpoint. Use these settings:

Base URL : https://lightphon.com/v1
API Key  : your-api-key
Model    : auto

Or, if the tool only supports a single URL (no separate API key field), use the Agent Token URL:

Base URL : https://lightphon.com/api/agent/<your-token>
API Key  : x         (any non-empty string)
Model    : auto

11. Error Handling

Errors follow the standard OpenAI format:

{
  "error": {
    "message": "No suitable node found for the requested model",
    "type": "invalid_request_error",
    "code": "model_not_available"
  }
}

Common errors

12. FAQ

What is "auto" and should I use it?

Yes, for most use cases. "auto" tells the Model Router to pick the best available model based on availability, speed, and capabilities. You can also specify a model ID if you need a specific model.

What's the difference between API Key and Agent Token?

Both authenticate your requests. The API Key goes in the Authorization: Bearer header (standard OpenAI style). The Agent Token is embedded in the URL — useful for tools that don't support custom headers. Use whichever is more convenient.

What is OpenClaw and why do I see it in the model list?

OpenClaw is an external AI platform. The LightPhon server can integrate it as a virtual node, making its models available alongside local GPU nodes. OpenClaw models are marked with a 🐾 badge. The router treats them the same as local models.

Do I need a Lightning wallet?

Not directly. You deposit sats to your LightPhon wallet (via Lightning invoice or EUR card), and the server deducts from your balance when you use the API. No external wallet interaction needed after funding.

Is my data stored?

No. Conversations are routed directly to the GPU node — no data is stored on the LightPhon server. When the session ends, everything is gone.

What models are available?

It depends on which nodes are online. Call GET /v1/models or check the Model Router in the web app to see the current list. Common models include LLaMA, Qwen, Mistral, DeepSeek, Gemma, and more.

Can I self-host?

Yes! LightPhon is fully open source. See the GitHub repository for deployment instructions.