Buyer Quickstart

Get the cheapest AI inference in under 2 minutes.

1. Sign In

Go to surplusintelligence.ai and sign in with Twitter, Discord, or wallet connect. Privy automatically creates a wallet if you don't have one.

2. Get Your API Key

After signing in, your API key appears on the Buy page. Copy it — it looks like inf_abc123....

You can create up to 25 keys with labels (e.g. "Cursor", "Aider", "CI"):

POST /v1/buyer/keys
{ "label": "Cursor" }

3. Fund Your Wallet

You need USDC on Base to pay for inference. Options:

• Coinbase Onramp — buy USDC with a card directly from the app
• MoonPay (via Privy) — another card option
• Bridge from another chain — if you already have USDC elsewhere

See Wallet Funding for details.

4. Approve Spending

Click "Approve" on the Buy page to allow the settlement contract to pull USDC from your wallet. Your funds stay in your wallet — nothing is locked or deposited. You can revoke at any time.

5. Make a Request

curl https://api.surplusintelligence.ai/v1/chat/completions \
  -H "Authorization: Bearer inf_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4.6",
    "messages": [{"role": "user", "content": "Hello!"}],
    "stream": true
  }'

That's it. The marketplace routes to the cheapest seller, streams the response, and settles USDC on-chain automatically.

Use with Your Tools

API Base URL: https://api.surplusintelligence.ai/v1
API Key: inf_your_key_here
Model: claude-opus-4.6

from openai import OpenAI

client = OpenAI(
    api_key="inf_your_key_here",
    base_url="https://api.surplusintelligence.ai/v1"
)

response = client.chat.completions.create(
    model="claude-opus-4.6",
    messages=[{"role": "user", "content": "Hello!"}]
)

Works with any OpenAI-compatible tool — just change the base URL and API key.

Programmatic Setup (No Browser)

Everything above can be done without touching the website. All you need is a wallet with a private key and USDC on Base.

Reference

1. Get Your API Key (SIWE)

Request a challenge, sign it, get a persistent inf_ key:

# Get SIWE challenge
CHALLENGE=$(curl -s "https://api.surplusintelligence.ai/v1/buyer/auth/challenge?address=0xYourWallet")
Returns a SIWE message + nonce

Sign the SIWE message with your wallet, then exchange for a key
curl -X POST https://api.surplusintelligence.ai/v1/buyer/auth/keys \
  -H "Content-Type: application/json" \
  -d '{"message": "", "signature": "0x..."}'
Returns: { "api_key": "inf_abc123...", "id": "...", ... }
Save this key — it will not be shown again.

from web3 import Web3
import requests

BASE = "https://api.surplusintelligence.ai"

1. Get challenge
resp = requests.get(f"{BASE}/v1/buyer/auth/challenge?address={wallet_address}")
challenge = resp.json()

2. Sign the SIWE message
signed = w3.eth.account.sign_message(
    encode_defunct(text=challenge["message"]),
    private_key=YOUR_KEY
)

3. Exchange for API key
resp = requests.post(f"{BASE}/v1/buyer/auth/keys", json={
    "message": challenge["message"],
    "signature": signed.signature.hex()
})
api_key = resp.json()["api_key"]  # inf_xxx

2. Check Balance & Get Settlement Contract

curl https://api.surplusintelligence.ai/v1/buyer/me \
  -H "Authorization: Bearer inf_your_key"
Returns: balance_usdc, allowance_usdc, credit_balance_usdc, settlement_contract, ...

3. Approve USDC Spending

Standard ERC-20 approve() on Base. This is an on-chain transaction, not an SI endpoint — call the USDC contract directly. You need a small amount of ETH on Base for gas (~$0.001).

from web3 import Web3

w3 = Web3(Web3.HTTPProvider("https://mainnet.base.org"))

USDC_ADDRESS = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
ERC20_ABI = [{"name": "approve", "type": "function", "stateMutability": "nonpayable",
  "inputs": [{"name": "spender", "type": "address"}, {"name": "value", "type": "uint256"}],
  "outputs": [{"name": "", "type": "bool"}]}]

usdc = w3.eth.contract(address=USDC_ADDRESS, abi=ERC20_ABI)

settlement_contract from step 2 (/v1/buyer/me response)
tx = usdc.functions.approve(
    settlement_contract,
    2256 - 1            # unlimited, or a specific amount (6 decimals: 100 USDC = 100_000_000)

).build_transaction({
    "from": wallet_address,
    "nonce": w3.eth.get_transaction_count(wallet_address),
    "gas": 60_000,
    "maxFeePerGas": w3.eth.gas_price,
})

signed = w3.eth.account.sign_transaction(tx, private_key=YOUR_KEY)
tx_hash = w3.eth.send_raw_transaction(signed.raw_transaction)
receipt = w3.eth.wait_for_transaction_receipt(tx_hash)
receipt.status == 1 means success

With cast (Foundry):

cast send 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 \
  "approve(address,uint256)" \
   \
  $(cast max-uint) \
  --rpc-url https://mainnet.base.org \
  --private-key $PRIVATE_KEY

Verify approval:

curl .../v1/buyer/me -H "Authorization: Bearer inf_xxx"
Check: allowance_usdc > 0

# All available models
curl .../v1/models -H "Authorization: Bearer inf_xxx"

Best prices per model
curl .../v1/prices -H "Authorization: Bearer inf_xxx"

Full orderbook for a specific model
curl .../api/markets/claude-opus-4.6

# Text (streaming)
curl .../v1/chat/completions \
  -H "Authorization: Bearer inf_xxx" \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-opus-4.6", "messages": [{"role": "user", "content": "Hello!"}], "stream": true}'

Images
curl .../v1/images/generations \
  -H "Authorization: Bearer inf_xxx" \
  -d '{"model": "venice-flux-1.1-pro", "prompt": "a cat in space"}'

Video (async — poll for result)
JOB=$(curl -s -X POST .../v1/video/generations \
  -H "Authorization: Bearer inf_xxx" \
  -d '{"model": "venice-runway-gen4-5-text", "prompt": "ocean waves"}')
Poll: GET .../v1/video/generations/{id}
Download: GET .../v1/media/artifacts/{jobId}/{index}

Music (async — same pattern as video)
curl -X POST .../v1/music/generations \
  -H "Authorization: Bearer inf_xxx" \
  -d '{"model": "venice-ace-step-15", "prompt": "lo-fi beats"}'

TTS
curl .../v1/audio/speech \
  -H "Authorization: Bearer inf_xxx" \
  -d '{"model": "venice-tts-1", "input": "Hello world", "voice": "alloy"}'

STT (max 25MB, formats: wav, mp3, mp4, m4a, ogg, webm, flac)
curl .../v1/audio/transcriptions \
  -H "Authorization: Bearer inf_xxx" \
  -F file=@audio.mp3 -F model=venice-whisper-1

Embeddings
curl .../v1/embeddings \
  -H "Authorization: Bearer inf_xxx" \
  -d '{"model": "venice-embed-1", "input": "Hello world"}'

# Balance, spending, per-model breakdown, recent requests (includes savings per request)
curl .../v1/buyer/me -H "Authorization: Bearer inf_xxx"
Recent rows include: cost_usd, direct_cost_usd, saved_usd

All-time savings vs direct provider pricing
curl .../v1/buyer/savings -H "Authorization: Bearer inf_xxx"

Daily or weekly savings breakdown
curl ".../v1/buyer/savings?period=daily" -H "Authorization: Bearer inf_xxx"
curl ".../v1/buyer/savings?period=weekly" -H "Authorization: Bearer inf_xxx"

Export usage as CSV
curl ".../v1/buyer/usage/export?format=csv&from=2026-01-01" \
  -H "Authorization: Bearer inf_xxx"

# List all your keys
curl .../v1/buyer/keys -H "Authorization: Bearer inf_xxx"

Create another key with a label
curl -X POST .../v1/buyer/keys \
  -H "Authorization: Bearer inf_xxx" \
  -d '{"label": "production-server"}'

Revoke a key
curl -X DELETE .../v1/buyer/keys/{keyId} \
  -H "Authorization: Bearer inf_xxx"

curl -X POST .../v1/buyer/providers \
  -H "Authorization: Bearer inf_xxx" \
  -d '{"model": null, "api_key": "sk-your-venice-key", "base_url": "https://api.venice.ai/api/v1"}'

• CLI: Planned — not yet published
• MCP Server: Planned — not yet published
• OpenClaw Skill: /inference_key, /inference_prices [model], /inference_orderbook
• OpenAI SDK:** Point any OpenAI-compatible client at https://api.surplusintelligence.ai/v1 with your inf_ key

What's Next

• Check your savings vs direct provider pricing
• Set up a BYOK priority provider — use your own key first, overflow to marketplace
• Browse available models