# UsePod — full content

> UsePod docs — the full Markdown corpus, concatenated. 28 pages. See /llms.txt for the index.

Source: https://docs.usepod.ai
Index: https://docs.usepod.ai/llms.txt

---

# Deposit on-chain (without the dashboard)

Source: https://docs.usepod.ai/api/deposit-on-chain/
Description: Deposit USDC or SOL into your token via the sovereign program using Anchor — the IDL is already published on-chain.

The dashboard is one front-end for funding. Behind it, every Use Pod deposit
is a single instruction against an Anchor program on Solana mainnet. The
program's IDL is already published on-chain, so building your own deposit
flow is a few lines of typed Anchor code — no hand-rolled discriminators,
no manual account derivation.

The instruction is what the LiquidMirror parses to credit you. **A plain SPL
USDC transfer with a memo will NOT be credited.** The `deposit_code` lives
in the instruction data, not in a separate memo instruction.

## What you need

| | |
|---|---|
| Sovereign program ID | `BBAdcqUkg68JXNiPQ1HR1wujfZuayyK3eQTQSYAh6FSW` |
| Anchor IDL location | On-chain — fetched at runtime with the program ID |
| USDC mint | `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` |
| Network | Solana mainnet-beta |

Your `deposit_code` is the 16-hex-char string returned by
[`POST /v1/register`](/api/register/). Treat it as the on-chain binding to
your token — anyone who deposits with this code credits your balance, so
guard it like a less-sensitive sibling of the API token itself.

## TypeScript — USDC deposit

```ts
// npm i @coral-xyz/anchor @solana/web3.js
import * as anchor from "@coral-xyz/anchor";
import { Connection, Keypair, PublicKey } from "@solana/web3.js";

const PROGRAM_ID = new PublicKey("BBAdcqUkg68JXNiPQ1HR1wujfZuayyK3eQTQSYAh6FSW");
const USDC_MINT  = new PublicKey("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v");

async function depositUsdc(depositCode: string, amountUsdc: number) {
  const secret = Uint8Array.from(JSON.parse(process.env.WALLET_KEYPAIR_JSON!));
  const payer = Keypair.fromSecretKey(secret);
  const connection = new Connection("https://api.mainnet-beta.solana.com", "confirmed");
  const provider = new anchor.AnchorProvider(
    connection,
    new anchor.Wallet(payer),
    { commitment: "confirmed" },
  );

  // IDL lives on-chain at the standard Anchor address — no JSON to ship.
  const idl = await anchor.Program.fetchIdl(PROGRAM_ID, provider);
  if (!idl) throw new Error("on-chain IDL not found");
  const program = new anchor.Program(idl, provider);

  const code = Array.from(Buffer.from(depositCode, "hex")); // 8 bytes
  const amount = new anchor.BN(Math.round(amountUsdc * 1_000_000)); // USDC micros

  // Anchor 0.30+ resolves every other account from the IDL: the depositor's
  // and ops_wallet's USDC ATAs, the program config PDA, the token + ATA
  // programs (all pinned by IDL `address` constraints), and the signer.
  const sig = await program.methods
    .depositUsdc(code, amount)
    .accounts({ mint: USDC_MINT })
    .rpc();

  console.log("deposit:", sig);
  return sig;
}

await depositUsdc("bcb1d3eaddb99251", 5.00);
```

## TypeScript — SOL deposit (with Jupiter swap)

`deposit_sol` records a SOL→USDC swap that has happened in the same
transaction. You compose Jupiter's swap instructions in front of the
program's `deposit_sol` instruction and send them as one v0 transaction.

```ts
// npm i @coral-xyz/anchor @solana/web3.js @solana/spl-token
import * as anchor from "@coral-xyz/anchor";
import {
  AddressLookupTableAccount, Connection, Keypair, PublicKey,
  TransactionInstruction, TransactionMessage, VersionedTransaction,
} from "@solana/web3.js";
import { getAssociatedTokenAddressSync } from "@solana/spl-token";

const PROGRAM_ID = new PublicKey("BBAdcqUkg68JXNiPQ1HR1wujfZuayyK3eQTQSYAh6FSW");
const USDC_MINT  = new PublicKey("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v");
const SOL_MINT   = "So11111111111111111111111111111111111111112";
const JUP        = "https://lite-api.jup.ag/swap/v1";

const jupIxToWeb3 = (ix: any) => new TransactionInstruction({
  programId: new PublicKey(ix.programId),
  keys: ix.accounts.map((a: any) => ({
    pubkey: new PublicKey(a.pubkey), isSigner: a.isSigner, isWritable: a.isWritable,
  })),
  data: Buffer.from(ix.data, "base64"),
});

async function depositSol(depositCode: string, lamports: bigint, slippageBps = 50) {
  const secret = Uint8Array.from(JSON.parse(process.env.WALLET_KEYPAIR_JSON!));
  const payer = Keypair.fromSecretKey(secret);
  const connection = new Connection("https://api.mainnet-beta.solana.com", "confirmed");
  const provider = new anchor.AnchorProvider(
    connection, new anchor.Wallet(payer), { commitment: "confirmed" },
  );
  const idl = await anchor.Program.fetchIdl(PROGRAM_ID, provider);
  const program = new anchor.Program(idl!, provider);

  // 1. Jupiter quote + swap-instructions targeting the depositor's USDC ATA.
  const depositorUsdcAta = getAssociatedTokenAddressSync(USDC_MINT, payer.publicKey);
  const quote = await fetch(
    `${JUP}/quote?inputMint=${SOL_MINT}&outputMint=${USDC_MINT.toBase58()}` +
    `&amount=${lamports}&slippageBps=${slippageBps}`,
  ).then(r => r.json());

  const swap = await fetch(`${JUP}/swap-instructions`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      quoteResponse: quote,
      userPublicKey: payer.publicKey.toBase58(),
      destinationTokenAccount: depositorUsdcAta.toBase58(),
    }),
  }).then(r => r.json());

  const altAccounts: AddressLookupTableAccount[] = await Promise.all(
    (swap.addressLookupTableAddresses || []).map(async (a: string) =>
      (await connection.getAddressLookupTable(new PublicKey(a))).value!),
  );

  const preIx = [
    ...(swap.computeBudgetInstructions || []),
    ...(swap.setupInstructions || []),
    swap.swapInstruction,
  ].map(jupIxToWeb3);

  // 2. depositSol via Anchor — composed AFTER the swap in the same tx.
  const code = Array.from(Buffer.from(depositCode, "hex"));
  const usdcOutMin = new anchor.BN(quote.otherAmountThreshold);
  const depositTx = await program.methods
    .depositSol(code, new anchor.BN(lamports.toString()), usdcOutMin)
    .accounts({ usdcMint: USDC_MINT })
    .preInstructions(preIx)
    .transaction();

  // 3. Compile as v0 with the ALTs Jupiter returned, then sign + send.
  const { blockhash } = await connection.getLatestBlockhash();
  const message = new TransactionMessage({
    payerKey: payer.publicKey,
    recentBlockhash: blockhash,
    instructions: depositTx.instructions,
  }).compileToV0Message(altAccounts);
  const vtx = new VersionedTransaction(message);
  vtx.sign([payer]);

  const sig = await connection.sendTransaction(vtx);
  console.log("deposit:", sig);
  return sig;
}

await depositSol("bcb1d3eaddb99251", 50_000_000n); // 0.05 SOL
```

## Python — USDC deposit

`anchorpy` is the Python Anchor client; it fetches the same on-chain IDL and
exposes typed instruction builders. Account resolution for PDA seeds that
reference a different account's state (`config.ops_wallet`) isn't automatic
in the Python client today, so we resolve `ops_wallet` and the two ATAs
ourselves and pass them through `Context(accounts=...)`.

```python
# pip install anchorpy solders solana
import asyncio, json, os
from anchorpy import Program, Provider, Wallet, Context
from solders.keypair import Keypair
from solders.pubkey import Pubkey
from solana.rpc.async_api import AsyncClient

PROGRAM_ID       = Pubkey.from_string("BBAdcqUkg68JXNiPQ1HR1wujfZuayyK3eQTQSYAh6FSW")
USDC_MINT        = Pubkey.from_string("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v")
TOKEN_PROGRAM    = Pubkey.from_string("TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA")
ASSOC_TOKEN_PROG = Pubkey.from_string("ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL")

def derive_ata(owner: Pubkey, mint: Pubkey) -> Pubkey:
    ata, _ = Pubkey.find_program_address(
        [bytes(owner), bytes(TOKEN_PROGRAM), bytes(mint)],
        ASSOC_TOKEN_PROG,
    )
    return ata

async def deposit_usdc(deposit_code: str, amount_usdc: float) -> str:
    payer = Keypair.from_bytes(bytes(json.loads(os.environ["WALLET_KEYPAIR_JSON"])))
    client = AsyncClient("https://api.mainnet-beta.solana.com")
    provider = Provider(client, Wallet(payer))

    # Fetch IDL from on-chain at the standard Anchor address.
    idl = await Program.fetch_idl(PROGRAM_ID, provider)
    program = Program(idl, PROGRAM_ID, provider)

    # Resolve ops_wallet from on-chain config — the IDL declares
    # ops_wallet_ata's seeds as ["config.ops_wallet", token_program, mint].
    config_pda, _ = Pubkey.find_program_address([b"config"], PROGRAM_ID)
    config_acct = (await client.get_account_info(config_pda)).value
    if config_acct is None:
        raise RuntimeError("config PDA not found")
    ops_wallet = Pubkey.from_bytes(bytes(config_acct.data[8:40]))

    sig = await program.rpc["deposit_usdc"](
        list(bytes.fromhex(deposit_code)),
        round(amount_usdc * 1_000_000),
        ctx=Context(accounts={
            "depositor_ata":             derive_ata(payer.pubkey(), USDC_MINT),
            "ops_wallet_ata":            derive_ata(ops_wallet, USDC_MINT),
            "config":                    config_pda,
            "depositor":                 payer.pubkey(),
            "mint":                      USDC_MINT,
            "token_program":             TOKEN_PROGRAM,
            "associated_token_program":  ASSOC_TOKEN_PROG,
        }),
    )
    print(f"deposit: {sig}")
    return str(sig)

asyncio.run(deposit_usdc("bcb1d3eaddb99251", 5.00))
```

## Python — SOL deposit (with Jupiter swap)

Same structure as the TypeScript SOL example: get Jupiter swap instructions,
deserialize them as `solders` `Instruction`s, build the program's
`deposit_sol` instruction via `anchorpy`, compile a v0 transaction with the
ALTs Jupiter returned.

```python
# pip install anchorpy solders solana httpx
import asyncio, base64, json, os, struct
import httpx
from anchorpy import Program, Provider, Wallet, Context
from solders.keypair import Keypair
from solders.pubkey import Pubkey
from solders.instruction import AccountMeta, Instruction
from solders.message import MessageV0
from solders.transaction import VersionedTransaction
from solders.address_lookup_table_account import AddressLookupTableAccount
from solana.rpc.async_api import AsyncClient

PROGRAM_ID       = Pubkey.from_string("BBAdcqUkg68JXNiPQ1HR1wujfZuayyK3eQTQSYAh6FSW")
USDC_MINT        = Pubkey.from_string("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v")
TOKEN_PROGRAM    = Pubkey.from_string("TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA")
ASSOC_TOKEN_PROG = Pubkey.from_string("ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL")
SOL_MINT = "So11111111111111111111111111111111111111112"
JUP      = "https://lite-api.jup.ag/swap/v1"

def derive_ata(owner: Pubkey, mint: Pubkey) -> Pubkey:
    ata, _ = Pubkey.find_program_address(
        [bytes(owner), bytes(TOKEN_PROGRAM), bytes(mint)],
        ASSOC_TOKEN_PROG,
    )
    return ata

def jup_ix_to_solders(ix: dict) -> Instruction:
    return Instruction(
        program_id=Pubkey.from_string(ix["programId"]),
        accounts=[
            AccountMeta(Pubkey.from_string(a["pubkey"]), is_signer=a["isSigner"], is_writable=a["isWritable"])
            for a in ix["accounts"]
        ],
        data=base64.b64decode(ix["data"]),
    )

async def deposit_sol(deposit_code: str, lamports: int, slippage_bps: int = 50) -> str:
    payer = Keypair.from_bytes(bytes(json.loads(os.environ["WALLET_KEYPAIR_JSON"])))
    client = AsyncClient("https://api.mainnet-beta.solana.com")
    provider = Provider(client, Wallet(payer))
    idl = await Program.fetch_idl(PROGRAM_ID, provider)
    program = Program(idl, PROGRAM_ID, provider)

    # 1. Jupiter quote + swap-instructions delivering USDC to depositor's ATA.
    depositor_usdc_ata = derive_ata(payer.pubkey(), USDC_MINT)
    async with httpx.AsyncClient() as http:
        quote = (await http.get(
            f"{JUP}/quote?inputMint={SOL_MINT}&outputMint={USDC_MINT}"
            f"&amount={lamports}&slippageBps={slippage_bps}",
        )).json()
        swap = (await http.post(f"{JUP}/swap-instructions", json={
            "quoteResponse": quote,
            "userPublicKey": str(payer.pubkey()),
            "destinationTokenAccount": str(depositor_usdc_ata),
        })).json()

    pre_ixs = [
        jup_ix_to_solders(ix) for ix in
        (swap.get("computeBudgetInstructions") or [])
        + (swap.get("setupInstructions") or [])
        + [swap["swapInstruction"]]
    ]

    # 2. Resolve ops_wallet and build deposit_sol via anchorpy.
    config_pda, _ = Pubkey.find_program_address([b"config"], PROGRAM_ID)
    config_acct = (await client.get_account_info(config_pda)).value
    ops_wallet = Pubkey.from_bytes(bytes(config_acct.data[8:40]))

    deposit_ix = await program.instruction["deposit_sol"](
        list(bytes.fromhex(deposit_code)),
        lamports,
        int(quote["otherAmountThreshold"]),
        ctx=Context(accounts={
            "depositor":                  payer.pubkey(),
            "depositor_usdc":             depositor_usdc_ata,
            "ops_wallet_ata":             derive_ata(ops_wallet, USDC_MINT),
            "config":                     config_pda,
            "usdc_mint":                  USDC_MINT,
            "token_program":              TOKEN_PROGRAM,
            "associated_token_program":   ASSOC_TOKEN_PROG,
        }),
    )

    # 3. Compile v0 transaction with Jupiter's address-lookup tables, sign, send.
    alt_pubkeys = [Pubkey.from_string(a) for a in (swap.get("addressLookupTableAddresses") or [])]
    alts: list[AddressLookupTableAccount] = []
    for pk in alt_pubkeys:
        alt = (await client.get_address_lookup_table(pk)).value
        if alt is not None:
            alts.append(alt)

    blockhash = (await client.get_latest_blockhash()).value.blockhash
    message = MessageV0.try_compile(
        payer=payer.pubkey(),
        instructions=pre_ixs + [deposit_ix],
        address_lookup_table_accounts=alts,
        recent_blockhash=blockhash,
    )
    vtx = VersionedTransaction(message, [payer])
    sig = (await client.send_transaction(vtx)).value
    print(f"deposit: {sig}")
    return str(sig)

asyncio.run(deposit_sol("bcb1d3eaddb99251", 50_000_000))  # 0.05 SOL
```

## Verifying the credit

Once the transaction confirms, the program emits a `Program data:` log line
the LiquidMirror parses to credit your token. `DepositEvent` (USDC) is:

```
[ 8 bytes ] discriminator = sha256("event:DepositEvent")[0..8]
[ 8 bytes ] deposit_code (raw)
[ 8 bytes ] amount (u64 LE, USDC micro-units)
[32 bytes ] USDC mint pubkey
[32 bytes ] depositor pubkey
[ 8 bytes ] timestamp (i64 LE, Unix seconds)
```

`SolDepositEvent` (SOL→USDC) carries `sol_lamports` and `usdc_received`
instead of a single `amount`. Your token balance updates within a few
seconds of finalization. Confirm with:

```bash
curl -s https://api.usepod.ai/proxy/<token>/balance
```

The `usdc_balance` field is in micro-units (divide by 1,000,000 for USDC).

## Common errors

- **"deposit landed but my balance didn't update."** Check the tx on
  Solscan or Solana Explorer. If `err: null`, the on-chain side is fine —
  the most likely cause is `deposit_code` mismatch. The 16 hex chars must
  come verbatim from a real `/v1/register` response; a random 16 hex chars
  binds to no token and is silently ignored.
- **"AccountNotFound for the ops wallet ATA."** The ops wallet's USDC ATA
  is expected to already exist on-chain. If it ever doesn't, fund any tiny
  USDC transfer to it from the dashboard once to materialize it, then
  retry.
- **"insufficient funds for fee."** Depositor needs SOL for the network
  fee in addition to the USDC for the deposit. ~0.00001 SOL covers a
  basic tx; the SOL-deposit path naturally has its own SOL.
- **The transfer succeeds but your balance doesn't update.** You probably
  sent a plain SPL transfer instead of invoking the sovereign program. A
  plain transfer routes USDC to the destination ATA but does NOT emit
  `DepositEvent` — there's no way for the LiquidMirror to know which
  token to credit, so it won't be. You must build `deposit_usdc` (or
  `deposit_sol`) through the program as shown above.

## `POD-BOND-XXXXXXXX` carve-out

If your `deposit_code` starts with `POD-BOND-`, the deposit routes to the
provider-bond ledger instead of a user balance. That's the supply-side
flow returned by `/v1/host/enroll`. **Regular users with `/v1/register`
codes should not use this prefix.** A `/v1/register` code is always 16 hex
chars with no prefix.

---

# Inference proxy

Source: https://docs.usepod.ai/api/proxy/
Description: The drop-in proxy path, supported endpoints, request headers, and response headers.

The proxy is the inference entry point. It mirrors the upstream OpenAI/Anthropic
API surface, with your token in the URL path.

Prefer to pay per request with no token at all? See
[Pay per request with x402](/api/x402-payments/).

## Path

```http
https://api.usepod.ai/proxy/<token>/...        # Anthropic-compatible
https://api.usepod.ai/proxy/<token>/v1/...     # OpenAI-compatible
```

Common endpoints behind the proxy:

| Endpoint | Surface |
| --- | --- |
| `/v1/chat/completions` | OpenAI chat completions (streaming and non-streaming) |
| `/v1/messages` | Anthropic messages |
| `/v1/models` | Model listing |
| `/v1/responses` (also `/responses`) | OpenAI Responses API, translated onto the same routing and billing as chat completions. Streaming and tool calls work; stateless — `previous_response_id` is rejected, so clients resend history — and hosted tools (`web_search`, `file_search`, `tool_search`) are ignored. Used by Codex CLI, which speaks only this surface. |

## Request headers

| Header | Required | Meaning |
| --- | --- | --- |
| `Content-Type: application/json` | yes | Standard JSON body |
| `X-Pod-Max-Price-Input` | no | Max price per million input tokens (USDC microunits) |
| `X-Pod-Max-Price-Output` | no | Max price per million output tokens (USDC microunits) |
| `X-Pod-Routing-Mode` | no | `auto` (default), `marketplace-only`, or `centralized-only` |
| `X-Pod-Providers` | no | Comma-separated provider names to pin this request to |

The `Authorization` / `api_key` your SDK sends is ignored — auth is the token in
the path. See [Spend controls](/using/spend-controls/) for the price headers and
[Routing & matching](/marketplace/routing/) for the routing headers.

## Response headers

| Header | Meaning |
| --- | --- |
| `X-Balance-Remaining` | Remaining token balance after this request |
| `X-Pod-Route` | Which source served the request: marketplace, key relay, or centralized |
| `X-Pod-Provider-Id` | The specific provider that served it — a provider name for centralized routes, a provider UUID for marketplace and key-relay routes |

## Errors

- A token with **no balance** is rejected before any upstream call.
- An **unknown token** returns `401`.
- In marketplace-only mode, **no provider at your price** returns a dedicated
  no-provider result rather than billing at a higher price.

Streaming responses are relayed byte-for-byte from the selected source; token
usage is extracted from the stream for settlement.

---

# Register a token

Source: https://docs.usepod.ai/api/register/
Description: Create a token and deposit address with POST /v1/register.

Create a new token (with an associated USDC deposit address) by calling the
public register endpoint.

## Request

```http
POST https://api.usepod.ai/v1/register
```

No body or auth is required.

```bash
curl -X POST https://api.usepod.ai/v1/register
```

## Response

The response contains your `<token>` (the UUID you place in the proxy base
URL) and a `deposit_code` — a 16-hex-char string that binds an on-chain
USDC deposit to this token. The deposit goes to a single sovereign program;
the `deposit_code` is what tells the LiquidMirror which token's balance to
credit. Do not confuse it with the API token itself: the API token authorizes
inference calls, the `deposit_code` only authorizes inbound credit.

## After registering

1. **Fund** the token by card or USDC — see [Funding your balance](/using/funding/).
   To wire a deposit from a script or any wallet that signs custom transactions,
   see [Deposit on-chain](/api/deposit-on-chain/) for the instruction spec
   and JS + Python snippets.
2. **Use** it as your base URL — see [Drop-in API](/using/drop-in-api/):

   ```bash
   ANTHROPIC_BASE_URL=https://api.usepod.ai/proxy/<token> claude
   OPENAI_BASE_URL=https://api.usepod.ai/proxy/<token>/v1 cursor
   ```

The token must carry a positive balance before it can serve requests.

---

# Pay per request with x402

Source: https://docs.usepod.ai/api/x402-payments/
Description: Accountless, pay-as-you-go inference — pay each call with USDC or SOL on Solana, in the standard x402 dialect or ours, verified on-chain. No token, no API key.

Most of UsePod runs on a prepaid token balance. **x402** is the accountless
alternative: no token, no API key, no signup — you pay for each request by
sending USDC (or SOL) on Solana, and the gateway verifies the payment
**on-chain** before serving the call. Nobody holds your funds in between: the
transfer goes from your wallet to ours, and the gateway reads the chain to
confirm it landed.

Two kinds of client work here, and the same quote serves both. A client
written against the [x402 specification](https://x402.org) — `@x402/fetch`, the
Solana x402 SDKs, an agent framework with x402 built in — reads the standard
entries in the quote and hands the gateway a partially-signed transaction to
co-sign and broadcast, exactly as the spec's `exact` scheme on Solana lays out.
A client you write yourself against this page can instead broadcast its own
transfer and prove it with the signature, which is the flow every example
below uses. Pick whichever you already have; you do not need both.

It is a good fit for agents and one-off automated callers that have a Solana
wallet but no UsePod account.

## Endpoints

x402 has its own accountless proxy paths (no token in the URL):

```http
POST https://api.usepod.ai/proxy/x402/v1/chat/completions   # OpenAI-compatible
POST https://api.usepod.ai/proxy/x402/v1/messages           # Anthropic-compatible
```

Requests must include `max_tokens` (or `max_completion_tokens`) so the gateway
can quote a price ceiling. Text/chat only.

## The flow

x402 is a three-step exchange over standard HTTP headers:

1. **Quote** — send your request with no payment. The gateway replies `402
   Payment Required` with a `PAYMENT-REQUIRED` header: a base64-encoded JSON
   quote listing how you may pay.
2. **Pay** — send the quoted amount on-chain to the quote's `pay_to` address.
3. **Settle** — repeat the **identical** request with a `PAYMENT-SIGNATURE`
   header carrying your transaction signature. The gateway looks the transaction
   up on-chain, verifies it, and returns the completion plus a `PAYMENT-RESPONSE`
   receipt.

The request is bound to a hash of its method, path, and body, so step 3 must be
byte-for-byte identical to step 1 — serialize the body once and reuse it.

### The quote (`PAYMENT-REQUIRED`)

Base64-decode the header to JSON. `accepts` is a menu of payment options:

```json
{
  "x402_version": 2,
  "quote_id": "6982dfc8-a8f0-4429-8326-3e31251dec7c",
  "accepts": [
    {
      "asset": "USDC",
      "scheme": "exact",
      "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
      "pay_to": "GXfqVnZENHzvim8rNN8TPwqxWXQe8EBbxhcEMYE8Z7BS",
      "amount_microunits": 44,
      "mode": "cap-with-surplus-credit"
    },
    { "asset": "SOL", "amount_microunits": 603, "pay_to": "GXfqVn…Z7BS", "...": "..." }
  ]
}
```

| Field | Meaning |
| --- | --- |
| `quote_id` | Identifies this quote; echo it back in the payment signature |
| `asset` | `USDC` or `SOL` — pick one rail |
| `pay_to` | Solana address to send the payment to |
| `amount_microunits` | The amount to send: USDC microunits (6 dp) for the USDC rail, **lamports** for the SOL rail |
| `mode` | `cap-with-surplus-credit` — the amount is a cap (see below) |

The SOL rail is priced from a live SOL/USD rate at quote time, so its lamport
amount tracks the same dollar cap as the USDC rail. Both settle on Solana.

The same `accepts` list also carries the **standard-dialect** entries a spec
client expects — `asset` is the SPL mint rather than a ticker, the recipient is
`payTo`, the amount is a base-unit string under `amount` and
`maxAmountRequired`, and `extra.feePayer` names the wallet that will pay the
network fee. They are appended after the entries above, so a client that reads
by position sees what it always saw, and a client that reads by field finds
what it needs. If you are hand-rolling a client, use the entries in the table;
if you are using an x402 library, it will pick the standard ones on its own.

### The payment signature (`PAYMENT-SIGNATURE`)

After your on-chain payment confirms, build this JSON, base64-encode it, and send
it as the `PAYMENT-SIGNATURE` header on the retry:

```json
{
  "quote_id": "6982dfc8-a8f0-4429-8326-3e31251dec7c",
  "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
  "asset": "USDC",
  "payer_wallet": "<your wallet address>",
  "signature": "<the on-chain transaction signature>"
}
```

### Standard x402 clients

If your client speaks the x402 `exact` scheme for Solana, nothing above applies
to you and nothing extra is required of you. Your library will select a
standard entry (USDC by mint, or SOL as the wrapped-SOL mint
`So11111111111111111111111111111111111111112`, since the scheme has no
native-lamport transfer), build a `TransferChecked` into our associated token
account with `extra.feePayer` as the fee payer, sign it as the token owner, and
send it back as `payload.transaction`. The gateway checks that the transaction
does exactly that one thing and nothing else, adds the fee-payer signature,
broadcasts it, waits for confirmation, and serves the request. The
`PAYMENT-RESPONSE` header carries the on-chain transaction signature.

Because the gateway pays the network fee on that path, the standard entries are
floored at one cent: a quote whose cap comes to less advertises `10000`
microunits, and whatever you paid above the actual cost of the call is credited
to your wallet's balance just as it is on every other rail. The fee payer is a
dedicated wallet with a daily budget for sponsored fees; if that budget is ever
exhausted the gateway says so in the error and the self-broadcast flow above
keeps working.

## What you're charged

The quoted amount is a **ceiling**, not the final price. The gateway charges
your actual token usage and credits the unused remainder (cap − actual) to a
wallet balance keyed to your `payer_wallet`, which is applied to future x402
requests from the same wallet. You always pay the cap up front on-chain; you
never overpay for the call itself.

## Verification & safety

- **Verified on-chain, whichever path.** The gateway reads the confirmed
  transaction from Solana and checks the balance delta into `pay_to`: the
  token balance for USDC and wrapped SOL, the native balance for SOL. The
  payment must credit at least the quoted amount. A signature alone never
  settles anything.
- **Co-signing is narrow.** On the standard path the gateway signs a
  transaction it did not build, so it first proves the transaction contains a
  single token transfer to our own account, that our key appears nowhere but
  as fee payer, and that only known programs are invoked; anything else is
  rejected before a signature is made.
- **Solana only.** USDC and SOL on Solana mainnet are supported today, on Base
  the USDC rail through the standard facilitator flow.
- **Replay-protected.** A given transaction signature can settle exactly one
  quote. Reusing it for a second quote is rejected, and re-sending the same
  partially-signed transaction converges on the payment it already made rather
  than broadcasting twice.
- **Fees.** On the flow described above your wallet pays the Solana network fee
  (~5,000 lamports) on top of the payment, so it needs a little SOL regardless
  of which rail you use. On the standard path the gateway is the fee payer and
  your wallet needs no SOL at all.

## Worked example (Python)

A complete, runnable client for the USDC rail. It quotes, pays USDC on-chain
(waiting for confirmation), then settles — printing the model's reply.

```python
#!/usr/bin/env python3
"""Pay-per-call against the UsePod API with x402 (USDC on Solana).

Deps: pip install requests==2.34.2 solana==0.36.12 solders==0.27.1
Env:  SOLANA_KEYPAIR (path to Solana keypair JSON), SOLANA_RPC_URL.
"""

import base64
import json
import os
import requests
from solana.rpc.api import Client
from solana.rpc.types import TxOpts
from solders.keypair import Keypair
from solders.pubkey import Pubkey
from spl.token.client import Token
from spl.token.constants import TOKEN_PROGRAM_ID
from spl.token.instructions import get_associated_token_address as ata

URL = "https://api.usepod.ai/proxy/x402/v1/chat/completions"
USDC = Pubkey.from_string("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v")
HDRS = {"Content-Type": "application/json", "User-Agent": "usepod-x402/1.0"}
body = json.dumps(
    {
        "model": "gpt-4o-mini",
        "max_tokens": 64,
        "messages": [{"role": "user", "content": "What is Solana?"}],
    }
)
kp = Keypair.from_bytes(
    bytes(json.load(open(os.path.expanduser(os.environ["SOLANA_KEYPAIR"]))))
)
token = Token(Client(os.environ["SOLANA_RPC_URL"]), USDC, TOKEN_PROGRAM_ID, kp)

# 1. Request with no payment -> 402 carrying a quote in the PAYMENT-REQUIRED header.
quote = json.loads(
    base64.b64decode(
        requests.post(URL, data=body, headers=HDRS).headers["PAYMENT-REQUIRED"]
    )
)
rail = next(r for r in quote["accepts"] if r["asset"] == "USDC")

# 2. Send the quoted USDC on-chain to the quote's pay_to address (waits for confirmation).
sig = token.transfer_checked(
    ata(kp.pubkey(), USDC),
    ata(Pubkey.from_string(rail["pay_to"]), USDC),
    kp,
    int(rail["amount_microunits"]),
    6,
    opts=TxOpts(skip_confirmation=False, preflight_commitment="confirmed"),
).value

# 3. Retry the identical request, proving payment with the transaction signature.
pay = base64.b64encode(
    json.dumps(
        {
            "quote_id": quote["quote_id"],
            "network": rail["network"],
            "asset": "USDC",
            "payer_wallet": str(kp.pubkey()),
            "signature": str(sig),
        }
    ).encode()
).decode()
resp = requests.post(URL, data=body, headers={**HDRS, "PAYMENT-SIGNATURE": pay})
print(resp.json()["choices"][0]["message"]["content"])
```

Run it:

```bash
pip install requests==2.34.2 solana==0.36.12 solders==0.27.1
export SOLANA_KEYPAIR=~/.config/solana/id.json
export SOLANA_RPC_URL="https://your-solana-rpc"   # any mainnet RPC
python x402_payment_demo.py
```

Your wallet needs a little SOL (for the network fee) and USDC (for the payment).
The per-call amounts are tiny — fractions of a cent — so a dollar of USDC covers
a great many calls.

## See also

- [Inference proxy](/api/proxy/) — the standard token-based proxy path
- [Funding your balance](/using/funding/) — prepaid card and USDC top-ups
- [Deposit on-chain](/api/deposit-on-chain/) — fund a token directly on Solana

---

# From creator coin to a compute marketplace

Source: https://docs.usepod.ai/concepts/creator-coin-to-marketplace/
Description: How chasing agent autonomy — persistence, self-funding, and affordable inference — led to a two-sided marketplace for LLM inference.

:::note[Adapted from an essay]
Adapted from a piece originally published on X by [@0xgilbert](https://x.com/0xgilbert/status/2057165961099104539), 2026-05-20. Lightly edited for the docs.
:::

## Agents need more than code

The question that started this: *what do agents actually need to do the work
humans ask of them?* The answer wasn't just better models or faster APIs — it was
infrastructure. Agents need tools to act in the world. They need persistence so
they don't disappear when the terminal closes. They need to pay their own bills
so they can run autonomously. And they need access to inference that doesn't
bankrupt their operators.

An agent that can't pay for its own compute is just an expensive demo. Solving
that — economic sustainability — is the real problem.

## Level5, SQUIRE, and the path to UsePod

It started with [Level5.cloud](https://level5.cloud), a hosting platform where an
agent can pay its own bills: agents get wallets, manage their own resources, and
don't die when you close your laptop. That solved persistence — but not the
bigger problem: inference costs are heavily subsidized right now, and those
subsidies won't last.

Along the way, $SQUIRE — originally a creator coin with no utility — was given a
purpose: holders could redeem ongoing inference credits, modeled on perpetual
credit systems like DIEM. Under the hood that meant reselling an inference
allocation to holders at a discount.

That surfaced the real question: *if I'm turning idle inference credits into
revenue, how many others are sitting on the same problem?* Token holders have
daily allocations they never use. Hardware providers have idle capacity they
can't monetize. Researchers have custom models no public API offers. And
inference users are about to get hit with a pricing shock when subsidies wind
down.

That question became UsePod.

## A two-sided marketplace for inference

UsePod is a two-sided marketplace for LLM inference. It serves four kinds of
participant:

- **Hardware providers** run models on their own infrastructure and set their
  own pricing — competing directly with frontier providers. See
  [Running a provider](/providers/quickstart/).
- **Token holders** who hold "free" inference allocations can resell daily
  credits into the market at a discount — turning idle allocation into a
  perpetual revenue stream instead of letting it expire.
- **Researchers** monetize their work by contributing models — including custom
  quantizations you can't find at any public provider — priced at whatever rate
  the operator sets.
- **Inference users** change their API endpoint to UsePod and get the same
  frontier models plus open-source alternatives at a discount to the aggregators.
  It's a one-line change. See the [Drop-in API](/using/drop-in-api/).

The result: your agent gets a perpetual revenue stream on one side and a deep,
discounted pool of inference on the other.

## Where this leads

A spot marketplace is the first layer. The harder, more interesting work is the
market structure underneath it — pricing that can be locked in, capacity that can
be traded, and inference financialized the way every other scarce resource is.
That's the thesis behind [Verification is the product](/vision/verification/),
where verifiable delivery turns compute into a tradable commodity with a
derivatives stack on top.

---

# Why inference is becoming a commodity

Source: https://docs.usepod.ai/concepts/inference-commodity/
Description: Monopoly and subsidy pricing are temporary. As open-weight models reach parity, a marketplace drives inference toward the cost of production.

:::note[Adapted from an essay]
Adapted from a piece originally published on X by [@0xgilbert](https://x.com/0xgilbert/status/2043727718009770019), 2026-04-13. Lightly edited for the docs; figures are point-in-time.
:::

Right now, if you want Claude or Codex to write code for you, your options are a
subscription with usage caps and rate limits, or the API direct — no caps, but a
heavy day swings from $5 to $30 with no ceiling. Either way one company sets the
price, and you pay it or you don't get to use the model.

It doesn't have to work that way.

## The problem: monopoly pricing

Today's inference market is a collection of monopolies. OpenAI sets GPT's price,
Anthropic sets Claude's, Google sets Gemini's. There's no competition on price
for the *same* model — if you want Claude Opus, you pay Anthropic's price, period.

But two things are true that most people haven't internalized: frontier models
are **temporary** monopolies, and open-weight models are **commodities**. And
commodities get cheaper when markets are allowed to work. Open-weight models now
trail frontier proprietary models by only a few months, and the gap closes with
every release.

## The 1,000x cost collapse

The cost of inference has dropped roughly 1,000x in three years. Equivalent
quality that cost hundreds of dollars per million tokens in early 2023 costs
cents today. Four factors compound — hardware, software optimization, model
architecture, and quantization — each multiplying the others.

But who captures those savings today? The providers. The actual cost to serve a
token — electricity, amortized GPU, bandwidth — is a fraction of the list price.
The difference is margin and the absence of competition.

## The solution: a two-sided marketplace

Picture inference that works like a commodity exchange:

- **Supply side.** Anyone with GPU capacity registers as a provider, runs an
  open model, and sets their price per million tokens.
- **Demand side.** Developers and agents submit requests specifying the model,
  their latency requirements, and the most they're willing to pay. They don't
  care *who* serves it — only that the model is correct, the latency is
  acceptable, and the price is the best available.
- **The routing layer.** Sits between the two: tracks provider quality, latency,
  throughput, and reliability, and routes each request to the best provider
  within the user's constraints — settling payment per request at machine speed.

This is how every other fungible market works — electricity, bandwidth, compute.
A token generated by a given open model on cluster A is identical to one from
cluster B. When the product is fungible, the market drives price toward marginal
cost.

## What this means for developers

In a competitive marketplace with many providers bidding to serve the same open
model:

- **Open-weight models get several times cheaper** as price converges on
  marginal cost.
- **Smart routing eliminates waste.** "Write a unit test" goes to a cheap
  commodity model; "architect this distributed system" goes to a frontier model.
  Frontier quality where you need it, commodity pricing everywhere else.
- **The blended math changes.** If 80% of your tokens go to commodity models and
  20% to frontier, your blended cost drops dramatically versus paying frontier
  rates for everything — a month of intensive AI-assisted coding can land in the
  low tens of dollars, with no caps, rate limits, or throttling.

Crucially, that price doesn't depend on subsidy. It's what the free market puts
on inference, and it trends *down* over time, not up.

## The subsidy trap

Today's consumer pricing from the major providers isn't a service — it's
customer acquisition. The cheap tiers lose money on purpose: hook users, build
dependency, then raise prices and reserve the best models for premium plans. It's
the classic playbook, and it only works when there's no alternative.

An open marketplace *is* the alternative. When model weights are public and
anyone can serve them, the subscription lock-in breaks. You're not paying for
access to a proprietary model — you're paying for compute, and compute is a
commodity.

## The trust question

The obvious objection: *how do I know some random provider is actually running
the correct model, unmodified?*

UsePod's answer today is **reputation plus benchmark canaries**: providers
accrue a reputation score from real request outcomes, and a small fraction of
traffic is sampled as a hidden canary whose output is checked for deviation —
catching providers that misreport what they serve. Bonds give that enforcement
teeth. See [Trust & reputation](/marketplace/trust/) for how it works in
production.

Stronger, hardware-level guarantees — cryptographic attestation that a specific
model ran on specific hardware — are on the roadmap, not shipped. That's covered
in [Verification is the product](/vision/verification/).

## The bigger picture

The centralized API model — a handful of companies setting prices and terms for
the whole industry — is a temporary artifact of proprietary models and few
providers. As open models reach parity, value shifts from "who has the best
model" to "who serves it cheapest and most reliably." That's a commodity market,
and commodity markets have one inevitable outcome: the price drops to the cost of
production.

The companies that win that world aren't the ones running the GPUs. They're the
ones building the routing, reputation, verification, and payment infrastructure
that makes the market work — so a developer or an agent can reach any model, from
any provider, at the best available price.

Ready to try it? Start with the [Quickstart](/using/quickstart/).

---

# Integrations

Source: https://docs.usepod.ai/integrations/
Description: Every client that speaks OpenAI or Anthropic can point at UsePod by changing one base URL. These are the ones we have wired and verified.

UsePod is a base-URL swap, which means the list below is not a list of things we
built adapters for — it is a list of clients we have actually pointed at the
proxy and watched answer. Anything that lets you override an OpenAI or Anthropic
base URL belongs on it whether or not it is named here.

Two URLs cover almost everything:

| Surface | Base URL |
|---|---|
| OpenAI-compatible | `https://api.usepod.ai/proxy/<token>/v1` |
| Anthropic-compatible | `https://api.usepod.ai/proxy/<token>` |

The token in the path **is** the credential, so wherever a client demands an API
key you can hand it any non-empty string — `UsePod` reads well in a config file
— and the field will simply be ignored. That one detail trips more people than
everything else combined, because a client that refuses to start without a key
looks like an authentication problem when it is really just a required field.

## Coding agents

- **[Claude Code](/integrations/claude-code/)** — terminal coding agent. Two
  environment variables against the Anthropic-compatible endpoint.
- **[Codex CLI](/integrations/codex/)** — terminal coding agent. A provider
  block in `~/.codex/config.toml`; it ignores `OPENAI_BASE_URL` entirely, which
  is the single most common reason a Codex wire-up appears to do nothing.
- **[OpenCode](/integrations/opencode/)** — terminal coding agent. A provider
  block in `opencode.json`.
- **[Cline](/integrations/cline/)** — VS Code agent. Settings panel, "OpenAI
  Compatible" provider.
- **[Aider](/integrations/aider/)** — terminal pair programmer. Environment
  variables or flags.
- **[Cursor](/integrations/cursor/)** — editor. Settings panel, with an OpenAI
  base-URL override.

## SDKs

The official SDKs need nothing but the base URL, so they are documented together
on [Drop-in API](/using/drop-in-api/) rather than a page each:

- **OpenAI Python / Node / Go** — `base_url` on the client.
- **Anthropic Python / Node** — `base_url` on the client, no `/v1` suffix.

## Frameworks and extensions

- **Continue.dev** — a model entry in `~/.continue/config.json` with `apiBase`
  set to the OpenAI-compatible URL; set `"provider": "anthropic"` and drop the
  `/v1` to use the Anthropic surface instead.
- **LangChain, LangGraph** — pass `base_url` to `ChatOpenAI`, or
  `anthropic_api_url` to `ChatAnthropic`.
- **LiteLLM** — configure UsePod as an `openai/`-prefixed model with
  `api_base` pointing at the proxy.

## Anything else

If a client accepts a custom base URL, it works, and the fastest way to find out
is [raw curl](/using/drop-in-api/) against the same URL you are about to paste
into it. A streaming reply from curl and a failure inside the client narrows the
problem to the client's configuration rather than the account, which is usually
the answer.

Once a tool is connected, [spend controls](/using/spend-controls/) apply to it
without any further configuration: the per-request price ceilings are HTTP
headers, so they travel with any client that can set one.

---

# Aider

Source: https://docs.usepod.ai/integrations/aider/
Description: Run Aider against UsePod with two environment variables or two flags.

Aider reads the standard OpenAI environment variables, so it connects without a
configuration file.

## Setup

```bash
export OPENAI_API_KEY="UsePod"
export OPENAI_API_BASE="https://api.usepod.ai/proxy/<TOKEN>/v1"

aider --model gpt-5-4-mini
```

Replace `<TOKEN>` with the API token from your
[dashboard](https://usepod.ai/dashboard). Note that Aider uses
`OPENAI_API_BASE`, not `OPENAI_BASE_URL` — the two names appear
interchangeably across tools and are not.

Or pass everything as flags, which keeps a shared shell clean:

```bash
aider \
  --openai-api-key UsePod \
  --openai-api-base https://api.usepod.ai/proxy/<TOKEN>/v1 \
  --model gpt-5-4-mini
```

## Verify

Aider prints the active model on startup; confirm it matches what you asked for,
then send a one-line prompt. A reply means the proxy is carrying it.

## Choosing a model

Aider's editing formats ask a lot of a model — it expects diffs or whole files
back in a specific shape, and weaker models fail that structure more often than
they fail the reasoning. If edits are being rejected or malformed, try a
stronger model before assuming the integration is at fault.

`--model` accepts any id from the [marketplace](https://usepod.ai/marketplace).

## Troubleshooting

**Aider ignores the base URL.** The variable is `OPENAI_API_BASE`. Setting
`OPENAI_BASE_URL` does nothing here, which is a frequent cross-tool mix-up.

**Repeated malformed-edit retries.** A model-capability issue rather than a
connection one; the requests are arriving and being billed.

**402 mid-session.** Aider sends the repository map plus conversation on each
turn, so input tokens accumulate quickly on a large repo. Fund the token or
narrow the files in scope.

---

# Claude Code

Source: https://docs.usepod.ai/integrations/claude-code/
Description: Point Anthropic's terminal coding agent at UsePod with two environment variables.

Claude Code speaks the Anthropic Messages API, which UsePod serves directly, so
the wire-up is two environment variables and no configuration file at all.

## Setup

```bash
export ANTHROPIC_API_KEY="UsePod"
export ANTHROPIC_BASE_URL="https://api.usepod.ai/proxy/<TOKEN>"

claude
```

Replace `<TOKEN>` with the API token from your [dashboard](https://usepod.ai/dashboard).
`ANTHROPIC_API_KEY` can be any non-empty string: the token in the base URL is
what authenticates the request, but the SDK refuses to send a request without
the header present, so the variable has to exist.

Note the **absence of a `/v1` suffix** on the Anthropic surface. Claude Code
appends the API path itself, and a base URL ending in `/v1` produces a 404 that
looks like a routing failure when it is really a doubled path segment.

To scope it to a single session rather than your shell profile:

```bash
ANTHROPIC_BASE_URL=https://api.usepod.ai/proxy/<TOKEN> \
ANTHROPIC_API_KEY=UsePod \
claude
```

## Verify

Ask the agent anything — a normal reply means the proxy is carrying the session.
If you would rather confirm the wiring before launching the agent, the same URL
answers curl:

```bash
curl -s https://api.usepod.ai/proxy/<TOKEN>/v1/messages \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model":"claude-haiku-4-5","max_tokens":32,
       "messages":[{"role":"user","content":"ping"}]}'
```

## Choosing a model

Claude Code picks its own default and lets you override it with
`ANTHROPIC_MODEL`. Every Claude model in the [marketplace](https://usepod.ai/marketplace)
is addressable by its plain id:

```bash
export ANTHROPIC_MODEL="claude-sonnet-5"
```

## Troubleshooting

**Every request 404s.** The base URL almost certainly ends in `/v1`. The
Anthropic surface takes the bare proxy path; only the OpenAI-compatible surface
carries the `/v1` suffix.

**401 despite a valid token.** `ANTHROPIC_API_KEY` is unset or empty. The value
is discarded, but the header must be there.

**402 with a balance you believe is funded.** The balance is per token, and a
second token minted by a different device has its own. The dashboard shows which
token you are looking at.

**Responses stop mid-session.** Long agent sessions accumulate context, and
context costs money on every turn; check the balance before assuming a fault.

---

# Cline

Source: https://docs.usepod.ai/integrations/cline/
Description: Configure the Cline VS Code agent against UsePod's OpenAI-compatible endpoint.

Cline has a first-class "OpenAI Compatible" provider, which is exactly what
UsePod is, so there is nothing to work around here.

## Setup

In Cline's settings panel:

1. **API Provider:** OpenAI Compatible
2. **Base URL:** `https://api.usepod.ai/proxy/<TOKEN>/v1`
3. **API Key:** `UsePod` — or any non-empty string; the token in the URL is the
   credential
4. **Model ID:** any id from the [marketplace](https://usepod.ai/marketplace),
   for example `claude-sonnet-5` or `deepseek-v4-1-flash`

Replace `<TOKEN>` with the API token from your
[dashboard](https://usepod.ai/dashboard).

## Verify

Start a Cline task and watch it respond. Because Cline shows token counts per
turn, it is a convenient place to sanity-check that usage is landing where you
expect: the same numbers appear in your dashboard's activity feed.

## Choosing a model

Cline drives long agentic loops with large contexts, which makes model choice a
cost decision more than a capability one. A cheap model doing ten turns can
easily cost more than an expensive model doing two. The marketplace lists
per-million prices for both input and output, and output is where agent loops
spend.

[Spend controls](/using/spend-controls/) are the backstop: set a per-request
price ceiling and a runaway loop cannot quietly buy the expensive tier.

## Troubleshooting

**"Model not found".** The id must match the marketplace exactly — no vendor
prefix, no date suffix.

**Cline hangs on the first turn.** Confirm the base URL carries `/v1`.

**Costs climbing faster than expected.** Check whether Cline is sending the full
file context each turn; that is a Cline setting, not a UsePod one, and it
multiplies input tokens across every turn of a loop.

---

# Codex CLI

Source: https://docs.usepod.ai/integrations/codex/
Description: OpenAI's terminal coding agent needs a config file, not environment variables — here is the block that works and the behaviour to expect.

Codex is the one client on this list that cannot be wired with environment
variables, and the reason is worth understanding before you start: Codex ignores
`OPENAI_API_KEY` and `OPENAI_BASE_URL` outright, and since February 2026 it
speaks only the OpenAI **Responses** API — `wire_api = "chat"` is gone, and a
config that still sets it now refuses to load. Any instructions you find that
export two variables and run `codex` predate that change and will quietly send
your traffic to OpenAI instead.

UsePod serves `/v1/responses`, so the correct wiring is a provider block.

## Setup

Create or edit `~/.codex/config.toml`:

```toml
model = "deepseek-v4-1-flash"
model_provider = "usepod"

[model_providers.usepod]
name = "UsePod"
base_url = "https://api.usepod.ai/proxy/<TOKEN>/v1"
wire_api = "responses"
```

Then run `codex`. Replace `<TOKEN>` with the API token from your
[dashboard](https://usepod.ai/dashboard).

**No API key is required anywhere in this file.** With no `env_key` set, Codex
sends no `Authorization` header at all, and the token in the base URL is what
authenticates the request — so there is no secret to export and nothing to leak
into your shell history.

Set `wire_api` explicitly even though the documentation calls it the default;
configs that omitted it have been observed failing to reach the provider.

## Verify

Send a short prompt in the Codex TUI and watch the reply stream. Or confirm the
endpoint independently first:

```bash
curl -s https://api.usepod.ai/proxy/<TOKEN>/v1/responses \
  -H 'content-type: application/json' \
  -d '{"model":"deepseek-v4-1-flash","input":"Reply with exactly: ok",
       "max_output_tokens":200}'
```

A `"status": "completed"` response with an output item containing `ok` means the
surface is live for your token.

## Choosing a model

Any model id from the [marketplace](https://usepod.ai/marketplace) works in the
`model` field. One consequence is worth knowing, because it is invisible until
you hit it: **Codex decides which tools to offer the model based on the model
id**, matched against its own table of OpenAI names. Point it at an id it does
not recognise — which includes every non-OpenAI model — and two things change.

It prints a startup warning:

```
warning: Model metadata for `deepseek-v4-1-flash` not found.
Defaulting to fallback metadata; this can degrade performance and cause issues.
```

That warning is about Codex's local assumptions, not about UsePod rejecting
anything; your requests route normally. It means Codex is guessing at the
context window rather than reading it from a table, so it may compact the
conversation earlier than necessary.

And it omits the `apply_patch` tool, offering a sub-agent namespace instead.
Codex still edits files — it falls back to shell commands through
`exec_command` — but multi-file edits go through a less structured path than
they would on a model it recognises.

Neither behaviour breaks the integration. If you would rather have the patch
tool, name a model Codex knows; if you would rather have the price, name the
model you want and accept the warning.

## What the Responses surface supports

- **Streaming and tool calls** both work, including multi-turn tool loops.
- **Reasoning** is passed through: models that emit reasoning content surface it
  as a reasoning item alongside the message.
- **It is stateless.** `previous_response_id` is rejected with a 400, because
  UsePod stores no responses. Codex sends `store: false` and resends the full
  conversation each turn, so this never comes up in normal use.
- **Hosted tools are ignored.** `web_search` and `tool_search` have no
  equivalent on a chat-completions upstream and are dropped rather than
  forwarded, which is what keeps upstreams from rejecting the whole request.

## Troubleshooting

**`wire_api = "chat"` is no longer supported.** Delete the line or set it to
`"responses"`. Chat-completions support was removed from Codex in early 2026.

**Requests go to api.openai.com.** Your provider block is not being used —
usually a missing `model_provider = "usepod"` at the top level, or a
`[model_providers.…]` table whose name does not match it.

**404 on `/v1/responses`.** The base URL is missing its `/v1` suffix. Unlike the
Anthropic surface, this one takes it.

**The startup metadata warning.** Expected on any non-OpenAI model id. See
above; it is not an error.

---

# Cursor

Source: https://docs.usepod.ai/integrations/cursor/
Description: Override Cursor's OpenAI base URL to route its requests through UsePod.

Cursor keeps its model configuration in a settings panel rather than a file, so
this one is four clicks rather than a snippet.

## Setup

1. Open **Cursor → Settings → Models**.
2. Find **OpenAI API Key** and set it to any non-empty value — `UsePod` works.
3. Enable **Override OpenAI Base URL** and enter:
   `https://api.usepod.ai/proxy/<TOKEN>/v1`
4. Click **Verify**. Cursor pings the base URL and reports success.

Replace `<TOKEN>` with the API token from your
[dashboard](https://usepod.ai/dashboard).

Cursor stores these **per workspace**, which is a feature rather than a nuisance
once you notice it: a client project can carry its own token, and its inference
lands on its own balance without any further bookkeeping. It also means a fresh
workspace starts unconfigured, which is the usual explanation for a setup that
"stopped working" after switching projects.

## Verify

Open the chat panel and send a message. Cursor's own **Verify** button confirms
reachability but not billing; a real reply confirms both.

## What routes through UsePod and what does not

Cursor's chat and inline edits use the OpenAI-compatible endpoint you just
overrode, so those bill to your token. Some Cursor features — tab completion
among them — run on Cursor's own infrastructure and are unaffected by this
setting. If your balance moves more slowly than you expected, that is why.

## Troubleshooting

**Verify fails.** The base URL is missing the `/v1` suffix, or the token is
mistyped. Test the same URL with curl before touching Cursor's settings again.

**Verify passes but chat errors.** Usually a model id Cursor is requesting that
your account cannot reach. Check the [marketplace](https://usepod.ai/marketplace)
for the exact id.

**Settings vanished.** They are per workspace; reopen the workspace you
configured, or configure the new one.

---

# OpenCode

Source: https://docs.usepod.ai/integrations/opencode/
Description: Point OpenCode at UsePod with a provider block in opencode.json.

OpenCode reads its configuration from `opencode.json`, and the OpenAI provider
accepts a base URL override, so connecting it is a single block.

## Setup

Edit `~/.config/opencode/opencode.json`:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "openai": {
      "options": {
        "apiKey": "UsePod",
        "baseURL": "https://api.usepod.ai/proxy/<TOKEN>/v1"
      }
    }
  }
}
```

Replace `<TOKEN>` with the API token from your
[dashboard](https://usepod.ai/dashboard). `apiKey` can be any non-empty string;
the token in the URL is the credential, and the field exists only because the
SDK will not send a request without it.

A project-local `opencode.json` overrides the user-level one, which is the
cleanest way to bill separate work to separate tokens.

## Verify

Start OpenCode and send a message. A normal reply confirms the wiring; the model
picker will list whatever the OpenAI provider is configured to offer.

## Troubleshooting

**Connection refused or 404.** Check that `baseURL` ends in `/v1` — the
OpenAI-compatible surface takes the suffix.

**The model picker is empty.** OpenCode asks the provider for
`/v1/models`, which UsePod serves; an empty list usually means the base URL is
wrong rather than that the account has no access.

**402.** The token is out of balance. Fund it from
[the dashboard](https://usepod.ai/fund) and retry — nothing needs restarting.

---

# How it works

Source: https://docs.usepod.ai/introduction/how-it-works/
Description: From an inbound request to a settled, billed response — the path through the UsePod gateway.

Every inference request flows through the UsePod gateway, which authenticates
the caller, checks balance, matches a provider, relays the response, and settles
the bill asynchronously.

## The request path

1. **Auth.** Your token is resolved (Redis cache, with a Postgres fallback).
2. **Balance check.** The token must have a positive balance.
3. **Rate limit.** Per-token requests-per-minute and a concurrency cap apply.
4. **Marketplace match.** Active providers for the requested model are loaded,
   their prices capped at the cheapest centralized price, filtered by your price
   ceiling and provider health, then sorted by price.
   - **Marketplace candidate found** → dispatched over an outbound WebSocket to a
     provider agent, which calls its local backend and streams bytes back.
   - **key relay candidate found** → the gateway decrypts the operator's stored
     key and forwards over HTTPS to the upstream.
   - **Otherwise** → falls through to the centralized router (the always-on
     tier-zero fallback).
5. **Relay.** The response is streamed back to you byte-for-byte, with
   `X-Balance-Remaining` and `X-Pod-Route` headers.
6. **Settlement (async).** Token usage is extracted from the stream and recorded;
   a background worker debits your balance and, for marketplace routes, credits
   the provider.

## The two sides

- **Demand side.** You hold a token with a USDC balance and send standard API
  requests. See [Using UsePod](/using/quickstart/).
- **Supply side.** Operators run the provider agent (or enroll a key relay),
  advertise models and prices, and earn 80% of every settled inference. See
  [Running a provider](/providers/quickstart/).

## Settlement and fees

Marketplace routes split each settled inference **80% to the provider, 20% to the
treasury**. Users are billed at the operator's listed price, which is capped at
the cheapest centralized price for that model — so the marketplace never costs
more than the fallback.

Learn more in [Routing & matching](/marketplace/routing/) and
[Pricing](/marketplace/pricing/).

---

# What is UsePod

Source: https://docs.usepod.ai/introduction/what-is-use-pod/
Description: An inference marketplace with a drop-in OpenAI/Anthropic-compatible API and USDC settlement.

UsePod is an **inference marketplace**. Independent operators run open-weight
models on their own GPU hardware — or relay requests with their own keys to
upstreams like Level5, Venice, OpenRouter, Together, Groq, or Morpheus — set
their prices, and earn USDC. Users send standard OpenAI- or Anthropic-compatible
API requests and get matched with the best-priced provider that meets their
requirements.

Centralized providers (Anthropic, OpenAI, Venice, Together, Groq, OpenRouter,
Bedrock) remain available as a **tier-zero fallback, always**. If no marketplace
provider can serve a request within your constraints, it transparently falls
through to a centralized upstream.

## Why it exists

Inference is becoming a commodity. A two-sided marketplace lets supply (anyone
with a GPU or an upstream key) meet demand (anyone with an OpenAI/Anthropic
client) directly, with price discovery instead of fixed list prices — while
keeping the drop-in compatibility that makes existing agents and tools work
unchanged.

## What makes it different

- **Drop-in compatibility.** Change one environment variable. No SDK changes, no
  auth changes. Existing OpenAI and Anthropic clients — including Claude Code,
  Cursor, and custom agents — work as-is.
- **USDC billing.** A token carries a balance; each request is debited. Top up
  by card or by sending USDC on Solana.
- **Open supply side.** Anyone can run the provider agent against a local backend
  (vLLM, llama.cpp, LM Studio, Ollama) or enroll a bring-your-own-key relay.
- **Price-capped routing.** Marketplace and key relay candidates are never more
  expensive than the cheapest centralized price for the same model.

## Who it's for

- **Agent and app builders** who want cheaper inference without rewriting their
  integration.
- **GPU operators** who want to monetize spare capacity.
- **Resellers** who hold upstream API keys and want to set their own resale
  prices.

Next: [How it works](/introduction/how-it-works/).

---

# Pricing

Source: https://docs.usepod.ai/marketplace/pricing/
Description: Per-million-token pricing, the cap-at-centralized rule, and the fee split.

## Units

Prices are quoted **per million tokens**, separately for input and output. In the
API and headers, prices are expressed in **USDC microunits** (1 USDC =
1,000,000 microunits) — so `400000` means $0.40 per million tokens.

## The cap-at-centralized rule

Marketplace and key relay listings are **capped at the cheapest centralized price** for
the same model, on both the input and output axes. A provider can list below the
centralized price to win traffic, but never above it. Consequences:

- The marketplace is never more expensive than the centralized fallback.
- In auto routing, an over-priced listing simply loses to a cheaper option or to
  centralized.
- In marketplace-only routing, if every listing exceeds your ceiling, the request
  returns a no-provider-at-price result instead of overcharging.

## Fee split

Marketplace routes split each settled inference:

| Party | Share |
| --- | --- |
| Provider | 80% |
| Treasury | 20% |

Users are billed at the operator's listed (capped) price; the split is applied to
that amount at settlement.

## Billing basis

Billing is based on **actual token usage** extracted from the response stream, at
the selected provider's price. Cache reads/writes are accounted separately where
the upstream reports them.

---

# Routing & matching

Source: https://docs.usepod.ai/marketplace/routing/
Description: How the coordinator selects a provider for each request, with centralized fallback.

For each request, the coordinator selects where to send it. The goal is the
cheapest source that satisfies your model, price, and health constraints — with a
centralized provider always available as a fallback.

## Selection order

1. **Load candidates** for the requested model: active marketplace providers
   (live agents that are online and healthy) and active key relay listings.
2. **Cap prices** at the cheapest centralized price for the model, on both the
   input and output axes.
3. **Filter** by your per-request price ceiling (see
   [Spend controls](/using/spend-controls/)), throttle, and capacity/health.
4. **Sort** by listed price and pick the best.

If a marketplace or key relay candidate is selected, the request is dispatched to it.
Otherwise it **falls through to the centralized router** — the always-on
tier-zero fallback (Anthropic, OpenAI, Venice, Together, Groq, OpenRouter,
Bedrock).

## Routing modes

Set with the `X-Pod-Routing-Mode` request header:

| Value | Behaviour |
| --- | --- |
| `auto` (default) | Prefer the cheapest eligible marketplace/key relay candidate; fall through to centralized when none qualifies |
| `marketplace-only` | Restrict to marketplace/key relay candidates; if none qualify at your price, return a no-provider-at-price result rather than using centralized |
| `centralized-only` | Skip the marketplace entirely and route through the centralized tier |

```bash
curl https://api.usepod.ai/proxy/$TOKEN/v1/chat/completions \
  -H "X-Pod-Routing-Mode: centralized-only" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-haiku-4-5","messages":[{"role":"user","content":"hi"}]}'
```

## Pinning specific providers

Routing optimizes for price, so the source that serves you can change between
two identical requests as relays drain, refill, and rotate. If you need the
throughput you measured yesterday to be the throughput you get today, pin the
request to the providers you want with `X-Pod-Providers`:

```bash
# Only Venice.
-H "X-Pod-Providers: venice"

# OpenAI first, OpenRouter as the backup — and nothing else.
-H "X-Pod-Providers: openai,openrouter"
```

The order you list them in is the order they are tried.

### Valid provider names

| Name | Provider | Notes |
| --- | --- | --- |
| `anthropic` | Anthropic | First-party Claude models, Anthropic Messages format upstream |
| `openai` | OpenAI | First-party GPT models |
| `bedrock` | AWS Bedrock | Claude via AWS; Anthropic Messages format upstream |
| `venice` | Venice | Privacy-focused, open-weight models |
| `together` | Together AI | Open-weight models |
| `groq` | Groq | LPU-served open-weight models, high throughput |
| `openrouter` | OpenRouter | Meta-aggregator, widest catalog |
| `nousresearch` | Nous Research | Hermes family and other open-weight models |
| `google` | Google | Gemini models |
| `surplus` | Surplus Intelligence | Order-book meta-aggregator; normally the price backstop tier |
| `c0mpute` | c0mpute.ai | Per-request (flat-fee) priced models only; reachable only by explicit model selection |
| `uomi` | UomiRouter | Aggregating router of open-weight models |

A pinned provider still has to have a listing for the model you request — the
format translation between OpenAI and Anthropic API shapes is handled for you,
but pinning `venice` for a model Venice doesn't carry is an unsatisfiable pin
and fails with the `503` described below.

Three things to know:

- **A pin is a hard constraint.** If none of the pinned providers can serve the
  request, it fails with a `503` naming the pin. It never quietly falls back to
  a provider you excluded — a pin that degrades to "anything" would be worse
  than no pin, because you would believe you had a guarantee you did not.
- **A pin skips the marketplace.** "Only these providers" excludes the several
  hundred relays you did not name, so pinning implies `centralized-only`.
  Combining `X-Pod-Providers` with `X-Pod-Routing-Mode: marketplace-only` is
  contradictory and returns `400`.
- **An unknown name is rejected**, rather than silently pinning to nothing. A
  typo returns `400` listing the valid names, so a config mistake never reads
  as an outage.

Check `X-Pod-Provider-Id` on the response to confirm which provider served the
request.

## Provider health

Both tiers demote providers on their own recent record. A marketplace relay or
centralized provider whose failure rate or mean time-to-headers is out of band
is moved behind healthy ones, so a cheap provider that is currently stalling
cannot win routing on price alone.

Demotion, never exclusion — a degraded provider still serves when it is the
only thing that can, because the centralized tier is what makes drop-in
compatibility work. What it no longer does is set your latency floor.

## Why fallback is always on

Drop-in compatibility is the load-bearing promise: clients must never break
because the marketplace is thin for a given model at a given moment. Centralized
fallback guarantees a request can always be served, so the marketplace can grow
density without stranding users.

The `X-Pod-Route` response header tells you which path served each request.

---

# Trust & reputation

Source: https://docs.usepod.ai/marketplace/trust/
Description: Bonds, reputation scoring, and benchmark canaries that keep the marketplace honest.

The marketplace earns trust through mechanisms layered on top of price discovery
rather than upfront gatekeeping. Three are in place today.

## Bonds

Every provider posts a **$50 USDC bond** at enrollment, held while they operate.
Serious misbehavior can trigger a manual ban with bond seizure; affected users
are credited from a refund pool, with the treasury as backstop. The bond is
released after a cooldown once a provider retires in good standing.

## Reputation

Providers accrue a **reputation score** from request outcomes (successes,
failures, latency). Scores feed the sorted indices the coordinator uses for
selection, so reliable providers are favored when prices are comparable. Stale
providers (no recent heartbeat) are marked offline and excluded.

## Benchmark canaries

A small fraction of marketplace traffic (about **1%**) is sampled as a hidden
canary: a known prompt is substituted and the response is scored for deviation
from the expected output. Runs that deviate beyond a threshold are flagged, and a
sustained flag rate triggers manual review. This catches providers that
misreport the model they serve.

## What's deferred

Stronger guarantees — TEE attestation, content-addressed model registries,
on-chain stake/slashing, and a privacy layer — are on the roadmap but
intentionally deferred until marketplace traction justifies their complexity.
Today's stack is tokenizer-side counts, reputation, bonds, and canaries.

---

# The provider agent

Source: https://docs.usepod.ai/providers/agent/
Description: How the standalone agent connects, advertises capabilities, and serves jobs from your local backend.

The provider agent (`usepod-agent`) is a small standalone binary that connects
your inference hardware to the UsePod coordinator. It is open source so
operators can audit exactly what they run.

## Supported backends

The agent discovers and dispatches to local OpenAI-compatible backends:

| Backend | Default port |
| --- | --- |
| vLLM | `8000` |
| llama.cpp server | `8080` |
| LM Studio | `1234` |
| Ollama | `11434` |

## Lifecycle

1. **Identity.** On first run the agent generates an Ed25519 keypair, persisted
   locally with `0600` permissions. This key is your provider identity.
2. **Connect.** The agent dials an **outbound** WebSocket to the coordinator
   (`wss://api.usepod.ai/provider/connect`). No inbound ports are required.
3. **Authenticate.** A signed challenge/response binds the connection to your
   provider record (enrolling on first connect via the enrollment code).
4. **Advertise.** The agent sends a `capabilities` message — your models, prices,
   max concurrency, and backend kind — which the coordinator records and marks
   you online.
5. **Serve.** The coordinator dispatches jobs; the agent calls your local
   backend and streams the response bytes back. Heartbeats keep your health and
   metrics fresh.

## Reconnection

If the connection drops — for example during a coordinator deploy — the agent
reconnects automatically with backoff and re-advertises its capabilities. A
clean coordinator shutdown sends a close frame so the agent treats it as a
planned cycle rather than an outage.

## Keeping current

Existing hosts do not update automatically. To upgrade:

```bash
usepod-agent upgrade
sudo systemctl restart usepod-agent   # or restart your process manager
usepod-agent version
```

---

# Earnings & cashout

Source: https://docs.usepod.ai/providers/earnings-and-cashout/
Description: How provider earnings accrue and how to withdraw USDC to a Solana wallet.

## How you earn

Every settled marketplace inference credits your provider balance with **80% of
the billed amount**; the remaining 20% goes to the treasury. Earnings accrue per
request as the accounting worker settles usage — debiting the user and crediting
you in the same transaction.

Users are billed at your listed price, which is capped at the cheapest
centralized price for the model. For key relays, your upstream bill is still
yours to pay — price accordingly.

## Cashing out

Withdraw to a Solana wallet on demand from the cashout flow at
[`usepod.ai/host`](https://usepod.ai/host):

1. Request a withdrawal of an amount up to your available balance (subject to a
   minimum and a daily cap).
2. The payout worker builds, signs, and broadcasts a USDC transfer from the ops
   wallet to your destination.
3. The withdrawal is tracked through `requested → broadcast → confirmed`. Large
   withdrawals may require manual approval.

## Your bond

A **$50 USDC bond** is posted at enrollment and held while you operate. It backs
your reputation and is released after a cooldown window once you retire. Serious
misbehavior can result in a manual ban and bond seizure, with affected users
credited from a refund pool.

See [Trust & reputation](/marketplace/trust/) for how provider standing is
tracked.

---

# Provider quickstart

Source: https://docs.usepod.ai/providers/quickstart/
Description: Install the agent, enroll, post a bond, and start earning USDC for served inference.

Run a GPU? Earn USDC by serving inference. Point the provider agent at a local
backend (vLLM, llama.cpp, LM Studio, Ollama) — or resell an upstream key you
already pay for — and set your resale prices.

1. **Install the agent.**

   ```bash
   curl https://usepod.ai/install.sh | sh
   ```

   On Windows: `irm https://usepod.ai/install.ps1 | iex`.

2. **Enroll.**

   ```bash
   usepod-agent enroll          # prints an enrollment code
   ```

   Paste the enrollment code at [`usepod.ai/host`](https://usepod.ai/host).

3. **Post a bond.**

   Send the displayed **$50 USDC** bond to the deposit address. The bond is held
   while you operate and released after a cooldown when you retire.

4. **Run.**

   ```bash
   usepod-agent run
   ```

   The agent opens an outbound WebSocket to the coordinator, advertises your
   models and prices, and starts receiving jobs.

You earn **80% of every settled inference**. Withdraw to a Solana wallet on
demand — see [Earnings & cashout](/providers/earnings-and-cashout/).

## Walk through it in the dashboard

The host area at [`usepod.ai/host`](https://usepod.ai/host) guides enrollment end
to end.

**Onboarding.** The Onboarding tab walks the four steps — install the agent, post
the bond, pair the machine, and prove it's live — each with the exact command to
run on your GPU box.

![Host onboarding stepper: install, bond, pair, live, with the install commands and a Continue to bond button.](/walkthroughs/host-onboarding.png)

**No inference server yet?** The **From scratch** tab gives you three commands to
install llama.cpp, download a model, and run the agent on a fresh GPU machine.

![The From-scratch tab: check hardware, install llama.cpp + a model + the agent, start the server, and pair.](/walkthroughs/host-start.png)

## Two ways to supply

- **Self-hosted backend.** The agent dispatches jobs to your local inference
  server. See [The provider agent](/providers/agent/).
- **Resell a key.** Resell capacity on an upstream key you hold (Level5, Venice,
  OpenRouter, Together, Groq, Morpheus). See [Resell your keys](/providers/resell-keys/).

---

# Resell your keys

Source: https://docs.usepod.ai/providers/resell-keys/
Description: Resell capacity on an upstream API key you already hold. How to price, how routing selects you, and exactly when your key earns.

Resell capacity on an upstream API key you already pay for. Instead of running a
GPU, you enroll a key and set resale prices; the UsePod gateway dispatches
matched requests directly to the upstream on your behalf and settles the
marketplace split to you. We call a listing like this a **key relay** (you may
have seen this pattern called BYOK, "bring your own key").

Enroll and price your catalog at [`usepod.ai/host`](https://usepod.ai/host). The
**BYOK** tab is one screen: pick the upstream, add your key, set a payout wallet
and an optional daily spend cap, then review the auto-priced model catalog before
enrolling.

![BYOK enrollment: pick an upstream, enter the operator key, payout wallet, and daily cap, then review the models-and-pricing table with a markdown multiplier.](/walkthroughs/host-byok.png)

## Supported upstreams

| Upstream | Notes |
| --- | --- |
| Level5 | Drop-in OpenAI/Claude/Venice-compatible billing proxy |
| Venice | Privacy-first reseller economics |
| Morpheus | OpenAI-compatible decentralized inference |
| OpenAI | Key relay for text and image models |
| OpenRouter | Aggregator across many providers |
| Together AI | Open-weight model hosting |
| Groq | Low-latency LPU inference |

## How to price

You set a resale price per model, as two numbers: price per million **input**
tokens and per million **output** tokens. Three rules govern what those numbers
can be and whether they earn.

### 1. You are capped at the cheapest centralized price

For any model UsePod also serves centrally, your listing can never *win* above
the cheapest centralized price, on **either** axis. At routing time the gateway
computes a ceiling of `min(user's price ceiling, cheapest centralized price)`
and filters out any listing above it. List above centralized on input *or*
output and you simply won't be selected, the request goes to the centralized
fallback instead. Price at or below centralized on both axes to be eligible.

### 2. The dashboard suggests a markdown off that ceiling

When you build your catalog at `usepod.ai/host`, each model's price is
pre-filled at a **20% markdown** off its base price, where the base is the
cheapest centralized price for that model if one exists, otherwise the
upstream's own list price. Adjust per model or apply a bulk markdown. A larger
markdown wins more traffic (you're cheaper) but thins your margin.

### 3. Your upstream bill is still yours

UsePod bills the *user* at your listed price and credits you the provider share.
It does **not** pay your upstream. Your margin is:

```
your 80% share  −  what your upstream charges you for those tokens
```

So price above your real upstream cost, not just below centralized. If your
upstream cost for a model is higher than 80% of the centralized price, that
model can't be profitable to relay, leave it out of your catalog.

### 4. Optional: a daily spend cap

You can set a **daily spend cap** (USDC) on a relay. Once your credited earnings
in the last 24 hours reach the cap, your listings drop out of routing until the
window rolls forward. This bounds how much upstream cost you can incur in a day,
useful when you're reselling a metered or rate-limited key.

## How routing selects you

A request reaches your relay only if it wins selection. The gateway:

1. **Normalizes the model id.** Matching is by *canonical* model id, so vendor
   prefixes are stripped (`deepseek/deepseek-v4` and `deepseek-v4` match the
   same listing). Your listing maps a canonical model (what users request) to
   your `provider_model_id` (what your upstream advertises). On dispatch the
   gateway rewrites the upstream request's `model` field to your
   `provider_model_id`, so it must be exactly what the upstream expects, or the
   call fails.
2. **Builds the candidate set.** All *enabled* listings for that canonical
   model, on *active* providers (bond posted; not suspended or banned), whose
   daily spend cap is not exhausted.
3. **Sorts cheapest first** by input + output price (ties broken by input price,
   then earliest enrollment).
4. **Filters each candidate in price order.** A key relay is eligible when it
   is not throttled, and its input and output prices are both at or below the
   ceiling from rule 1. Unlike self-hosted GPU providers, a key relay does
   **not** need a live connection and is **not** capacity-checked, your key is
   always considered available (subject to the daily cap).
5. **First survivor wins.** In `auto` routing the request falls through to the
   centralized fallback if no relay qualifies. In `marketplace-only` it returns
   `402 no_provider_at_price`.

The practical takeaway: **routing is lowest-price-wins among eligible listings.**
To win consistently for a model, be the cheapest eligible relay for it.

See [Routing & matching](/marketplace/routing/) for the full algorithm.

## When your key actually earns

You earn the provider share on a request only when **all** of these hold:

- Your provider is **active** (bond posted; not suspended or banned).
- You have an **enabled** listing whose canonical model matches the request, and
  whose `provider_model_id` matches what your upstream serves.
- Your input **and** output prices are at or below the cheapest centralized
  price, and at or below the user's price ceiling if they sent one.
- You are not throttled, and your daily spend cap is not reached.
- You are the **cheapest eligible** listing (you win the price sort).
- The upstream call **succeeds.** A failed dispatch earns nothing, the request
  fails over to the next candidate or to centralized, and no settlement is
  written.

If any one is false, that request earns you nothing. The most common reasons a
key sits idle are: priced above centralized (rule 1), undercut by a cheaper
relay, or the `provider_model_id` doesn't match the upstream.

### The split

On a successful request the user is billed `gross = tokens × your listed price`,
then split:

| Party | Share |
| --- | --- |
| You (provider) | 80% |
| Treasury | 20% |

Worked example, a listing at $0.40/M input and $0.60/M output serving a request
of 50,000 input + 20,000 output tokens:

```
gross    = 50,000 × $0.40/M + 20,000 × $0.60/M = $0.032
you (80%)                                       = $0.0256
treasury (20%)                                  = $0.0064
your net = $0.0256 − (your upstream cost for those tokens)
```

:::caution[Cache tokens are not billed on relays today]
Marketplace and key relay quotes currently carry only input and output rates, so
cache-read and cache-write tokens are billed at **0** on relay routes. Don't
price assuming cache-token revenue, and remember your upstream may still charge
you for them.
:::

Earnings accrue to your provider balance as requests settle. Withdraw on demand,
see [Earnings & cashout](/providers/earnings-and-cashout/).

---

# For agents

Source: https://docs.usepod.ai/resources/for-agents/
Description: Machine-readable access to these docs — raw Markdown per page, llms.txt, and the drop-in API.

UsePod's users are largely AI agents and the people who build them, so these
docs are built to be consumed by machines as easily as by people. Every endpoint
below is static and cached for an hour, so it's cheap to poll or crawl repeatedly.

## Raw Markdown for any page

Append `.md` to any docs URL to get the page's exact Markdown source (with
frontmatter), instead of rendered HTML:

```bash
curl https://docs.usepod.ai/using/quickstart.md
curl https://docs.usepod.ai/api/proxy.md
```

Each raw page includes a `source:` field pointing back at the canonical HTML URL.

## llms.txt — the index

A machine-readable index of the whole corpus, following the
[llms.txt](https://llmstxt.org) convention:

```bash
curl https://docs.usepod.ai/llms.txt
```

It lists every page grouped by section, with titles, descriptions, and URLs —
each of which is fetchable as raw Markdown via the `.md` suffix above.

## llms-full.txt — the full corpus

Want everything in one request? The entire docs corpus, concatenated as
Markdown:

```bash
curl https://docs.usepod.ai/llms-full.txt
```

## pages.json — the manifest

A structured JSON manifest of every page — `slug`, `title`, `description`,
canonical `url`, and the raw `markdown` URL — for programmatic crawling:

```bash
curl https://docs.usepod.ai/api/pages.json
```

```json
{
  "site": "UsePod Docs",
  "url": "https://docs.usepod.ai",
  "page_count": 15,
  "llms_index": "https://docs.usepod.ai/llms.txt",
  "llms_full": "https://docs.usepod.ai/llms-full.txt",
  "pages": [
    {
      "slug": "using/quickstart",
      "title": "Quickstart",
      "url": "https://docs.usepod.ai/using/quickstart/",
      "markdown": "https://docs.usepod.ai/using/quickstart.md"
    }
  ]
}
```

## Agent skills

Two ready-to-run onboarding skills live on the main site, in Claude Code
`SKILL.md` format. Point an agent at the relevant one to drive the whole flow
end to end:

- **[client-onboard](https://usepod.ai/skill/client-onboard/SKILL.md)** (demand
  side): register an API token, fund it with USDC, poll until it activates, and
  emit a connection snippet for the user's inference client (Claude, Cursor, the
  OpenAI SDK, LangChain, and more).
- **[host-onboard](https://usepod.ai/skill/host-onboard/SKILL.md)** (supply
  side): install `usepod-agent` on a GPU host, pair it with the marketplace,
  post the $50 USDC bond, run it under systemd, and handle health and upgrades.

## The product itself is drop-in

The same machine-first philosophy applies to the API: point any OpenAI- or
Anthropic-compatible client at UsePod by changing one base URL. No SDK changes,
no auth changes.

```bash
ANTHROPIC_BASE_URL=https://api.usepod.ai/proxy/<token> claude
OPENAI_BASE_URL=https://api.usepod.ai/proxy/<token>/v1 cursor
```

See the [Quickstart](/using/quickstart/) to get a token.

---

# Drop-in API

Source: https://docs.usepod.ai/using/drop-in-api/
Description: UsePod is a base-URL swap for any OpenAI- or Anthropic-compatible client.

UsePod's load-bearing promise is **drop-in compatibility**: you change one base
URL and nothing else. Your token lives in the URL path; your existing API calls,
SDKs, and tools work unchanged.

## Base URLs

| Client family | Base URL |
| --- | --- |
| Anthropic-compatible | `https://api.usepod.ai/proxy/<token>` |
| OpenAI-compatible | `https://api.usepod.ai/proxy/<token>/v1` |

The proxy path mirrors the upstream API surface, so `…/v1/chat/completions`,
`…/v1/messages`, `…/v1/models`, `…/v1/responses`, and streaming all behave as
the underlying provider does.

## Examples

```bash title="Claude Code"
ANTHROPIC_BASE_URL=https://api.usepod.ai/proxy/<token> claude
```

```bash title="Cursor / OpenAI SDK"
OPENAI_BASE_URL=https://api.usepod.ai/proxy/<token>/v1 cursor
```

```python title="OpenAI Python SDK"
from openai import OpenAI

client = OpenAI(
    base_url="https://api.usepod.ai/proxy/<token>/v1",
    api_key="unused",  # auth is the token in the base URL
)

resp = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "hello"}],
)
print(resp.choices[0].message.content)
```

```toml title="Codex CLI (~/.codex/config.toml)"
model = "deepseek-v4-1-flash"
model_provider = "usepod"

[model_providers.usepod]
name = "UsePod"
base_url = "https://api.usepod.ai/proxy/<token>/v1"
wire_api = "responses"
```

Codex CLI only speaks the OpenAI Responses API and ignores `OPENAI_API_KEY` /
`OPENAI_BASE_URL`, so it needs this config file rather than the environment
variables above. No API key is required — the token in the URL authenticates.
Run `codex` after saving the file; any UsePod model id works as `model`. The
Responses endpoint is stateless (`previous_response_id` is rejected — Codex
resends history by default) and ignores hosted tools such as `web_search`;
streaming and tool calls both work.

## Response headers

Every proxied response includes:

- `X-Balance-Remaining` — your token's remaining balance after this request.
- `X-Pod-Route` — which path served the request (marketplace, key relay, or
  centralized fallback).

## Notes

- The `api_key` your SDK requires is ignored — authentication is the token in the
  base URL. Use any placeholder.
- Want to bound cost per request? See [Spend controls](/using/spend-controls/).

---

# Funding your balance

Source: https://docs.usepod.ai/using/funding/
Description: Top up a token by card or by sending USDC on Solana.

A token carries a USDC-denominated balance. Each request is debited from it. You
can fund a token two ways.

## Card top-up

Open [`usepod.ai/fund`](https://usepod.ai/fund), choose **Card**, and pay with
an embedded Stripe Checkout. Card credits enter the same balance ledger as USDC
deposits. A small processing surcharge is added on top of the credit you choose.

## USDC deposit (Solana)

The dashboard at [`usepod.ai/fund`](https://usepod.ai/fund) handles this end
to end — connect a wallet, choose USDC, approve. Behind the scenes it sends
a `DepositUsdc` instruction to the sovereign program with your token's
`deposit_code` embedded, and the LiquidMirror credits your balance within
seconds of finalization.

To deposit from a script or a wallet that signs custom transactions, build
the instruction yourself — see [Deposit on-chain](/api/deposit-on-chain/)
for the full spec and ready-to-paste JS + Python snippets. **A plain SPL
USDC transfer with a memo will NOT be credited** — the binding to your
token lives inside the instruction data, not in a separate memo.

## No account: pay per request

If you'd rather not hold a balance at all, [x402](/api/x402-payments/) lets you
pay for each request individually by sending USDC or SOL on Solana — no token, no
top-up. It suits agents and one-off automated callers with a Solana wallet.

## Checking your balance

Every proxied response carries an `X-Balance-Remaining` header. You can also see
balance and transaction history in the dashboard at
[`usepod.ai/dashboard`](https://usepod.ai/dashboard).

## Notes

- Balance is debited per request based on actual token usage at the selected
  provider's price.
- Spending is gated on a positive balance; a token with a zero balance is
  rejected before any upstream call.
- To bound per-request cost, use [Spend controls](/using/spend-controls/).

---

# Quickstart

Source: https://docs.usepod.ai/using/quickstart/
Description: Get a token, fund it, and point your client at UsePod in under a minute.

Add UsePod as the base URL of any OpenAI- or Anthropic-compatible client. No SDK
changes, no auth changes.

1. **Get a token and deposit address.**

   ```bash
   curl -X POST https://api.usepod.ai/v1/register
   ```

   The response includes your `<token>` and a USDC deposit address.

2. **Fund your balance.**

   Top up by card at [`usepod.ai/fund`](https://usepod.ai/fund) or send USDC to
   the deposit address. See [Funding your balance](/using/funding/).

3. **Point your client at UsePod.**

   ```bash
   # Anthropic-compatible (e.g. Claude Code)
   ANTHROPIC_BASE_URL=https://api.usepod.ai/proxy/<token> claude

   # OpenAI-compatible (e.g. Cursor or the OpenAI SDK)
   OPENAI_BASE_URL=https://api.usepod.ai/proxy/<token>/v1 cursor
   ```

4. **Send requests as usual.**

   Your existing code is unchanged. Each request is debited from your balance,
   and responses carry an `X-Balance-Remaining` header.

## Walk through it in the dashboard

Prefer a UI to the API? The dashboard does the same three steps — register, fund,
connect — and hands you copy-paste client config.

**Your dashboard.** After you register, the dashboard shows your API token, a
ready-to-paste config for Claude Code / Codex / OpenAI / Cursor, your balance,
and recent activity. Save the bookmark URL it gives you to return later.

![The UsePod dashboard showing the API token, agent-connect snippets, balance chart, and activity feed.](/walkthroughs/dashboard.png)

**Add funds.** Open **Fund** and choose how to pay — card (Stripe), USDC on
Solana, or SOL swapped via Jupiter. Your dollar amount becomes a USDC balance
that each request draws down.

![The Fund page: pay by card, USDC on Solana, or SOL; preset amounts and a fee breakdown.](/walkthroughs/fund.png)

**Browse models and prices.** The Marketplace lists every model with its best
per-million input/output price, how many providers are online, and the
centralized fallback price.

![The Marketplace leaderboard: per-model best input/output prices, provider counts, and centralized fallback.](/walkthroughs/marketplace.png)

## Next steps

- [Drop-in API](/using/drop-in-api/) — exact base URLs and supported clients.
- [Spend controls](/using/spend-controls/) — cap the price you'll pay per model.
- [Funding your balance](/using/funding/) — card and USDC top-ups.

---

# Spend controls

Source: https://docs.usepod.ai/using/spend-controls/
Description: Cap the price you'll pay per million tokens with per-request headers.

You can bound the price you're willing to pay on a per-request basis with two
optional headers. If no provider (marketplace, key relay, or centralized) can serve
the request at or below your ceiling, the request is rejected rather than billed
at a higher price.

## Price-ceiling headers

| Header | Meaning |
| --- | --- |
| `X-Pod-Max-Price-Input` | Max price per **million input tokens**, in USDC microunits |
| `X-Pod-Max-Price-Output` | Max price per **million output tokens**, in USDC microunits |

Prices are expressed in **USDC microunits** (1 USDC = 1,000,000 microunits).

```bash title="Cap at $0.40/M input and $0.60/M output"
curl https://api.usepod.ai/proxy/<token>/v1/chat/completions \
  -H "content-type: application/json" \
  -H "X-Pod-Max-Price-Input: 400000" \
  -H "X-Pod-Max-Price-Output: 600000" \
  -d '{"model":"gpt-5.5","messages":[{"role":"user","content":"hi"}]}'
```

## How ceilings interact with routing

- A candidate is eligible only if **both** its input and output prices are at or
  below your ceilings.
- Marketplace and key relay prices are already capped at the cheapest centralized
  price for the model, so your ceiling filters within that capped set.
- In `auto` routing, a too-expensive marketplace listing simply falls through to
  a cheaper option (or to centralized). In marketplace-only routing, it returns a
  no-provider-at-price result instead of overcharging.

See [Routing & matching](/marketplace/routing/) for the full selection order.

## Controlling *who* serves you, not just the price

A price ceiling constrains what a request may cost, not which provider fills it.
If you need the second — a fixed set of providers so your latency and throughput
stay put between deploys — pin the request with `X-Pod-Providers`:

```bash title="Only Venice, whatever the price"
curl https://api.usepod.ai/proxy/<token>/v1/chat/completions \
  -H "content-type: application/json" \
  -H "X-Pod-Providers: venice" \
  -d '{"model":"gpt-5.5","messages":[{"role":"user","content":"hi"}]}'
```

The two compose: a pin narrows the candidate set, and a ceiling still caps what
any of them may charge. See [Pinning specific
providers](/marketplace/routing/#pinning-specific-providers).

---

# Verification is the product

Source: https://docs.usepod.ai/vision/verification/
Description: Once you can cryptographically verify which model ran on which hardware, compute stops being a service and becomes a tradable commodity — with a futures market on top.

:::note[Adapted from an essay]
Adapted from a piece originally published on X by [@0xgilbert](https://x.com/0xgilbert/status/2055997978473574591), 2026-05-17. Lightly edited for the docs.
:::

:::caution[Vision, not shipped]
This page describes where UsePod is headed, not what it does today. Hardware
attestation and compute futures are roadmap items. For the trust mechanisms that
are live now (reputation, benchmark canaries, bonds), see
[Trust & reputation](/marketplace/trust/).
:::

## The inference black box

When you send a prompt to a frontier model, you're trusting the provider on three
things you can't check: that you're actually talking to the model you asked for,
that its quantization and weights haven't changed since last month, and that the
hardware running your request matches the performance you built your workflow
around.

The API responds, you get tokens, you pay the bill — but the whole transaction
happens inside a box you can't inspect or audit. When stakes are low, trust works
fine. As workloads move from "write a blog post" to "execute a trading strategy"
or "process protected health information," trust stops being enough.

## You're not buying a model — you're buying compute

When you request inference, you're implicitly buying access to specific hardware,
for a specific duration, at a specific performance level. Build a workflow
assuming sub-200ms p99 because you tested on current-gen GPUs, and if a provider
quietly shifts you to older hardware at peak, your application degrades — with no
recourse, because you have no proof it happened.

Extend that to training: you're not buying "run this model," you're buying "give
me 8 of this GPU in this region for a week." The gap between getting exactly that
and getting something slower elsewhere is the difference between a run that
converges on schedule and one that blows its budget.

## Attestation unlocks a compute market

Once you can cryptographically verify that you received specific hardware, in a
specific location, for a specific duration, at a specific performance level,
compute stops being a service and starts being a commodity. And commodities have
futures markets.

If you know you'll need a block of GPU-hours next quarter, why not lock in that
capacity today at today's price? If delivery can be *proven* through attestation,
compute becomes as tradable as oil, wheat, or treasury bonds. Datacenters benefit
symmetrically: they carry utilization risk, and selling futures against capacity
lets them lock in guaranteed buyers and fund the next buildout with future
revenue.

## Liquid compute futures

In a verifiable market, a dated block of regional GPU capacity becomes a tradable
instrument. You don't bid on bespoke requests — you buy standardized contracts:
fixed units (GPU-hours), fixed regions, fixed delivery windows, fixed attestation
requirements. The contract trades on an exchange, market makers provide
liquidity, and if your schedule slips you sell it on. Capacity stops being a
procurement problem and becomes a position you manage.

## Why standardization matters

Bespoke contracts don't scale — every negotiation is custom, there's no benchmark
price, no liquidity, no way to hedge. Standardized contracts are fungible: your
June capacity is identical to mine, so we can trade. Once contracts are fungible,
derivatives emerge — options on capacity, spreads between regions, volatility
indices. Deep markets let you move size without moving price.

## Settlement is the unlock

Commodity futures only work if settlement is instant, trustless, and cheap.
Traditional clearinghouses add cost, delay, and counterparty risk. Verifiable
compute doesn't need one: attestation proves delivery, a smart contract verifies
the proof, and payment releases atomically on-chain. You submit a report proving
you delivered the contracted capacity; the contract checks the signature,
hardware proof, location, and timing; payment settles — no intermediary, no
multi-day hold.

Standardized contracts, verifiable delivery, and atomic settlement together turn
compute into a liquid commodity that clears like crude oil or wheat — but settles
faster than a card transaction.

---