API Reference

One endpoint. Full OpenAI compatibility.

Base URL

https://api.x420.ai/v1

Authentication

Pass your API key as a Bearer token in the Authorization header:

Authorization: Bearer sk-proxy-your-key

POST /v1/chat/completions

POST/v1/chat/completions

Forwards your request to the best available upstream model and bills the actual token usage from your wallet.

Request body

Parameter	Type	Description
model	string	Required. The model ID, e.g. openai/gpt-4o or anthropic/claude-sonnet-4-6.
messages	array	Required. Array of message objects with role and content.
stream	boolean	Optional. Set to true to receive a Server-Sent Events stream.
max_tokens	integer	Optional. Hard cap on completion tokens. Defaults to 4096, max 16384.

Any additional parameter supported by the target model (temperature, top_p, system, etc.) is passed through to the upstream API unchanged.

Response

The response body is passed through verbatim from the upstream model. Two extra headers are added:

Header	Description
x-balance-cents	Your wallet balance after this request (integer, cents).
x-cost-cents	How much this request cost (integer, cents).

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "model": "openai/gpt-4o-mini",
  "choices": [{
    "message": { "role": "assistant", "content": "Hello!" },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 4,
    "total_tokens": 16
  }
}

Streaming

When stream: true, the response is a standard SSE stream. The final chunk includes the usage stats needed for billing. You don't need to do anything special — X420.ai handles billing automatically.

// Node.js streaming example
const stream = await client.chat.completions.create({
  model: 'openai/gpt-4o-mini',
  messages: [{ role: 'user', content: 'Tell me a story.' }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
}

Error codes

HTTP	Code	Description
400	VALIDATION_ERROR	Request body failed schema validation.
400	MODEL_UNKNOWN	The requested model ID is not available on OpenRouter.
401	MISSING_API_KEY	No Bearer token in the Authorization header.
401	INVALID_API_KEY	The key does not match any active account.
402	INSUFFICIENT_BALANCE	Your wallet balance is lower than the estimated request cost.
403	ACCOUNT_SUSPENDED	Your account has been suspended. Contact support.
429	—	Rate limit exceeded (300 req/min per key).
502	UPSTREAM_ERROR	OpenRouter returned an error after 3 retries.