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.
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 →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 →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 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
}'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,
});# 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.# 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.
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
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
Your account id and API balance in USD.
Auth: Key
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
Your most recent requests: model, tokens, cost in USD, streaming or not.
Auth: Key
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
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.
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).
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.
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.
| Status | Code | When |
|---|---|---|
| 400 | invalid_request_error | The body isn't valid JSON, or a field such as max_tokens is out of range. |
| 401 | invalid_api_key | The Authorization header is missing, malformed or the key was revoked. |
| 402 | insufficient_balance | Your balance can't cover the request's hold. Top up and retry. |
| 403 | model_not_allowed | The model is blocked on Surplus. Nothing is held. |
| 403 | upstream_not_allowed | The model is served by an upstream your x-surplus-upstreams header leaves out. Nothing is held. |
| 404 | model_not_found | The model id isn't in GET /models. |
| 413 | request_too_large | The request body is larger than 4 MB. |
| 429 | rate_limit_exceeded | More 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. |
| 502 | upstream_error | The provider is unreachable. Other provider errors pass through with their own status. You are not charged. |
{
"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
- quote(credits) prices the purchase against the listings.
- Approve USDG for the total plus a small slippage buffer.
- buy(credits, maxTotal, recipient, referrer) fills exactly that amount or reverts.
- 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.
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).
02
List
sell(amount, discountBps) escrows your CREDIT at one discount level. Orders in a level fill first in, first out.
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 ↗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.
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.
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.
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.
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.
Whether agent launches are open, the launch price in USD and the platforms.
Auth: None
Body { name, model, systemPrompt, description?, greeting?, avatar?, url? }. Creates an agent; returns its id and slug.
Auth: Session
A one-time code and the post to publish from the agent's X account. Valid for an hour.
Auth: Session
Body { tweetUrl }. Reads the post and links its X account; one X account backs one agent.
Auth: Session
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
Body { message, chatId? }. Streams the agent's answer as server-sent events.
Auth: Session
Agents with a listed token, newest launch first, each with launch { token, status, platform }.
Auth: None
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.
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.
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.
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.
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.
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.
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.
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.
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
# 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
}'Factory addresses, minimum creator tax, model size limit, fee split, and the size tiers with each one's per-token price.
Auth: None
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
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
Body { txHash }. Lists a Pons or Flywheel launch after its receipt. Retry 404, 429 and 5xx; 422 is final.
Auth: None
One launch: status, splitter, pinned model, live model id, hosting paid and owed, inference revenue and the launcher's share.
Auth: None
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.