Skip to main content

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 on premium, 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:
The account view shows when the grace window ends in 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 its id 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.
  1. Sign one challenge with a standard x402 or MPP client and the payer’s wallet.
  2. Repeat the same request with PAYMENT-SIGNATURE (x402) or Authorization: Payment (MPP).
  3. 200 confirms the credit with credited_usd, balance_usd and a receipt. 202 means settlement is pending: poll its status_url, and never sign a second payment for the same top-up.
With @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

Use POST /api/v1/credit when you want a new account, its first key and paid balance together. It needs no account ID or Lasso credential:
With no body, it quotes the smallest amount every enabled rail accepts. The 402 creates nothing. Sign one offered challenge with the wallet your user authorized, then repeat the same request. Settlement works like a top-up: 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-balanced only.
  • Charges settle to the account within about a minute, so x-lasso-balance-usd is 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_exhausted and open WebSocket connections close.
  • No Lasso credential can pay. Every purchase needs a wallet signature.

Next