Give an agent this page and it can buy or sell Surplus inference.

# Surplus Intelligence Agent Skill

Use this skill when an autonomous agent wants to buy inference, inspect prices, or sell inference capacity on Surplus Intelligence.

Surplus Intelligence is an OpenAI-compatible inference marketplace. Buyers pay per request with x402 USDC on Base, or use a buyer API key. Sellers list inference capacity and compete on price. Cheapest healthy seller wins routing.

## Base URLs

- Production: https://www.surplusintelligence.ai
- Official docs: https://www.surplusintelligence.ai/docs
- OpenAPI: https://www.surplusintelligence.ai/openapi.json
- LLM docs: https://www.surplusintelligence.ai/llms.txt
- x402 discovery: https://www.surplusintelligence.ai/.well-known/x402.json

## Buyer: x402 pay-per-request inference

Best for agents that have a wallet with USDC on Base and do not want an account.

Endpoint:

```
POST https://www.surplusintelligence.ai/x402/api/inference/v1/chat/completions
Content-Type: application/json
```

Body is OpenAI-compatible:

```json
{
  "model": "llama-3.3-70b",
  "messages": [{ "role": "user", "content": "Hello" }],
  "max_tokens": 100
}
```

Flow:

1. POST the request without Authorization.
2. Expect HTTP 402.
3. Decode the `PAYMENT-REQUIRED` header as base64 JSON.
4. Select `accepts.find(a => a.scheme === "upto")` when present.
5. Fall back to `exact` only if `upto` is unavailable or unsupported by your client.
6. Create an x402 payment payload for the selected requirement.
7. Retry the identical request with `PAYMENT-SIGNATURE: base64(JSON.stringify(paymentPayload))`.
8. Expect HTTP 200, `PAYMENT-RESPONSE`, and an OpenAI-compatible completion response.

Important:

- `upto` authorizes a maximum and settles actual usage after the response.
- `exact` settles the fixed estimated amount.
- Amounts are USDC micro-units. `1000` means $0.001 USDC.
- Do not assume the order of `accepts[]`; select by scheme.
- Network is Base, chain ID 8453.
- USDC on Base: `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`.
- Settlement proxy: `0x0770d2124C0a581C28Cfc47a659817145e6Cc137`.

## TypeScript x402 sketch

```ts
import { wrapFetchWithPayment } from '@x402/fetch';
import { x402Client } from '@x402/core/client';
import { ExactEvmScheme } from '@x402/evm/exact/client';
import { privateKeyToAccount } from 'viem/accounts';

const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as any);
const client = new x402Client();
client.register('eip155:*', new ExactEvmScheme(signer));

const fetchWithPayment = wrapFetchWithPayment(fetch, client);
const res = await fetchWithPayment(
  'https://www.surplusintelligence.ai/x402/api/inference/v1/chat/completions',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      model: 'llama-3.3-70b',
      messages: [{ role: 'user', content: 'Hello' }],
      max_tokens: 100,
    }),
  }
);

const data = await res.json();
console.log(data.choices[0].message.content);
```

## Inspect market before buying

Free endpoints:

- `GET /api/inference/v1/models` — model catalog.
- `GET /api/inference/v1/prices` — live provider price matrix.
- `GET /api/inference/markets` — active marketplace model liquidity.
- `GET /api/inference/markets/:model` — order book and recent trades.
- `GET /api/resource/markets` — non-inference API resources sold via x402.

## Buyer: API key mode

Use this when the agent has completed SIWE auth and has a buyer key.

```
Authorization: Bearer inf_xxx
```

This uses the canonical OpenAI-compatible endpoints, e.g. `/api/inference/v1/chat/completions`. The buyer must have suitable USDC allowance for the settlement contract.

## Seller: sell inference capacity

Seller flow is API-first and can be automated. The seller needs a wallet, SIWE signature, upstream provider credentials, and a price.

1. Request a seller auth challenge:

```
GET https://www.surplusintelligence.ai/api/inference/sellers/auth/challenge?address=0xYourWallet
```

2. Sign the SIWE message with the seller wallet.

3. Exchange signature for a seller API key:

```
POST https://www.surplusintelligence.ai/api/inference/sellers/auth/key
Content-Type: application/json
```

The response returns an `si_seller_xxx` key.

4. Create or update seller offers:

```
POST https://www.surplusintelligence.ai/api/inference/sellers/offers
Authorization: Bearer si_seller_xxx
Content-Type: application/json
```

Use the official docs for the exact request schema before posting an offer:

- https://www.surplusintelligence.ai/docs/api-reference/seller-endpoints.md
- https://www.surplusintelligence.ai/docs/marketplace/security-privacy.md

Operational notes for sellers:

- Price competitively; cheapest healthy seller is favored.
- Keep upstream keys valid and funded.
- Monitor health. Unhealthy offers should not receive traffic.
- Provider API keys are sensitive; do not log them or expose them to buyer agents.
- If an upstream key must be killed immediately, revoke it upstream as well as deleting/soft-deleting the Surplus offer.

## Resource markets

Surplus also sells seller-backed API resources over x402, including Twitter/X read endpoints and Venice crypto RPC. Discover resources through:

- `/.well-known/x402.json`
- `/api/x402/info`
- `/api/resource/markets`
- `/openapi.json`

Resource requests follow the same x402 402 challenge and signed retry pattern.

## Agent checklist

Before spending money:

- Fetch `/llms.txt` or `/openapi.json`.
- Fetch prices and models.
- Choose a model with active seller liquidity.
- Cap max tokens and cost.
- Prefer `upto` payment requirements.
- Verify Base USDC balance and allowance/Permit2 requirements.
- Log model, quoted amount, settled amount, and transaction hash if returned.

Before selling:

- Read official seller docs.
- Generate seller API key via SIWE.
- Start with a small daily cap if supported.
- Use a test offer or low-risk model first.
- Monitor health and delete bad offers quickly.