## Balance System Overview

ModelStack bills every request pay-as-you-go from your wallet balance.

## Your Wallet

Your wallet has two balances:

### Bonus Balance

- Granted from referrals and promotions
- Expires 30 days after being granted
- Can pay for **Economy or Standard** tier requests (never Premium)

### Prepaid Balance

- Purchased top-ups
- Expires 12 months after purchase
- Can pay for **Economy, Standard, or Premium** tier requests

For Economy- and Standard-tier requests, bonus balance is spent first; once it's exhausted, prepaid balance covers the rest. Premium-tier requests always draw from prepaid balance only — bonus balance can never pay for Premium, even if you have plenty of it.

## How a Request Is Priced

This is the part that changed with Economy's return: the rate no longer depends on tier alone — it depends on **tier and which wallet pays**. Bonus and prepaid each have their own rate table:

| Tier         | Bonus Wallet Rate           | Prepaid Wallet Rate          |
| ------------ | ----------------------------- | ------------------------------ |
| **Economy**  | 1.0x (no discount)            | 0.2x by default (80% off)      |
| **Standard** | 1.5x (50% markup)             | 0.5x by default (50% off)      |
| **Premium**  | Not eligible                  | 1.0x (no discount)             |

<Info>
  Standard's default 0.5x prepaid rate can be lower for some model families —
  Anthropic defaults to 0.35x, OpenAI to 0.2x — and two models (`gpt-5.4`,
  `gpt-5.6-terra`) are pinned to 0.2x regardless of family. These overrides
  only ever apply to the prepaid rate; bonus rates and Premium never have an
  override — Premium is always exactly 1.0x.
</Info>

### A Single Request Can Split Across Both Wallets

Because bonus and prepaid rate a tier differently, an Economy or Standard request can be billed partly from each wallet, at each wallet's own rate. Bonus covers as much of the raw provider cost as your available bonus balance can afford at bonus's rate; prepaid covers whatever raw cost is left over, at prepaid's rate. The total charge — and the "discount rate" your dashboard shows for that transaction — is a blended figure, not one of the two table values above.

**Example — Standard tier, $100 raw provider cost, $30 available bonus balance, prepaid funded:**

- Bonus affords $30 ÷ 1.5x = $20 of raw cost, and is charged $30 for it.
- Prepaid covers the remaining $80 of raw cost at 0.5x = $40.
- **Total charged: $70** — a blended 0.7x effective rate.

Without any bonus balance, the same $100 request would simply cost $50 on prepaid (0.5x, no blending).

<Info>
  If your prepaid balance has never been funded (at or below $0), an Economy
  or Standard request is billed **entirely from bonus**, at bonus's rate —
  including the portion that would normally fall to prepaid. This keeps an
  unfunded free account from ever accidentally incurring real-money debt.
</Info>

## Insufficient Balance

If your eligible wallet balance can't cover a request:

- The request is rejected with a **`402 Payment Required`** (`insufficient_balance`) error.
- Premium requests are also rejected up front if your prepaid balance is at or below $0 — regardless of how much bonus balance you have.

Your wallet is allowed to go up to **$0.50 negative** briefly. Settlement happens after a response has already streamed, so the final charge can be slightly higher than what was checked before the request started; this small overdraft window absorbs that difference rather than failing to bill for usage you already received. Once your wallet is at or below $0, further requests are blocked until you top up.

<Warning>
  Slight overdraft (up to $0.50) after a streamed response is expected
  behavior, not a billing bug.
</Warning>

## Purchasing Prepaid Balance

Available amounts: $10, $25, $50, $100, $250, $500

Purchase from your [Dashboard](https://modelstack.cc/dashboard/billing).

**Key Features:**

- Expires 12 months after purchase
- Can pay for Economy, Standard, or Premium requests
- Works without a subscription

## Checking Your Balance

View your wallet status in the [Dashboard](https://modelstack.cc/dashboard/billing):

### Wallet Balance

- Current bonus balance and its expiration
- Current prepaid balance and its expiration
- Recent transactions

## Best Practices

### Manage Your Wallet

1. **Keep a prepaid balance buffer** — Premium requests always need it, and Economy/Standard need it once bonus balance runs out.
2. **Top up in larger amounts** to reduce how often you need to purchase.
3. **Watch bonus balance expiration** (30 days) — spend it on Economy- or Standard-tier requests before it expires. Remember bonus is a markup (1.5x) on Standard, so it's most efficient spent on Economy (1.0x, no markup).

### Avoid Surprises

1. A **`402`** error means your wallet balance is insufficient — top up to continue.
2. Remember Premium always needs **prepaid** balance specifically, even if your bonus balance is healthy.
3. Check your dashboard before running large batches to confirm you have enough balance.