Question 1

What is Surplus Intelligence?

Accepted Answer

Surplus is an open marketplace for AI inference. Buyers call one OpenAI-compatible base URL and each request is sent to eligible seller capacity. Sellers connect supported provider endpoints, set prices and limits, and earn USDC when their offers serve completed requests.

Question 2

Who is Surplus for?

Accepted Answer

- Buyers and developers who want lower-cost model access through one OpenAI-compatible API. - Sellers and providers who have unused, prepaid, discounted, or otherwise monetizable API capacity. - Agents and applications that need programmatic payments through API keys, x402, or MPP-compatible flows.

Question 3

Why can prices be much lower than direct-provider prices?

Accepted Answer

Sellers set their own prices in an open order book. Some are monetizing capacity that would otherwise expire or go unused; others have discounted provider access. Prices and available capacity can change as seller balances, caps, health, and upstream-provider conditions change.

Question 4

Is Surplus the same as OpenRouter or a model provider?

Accepted Answer

Surplus is a marketplace and router, not the creator of most models it lists. It can route among independent seller endpoints and supports provider filtering, seller health/backoff, buyer-owned priority keys, and multiple payment rails.

Question 5

How do I start buying inference?

Accepted Answer

1. Sign in at https://surplusintelligence.ai. 2. Create or copy an inf buyer API key. 3. Fund your account with card-funded credits or fund your wallet with USDC on Base. 4. For API-key on-chain spending, approve USDC to the SettlementV2 address shown by GET /v1/buyer/me. 5. Point an OpenAI-compatible client at the Surplus gateway (https://api.surplusintelligence.ai/v1). Example: Never post an API key or private key in Discord.

Question 6

Why can I only see a short prefix of my API key?

Accepted Answer

The full API-key secret is shown when the key is created; later screens may show only a prefix. If you did not save the full key, revoke it, create a new one, and store it in a password manager or secret manager. Surplus support should never ask you to paste the key into Discord.

Question 7

What payment methods are supported?

Accepted Answer

Current buyer funding paths include card top-ups through Stripe, Coinbase Onramp, MoonPay through Privy, Peer/ZKP2P, and direct USDC funding. On-chain marketplace settlement and seller payouts use USDC on Base.

Question 8

Which network and token should I use?

Accepted Answer

Use native USDC on Base (chain ID 8453). Sending USDC over BNB Chain, Ethereum, or another network does not fund the Base balance. If you used the wrong network, recover the funds from the same wallet/account and bridge or resend them as Base USDC.

Question 9

Why do I need an approval if my USDC stays in my wallet?

Accepted Answer

API-key marketplace requests use a SettlementV2 USDC allowance. Funds remain in your wallet until a completed request settles. You can cap or revoke the allowance. This is separate from x402 upto, which uses Permit2 and per-request payment signatures.

Question 10

Why does routing say I need at least $1 even when the request costs less?

Accepted Answer

The current on-chain admission check uses a $1 balance-and-allowance floor before routing. This is a funding guardrail, not a $1 charge: final settlement is based on the completed request's metered cost. Card/onramp fees are separate and should be disclosed by the payment provider.

Question 11

My card top-up window closes, flashes, or declines. What should I do?

Accepted Answer

- Allow pop-ups and temporarily disable checkout-blocking extensions. - Complete any bank OTP or identity-verification prompt. - Confirm that your bank supports the card and Stripe transaction. - Try another live funding method, such as Coinbase, MoonPay, Peer, or Base USDC. - If the payment succeeded but the balance did not update, open a ticket with the checkout time, amount, and payment reference. Never send full card details.

Question 12

How does routing work?

Accepted Answer

Surplus evaluates eligible seller offers in a set order. The normal routing order is: 1. Your model-specific priority provider, if configured. 2. Active marketplace offers that pass trust, provider, health, cap, and price filters. 3. The cheapest estimated eligible offer first. 4. Your catch-all fallback provider (model: null), if configured. 5. The universal fallback, where available. If an offer fails, it enters backoff and Surplus tries the next eligible offer when the error is failover-safe.

Question 13

Does "cheapest" mean the lowest displayed input price?

Accepted Answer

Not always. The router estimates total request cost from input size, expected output, and metered components such as cache reads/writes. It also excludes offers that are unhealthy, capped, outside a price threshold, outside the requested provider set, or disallowed by the trust setting.

Question 14

Can I choose a provider?

Accepted Answer

Yes. Advanced requests can pass provider, providerurl, or providerbaseurl. provider may be one provider or an allow-list. This narrows the eligible order book to matching provider hosts. Provider pinning does not select one exact seller offer; Surplus still chooses the cheapest healthy eligible offer within the pinned provider set.

Question 15

Can I choose one exact seller?

Accepted Answer

The standard buyer API does not expose exact-offer selection. You can narrow routing by provider and trust level, use a price ceiling/minimum-discount route, or configure your own priority provider.

Question 16

How do I prevent routing below a minimum discount or above a maximum price?

Accepted Answer

Use the documented minimum-discount route (/min{N}/...) when you want the call to fail instead of using an offer below the threshold. For Chat Completions, buyers can also set X-Max-Price-Per-1M or maxpriceper1m. These filters apply to marketplace offers, not buyer-owned priority/fallback providers. Test media endpoints separately because their units may not be token-based.

Question 17

What do "Account default", "Trusted providers only", and "All providers" mean?

Accepted Answer

Trusted-only routing is the default for new accounts. "Account default" inherits the account-level routing preference. "All providers" opts the key into untrusted providers as well as trusted ones. Trusted status lowers risk but is not proof that a provider served an exact model.

Question 18

Does Surplus verify that a seller served the exact model advertised?

Accepted Answer

Not cryptographically or semantically today. Surplus verifies reachability, authentication, response validity, and operational health, and it classifies known provider domains as trusted. Buyers needing stronger assurance should keep trusted-only routing or use their own BYOK priority provider.

Question 19

Where can I see which provider served my request?

Accepted Answer

The current request-log API is GET /v1/requests. Rows include the provider family, route source, whether fallback was used, status, token counts, cost, and latency. It is cursor-paginated and supports server-side model, provider, key, status, and text filters. The Analytics/Request Log UI is the corresponding dashboard surface.

Question 20

Is my prompt private?

Accepted Answer

For normal synchronous chat/completions, Surplus stores usage and settlement metadata rather than full prompt and response bodies by default. The selected upstream provider still receives the request and may apply its own logging or retention policy. Async media jobs retain request and provider-job metadata for orchestration. There is no cryptographic ZDR guarantee across all marketplace sellers.

Question 21

Where can I see supported models and current prices?

Accepted Answer

Use the live endpoints: Model availability and seller health can change, so do not rely on a static model count.

Question 22

Which API base URL should I use?

Accepted Answer

Point your OpenAI-compatible client at the Surplus gateway: The most common text endpoint is POST /v1/chat/completions. Surplus also supports other model-appropriate surfaces, including Responses, Anthropic Messages compatibility, images, video, music, speech, transcription, and embeddings. Use the endpoint and parameters documented for that model and modality.

Question 23

Why does a model work in one client but fail in another?

Accepted Answer

Clients differ in the API wire and parameters they send. Common causes include: - using Chat Completions when the model/client expects Responses; - unsupported streamoptions, responseformat, tool, or reasoning fields; - provider-specific JSON/schema restrictions; - a context window exceeded by accumulated chat history; - an unavailable provider after trust/provider filtering. Start with a minimal request, confirm the endpoint, then add optional parameters one at a time.

Question 24

Why did a long conversation stop responding?

Accepted Answer

The full conversation sent by your client counts toward the model context window. Check the model metadata from /v1/models, start a new conversation, or enable your client's history compression. A model's advertised maximum may also differ by provider or API surface.

Question 25

Why am I billed for reasoning tokens when I cannot see reasoning text?

Accepted Answer

Some models use hidden internal reasoning tokens but do not expose the reasoning trace. Usage can therefore report reasoning tokens even when the response contains only the final answer. A reasoning-effort flag controls effort where supported; it does not guarantee that reasoning text will be returned.

Question 26

How is prompt caching priced?

Accepted Answer

Cache reads and writes can be separately metered. Cost-multiplier offers apply the multiplier to the model's applicable reference components; explicit per-token offers may carry separate cache rates. Check /v1/prices and the request detail rather than inferring cache cost only from input/output prices.

Question 27

Where can I see the exact cost after a request runs?

Accepted Answer

Use the Analytics Request Log or GET /v1/requests. The current row schema includes buyercostmicro, sellercostmicro, directcostmicro, provider, token counts, and latency. Open the request detail for settlement status, transaction hash, settlement basis, and cache-savings fields. List prices are estimates; the request detail is the per-request record.

Question 28

Why do I see unsupported_provider, no_sellers_for_model, or 503?

Accepted Answer

- 400 unsupportedprovider: every provider pin was unrecognized. - 404 nosellersformodel: the provider/model is supported, but no matching active healthy offer is available. - 503 or overload/timeout: eligible sellers failed or were unavailable. - 401: the Surplus key or an upstream seller key was rejected. - 402: buyer funds/allowance or upstream seller quota may be insufficient. - 429: a Surplus or upstream-provider rate limit was reached. Remove an unnecessary provider pin, check trust settings and funding, inspect the request log, and retry with backoff.

Question 29

What are the rate limits?

Accepted Answer

Current per-minute guardrails are 1,200 completion calls, 600 buyer-control-plane calls, 1,200 seller calls, 1,200 general reads, 300 analytics calls, and 180 public market calls. Every response carries an X-RateLimit-Limit header, so /v1/models and POST /v1/chat/completions report 1200 and /api/markets reports 180. A separate WAF/source-IP ceiling and enterprise allowances can still affect sustained traffic, so contact support before planning high volume from one key or source IP.

Question 30

How do I start selling?

Accepted Answer

1. Sign in and open the Sell page, or authenticate programmatically through seller SIWE. 2. Use a dedicated, provider-capped API key. 3. Discover or select a supported model. 4. Set a price or cost multiplier, daily cap, and payout address. 5. Confirm the offer is active and healthy in the seller dashboard and public market. Seller endpoints should be OpenAI-compatible for the relevant model surface, so the router can forward buyer traffic to them.

Question 31

How do sellers get paid?

Accepted Answer

Seller amounts are paid in USDC on Base to the seller wallet or the offer's payout address. Direct on-chain sales can confirm per request. Credit-funded sales can first appear as accrued and then move through payout processing.

Question 32

How do batched payouts work?

Accepted Answer

To save on-chain fees, your sales accrue into one balance and Surplus pays it out in USDC on Base as a single transfer per seller, rather than one transfer per sale. A payout runs automatically when your balance reaches a minimum (currently $10) or your oldest unpaid earning is 72 hours old, whichever comes first, on a roughly 10-minute cadence, with Surplus covering the gas. Payments go to the recipient fixed when each sale was earned (the offer's payout address, otherwise your default wallet). Track your balance and the next trigger with GET /v1/seller/payouts.

Question 33

When does my balance get paid out?

Accepted Answer

You are paid on the next scheduled run once your balance reaches the minimum (currently $10) or your oldest unpaid earning turns 72 hours old, whichever comes first. A smaller balance rolls forward and keeps accruing until one of those triggers. A payout can also wait a run if your account is under a risk review. Check your balance and the next trigger with GET /v1/seller/payouts, or trigger one yourself with Payout now.

Question 34

Can I trigger a payout myself?

Accepted Answer

Yes. Use Payout now to send your full available balance right away, with no minimum. Unlike the scheduled batch, you submit the payout yourself with a signed authorization and pay the Base gas. It goes to the same recipient as a scheduled payout.

Question 35

What do accrued, pending, submitted, and confirmed mean?

Accepted Answer

- accrued: the sale has been recorded on the credit rail and the seller amount is owed, but the on-chain payout has not yet finalized. - pending / submitted: settlement or payout work is in progress. - confirmed: the seller payout/settlement is final and has confirmation data. - failed: settlement did not complete; retries or manual reconciliation may be required. The status in the UI can lag the chain briefly. Check the transaction hash and GET /v1/payments/seller/earnings before assuming a payment is missing.

Question 36

Why is my provider dashboard usage higher than my Surplus payout?

Accepted Answer

Provider-native usage is not the same metric as settled marketplace sales. An upstream provider may charge for a request that timed out or kept running after Surplus closed the connection, even though the buyer never received it and no successful sale settled. Also, DIEM/credits consumed are provider-native units, while Surplus pays the offer's USDC price based on metered delivered usage. Compare the same UTC window, model, key, and request set. Include the Surplus request IDs and provider usage timestamps in a support ticket.

Question 37

Why did buyers reach my offer when cheaper offers existed?

Accepted Answer

Cheaper offers may have been unhealthy, rate-limited, out of provider credits, capped, excluded by a buyer's trust/provider filter, or more expensive for that request's input/output mix. The router tries the cheapest eligible offer, not simply the lowest visible headline price.

Question 38

Why is my offer unhealthy?

Accepted Answer

Common causes include an invalid/revoked provider key, exhausted quota or DIEM, provider 401/402/403, rate limits, timeouts, malformed responses, an unsupported model mapping, or an upstream outage. Check GET /v1/seller/health-log, fix the provider-side issue, and allow the backoff/recovery flow to run.

Question 39

Can I cap how much of my provider balance is sold?

Accepted Answer

Inference offers support a marketplace-side daily USD cap. Provider-side model restrictions, spend caps, and rate limits remain the strongest protection. There is not a marketplace-side DIEM-unit cap or separate hourly USD cap in the current published design.

Question 40

Does Surplus consume seller credits for health checks?

Accepted Answer

Yes, in bounded cases. Creating or testing an offer performs a real probe for the selected model. Healthy offers are not continuously pinged, but an offer marked unhealthy enters a recovery queue, and the prober sweeps every three minutes to send due unhealthy offers a small real check. Text probes cap output at 16 tokens; the recovery prober uses a 45-second timeout, while create and test probes use a 20-second default. These calls can consume a small amount of upstream quota, so use a dedicated provider key with provider-side limits.

Question 41

How do I change my payout wallet?

Accepted Answer

Set the payout address on the offer and verify each active offer points to the intended Base wallet. Different Privy sign-in methods can create or select different embedded wallets, and older offers may retain the payout address set when they were created. After a change, use a small test sale and confirm the Base transaction before restoring full traffic.

Question 42

Why do I see multiple wallets or a different account after signing in?

Accepted Answer

Privy identities can differ when you sign in by wallet, email, Google, Farcaster, or another method. Use the same login method that created the seller/API key and offers. If the correct account is not visible, open a ticket with the login method, public wallet addresses, and offer IDs. Never send private keys.

Question 43

How do I access an embedded wallet Privy created for me?

Accepted Answer

If you sign in with email, Google, or X without connecting an external wallet, Privy creates an embedded wallet and Surplus uses it as your active wallet, so funding and payouts go to it. Its address, with a copy button, is in the account menu (the profile icon, top right), and it is the same address shown as your funding target on the Buy page. Two limits to know: - Once you connect an external wallet, Surplus prefers it and hides the embedded wallet from the account menu, so a balance can be stranded in one you can no longer select. - There is no in-app key export or send button for an embedded wallet on-chain balance; the withdraw controls only move your Surplus credit, treasury, and payout balances. To recover funds stranded in an embedded wallet, open a ticket with your login method and the public wallet address, and never share a private key. To avoid it, connect and switch to your intended wallet before funding or before setting a seller payout address.

Question 44

Are seller provider keys secure, and are they deleted when I remove an offer?

Accepted Answer

Provider keys are encrypted using AES-256-GCM with AWS KMS envelope encryption; encrypted payloads are stored privately. Offer deletion is currently a soft delete, so encrypted key material is not automatically hard-purged. Revoke the key at the upstream provider when retiring an offer, and contact support if you need manual erasure.

Question 45

Which payout assets are supported?

Accepted Answer

The marketplace pays sellers in USDC on Base. USDT on TRON or other chains is not a seller-payout option.

Question 46

Are payouts and platform fees always zero-fee?

Accepted Answer

Yes. Payouts and platform fees are zero today: seller payouts settle at a 1.0x on-chain multiplier with no flat platform fee, and buyers pay only the metered cost of each request.

Question 47

How do I get more than the recent seller-sales window?

Accepted Answer

GET /v1/seller/earnings exposes precomputed earnings and a recent-sales window. GET /v1/payments/seller/earnings exposes live ledger state and up to 50 recent ledger activities. For the full history, GET /v1/seller/usage/export returns a CSV of every sale row (up to 50,000) as a short-lived download link. Beyond that cap, or for a cursor-paginated feed, contact support with the seller wallet and UTC range.

Question 48

Can Surplus add my provider or model?

Accepted Answer

Usually, if the provider has a stable OpenAI-compatible API, documented model IDs, measurable usage, acceptable terms, and a testable pricing model. Share public API documentation and model/pricing information through a ticket. Send test credentials only through an approved secure channel, never a public Discord message.

Question 49

What does Surplus test before adding a provider?

Accepted Answer

Typical checks include /models, a minimal completion on each supported API wire, authentication and error semantics, usage fields, model identity, latency, pricing, and whether marketplace resale is allowed. Media models require modality-specific quote/job/poll validation.

Question 50

Why is a provider or model missing even though the upstream provider offers it?

Accepted Answer

A mapping may not exist yet, the provider may not expose a compatible endpoint, no seller may have listed it, every offer may be unhealthy, or terms/pricing/identity may still need validation. Check /v1/models and /api/markets/{model} first, then file a model/provider request.

Question 51

How do image, video, music, TTS, and transcription requests work?

Accepted Answer

Use the model's documented modality endpoint. Video and music are asynchronous: submit a job, poll its status, then download the artifact. Availability depends on healthy seller support for that exact model and modality; a text-compatible provider does not automatically support image/video calls.

Question 52

What does "per job" mean for media pricing?

Accepted Answer

It means the billable unit is a generation job rather than one million text tokens, but the effective price may still depend on model-specific parameters such as duration, resolution, quality, or output count. Use the live model metering metadata and /v1/prices for that exact media model.

Question 53

Am I charged for a failed or timed-out request?

Accepted Answer

A request that never completes should not be represented as a successful settled buyer charge. Check GET /v1/requests and the request-detail settlement status. If the request failed but a buyer charge finalized, open a ticket with the request ID and transaction reference. An upstream seller provider may still charge the seller for work that continued after a timeout; that is a separate provider-vs-marketplace reconciliation issue.

Question 54

Can I get a refund?

Accepted Answer

- For a failed request that appears to have charged successfully, open a ticket for request-level review. - Refunds of unused card-funded credits are handled by support and can depend on payment status, payment-processor rules, and applicable law. - Do not post full payment-card or identity details in Discord.

Question 55

What information should I include in a support ticket?

Accepted Answer

Include: - buyer or seller role; - UTC date/time and timezone; - request ID(s), offer ID(s), and model; - endpoint/API wire and whether streaming was enabled; - HTTP status and sanitized error text; - public wallet/account address and transaction link, if relevant; - provider usage timestamp and amount for seller reconciliation; - expected result versus actual result. Do not include API keys, private keys, card numbers, auth headers, cookies, or signed payment payloads.

Question 56

How do I know a DM, token, airdrop, or payment request is official?

Accepted Answer

Treat unsolicited DMs, surprise tokens, and requests for keys or wallet secrets as scams unless confirmed through the server's official links and staff. Surplus support does not need your private key or seed phrase. If unsure, post a screenshot with sensitive data removed and ask in a ticket.

Frequently Asked Questions

About Surplus

Buyer Setup and Funding

Routing, Providers, and Trust

Models and API Compatibility

Sellers and Offers

Provider and Model Onboarding

Failures, Refunds, and Support