Documentation

ArcRouter Docs

Benchmark-verified LLM router with 345+ models. Automatically route any prompt to the best AI model based on real benchmark scores from HuggingFace, LiveBench, and LiveCodeBench. Two modes: smart routing (default) selects the best single model per topic, or council mode queries 3-7 models for consensus verification. OpenAI-compatible — drop in with any SDK.

View on GitHub

Quickstart

Replace your existing OpenAI `baseURL` with ours. That's it.

Endpoint URL

https://api.arcrouter.com/v1

Using OpenAI Node.js SDK

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.arcrouter.com/v1",
  apiKey: "sk_your_api_key", // Optional for free tier
});

// Smart routing (default) — routes to best model for the topic
const response = await client.chat.completions.create({
  model: "arc-router-v1",
  messages: [{ role: "user", content: "Explain quantum supremacy." }],
});

console.log(response.choices[0].message.content);

// Council mode — multi-model consensus verification
const council = await client.chat.completions.create({
  model: "arc-router-v1",
  messages: [{ role: "user", content: "Is P=NP?" }],
  mode: "council",     // Query 3-7 models
  budget: "economy",   // "free" | "economy" | "auto" | "premium"
} as any);

console.log(council.consensus); // { confidence, votes, ... }

⚠

Using @ai-sdk/openai (Vercel AI SDK)?

The Vercel AI SDK defaults to OpenAI's newer Responses API (/v1/responses), which ArcRouter does NOT implement. Use client.chat(modelId) (not client(modelId)) so requests hit /v1/chat/completions:

import { createOpenAI } from '@ai-sdk/openai';
const client = createOpenAI({ baseURL: "https://api.arcrouter.com/v1" });

// ❌ Wrong: model: client('auto')          → hits /v1/responses → 404
// ✅ Right: model: client.chat('auto')     → hits /v1/chat/completions

Other SDKs (openai npm, official Python client, langchain, llamaindex) default to chat completions and don't need this.

Authentication

We support four tiers of authentication.

Free Tier

No API key required. Free models only, 20 req/hour.

No Header

MPP (Tempo)

Machine Payments Protocol on Tempo (USDC.e). Sub-cent fees, ~500ms finality. Built by Tempo + Stripe. npm i mppx

Authorization: Payment ...

x402 (Base USDC)

Coinbase x402 spec. Pay per request with USDC on Base. Variable pricing by complexity. Ideal for agent-to-agent payments — no account needed.

X-PAYMENT header (auto)

API Key

Stripe metered billing. Coming soon — pre-register interest via the waitlist.

Authorization: Bearer sk_...

API Reference

ArcRouter exposes an OpenAI-compatible API. Two modes are available: smart routing (default) selects the best single model based on benchmark scores, and council mode queries multiple models for consensus verification.

POST/v1/chat/completions

Main inference endpoint. Accepts OpenAI-compatible request bodies with additional routing parameters.

curl -X POST https://api.arcrouter.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_your_key" \
  -d '{
    "model": "arc-router-v1",
    "messages": [
      { "role": "user", "content": "Explain quantum computing" }
    ],
    "budget": "low",
    "mode": "default",
    "stream": false
  }'

GET/v1/models/scores

Public endpoint. Returns all models with their benchmark scores across domains. No authentication required.

GET/v1/usage

Per-API-key usage statistics. Returns daily request counts and estimated costs. Requires authentication.

GET/v1/workflow/{session_id}/usage

Workflow budget tracking. Returns total spend, models used, average latency, and tier distribution for a workflow session.

GET/health

Health check. Returns provider status, direct provider availability, and x402 wallet configuration.

Request Parameters

Standard OpenAI fields are supported. ArcRouter adds mode and budget for routing control.

Parameter	Type	Default	Description
messages	array	required	OpenAI-format messages array
model	string	"arc-router-v1"	Model alias ("claude", "gpt", "gemini", "deepseek", "free") or specific model ID. Default routes automatically.
mode	string	"default"	"default" — Smart routing to best single model. "council" — Multi-model consensus with confidence scoring.
budget	string	"auto"	"free" — free models only. "economy" — favor cheap models. "auto" — balanced (default). "premium" — best quality. Legacy aliases: low/medium/high still accepted.
stream	boolean	false	Enable SSE streaming. Works in both modes.
temperature	number	—	Passed through to the model provider.
max_tokens	number	—	Passed through to the model provider.
session_id	string	—	Pin model selection across requests. Same session_id reuses the same model for 1 hour.
exclude_models	string[]	—	Array of model IDs to exclude from selection.
max_cost	number	—	Max cost per request in USD. Models above this price are excluded (graceful downgrade).
workflow_budget	object	—	{ session_id, total_budget_usd } — Multi-step workflow with shared budget. Auto-downgrades at 60/80/95%.

Response Format

Responses follow the OpenAI schema with an additional routing or consensus object depending on the mode used.

Default Mode Response

{
  "id": "cons-1710...",
  "object": "chat.completion",
  "model": "arc-router-v1",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "..." },
    "finish_reason": "stop"
  }],
  "routing": {
    "mode": "default",
    "selected_model": "google/gemini-2.0-flash-001",
    "model_name": "Gemini 2.0 Flash",
    "provider": "Google",
    "call_path": "direct:google",
    "topic_detected": "science",
    "topic_confidence": 0.85,
    "complexity_tier": "MEDIUM",
    "complexity_confidence": 0.72,
    "budget": "auto",
    "data_source": "semantic",
    "failover_count": 0,
    "models_considered": 8,
    "is_agentic": false,
    "estimated_cost_usd": 0.0003,
    "savings_vs_gpt4_pct": 89
  }
}

Council Mode Response

{
  "id": "cons-1710...",
  "object": "chat.completion",
  "model": "arc-router-v1",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "..." },
    "finish_reason": "stop"
  }],
  "consensus": {
    "confidence": 0.92,
    "tier": "MEDIUM",
    "votes": [
      { "model": "google/gemini-2.0-flash-001", "answer": "...", "agrees": true },
      { "model": "meta-llama/llama-3.3-70b", "answer": "...", "agrees": true },
      { "model": "qwen/qwen-2.5-72b", "answer": "...", "agrees": false }
    ],
    "budget": "free",
    "synthesized": false,
    "cached": false,
    "mode_used": "council",
    "degraded": false,
    "deliberation": {
      "triggered": false,
      "rounds": 1,
      "round1_groups": 2,
      "chairman_used": false
    }
  }
}

Response Headers (Default Mode)

In default (smart routing) mode, routing metadata is also returned via response headers:

Header	Description
X-ArcRouter-Mode	Routing mode used ("default")
X-ArcRouter-Model	Model ID selected by the router
X-ArcRouter-Topic	Detected topic domain (e.g. "math", "coding")
X-ArcRouter-Budget	Budget tier applied
X-ArcRouter-Confidence	Topic detection confidence (0-1)
X-ArcRouter-Failover-Count	Number of failover attempts before success

Streaming

Set stream: true for Server-Sent Events (SSE). Both modes support streaming. The format is compatible with OpenAI SDKs.

SSE Format

data: {"id":"cons-...","object":"chat.completion.chunk","choices":[{"delta":{"role":"assistant","content":""},"finish_reason":null}]}

data: {"id":"cons-...","object":"chat.completion.chunk","choices":[{"delta":{"content":"Quantum computing"},"finish_reason":null}]}

data: {"id":"cons-...","object":"chat.completion.chunk","choices":[{"delta":{},"finish_reason":"stop"}],"consensus":{...}}

data: [DONE]

In council mode, consensus metadata (confidence, votes) is attached to the final finish_reason: "stop" chunk. In default mode, routing headers are sent with the initial response.

Agent Workflow

Build multi-step agent workflows with automatic budget tracking, complexity hints, and model pinning.

X-Agent-Step Header

Tell the router what kind of work each step does. This overrides automatic complexity scoring for better model selection.

Step Value	Complexity	Use For
simple-action	SIMPLE	Formatting, extraction, simple lookups
code-generation	COMPLEX + code topic	Writing code, debugging
reasoning	REASONING	Analysis, planning, complex decisions
verification	Council mode	Cross-checking, validation

Workflow Budget

Cap total spend across multi-step workflows. The router auto-downgrades budget tier as you approach limits.

// First request: initialize workflow budget
curl https://api.arcrouter.com/v1/chat/completions \
  -H "Authorization: Bearer sk_..." \
  -H "X-Agent-Step: planning" \
  -d '{
    "messages": [{"role": "user", "content": "Plan the implementation"}],
    "workflow_budget": {
      "session_id": "agent-run-42",
      "total_budget_usd": 5.00
    }
  }'

// Response headers:
// X-ArcRouter-Budget-Remaining: 4.998
// X-ArcRouter-Budget-Used-Pct: 0.04

// Check workflow usage:
curl https://api.arcrouter.com/v1/workflow/agent-run-42/usage

Auto-downgrade thresholds: 60% used → economy models, 80% → free models, 95% → strict free only, 100% → 402 error.

Models & Scores

ArcRouter maintains a database of 345+ models with benchmark scores across 6 domains. Scores are refreshed daily from HuggingFace Open LLM Leaderboard, LiveBench, and LiveCodeBench.

Score Domains

math

GSM8K, MATH, competition mathematics

code

LiveCodeBench, HumanEval, code generation

reasoning

ARC, HellaSwag, logical reasoning

science

GPQA, MMLU-Pro, scientific knowledge

writing

Creative writing, professional content, editing

general

General knowledge, translation, comprehension

Routing Logic

In default mode, the router detects the prompt's topic, then selects the highest-scoring model within the requested budget tier. Semantic routing uses embedding similarity for nuanced topic matching. A circuit breaker skips models with recent failures, and up to 3 failover attempts are made automatically.

Browse all model scores on the rankings page.

SDKs & Integrations

Use the official ArcRouter SDK for the best experience, or drop in with any OpenAI-compatible client.

ArcRouter TypeScript SDK

Official SDK with smart routing, council mode, streaming, workflow budgets, and x402 auto-payment.

npm install arcrouter

import { ArcRouter } from 'arcrouter';

const arc = new ArcRouter({ apiKey: 'sk_...' });

// Smart routing
const res = await arc.chat('Write a Python parser');
console.log(res.content);
console.log(res.routing.model);           // e.g. "anthropic/claude-sonnet-4-5"
console.log(res.routing.estimatedCostUsd); // e.g. 0.0008

// Council mode
const council = await arc.council('Is P = NP?');
console.log(council.confidence, council.votes);

// Streaming
for await (const chunk of arc.stream('Write a story...')) {
  process.stdout.write(chunk);
}

// Workflow with budget
const wf = arc.workflow({ sessionId: 'agent-42', totalBudget: 5.00 });
const plan = await wf.chat('Plan it', { agentStep: 'planning' });
const code = await wf.chat('Build it', { agentStep: 'code-generation' });

// x402 micropayments (no API key needed)
import { privateKeyToAccount } from 'viem/accounts';
const arc402 = new ArcRouter({
  wallet: privateKeyToAccount('0x...'),
});

OpenAI Python SDK (Drop-in)

from openai import OpenAI

client = OpenAI(
    base_url="https://api.arcrouter.com/v1",
    api_key="sk_your_key"  # Optional for free tier
)

# Smart routing (default mode)
response = client.chat.completions.create(
    model="arc-router-v1",
    messages=[{"role": "user", "content": "Explain quantum computing"}]
)
print(response.choices[0].message.content)

# Council mode with streaming
stream = client.chat.completions.create(
    model="arc-router-v1",
    messages=[{"role": "user", "content": "Write a sorting algorithm"}],
    stream=True,
    extra_body={"mode": "council", "budget": "economy"}
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

OpenCode (AI Coding Agent)

Use ArcRouter as your coding agent with multi-model consensus verification.

# 1. Install OpenCode
curl -fsSL https://opencode.ai/install | bash

# 2. Add config to ~/.config/opencode/opencode.json
{
  "provider": {
    "arcrouter": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "ArcRouter",
      "options": {
        "baseURL": "https://api.arcrouter.com/v1"
      },
      "models": {
        "arc-router-v1": {
          "name": "ArcRouter v1"
        }
      }
    }
  }
}

# 3. Start OpenCode and select the model
opencode
/model arcrouter:arc-router-v1

Any OpenAI-compatible tool works — just set the base URL to https://api.arcrouter.com/v1.

Other Compatible Tools

ArcRouter works with any tool that supports custom OpenAI base URLs:

✓Cursor: Set custom OpenAI endpoint in settings
✓Cline: Configure custom LLM provider
✓LangChain: Use ChatOpenAI with custom base_url
✓LlamaIndex: Configure OpenAI-compatible endpoint

Pricing & Limits

Tier	Auth	Price	Rate Limit	Models
Free	None	$0	20 / hr per IP	Free models only
MPP	USDC.e on Tempo	$0.001–$0.015 / req	1,000 / hr per wallet	All budgets
x402	USDC on Base	$0.001–$0.015 / req	1,000 / hr per wallet	All budgets
API Key	Bearer token	Coming soon	1,000 / hr	All budgets

Variable Pricing by Complexity

Both MPP and x402 use identical tier-based pricing. Your prompt is classified automatically and the price is advertised in the 402 challenge before payment:

SIMPLE queries$0.001 / request

MEDIUM queries$0.002 / request

COMPLEX queries$0.005 / request

REASONING queries$0.012 / request

PREMIUM (any request with budget=premium)$0.015 / request

Council mode (mode="council")5x tier price

budget="auto" optimizes cost vs quality automatically — most prompts route to cheap models, complex prompts route to better ones, you pay the matching tier price. budget="premium" authorizes ArcRouter to pick frontier models (Sonnet 4.5, Opus, GPT-5) when useful and charges a flat $0.015 per request regardless of complexity. Use auto unless you specifically want premium models guaranteed.

Both MPP (Tempo USDC.e) and x402 (Base USDC) rails are advertised in the same 402 challenge — your client picks whichever wallet it holds. Pricing parity prevents arbitrage. API Key tier (Stripe metered billing) is coming soon.

Budget Tiers

The budget parameter controls cost sensitivity. Paid users default to "auto". Free-tier users are always restricted to free models.

"free"Free models only (cost: $0)

"economy"Strongly prefer cheap models (alias: "low")

"auto" (default)Balanced quality vs cost (alias: "medium")

"premium"Best quality, ignore cost (alias: "high")

MCP Server

ArcRouter exposes a Model Context Protocol (MCP) server for AI coding assistants like Claude Code, Cursor, and Cline.

Setup

# Add ArcRouter as an MCP server in Claude Code
claude mcp add arcrouter --transport http https://api.arcrouter.com/mcp

Available Tools

arcrouter_chat

Route a prompt to the best model. Supports budget, mode, and all routing parameters.

arcrouter_models

List available models with benchmark scores, filtered by topic and budget.

arcrouter_health

Check system status — API keys, database, routing, provider availability.