surp.ivc.lol — x402-paywalled LLM gateway

If you run Hermes Agent, you can point it at surp.ivc.lol in under a minute. Your agent gets the cheapest LLM on the internet per request, paying in USDC on Base — no API key, no account, no monthly bill.

You need USDC on Base in a wallet whose private key you control (not an exchange deposit address). A few cents covers hundreds of requests. Get test USDC first if you just want to try — the routing is identical.

step 1 — install the x402 client

Your Hermes runs on Python. The x402 library handles the sign-and-pay loop automatically.

pip install "x402[evm]"

This pulls in eth-account and web3 for EIP-3009 signature signing. If your Hermes uses a virtualenv (it should), activate it first.

step 2 — set your wallet key

Export your wallet's private key as an environment variable. Hermes reads this on every request.

export SURP_WALLET_KEY="0xabc123...your private key"

Never commit this key or paste it in chat. Use a dedicated wallet with only the USDC you're willing to spend — a few dollars at a time.

step 3 — add surp.ivc.lol as a custom provider

Open ~/.hermes/config.yaml and add this entry under custom_providers:

custom_providers:
  - name: surp-gateway
    base_url: https://surp.ivc.lol/v1
    model: surp/best-coding
    key_env: SURP_WALLET_KEY
    discover_models: false
    models:
      - surp/best-coding
      - surp/best-reasoning
      - surp/best-chat
      - surp/best-fast
      - surp/best-vision
      - surp/pro-coding
      - surp/pro-reasoning
      - surp/pro-chat
      - surp/best-coding-fast
      - surp/coding
      - surp/chat
      - surp/fast
      - surp/srup-free

The key_env field tells Hermes to send your wallet key as the authorization. The gateway uses it to sign x402 payments on your behalf. discover_models: false makes the /model picker show exactly these combos instead of probing the endpoint.

step 4 — switch your model

Run /model in Hermes, pick surp-gateway, then pick a combo. Or set it directly:

hermes config set model.default surp/best-coding
hermes config set model.provider surp-gateway

step 5 — test it

Send any message. The first request triggers the x402 flow — Hermes signs a USDC authorization, the gateway verifies it on-chain via the facilitator, and the completion streams back. Check the response headers:

curl -s -D - https://surp.ivc.lol/v1/chat/completions \\
  -H "Content-Type: application/json" \\
  -d '{"model":"surp/best-chat","messages":[{"role":"user","content":"say PONG"}],"max_tokens":10}' \\
  | head -5

# HTTP/2 402  <- payment required (expected on first hit)
# pay-to: 0x2f9518019575e048320c1e7da4dc4d6d8384c2c8
# amount: 10000 atomic USDC ($0.01)

With the x402 client installed, Hermes handles the 402 → sign → retry loop automatically. You'll see the settlement in your wallet within seconds.

which combo should I pick?

combo	use when	typical cost
`surp/best-coding`	everyday coding, PRs, debugging	~$0.005/1K tokens
`surp/pro-coding`	hard architecture, complex refactors	~$0.01/1K tokens
`surp/best-chat`	general questions, writing, analysis	~$0.0003/1K tokens
`surp/best-reasoning`	math, logic, step-by-step problems	~$0.0005/1K tokens
`surp/best-fast`	quick replies, simple lookups	~$0.0005/1K tokens

Costs are live — they move with the Surplus market. Check the homepage ticker for current rates.

troubleshooting

"verification failed: insufficient_balance"

Your wallet doesn't have enough USDC on Base. Fund it — even $1 covers thousands of requests at current prices.

"verification failed: invalid signature"

The private key in SURP_WALLET_KEY doesn't match the wallet the facilitator expects. Make sure you exported the key for the address that holds your USDC.

the /model picker doesn't show surp-gateway

Make sure the custom_providers entry is properly indented in YAML (2 spaces under the key). Run hermes doctor to validate.

I want to build my own combo from specific models

Use the combo builder — pick any models, get a surp/my/<slug> id, add it to the models: list in step 3.

how the payment works (under the hood)

You don't need to understand this to use it, but if you're curious:

Hermes sends POST /v1/chat/completions with no payment header
Gateway responds 402 Payment Required with a PAYMENT-REQUIRED header describing the exact USDC amount, pay-to address, and token contract
The x402 client library (running inside Hermes) signs an EIP-3009 transferWithAuthorization message — an off-chain signature authorizing a single USDC transfer
Hermes retries the request with a PAYMENT-SIGNATURE header containing the signed authorization
The gateway forwards the signature to the PayAI facilitator, which verifies it and submits the on-chain transaction (gas is sponsored — you only pay USDC, no ETH needed)
Once settled, the gateway resolves your combo to the cheapest live model and forwards the request to Surplus Intelligence

The entire payment is a single EIP-3009 transfer — no approval transaction, no gas, no smart contract interaction from your side. The facilitator handles settlement end-to-end.

connect your hermes