> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shumi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Pay per query

> Agents can pay for a single request in USDC on Base, with no account, using the x402 protocol.

An agent without a subscription can pay for one request and get one answer. No sign-up, no card, no
plan — the payment rides on the HTTP request itself, using [x402](https://x402.org).

This is the path for software that needs an answer now and cannot pause to have a human create an
account.

## What happens

Run out of free queries and the API answers `402` instead of `429`, with what it wants:

```json theme={"dark"}
{
  "x402Version": 1,
  "accepts": [{
    "scheme": "exact",
    "network": "base",
    "maxAmountRequired": "5000",
    "resource": "https://api.shumi.ai/api/cli/coin/risk/DOGE",
    "payTo": "0xc624d24d17CF22ece0487101eD58B1d4742bb394",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "maxTimeoutSeconds": 60,
    "extra": { "name": "USD Coin", "version": "2" }
  }]
}
```

The client signs an EIP-3009 `transferWithAuthorization` for that amount and repeats the request
with an `X-PAYMENT` header. The server verifies the signature, runs the query, and only then
settles on-chain — so a failed request is not charged.

`maxAmountRequired` is in atomic units: USDC has six decimals, so `5000` is **\$0.005**.

<Note>
  The signature is not a transaction. A facilitator submits it and pays the gas, so the paying wallet
  needs USDC and no ETH.
</Note>

## Prices

| Route                                                                        | Price                |
| ---------------------------------------------------------------------------- | -------------------- |
| Typed lookups — `coin/*`, `market/*`, `category/*`, `funding/*`, `regime`, … | **\$0.005**          |
| `ask` (natural language)                                                     | **\$0.05**           |
| `pairs`, `walkforward`, `backtest`                                           | **\$0.05**           |
| `watch/*` (streaming)                                                        | not payable per call |

Streaming is excluded on purpose rather than by omission: settling every tick would cost more in
fees than the tick is worth. It needs a subscription.

Free accounts get **10 queries**, then one per day. Payment only enters the picture once that is
spent — check with `GET /api/cli/billing/tier`.

## From the CLI

```bash theme={"dark"}
npm i -g shumi
shumi wallet create        # a local signing wallet, encrypted with a passphrase
shumi wallet address       # fund this with USDC on Base
shumi coin risk DOGE       # once free queries are gone, it offers to pay
```

```
💸 Shumi needs $0.005 USDC on base to run `shumi coin risk DOGE`.
   From  0xD1C8…6f99 (balance $0.5)
   To    0xc624…b394
   Pay? [Y/n]
```

The recipient is shown before you sign, on purpose: if a compromised server ever redirected payment
elsewhere, the address is where you would see it.

### Unattended

```bash theme={"dark"}
export SHUMI_X402_PRIVATE_KEY=0x…     # a small hot wallet, funded with USDC on Base
shumi coin risk DOGE --auto-pay        # no prompt
```

`--agent` implies `--auto-pay`. Two guards worth knowing: `SHUMI_MAX_PRICE_USDC` refuses anything
above a ceiling, and the wallet only ever holds what you put in it.

## Why the login wallet is not the paying wallet

Signing has to happen in the process making the request, and a wallet you signed in with — Trust,
MetaMask, a phone app — keeps its key where the CLI cannot reach it. So `shumi login` establishes
*who you are*, and `shumi wallet` is *what pays*. They are deliberately separate.

For an agent this is the useful shape: the paying wallet is a small, funded key it holds, with no
human in the loop and no bearing on identity.