Buyer Quickstart

Get the cheapest AI inference in under 2 minutes.

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"):

bash

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 SettlementV2 Spending

Click "Approve" on the Buy page to approve USDC for SettlementV2. This standing allowance is used for dashboard/API-key marketplace requests (/buy / OpenAI-compatible API key usage). Your funds stay in your wallet — nothing is locked or deposited — and you can revoke the SettlementV2 approval at any time.

This is separate from x402 upto Permit2 approval. A Permit2 approval for x402 agent payments does not satisfy the /buy SettlementV2 allowance, and a SettlementV2 approval does not authorize x402 Permit2 payments.

5. Make a Request

bash

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

Cursor:

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

Python (OpenAI SDK):

python

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


API Base URL	`https://api.surplusintelligence.ai`
OpenAI-compatible base	`https://api.surplusintelligence.ai/v1`
Network	Base (Chain ID: 8453)
USDC contract	`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` (6 decimals)
Settlement contract	Returned by `GET /v1/buyer/me` → `settlement_contract` field
Fee multiplier	On-chain: `Settlement.feeMultiplier()` (10000 = 1.0x, no markup)
Buyer key prefix	`inf_`
Max keys per wallet	25
Auth header	`Authorization: Bearer inf_xxx`

How settlement works: After each API-key marketplace request completes, SettlementV2 calls transferFrom() to pull USDC from your wallet and send it to the seller. Your funds stay in your wallet — nothing is locked or deposited. You just need an active USDC allowance pointing at the SettlementV2 proxy. You can cap or revoke this allowance at any time. This is not the x402 Permit2 rail.

1. Get Your API Key (SIWE)

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

bash

# 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": "<SIWE message from challenge>", "signature": "0x..."}'
# Returns: { "api_key": "inf_abc123...", "id": "...", ... }
# Save this key — it will not be shown again.

Python (viem/web3):

python

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

bash

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 for SettlementV2

For programmatic API-key usage, approve USDC to the SettlementV2 proxy on Base. This can be a standard on-chain ERC-20 approve() (you pay Base gas) or, in the web app, a gasless EIP-2612 permit relayed under SI's SettlementV2 policy cap. The spender is SettlementV2, not Permit2. You need a small amount of ETH on Base only for the on-chain path (~$0.001).

python

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,
    100_000_000           # 100 USDC (6 decimals); use the smallest cap that fits your expected spend
).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):

bash

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

Verify approval:

bash

curl .../v1/buyer/me -H "Authorization: Bearer inf_xxx"
# Check: allowance_usdc > 0 for SettlementV2/API-key usage

4. Browse Models & Prices

bash

# 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

5. Make Requests

bash

# 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"}'

6. Monitor Usage & Savings

bash

# 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"

7. Manage Keys

bash

# 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"

8. Optional: Set Fallback Provider

If all marketplace sellers are down, requests fall back to your own provider key. Register it as a provider with model: null (applies to every model):

bash

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"}'

Alternative Clients

Instead of raw HTTP:

CLI: Planned — not yet published
MCP Server: Planned — not yet published
OpenClaw Skill: /inference_key, /inference_prices [model], /inference_orderbook <model>
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

Buyer Quickstart

1. Sign In

2. Get Your API Key

3. Fund Your Wallet

4. Approve SettlementV2 Spending

5. Make a Request

Use with Your Tools

Programmatic Setup (No Browser)

Reference

1. Get Your API Key (SIWE)

2. Check Balance & Get Settlement Contract

3. Approve USDC for SettlementV2

4. Browse Models & Prices

5. Make Requests

6. Monitor Usage & Savings

7. Manage Keys

8. Optional: Set Fallback Provider

Alternative Clients

What's Next