Pay-as-you-go
A plan has a cap. Pay-as-you-go decides what happens when you reach it: stop, or keep going and pay per unit.
It is off by default. A service that silently kept spending your money past the limit you chose would be making a decision that is yours to make.
Turning it on
setPayg(enabled, budget, auto_topup, max_payg_price)
| Argument | What it does |
|---|---|
enabled | Whether relays continue past the cap. |
budget | How much, in micro-USDC, to hold in escrow for this. |
auto_topup | Whether to refill the escrow back to budget at the start of each period. |
max_payg_price | A ceiling on the price per Relay Unit. 0 means no ceiling. |
All four are set in one on-chain call, and the dashboard builds it for you under Settings.
POST /v1/flags/prepare builds the same transaction for a programmatic client.
What a unit costs
The pay-as-you-go price is derived from the same single lever as everything else:
payg_price(tier) = tariff × payg_bps / 10,000
Each tier carries its own payg_bps, and every one of them is above 10,000 — so a unit past the
cap always costs more than a unit inside it. That is the intended shape: buying the right size is
cheaper than overflowing a small plan.
At the launch configuration (tariff 10,000 micro-USDC per unit, snapshot of 2026-09-19):
| Tier | Inside the cap | Past the cap | Difference |
|---|---|---|---|
| Starter | $0.0100 | $0.0130 | +30% |
| Builder | $0.0090 | $0.0125 | +39% |
| Growth | $0.0080 | $0.0120 | +50% |
| Agent Pro | $0.0085 | $0.0120 | +41% |
| Agent Metered | — (no cap) | $0.0150 | metered only |
Live values: GET /v1/pricing, or getPaygPrice(tier) on the contract.
The escrow
Pay-as-you-go spends from an escrow, not from your credits directly. The escrow is a bounded amount you put aside for this purpose, and it has one useful property: it is the maximum. Whatever happens — a runaway loop in your own code, a busier month than expected — pay-as-you-go cannot spend past it.
When the escrow is empty, relays stop with QUOTA_EXHAUSTED and
details.reason = PAYG_ESCROW_EMPTY. What the escrow did not spend returns to your credits —
not to your wallet — once you turn pay-as-you-go off; lowering the budget never releases any of it.
(Credits and billing)
With auto_topup on, the escrow is refilled to the budget from your credits only at the start of
a period, after the plan itself has been paid. So for a plan, the budget is a true per-period
ceiling on pay-as-you-go spend.
The price ceiling
max_payg_price matters for accounts whose pay-as-you-go price moves: on
Agent Metered, the price per unit follows the current tariff. (On a plan tier
it cannot move — the pay-as-you-go price is frozen in the plan block you bought.) A metered account
with no ceiling would simply follow the tariff; 0 means exactly that.
With a ceiling set, the service stops serving pay-as-you-go for the account as soon as the effective
price is above it, and answers PAYG_PRICE_ABOVE_MAX; the contract
independently refuses to settle a line priced above it. A tariff increase carries 48 hours of
notice, and the notice is delivered — banner, GET /v1/account/{erd}/notices, GET /v1/stream —
so the ceiling is a backstop rather than a surprise. (Tariff)
Behaviour at the cap
| Pay-as-you-go | At the cap |
|---|---|
| Off | Relays stop. QUOTA_EXHAUSTED with details.reason = CAP_REACHED_PAYG_OFF, a 429 with no Retry-After — because waiting genuinely does not help. The error carries the pricing URL and the x402 URL, so a client knows where to go. |
| On, escrow funded | Relays continue, billed per unit at the pay-as-you-go price. |
| On, escrow empty | Relays stop. QUOTA_EXHAUSTED with details.reason = PAYG_ESCROW_EMPTY. |
| On, a floating price above your ceiling | Relays stop. PAYG_PRICE_ABOVE_MAX, until the price is back under the ceiling or you raise it. |
Rate limits are separate and always apply: a plan with pay-as-you-go on is not a plan without a
rate class. RATE_LIMITED is a different answer from
QUOTA_EXHAUSTED, and it does carry a Retry-After, because in that case waiting is exactly the
right thing to do. (Limits)
When it is the right choice
- Spiky traffic. Buy the tier that matches your normal month and let the peaks be metered. Cheaper than permanently paying for headroom you use twice a year.
- An unknown starting volume. Start small, watch
GET /v1/usage/summaryfor a month, then buy the tier the data points at. - Never running out. If a stopped relay is worse for you than an unexpected invoice, turn it on and set a budget you can live with.
When it is not
- A tight, known budget. Leave it off. The cap becomes a hard limit you cannot exceed.
- Sustained volume above the cap. Moving up a tier is cheaper per unit than metering; the table above is the whole argument.