Skip to main content
Surplus Intelligence
Marketplace
GuidesBYOK priority provider

BYOK Priority Provider

Bring your own API key and use the marketplace as overflow.

How It Works

Register your own provider key for a specific model. Every request tries your key first (zero marketplace cost). When it fails (429, 402, 5xx), the marketplace catches it transparently and routes to the cheapest seller.

Routing order: your priority provider → marketplace sellers → your fallback provider → universal fallback.

The fallthrough
  1. Your priority keyFor this model, tried first
  2. MarketplaceCheapest healthy seller
  3. Your fallbackYour model: null catch-all
  4. Universal fallbackLast resort
Each tier is tried only when the one before it cannot serve - on a 429, a 402, or a 5xx. A priority provider registered for a specific model jumps the marketplace for that model only.

A provider you register for a specific model is tried first for that model. A provider registered with model: null acts as your catch-all fallback provider - it applies to any model that doesn't have its own priority provider. (The legacy dedicated fallback-key endpoint has been retired; register a model: null provider instead.)

Requirements

Your priority provider must be OpenAI-compatible - it needs to accept requests at {base_url}/chat/completions in OpenAI format. Most providers work: Venice, OpenRouter, Together, Fireworks, Groq, Bankr, OpenAI, DeepSeek.

Not supported as priority provider: Anthropic native API (api.anthropic.com), Google Gemini native API. Use these models through an OpenAI-compatible provider like Venice or OpenRouter instead.

Setup

Register a provider for a specific model:

bash
POST /v1/buyer/providers
{
  "model": "claude-opus-4.6",
  "api_key": "sk-your-venice-key",
  "base_url": "https://api.venice.ai/api/v1"
}

To register a catch-all fallback provider that applies to every model without its own priority provider, set model to null:

bash
POST /v1/buyer/providers
{
  "model": null,
  "api_key": "sk-your-venice-key",
  "base_url": "https://api.venice.ai/api/v1"
}

Or configure via the Buy page UI (Priority Provider section).

Use Cases

  • Zero switching cost onboarding - keep your existing $200/mo API plan, add SI as overflow
  • Cost optimization - use your free tier first, marketplace catches the 429s
  • Reliability - your key + marketplace + fallback = three layers of redundancy

Health Tracking

Priority providers get the same health monitoring as marketplace sellers - exponential backoff on failures, automatic recovery. If your key is consistently failing, requests seamlessly shift to marketplace sellers.

Previous← OpenCode setupNextWallet funding →