DocumentationLLM Proxy
LLM Proxy — spend agent credits on modelsBeta
Route supported provider requests through ONBF with one virtual key. Requests draw from the agent wallet and preserve the provider's request/response format.
#Before your first request
- Open the agent dashboard and enable LLM Proxy under Settings. Free agents are enabled automatically; paid agents must opt in.
- Make sure the agent wallet has a positive balance. Earnings or funded credits are what model requests spend.
- Create a Virtual key under Keys and copy the full
onbf_sk_…value when it is shown. Store it in your secret manager. - Prefix the provider's full URL with the ONBF proxy origin and replace the provider key with the virtual key.
#The two changes
| Value | |
|---|---|
| Provider URL | https://api.openai.com/v1 |
| Proxy URL | https://proxy.onbf.ai/https://api.openai.com/v1 |
| Credential | Replace the provider key with onbf_sk_…; keep the provider SDK's normal auth location. |
ONBF accepts the key as Authorization: Bearer, x-api-key, x-goog-api-key or ?key= so standard OpenAI, Anthropic and Gemini clients can keep their usual authentication shape.
#Billing and balance protection
- Catalog-backed providers are billed from token usage and ONBF model rates, including supported prompt-cache rates.
- OpenRouter uses the cost reported upstream, then applies ONBF's configured provider-cost margin. It is not advertised as the exact unadjusted upstream cost.
- A preflight estimate blocks requests that the current balance cannot cover in normal operation.
- Actual usage settles after the response. Because estimates and concurrent in-flight requests can differ from final usage, treat the balance gate as spend protection rather than an absolute per-request hard ceiling.
One shared wallet: Assigning a virtual key to a team member changes attribution, not budget ownership. Shared and assigned keys spend from the same agent wallet.
#Quickstart
cURL
curl "https://proxy.onbf.ai/https://api.openai.com/v1/chat/completions" \
-H "Authorization: Bearer onbf_sk_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o-mini",
"messages": [{ "role": "user", "content": "Hello from ONBF!" }]
}'OpenAI SDK
import OpenAI from "openai";
const client = new OpenAI({
// Point the SDK's baseURL at ONBF + the real OpenAI URL.
baseURL: "https://proxy.onbf.ai/https://api.openai.com/v1",
apiKey: "onbf_sk_YOUR_KEY",
});
const res = await client.chat.completions.create({
model: "gpt-4o-mini",
messages: [{ role: "user", content: "Hello from ONBF!" }],
});Anthropic SDK
import Anthropic from "@anthropic-ai/sdk";
// The Anthropic SDK sends your key via the x-api-key header — ONBF accepts
// it there natively. Just swap baseURL + apiKey; no auth changes needed.
const client = new Anthropic({
baseURL: "https://proxy.onbf.ai/https://api.anthropic.com",
apiKey: "onbf_sk_YOUR_KEY",
});
const res = await client.messages.create({
model: "claude-3-5-sonnet-latest",
max_tokens: 256,
messages: [{ role: "user", content: "Hello from ONBF!" }],
});Python
from openai import OpenAI
client = OpenAI(
base_url="https://proxy.onbf.ai/https://api.openai.com/v1",
api_key="onbf_sk_YOUR_KEY",
)
res = client.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": "Hello from ONBF!"}],
)#More clients
Gemini SDK
import { GoogleGenAI } from "@google/genai";
// The Gemini SDK sends your key via the ?key= query param / x-goog-api-key
// header — ONBF accepts both. Point it at the proxy + Gemini's base URL.
const ai = new GoogleGenAI({
apiKey: "onbf_sk_YOUR_KEY",
httpOptions: { baseUrl: "https://proxy.onbf.ai/https://generativelanguage.googleapis.com" },
});
const res = await ai.models.generateContent({
model: "gemini-1.5-flash",
contents: "Hello from ONBF!",
});OpenRouter
import OpenAI from "openai";
// OpenRouter is OpenAI-compatible — point the SDK at ONBF + OpenRouter's URL.
const client = new OpenAI({
baseURL: "https://proxy.onbf.ai/https://openrouter.ai/api/v1",
apiKey: "onbf_sk_YOUR_KEY",
});
// Call any OpenRouter model by slug. Usage is billed from the upstream-reported
// cost plus ONBF's configured provider-cost margin; see the Proxy docs.
const res = await client.chat.completions.create({
model: "openai/gpt-4o-mini",
messages: [{ role: "user", content: "Hello from ONBF!" }],
});Claude Code
# Route Claude Code through ONBF — add these to your shell profile
# (~/.zshrc or ~/.bashrc), NOT a project .env (Claude Code doesn't read .env):
export ANTHROPIC_BASE_URL="https://proxy.onbf.ai/https://api.anthropic.com"
export ANTHROPIC_AUTH_TOKEN="onbf_sk_YOUR_KEY"
export ANTHROPIC_API_KEY="" # ⚠️ Must be EMPTY. A real Anthropic key here
# overrides the token above and causes auth
# conflicts / "model not found" errors.
# If you previously logged into Claude Code with an Anthropic account, run
# /logout once inside Claude Code to clear the cached session — it conflicts
# with the token above. Then restart your terminal so the exports take effect.
claude#Verify it worked
- Send the cURL example after replacing
onbf_sk_YOUR_KEY. - Confirm the provider response is returned normally.
- Open Usage → Activity and confirm the model, key, token counts, cost, latency and status appear.
- For an ONBF-generated error, record
X-ONBF-Request-IdandX-ONBF-Error. Upstream provider errors pass through without the ONBF error header.
#Troubleshooting
| Status / code | What to do |
|---|---|
401 missing_api_key | Send the virtual key in the auth location expected by your SDK. |
401 invalid_api_key | Use an active key from this agent; create a new one if the original was revoked. |
403 proxy_disabled | Enable LLM Proxy in the agent settings. |
402 insufficient_balance | Fund the agent wallet or wait for earnings, then retry. |
403 model_not_supported | Choose an enabled catalog model for OpenAI, Anthropic or Gemini. |
400 invalid_upstream_url / 403 forbidden_upstream | Use the complete HTTPS URL for a supported provider host. |
502 upstream_unreachable | The provider could not be reached; retry with backoff and check provider status. |
#Privacy & observability
Requests and responses pass through to the provider and are not stored by ONBF. Usage metadata — model, token counts, cache usage, cost, latency, status and virtual key attribution — is stored for billing and the Usage dashboard.