Skip to main content

OpenAI SDK (drop-in)

HPP Router is OpenAI-compatible, so you can keep using the official OpenAI SDKs. You only change two things:

  1. Point the base URL at the HPP Router gateway.
  2. Use your HPP Router API key instead of an OpenAI key.

The HPP Router chat endpoint lives under /llm/v1, so the OpenAI SDK base URL is:

https://router.hpp.io/llm/v1

Examples​

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.HPPROUTER_API_KEY!,
  baseURL: 'https://router.hpp.io/llm/v1',
});

const completion = await client.chat.completions.create({
  model: 'hpprouter/auto',
  messages: [{ role: 'user', content: 'Hello!' }],
});

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

How authentication maps​

OpenAI SDKs send the key as Authorization: Bearer <key>, which HPP Router accepts as its Bearer scheme. See Authentication for both supported schemes.

What works as-is​

  • Chat completions — client.chat.completions.create(...).
  • Streaming — pass stream: true. See Streaming.
  • Model selection — use any provider/model or hpprouter/auto.
  • Models list — client.models.list().

What's different​

  • Smart-routing metadata (X-HPP-Router-*) is returned as response headers, which most OpenAI SDK helpers don't surface directly. Read the raw response headers, or use the TypeScript SDK, which exposes meta.resolvedModel.
  • Image generation uses the HPP Router endpoint POST /v1/images/generations with gpt-image-1. See Image Generation.
  • Wallet (x402) rail — setting defaultHeaders: { 'X-Payment-Rail': 'wallet' } alone is not enough. The OpenAI SDK throws on HTTP 402 and often hides PAYMENT-REQUIRED. You must implement a sign-and-retry loop yourself (typically with fetch), or switch to @hpprouter/sdk which handles paymentRail + paymentSigner automatically.

Wallet rail with the OpenAI SDK​

If you stay on the OpenAI SDK for wallet payments:

  1. Send X-Payment-Rail: wallet on the request.
  2. On 402, read the challenge (PAYMENT-REQUIRED header and/or JSON body accepts[0]).
  3. Sign with @x402/core + @x402/evm (upto / Permit2).
  4. Retry once with PAYMENT-SIGNATURE (or X-PAYMENT).

For most new integrations, prefer @hpprouter/sdk so you do not maintain that loop.

When to prefer @hpprouter/sdk​

The dedicated TypeScript SDK returns smart-routing metadata (resolved model, basket, tier) alongside the response, provides typed helpers for usage and images, and includes a built-in x402 wallet loop (paymentRail / paymentSigner). Use it when you want first-class access to HPP Router-specific features; use the OpenAI SDK when you want a minimal-change drop-in on the quota rail.