Balance and payment fallback
Each account has one USD balance that every key draws on. Anyone can top it up with USDC through a standard 402 exchange, with no Lasso credential. If an account that has paid runs out, its app keeps serving on public providers for 30 days while you top up. Any of the account’s RPC keys reads it:Where premium requests are paid from
For a request onpremium, Lasso takes the first source that applies:
An account that has never paid has only its starting balance: once it’s spent,
requests return
balance_exhausted until someone tops it up.
Your app keeps serving when the balance runs out
Say your indexer’s balance hits zero at 3 a.m. Its requests keep succeeding, now on public providers,load-balanced, at 30 RPS:
fallback.until. Open
WebSocket subscriptions keep streaming. Top up, and the next request is served
by premium providers again, with no reconnect and no redeploy. Watch for
x-lasso-fallback: payment to catch this in your app.
Accounting never interrupts serving: if recording usage is delayed, requests
keep their route and price.
Top up
Credit the account by itsid from the account view above. Lasso answers 402;
its offer.rails lists the rails that accept this amount, each with a
challenge: x402 in PAYMENT-REQUIRED, MPP in WWW-Authenticate: Payment.
- Sign one challenge with a standard x402 or MPP client and the payer’s wallet.
- Repeat the same request with
PAYMENT-SIGNATURE(x402) orAuthorization: Payment(MPP). 200confirms the credit withcredited_usd,balance_usdand a receipt.202means settlement is pending: poll itsstatus_url, and never sign a second payment for the same top-up.
@x402/fetch, the whole
exchange is one call. Run it as an ES module with @x402/fetch, @x402/evm
and viem installed, a funded Base USDC wallet in PAYER_PRIVATE_KEY, and
the account in LASSO_ACCOUNT_ID:
mppx does the same over MPP on
Tempo. Resubmitting the same signed payment returns its result and never
credits twice. Rails, networks, assets and the per-purchase range are in
account_payments.rails in agent.json.
People can also add balance or subscribe in the dashboard.
Buy a funded key
UsePOST /api/v1/credit when you want a new account, its first key and paid
balance together. It needs no account ID or Lasso credential:
200 confirms the credit, and 202 returns a status_url to poll.
The paid response returns key.rpc_url_template, key.ws_url_template, key.key,
key.management_token and key.account_id; save them privately. If the
response is lost, replay the same signed payment: it returns the same
credentials and credits once. Credentials revoked or rotated since aren’t
returned again.
Use the account credit route for every later top-up; a new funded-key payment
creates a different account. Funded-key purchases share the 10-per-hour,
per-IP creation limit with POST /api/v1/keys.
Watching spend
Limits
- The grace window lasts 30 days from when paid spending power runs out, and restarts every time the account pays.
- Payment fallback serves public providers at the public rate limit
(30 RPS, bursts to 60) with
load-balancedonly. - Charges settle to the account within about a minute, so
x-lasso-balance-usdis an estimate and a busy account can dip a few cents below zero; the next top-up repays it first.GET /api/v1/accounts/{id}is authoritative. - When the grace window ends without a top-up, requests answer 402
balance_exhaustedand open WebSocket connections close. - No Lasso credential can pay. Every purchase needs a wallet signature.
Next
- Serving access and pricing: what each request costs.
- Accounts, people and agents: who owns the balance and who can top it up.
- Set up production RPC with an agent: fund once, then hand off.