man surp.ivc.lol
A per-request, x402-paywalled HTTP API for LLM inference. You send a chat completion request with a combo as the model name; we resolve that combo to the single cheapest concrete model currently listed on Surplus Intelligence, charge you that spot price plus a small markup, and forward the request. Settlement is on-chain USDC on Base via the x402 protocol.
Combos come in two tiers × five classes, plus three bare aliases and a free tier:
| combo | tier | class | meaning |
|---|---|---|---|
| surp/best-coding | best | coding | cheapest model with "coder"/"codex"/"qwen3-coder" in the name |
| surp/best-reasoning | best | reasoning | cheapest "thinking"/"r1"/"reasoning" model |
| surp/best-fast | best | fast | cheapest small/mini/nano/lite model |
| surp/best-vision | best | vision | cheapest multimodal vision model (-vl / vision / 5v) |
| surp/best-chat | best | chat | cheapest text LLM not in a specialized class |
| surp/best-coding-fast | best | coding∩fast | cheapest coding model (fast-coding cross, falls back to coding pool) |
| surp/pro-coding | pro | coding | cheapest frontier-tier coding model (qwen3-coder-turbo, gpt-5.x-codex) |
| surp/pro-reasoning | pro | reasoning | cheapest frontier reasoning model (deepseek-r1, qwen3-thinking) |
| surp/pro-vision | pro | vision | cheapest frontier vision model (qwen3-vl-235b, etc.) |
| surp/pro-chat | pro | chat | cheapest frontier chat model (gpt-5.6, claude-opus, gemini-pro) |
| surp/pro-fast | pro | fast | cheapest frontier fast model (gemini-2.5-pro, etc.) |
| surp/coding | — | — | alias for surp/best-coding |
| surp/fast | — | — | alias for surp/best-fast |
| surp/chat | — | — | alias for surp/best-chat |
| surp/srup-free | — | — | zero-price model if any exist, else absolute cheapest text LLM |
The 15 built-ins are opinionated. If you'd rather decide the candidate set yourself, use the builder: pick any number of models (2–20) from the 152 text LLMs on Surplus, and we save that set as a combo with its own model id.
On every request we compare only your chosen models at their live prices and route to the cheapest one. You are never routed outside your set.
Frontier models are near-substitutes for most work, but their prices differ by more than an order of magnitude and move independently. Pick five you'd be happy with and you pay the price of whichever is cheapest at that second:
$ 1.3930/1M gpt-5.6-luna-pro <-- routed
$ 2.7621/1M grok-4.3
$ 7.1928/1M claude-sonnet-5
$10.4895/1M kimi-k3
$17.9000/1M claude-opus-5
-> 92% cheaper than the priciest pick in the same set
curl -X POST https://surp.ivc.lol/api/combos/custom \
-H "Content-Type: application/json" \
-d '{"name":"my frontier five",
"models":["claude-opus-5","gpt-5.6-sol","claude-opus-4.8","grok-4.5","gemini-3.1-pro"]}'
Returns a model_id like surp/my/d1e8eff1. Use it exactly like a built-in combo:
curl -X POST https://surp.ivc.lol/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{"model":"surp/my/d1e8eff1","messages":[{"role":"user","content":"hi"}]}'
Slugs are a content hash of the sorted model set, so the same picks always produce the same id — combos are shareable and de-duplicated. Inspect any combo (including its live pool ordering) at GET /api/combos/custom/<slug>, or browse what others built at GET /api/combos/custom.
curl -X POST https://surp.ivc.lol/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{"model":"surp/best-chat","messages":[{"role":"user","content":"hi"}],"max_tokens":100}'
The first time, you get back HTTP 402 Payment Required with an PAYMENT-REQUIRED header. That header is a base64-encoded JSON blob describing exactly what USDC authorization to sign: the pay-to address, the amount in atomic USDC units (6 decimals), the asset contract (USDC on Base), the network, and the max settlement window.
{
"x402Version": 2,
"error": "payment-required",
"combo": "surp/best-chat",
"routed_model": "glm-5.2",
"surplus_price_per_1m": 30000,
"expected_tokens": 100,
"price_usd": "$0.01",
"accepts": [{
"scheme": "exact",
"network": "eip155:8453",
"asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
"amount": "10000",
"payTo": "0x...",
"maxTimeoutSeconds": 600
}]
}
Use any x402 client library to sign the EIP-3009 authorization and retry with the X-Payment header:
# Python (x402 client library)
from x402.http import x402HTTPClientSync
client = x402HTTPClientSync()
resp = client.post(
"https://surp.ivc.lol/v1/chat/completions",
json={"model":"surp/best-chat","messages":[{"role":"user","content":"hi"}]},
)
print(resp.json()) # the actual chat completion
The client lib handles the 402 → sign → retry loop automatically. See docs.x402.org for JS, Python, and TypeScript clients.
For a given request with max_tokens = N:
price_usd = (surplus_best_price_per_1m / 1e6) * (N / 1_000_000) * (1 + markup_bps/10000) price_usd = max(price_usd, floor_cents/100) amount_atomic_usdc = ceil(price_usd * 100) * 10_000 # 6-decimal USDC
Currently markup_bps = 500 (5%), floor_cents = 1 (one penny minimum). Surplus's best_price_per_1m is denominated so that 1e6 = $1.00 per 1M tokens (calibrated against known retail prices). The markup covers our gateway/facilitator operating cost and a tiny margin; everything else passes through to the underlying Surplus seller at spot.
GET /api/combos — freeReturns the live resolution for all 15 combos — the model each one currently routes to, its Surplus spot price, and the pool size. Useful for building dashboards.
GET /api/models — freeThe full catalog of Surplus text LLMs with live prices, class labels, and frontier-tier flags. This is what the builder reads.
POST /api/combos/custom — freeCreate a custom combo. Body: {"name": str, "models": [str, ...]} (2–20 models). Idempotent on the model set. Unknown or non-text model ids are rejected with a 400.
GET /api/combos/custom / GET /api/combos/custom/<slug> — freeList community combos (most-used first), or inspect one including its live cheapest-first pool.
GET /api/health — freeGateway status: resolver URL, facilitator URL, network, pay-to address, markup, market cache size.
POST /v1/chat/completions — x402OpenAI-compatible. model must be surp/<combo>. Streaming ("stream": true) supported — we pipe SSE chunks straight through from the underlying seller.
GET /v1/models — freeReturns the 15 combos as OpenAI-format model IDs.
Every paid response carries these headers so you can verify the routing on-chain:
X-Payment-Settled: true — facilitator confirmed the USDC transferX-Routed-Model: <model_id> — which Surplus model actually served the requestX-Surplus-Price-Per-1M: <atomic> — the spot price we paidThe difference between what you paid and X-Surplus-Price-Per-1M × tokens / 1e6 is our markup. That's the entire business model, and it's fully auditable per-request.