# UsePod — full content

> UsePod docs — the full Markdown corpus, concatenated. 21 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 |

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

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.

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

## 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, verified directly on-chain. No token, no API key.

Most of Use Pod 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 native SOL) on Solana, and the gateway verifies the payment
**directly on-chain** before serving the call. There is no facilitator and no
intermediary holding your funds.

It is a good fit for agents and one-off automated callers that have a Solana
wallet but no Use Pod 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 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>"
}
```

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

- **Direct on-chain.** The gateway verifies your payment by reading the
  transaction from Solana (it never broadcasts on your behalf). For USDC it
  checks the token-balance delta into `pay_to`; for SOL, the native-balance
  delta. The payment must credit at least the quoted amount.
- **Solana only.** USDC and native SOL on Solana mainnet are supported today.
- **Replay-protected.** A given transaction signature can settle exactly one
  quote. Reusing it for a second quote is rejected.
- **Fees.** 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.

## 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 Use Pod 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/).

---

# 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

- **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.

## 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`, 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)
```

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

---

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

---