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 your account has paid before and the money runs out, your app keeps serving on public providers for 30 days while you top up.

curl -sS https://lasso.sh/api/v1/accounts/current \
  -H "authorization: Bearer $LASSO_MANAGEMENT_TOKEN" \
  | jq '{balance_usd, managed_access, fallback, included_usage}'

Where premium requests are paid from

For a request on premium, Lasso takes the first source that applies:

Your account	Served from	Charged
Included usage from a subscription remains this month	Premium providers	From included usage
The balance covers the request	Premium providers	From the balance
The money ran out less than 30 days ago (the window restarts whenever the account pays), and the account has paid before	Public providers, `x-lasso-fallback: payment`	No
A person sponsors the account, and its free allowance remains this month	Public providers, `x-lasso-fallback: free`	No; counts against the allowance
None of the above	Not served: 402 `balance_exhausted`, naming the credit URL	No

A provisional account that has never paid has only its starting grant: 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:

HTTP/1.1 200 OK
x-lasso-access: public
x-lasso-fallback: payment
x-lasso-usd: 0

The account view shows when the grace window ends in fallback.until. Open WebSocket subscriptions keep streaming from the upstreams they’re on. Top up, and the next request is served by premium providers again, with no reconnect and no redeploy.

Top up

Credit the account. 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.

POST https://lasso.sh/api/v1/accounts/{account_id}/credit
Content-Type: application/json

{"usd":"1"}

Sign one challenge with a standard x402 or MPP client and the payer’s wallet.
Repeat the same request with PAYMENT-SIGNATURE (x402) or Authorization: Payment (MPP).
200 returns 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:

import { wrapFetchWithPaymentFromConfig } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm";
import { privateKeyToAccount } from "viem/accounts";

const payer = privateKeyToAccount(process.env.PAYER_PRIVATE_KEY as `0x${string}`);
const payingFetch = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: [{ network: "eip155:8453", client: new ExactEvmScheme(payer) }],
});

const response = await payingFetch(
  `https://lasso.sh/api/v1/accounts/${process.env.LASSO_ACCOUNT_ID}/credit`,
  { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ usd: "1" }) },
);
console.log(response.status, await response.json());

mppx does the same over MPP on Tempo. Resubmitting the same signed payment returns that payment’s result and never credits twice. Rails, networks, assets and the per-purchase range (minimum_usd to maximum_usd) are in account_payments.rails in agent.json. People can also subscribe in the dashboard.

Watching spend

Signal	What it tells you
`x-lasso-usd`	This request’s charge; `0` when included usage, free access, Custom access or payment fallback covered it
`x-lasso-balance-usd`	An estimate of the balance after this charge
`x-lasso-access`	`premium`, `public` or `custom`
`x-lasso-fallback`	Why a request was served somewhere other than the profile it named
`GET /api/v1/accounts/{id}`	The authoritative balance, subscriptions, included usage, access and grace window

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.
x-lasso-balance-usd is an estimate at the region that served you; GET /api/v1/accounts/{id} is authoritative. Concurrent traffic can take a balance slightly below zero; the next top-up repays it first.
When the grace window ends without a top-up, open WebSocket connections close with balance_exhausted and the credit URL.
The management token can’t pay. Every purchase needs a wallet signature.

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.

Start here

Concepts

Guides

Reference

Balance and payment fallback

Balance and payment fallback

Where premium requests are paid from

Your app keeps serving when the balance runs out

Top up

Watching spend

Limits

Next

​Balance and payment fallback

​Where premium requests are paid from

​Your app keeps serving when the balance runs out

​Top up

​Watching spend

​Limits

​Next

Balance and payment fallback

Where premium requests are paid from

Your app keeps serving when the balance runs out

Top up

Watching spend

Limits

Next