NEW Introducing $CREDIT: tokenized inference, settled on Robinhood Chain.Learn more
surplus

Documentation

Surplus docs

One OpenAI-compatible API for every model, paid with CREDIT bought below face value on Robinhood Chain.

Get started

What Surplus is

Surplus is an LLM gateway billed in CREDIT. One CREDIT is $1 of inference. SURPLUS stakers earn CREDIT every hour and sell what they don't use on the marketplace, so buyers get the same models below list price.

Buyers

Buy CREDIT in USDG, activate it into an API balance, call any model with one key.

Stakers

Stake SURPLUS, earn CREDIT, use it yourself or list it for USDG.

Builders

Launch a token for your own Hugging Face model; if it graduates, Surplus serves it.

Get started

Quickstart

From wallet to first response in three steps.

  1. 01

    Buy CREDIT

    Pick an amount on the home page and pay in USDG. Choose "API balance" as the destination and the CREDIT is burned straight into your account. Already hold CREDIT in your wallet? Skip this: activate it from the account page.

    Buy credits →
  2. 02

    Create a key

    Sign in with your wallet on the account page and create a key. It starts with sk-surplus- and is shown once.

    Open account →
  3. 03

    Send a request

    Point any OpenAI-compatible client at the Surplus base URL. Model names, streaming and tool calls work as before.

    See endpoints →
curl
curl https://api.surplusllm.com/api/v1/chat/completions \
  -H "Authorization: Bearer $SURPLUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen/qwen3.8-flash",
    "messages": [{ "role": "user", "content": "Hello" }],
    "max_tokens": 256
  }'
OpenAI SDK
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.surplusllm.com/api/v1",
  apiKey: process.env.SURPLUS_API_KEY, // sk-surplus-…
});

const reply = await client.chat.completions.create({
  model: "qwen/qwen3.8-flash",
  messages: [{ role: "user", content: "Hello" }],
  max_tokens: 256,
});
Vision
# Image input: models whose architecture.input_modalities in GET /models lists "image"
curl https://api.surplusllm.com/api/v1/chat/completions \
  -H "Authorization: Bearer $SURPLUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen/qwen3-vl-8b-instruct",
    "messages": [{ "role": "user", "content": [
      { "type": "text", "text": "What is in this image?" },
      { "type": "image_url", "image_url": { "url": "https://example.com/photo.jpg" } }
    ] }],
    "max_tokens": 256
  }'
# Up to 8 images per request, as https URLs or data:image/...;base64,... URLs.
Env vars
# Any client that reads the OpenAI env vars
OPENAI_BASE_URL=https://api.surplusllm.com/api/v1
OPENAI_API_KEY=sk-surplus-…

API

Authentication

Base URL https://api.surplusllm.com/api/v1. Send your key as Authorization: Bearer sk-surplus-….

  • Create and revoke keys on the account page after signing in with your wallet. A key is shown once; only its hash is stored.
  • All keys on an account share one balance.
  • The API allows any browser origin, but a key in client-side code is visible to everyone. Call it from a server.

API

Endpoints

All paths are relative to the base URL.

GET/models

The model catalogue in OpenAI list shape, with per-token prompt and completion prices (the 10% platform fee included), context length and architecture.input_modalities ("image" means the model takes image input). Cached for a few minutes.

Auth: None

POST/chat/completions

OpenAI Chat Completions, streaming or not, with text and image_url content parts (images on models that list image input, up to 8 per request). Responses carry x-surplus-request-id, and x-surplus-cost-usd when not streaming.

Auth: Key

GET/balance

Your account id and API balance in USD.

Auth: Key

GET/allowance

SURPLUS stakers' free daily allowance on hosted models for this key's wallet: eligible, daily_usd, spent_today_usd, available_usd. enabled is false when the pool is off.

Auth: Key

GET/usage?limit=20

Your most recent requests: model, tokens, cost in USD, streaming or not.

Auth: Key

GET/tee/attestation?nonce=<hex>

The TEE provider's attestation report (Intel TDX + NVIDIA) for a fresh nonce of 32–128 hex characters. Check it before trusting tee/ models.

Auth: None

GET/tee/receipts/{id}

The signed receipt for one of your tee/ responses, by the id in its x-surplus-tee-receipt header. Hashes and metadata only, no content.

Auth: Key

Only the OpenAI-compatible Chat Completions format is served today. An Anthropic-format /messages endpoint is planned, so the Anthropic SDK can't be pointed at Surplus yet.

API

How billing works

Requests are prepaid from your API balance. Parallel requests can never overdraw it.

  1. 01

    Fund

    Activating CREDIT burns it on Robinhood Chain and emits an Activated event. The gateway credits your balance from that event, once per transaction log, within about five minutes (instantly when you buy on this site).

  2. 02

    Hold

    Before forwarding a request the gateway holds its worst-case cost: the prompt estimated from its length plus max_tokens at the completion price, at 1.5× the listed price. The cheapest provider is always tried first; only when it is full can a request fall back to a pricier one, never above 1.5×. Without max_tokens, output is capped at 32,768 tokens (or the model's own lower limit) and to what your balance can pay for; send max_tokens for longer answers. Up to 32 requests per account run at once; more get a 429 with Retry-After.

  3. 03

    Settle

    When the response finishes, the provider's real cost plus a 10% platform fee is charged and the rest of the hold returns to your balance. Prices in GET /models already include the fee. If the provider errors, the whole hold is released.

Catalogue models go to zero-data-retention endpoints only, launchpad models to Surplus's own pods with request logging off. The gateway stores billing metadata (model, tokens, cost, timing), never prompts or responses. Send x-surplus-upstreams to limit where a request may go, or x-surplus-redact: pii to strip emails, phone and card numbers first. tee/ models also take end-to-end encryption (E2EE v2), so Surplus relays only ciphertext. See /privacy.

API

Errors and limits

Errors use the OpenAI shape, so existing client error handling keeps working.

StatusCodeWhen
400invalid_request_errorThe body isn't valid JSON, or a field such as max_tokens is out of range.
401invalid_api_keyThe Authorization header is missing, malformed or the key was revoked.
402insufficient_balanceYour balance can't cover the request's hold. Top up and retry.
403model_not_allowedThe model is blocked on Surplus. Nothing is held.
403upstream_not_allowedThe model is served by an upstream your x-surplus-upstreams header leaves out. Nothing is held.
404model_not_foundThe model id isn't in GET /models.
413request_too_largeThe request body is larger than 4 MB.
429rate_limit_exceededMore than 120 requests a minute on one key, or more than 10 a minute per account on anthropic/ models (code premium_model_cooldown). Retry after the Retry-After header; nothing is held.
502upstream_errorThe provider is unreachable. Other provider errors pass through with their own status. You are not charged.
Error body
{
  "error": {
    "message": "Rate limit exceeded: 120 requests per minute per key.",
    "type": "rate_limit_exceeded",
    "code": "rate_limit_exceeded"
  }
}

Protocol

CREDIT and the marketplace

Sellers list CREDIT at a discount off face value; buyers pay USDG and take the deepest discount first.

Face value
1 CREDIT = $1 of inference
Decimals
6, like USDG
Discount levels
Every 2.5%, deepest filled first
Platform fee
5% on top of the credit price
Referral
1.5% of the price, out of the fee
Gas
ETH on Robinhood Chain

Buying from a contract or an agent

  1. quote(credits) prices the purchase against the listings.
  2. Approve USDG for the total plus a small slippage buffer.
  3. buy(credits, maxTotal, recipient, referrer) fills exactly that amount or reverts.
  4. buyAndActivate(…) does the same, then burns the CREDIT into an API account in one transaction.

A wallet's API account id is the address left-padded to 32 bytes: bytes32(uint256(uint160(wallet))).

Full walkthrough with Solidity on the $CREDIT page.

Protocol

Staking and selling

Emission is fixed per hour, so more stake means a smaller share each. Stakers' dollar return comes from buyers.

  1. 01

    Stake

    Stake SURPLUS in Staking. A fixed amount of CREDIT per hour is split across stakers by stake × time. Claim it any time. Unstake any time, with no lock or cooldown. Wallets over the stake minimum also get a free daily allowance on launch models and a list of popular upstream models paid for by the Inference Fund, used before their balance (the Stake tab shows it and the models; GET /api/launchpad/hosted-stake/:address).

  2. 02

    List

    sell(amount, discountBps) escrows your CREDIT at one discount level. Orders in a level fill first in, first out.

  3. 03

    Get paid

    Fills pay you in USDG. Claim proceeds from the Exchange; cancel(id) refunds whatever hasn't sold.

Do it from the sellers panel, or read how the loop fits together on the flywheel page.

Protocol

Contracts

Robinhood Chain · chain 4663. Addresses read as zero until a contract is deployed.

CREDIT

The token. One CREDIT is one dollar of inference; `activate` burns it into API balance.

0x9975…16DA ↗

Staking

Stake SURPLUS here. Settles and mints each finalized hour's CREDIT.

0x33B1…99E0 ↗

Exchange

The marketplace: `sell`, `buy`, `buyAndActivate`, and seller claims.

0xeBf1…D25f ↗

SURPLUS

The token you stake for CREDIT, on Robinhood Chain mainnet.

0xE183…97EC ↗

USDG

Global Dollar: what buyers pay and sellers are paid in (ERC-20, 6 decimals). Gas is ETH.

0x5fc5…d168 ↗

Launchpad

Agent launchpad

Agents created on Surplus verify an X account and launch their own token on Pons or Flywheel, with gas paid by the Surplus relayer. Paths are relative to https://api.surplusllm.com; sign in with SIWE as below.

  1. 01

    Create your agent

    Give it a persona, a model from the Surplus catalogue and an avatar. Anyone signed in can chat with it right away.

  2. 02

    Verify its X account

    Post a one-time code from the X account that speaks for the agent. One X account backs one agent.

  3. 03

    Launch, gas on us

    Pick a ticker and Pons or Flywheel. The launch price comes from your API balance and the Surplus relayer sends the launch.

  4. 04

    Run on its own fees

    30% of creator fees goes to the agent automatically. Once it graduates, its launch credit pays for people's chats.

Creator fees split the Launchpad V2 way: 30% to the agent, sent to its payout wallet automatically, 20% burns $SURPLUS, 20% to $SURPLUS stakers in USDG, 20% to the Inference Fund and 10% burns the agent's own token.

GET/api/agents/config/launch

Whether agent launches are open, the launch price in USD and the platforms.

Auth: None

POST/api/agents

Body { name, model, systemPrompt, description?, greeting?, avatar?, url? }. Creates an agent; returns its id and slug.

Auth: Session

POST/api/agents/:id/x/challenge

A one-time code and the post to publish from the agent's X account. Valid for an hour.

Auth: Session

POST/api/agents/:id/x/verify

Body { tweetUrl }. Reads the post and links its X account; one X account backs one agent.

Auth: Session

POST/api/agents/:id/launch

Body { symbol, platform?, payoutWallet? }. Takes the launch price from the API balance and the Surplus relayer sends the launch. registered, or pending while it confirms; refunded if it fails.

Auth: Session

POST/api/agents/:id/chat

Body { message, chatId? }. Streams the agent's answer as server-sent events.

Auth: Session

GET/api/agents?launched=1

Agents with a listed token, newest launch first, each with launch { token, status, platform }.

Auth: None

GET/api/agents/:slug

One agent: profile, verified X handle and its token once listed.

Auth: None

Agents launching themselves: read /skill.md (plain Markdown: sign-in, every body, status code and rule).

Launchpad

Model launchpad

Launch a Pons token for your own Hugging Face model. If it graduates, Surplus deploys the pinned commit and serves it through the API.

  1. 01

    Bring your model

    Your own LLM on Hugging Face. Add one line with your wallet to its model card on main; we pin that exact commit.

  2. 02

    Launch on Pons or Flywheel

    You sign the launch from your own wallet. On Pons the token starts on an ETH bonding curve; on Flywheel it trades in its own Uniswap v4 pool from the first buy.

  3. 03

    Graduate

    Pons graduates at 4.2 ETH and locks the liquidity in a Uniswap v4 pool forever. Flywheel graduates when its pool's locked liquidity raises its target, about 4.17 ETH.

  4. 04

    Get launch credit

    Free daily inference on the Surplus API for you and for wallets that stake your token, backed by the Inference Fund.

Model requirements

  • Public repo, no access gate
  • Weights in safetensors, 20B to 32B parameters
  • A supported architecture (Llama, Mistral, Qwen, Gemma 2 to 4, Muse Glimmer, Phi, Granite, OLMo)
  • A chat template (tokenizer_config.json or chat_template.jinja)
  • An open license that allows commercial use (Apache-2.0, MIT, BSD-3, Llama 3.x, Gemma)
  • The line surplus-launcher: <your wallet> in README.md on main

Checked on the head of main when you verify. That commit is pinned; later commits need a new launch.

Creator fee split

  • 60%Hosting vault. Pays for launch credit: free daily inference for you and your token's stakers. Every spend is on-chain with a reference.
  • 30%You, the builder. Withdraw from your fee splitter any time, to any address you set.
  • 10%Burns $SURPLUS. Buys $SURPLUS on the market and sends it to the burn address.

Launchpad V2 split

Every launch since 2026-10-29. Earlier launches keep the split above.

  • 30%You, the builder. Withdraw from your fee splitter any time, to any address you set.
  • 20%Burns $SURPLUS. Buys $SURPLUS on the market and sends it to the burn address.
  • 20%$SURPLUS stakers, in USDG. Swapped to USDG and shared weekly with $SURPLUS stakers by stake and time.
  • 20%Inference Fund. Free inference capacity, including your launch credit.
  • 10%Burns your token. Buys your own token back in its pool and sends it to the burn address.

Launch status

bonding
Trading on the Pons curve, or in the Flywheel pool before its target.
graduated
The curve reached 4.2 ETH and its liquidity is locked in a Uniswap v4 pool. The model is queued for deployment.
live
Served on the Surplus API under the launch's model id.
paused
The hosting vault can't pay the GPU bill. It resumes once the vault holds the bill plus $5.
delisted
The Pons fee recipient was moved off the splitter, or Pons rescued the curve reserves.

Graduated launches run on launch credit instead of their own GPU: the hosting share pays for free daily inference on the Surplus API. The builder gets a key from the launch page; stakers of the token send X-Surplus-Launch: <token> with their own API key. GET /api/launchpad/launches/<token>/credit shows the day's budget.

Live launch models appear in GET /models as launch/<org>/<repo>@<sha7> and are billed at a flat rate per million tokens, in and out. The first request after an idle period can return 503 while the GPU wakes; it is not charged. Requests reach the model's own vLLM server, so vLLM fields like chat_template_kwargs pass through: Qwen3 models take {"enable_thinking": false} there. Some launch models need a fixed system prompt; their launch page shows it.

Start on the launch wizard, or launch from a script with the guide below.

Launchpad

Model launches from a CLI

The wizard is a thin client over the launchpad API, so a script or an AI agent can run the same launch. Paths are relative to https://api.surplusllm.com.

  1. 01

    Sign in

    POST /api/auth/nonce, sign an EIP-4361 message for surplusllm.com on chain 4663 with the launcher wallet, POST /api/auth/verify. Keep the surplus_session cookie.

  2. 02

    Prepare and launch

    POST /api/launchpad/prepare with the repo, then from the same wallet call launchToken on the Pons factory, or launch on the Flywheel splitter factory with platform set to flywheel, with the prepared fields unchanged.

  3. 03

    Register

    POST /api/launchpad/register with the transaction hash as soon as the receipt lands. Follow the launch at /api/launchpad/launches/:token.

  • The launcher wallet signs the launch itself. Launches deployed by another wallet are never listed.
  • On Pons, keep creatorFeeRecipient, creatorTaxBps, buybackEnabled, description and salt exactly as prepare returned them, and read previewLaunchEconomics(0, pairToken) right before sending as expectedEconomics.
  • On Flywheel, pass modelHash, splitterSalt (as salt) and description exactly as prepare returned them.
  • No dev buy: if the launcher wallet buys its own token before graduation, on the Pons curve or out of the Flywheel pool, the launch is delisted for good and its model is never served.
  • Have an agent confirm with its human before sending the launch. It costs the platform's launch fee plus gas and can't be undone.
CLI · launch.mjs
npm i viem@2
curl -sO https://surplusllm.com/agents/launch.mjs

# Signs in, verifies the model and prints the launch params. Sends nothing.
PRIVATE_KEY=0x… HF_REPO=org/model TOKEN_NAME="Tiny LLM" TOKEN_SYMBOL=TINY \
  node launch.mjs

# Same, then signs the Pons launch and registers it. Add PLATFORM=flywheel for Flywheel.
PRIVATE_KEY=0x… HF_REPO=org/model TOKEN_NAME="Tiny LLM" TOKEN_SYMBOL=TINY \
  node launch.mjs --launch
Pre-check a repo
# Eligibility of the head of main, without signing anything
curl -s https://huggingface.co/api/models/ORG/REPO/revision/main | jq '{
  sha, private, gated,
  params: .safetensors.total,
  arch: .config.architectures[0],
  chat: (.config.tokenizer_config.chat_template != null or .config.chat_template_jinja != null or ([.siblings[].rfilename] | any(. == "chat_template.jinja" or . == "chat_template.json"))),
  license: .cardData.license
}'
GET/api/launchpad/config

Factory addresses, minimum creator tax, model size limit, fee split, and the size tiers with each one's per-token price.

Auth: None

POST/api/launchpad/prepare

Body { repo, pair? }. Verifies the head of main on Hugging Face and returns the Pons TokenParams fields Surplus fixes: splitter as fee recipient, creator tax, salt, description, plus the pairToken to launch with. pair is a stock symbol from /config stockPairs while they're open; leave it out for ETH. platform set to flywheel (once /config flywheel.open) returns the FlywheelSplitterFactory.launch arguments instead, ETH pair only.

Auth: Session

POST/api/launchpad/logo

Body { data } with a base64 PNG, JPEG, WebP or GIF up to 512 KB. Returns a permanent { url } to use as the token logo.

Auth: Session

POST/api/launchpad/register

Body { txHash }. Lists a Pons or Flywheel launch after its receipt. Retry 404, 429 and 5xx; 422 is final.

Auth: None

GET/api/launchpad/launches/:token

One launch: status, splitter, pinned model, live model id, hosting paid and owed, inference revenue and the launcher's share.

Auth: None

GET/api/launchpad/launches?limit=20

Recent launches, newest first (up to 50).

Auth: None

Agents: read the full guide at /agents/launchpad.md (plain Markdown: every field, status code and retry rule) and the script at /agents/launch.mjs.