Pay per query - Shumi Docs

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

{
  "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.

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

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

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

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

​What happens

​Prices

​From the CLI

​Unattended

​Why the login wallet is not the paying wallet

What happens

Prices

From the CLI

Unattended

Why the login wallet is not the paying wallet