Skip to main content
The Node SDK mirrors the Python one: it points your OpenAI client at the Orbitrage gateway and tags every request with a trace id. Zero dependencies, and works in Node, Bun, Deno, Cloudflare Workers, and Next.js. Orbitrage is OpenAI-format only — to use Claude, Gemini, Grok, etc., just name the model.

npm

npm install orbitrage

License

Apache-2.0 · Node >= 18

Install

openai (>=4) is the only peer you need:

Initialize

Call init() once, at the very top of your program, before importing your LLM client. It returns a promise — await it.
You can import the named functions instead of the namespace:

What init() does

  1. Generates a stable trace id and adds it to every request as x-orbitrage-run-id.
  2. Installs a global fetch interceptor that injects trace + user headers on any request to an Orbitrage host. This is the primary mechanism and works even in frozen-ESM environments like Next.js.
  3. Best-effort patches the OpenAI constructor and sets OPENAI_BASE_URL so no-arg clients point at the gateway. Your explicit baseURL or apiKey always wins.
It loads no OTel/Traceloop and exports nothing.

OrbitrageConfig

string
required
Your orb_ key. Falls back to ORBITRAGE_API_KEY.
string
End-user id to attribute calls to (sets x-orbitrage-end-user-id).
string
Override the gateway URL. Defaults to https://api.orbitrage.ai/v1 (or ORBITRAGE_BASE_URL).
boolean
default:"true"
Set false to make init() a no-op.
boolean
default:"false"
Suppress the startup log line.
init() is idempotent. Legacy v0.4 options (disableBatch, captureContent, instruments, …) are accepted and ignored.

Per-end-user attribution

Forcing a model

Pinning a frontier model (claude-*, gpt-*, gemini-*, grok-*) requires an enabled key for that vendor — the call runs on your provider account and Orbitrage bills $0. Without one it throws a 403 with code byok_key_required. See BYOK.

API surface

Using a framework?

LangChain, the Vercel AI SDK, Mastra, and others use the OpenAI client (or fetch) under the hood, so they’re captured transparently. See Integrations.