Source: https://sparetokens.ai/docs/giving-styles
Description: Choose how to give: a fixed amount, expiring credit, a share, everything spare, idle machine time or a one-off boost, always within the caps you set.

[Home](https://sparetokens.ai/) / [Docs](https://sparetokens.ai/docs) / Giving styles

# Giving styles

Choose how to give: a fixed amount, expiring credit, a share, everything spare with a ceiling, idle time or a boost, then preview it.

A giving style is the rule that decides when a source may give and how much. You pick one style per source, the worker works it out on your machine before each task, and a task never starts unless its worst-case cost fits within every limit that applies. The [protections](https://sparetokens.ai/docs/limits-and-protections) underneath every style cannot be switched off.

## The styles
- **A fixed amount (`fixed`)**: The default for API keys. Give up to a set amount per day, week or month, for example $5 a month. It is a hard ceiling, checked before every task, and it is not paced, so the amount can be given as soon as work is available. Set it with `--fixed 5` and `--period`, or as a percentage of a budget with `--fixed 10% --of 50`.
- **Use up expiring credit (`expiring`)**: For promo or prepaid API credit with an end date. Tell it the balance, the date it expires and a floor to keep. The worker paces giving evenly from the day you set the balance to the end of the expiry day, so nothing is wasted and nothing arrives in a burst, and it stops at the floor. If you move the date earlier the pace speeds up on the next check. `--expiring 30 --by 2026-11-30 --floor 2`.
- **A steady share (`share`)**: Give a percentage of a budget each period, spread evenly through the period. `--share 10% --of 100 --period month` gives up to $10 a month, no faster than the month passes.
- **Everything spare (`all`)**: Give whenever the source is free, down to a minimum keep-back that can never be lowered below 5%. An API key must have a ceiling (`--ceiling 20`, per month unless you add `--ceiling-period`), so "everything" is always bounded. For a local model it behaves like idle time with no hours limit.
- **Idle time (`idle`)**: The default for local models. Run only when the machine has been idle for a while (10 minutes by default), is plugged in and is not hot, optionally only in certain hours (`--nights` is 22:00 to 07:00). It stops and releases the task the moment you are back. If the machine's idle, power or temperature state cannot be read, it does not run.
- **A one-off boost (`sparetokens boost`)**: "Give $5 now" or "run for the next 2 hours". A boost replaces the schedule and the style for a while, then expires by itself. It never replaces the protections, a keep-back or a ceiling. `sparetokens boost anthropic 5` (valid 24 hours) or `sparetokens boost mac 2h`; `--cancel` ends one early.
- **Only what would expire (`leftovers`)**: Give in the last hours before an allowance that resets (default 6 hours before the reset), always keeping a share back for yourself (default 15%). It needs a fresh reading of the remaining allowance and gives nothing without one. It is available only for a provider whose terms allow automated use of that allowance. Consumer subscription logins, such as Claude and ChatGPT plans, do not, so this style is not offered for them. `sparetokens give` refuses it and says why.

Tasks go to the source that suits them, so a source never wastes effort on work it fails.

## Which style should I choose?

Start from what you have. You can change style any time with `sparetokens give`, and `sparetokens preview` shows the effect first.
| If you have | Choose | Why |
| An API key and no particular plan | `fixed` | The simplest and the default. A hard ceiling per day, week or month, checked before every task. |
| Promo or prepaid credit with an end date | `expiring` | Paced evenly to the date so nothing is wasted and nothing arrives in a burst. Early in the window there is little room, so a fixed amount can be easier for a first run. |
| A monthly budget and a wish to give a little of it | `share` | A steady percentage, spread through the period. |
| Plenty to spare and a clear upper limit | `all` with `--ceiling` | Gives whenever the source is free, down to a keep-back of at least 5%, never past the ceiling. |
| A Mac or Linux machine with a local model | `idle` | Runs only when the machine is idle, plugged in and cool, and stops the moment you return. Add `--nights` for 22:00 to 07:00. |
| A weekend you want to push | `boost` | "Give $5 now" or "run for 2 hours". It expires by itself and never replaces the protections. |
| A provider that allows automated use of a resetting allowance | `leftovers` | Gives in the last hours before a reset. Not offered for consumer subscription logins. |

New to all this? The [API credit guide](https://sparetokens.ai/start/api-credit) and the [local model guide](https://sparetokens.ai/start/local-model) walk through the first rule and its preview step by step. Unfamiliar words are in the [glossary](https://sparetokens.ai/docs/glossary).

## Setting a style

Use `sparetokens give`. It writes the readable file `rules.toml` in your config directory, checks it, and says what it saved. A short name such as `openai`, `anthropic`, `xai`, `openrouter` or `mac` creates the source if it does not exist yet.

```
sparetokens give anthropic --fixed 5 --key-ref env:ANTHROPIC_API_KEY
sparetokens give promo --provider anthropic-api --expiring 30 --by 2026-11-30 --floor 2
sparetokens give xai --all --ceiling 20 --nights
sparetokens give mac --idle --nights
sparetokens boost anthropic 5
sparetokens preview promo
sparetokens status
```

## The rules file

The same rules can be written by hand or by an agent. A key is only ever referenced by name (`key_ref`), never written into the file, and a value shaped like a key is refused.

```
# ~/.config/sparetokens/rules.toml
[source.work-api]
provider = "anthropic-api"
key_ref = "env:ANTHROPIC_API_KEY"   # a name, never the key
style = "expiring"
balance_usd = 30
expires = "2026-11-30"
floor_usd = 2

[source.mac-ollama]
style = "idle"
idle_minutes = 10
hours = "22:00-07:00"
plugged_in_only = true
```

Settings by style:
- **fixed:** `amount_usd`, `amount_tokens` or `amount_pct` (with `budget_usd` or `budget_tokens`), and `period` (day, week or month).
- **expiring:** `balance_usd`, `expires` (a date), `floor_usd`, and optionally `balance_as_of`, the date the balance was true. Without it the worker remembers when it first saw the balance.
- **share:** `share_pct`, `period` and `budget_usd` or `budget_tokens`.
- **all:** `ceiling_usd` (required for API keys), `keep_back_pct` (5 or more), optionally `balance_usd` and `floor_usd`.
- **idle:** `idle_minutes`, `plugged_in_only`.
- **leftovers:** `window_hours`, `keep_back_pct`, `window`.
- **any style:** `hours` (only between these local times), `quiet_hours` (never between these), `ceiling_usd` with `ceiling_period`, and the source settings `provider`, `key_ref`, `enabled`, `model`, `per_task_usd`, `per_day_usd`, `per_task_tokens`, `per_day_tokens`, `max_turns` and `timeout_s`.

Mistakes are reported with the source and the setting, for example "[source.xai]: everything spare on an API key needs a ceiling". A source defined in `config.json` can have its rules set in `rules.toml` under the same name; `rules.toml` wins.

## How rules combine

**Within one source, the strictest limit wins.** The layers are checked in this order and the first one that says no gives the reason you see:
- The always-on protections.
- Your keep-back, ceilings and the floor of expiring credit.
- The schedule: hours and quiet hours.
- The style, which decides how much, inside all of the above.

For example, everything spare with a $20 monthly ceiling and nights only gives everything spare at night, up to $20.

**Across sources, the worker spends what expires first.** Sources are offered work in this order: capacity that disappears soonest (an allowance close to its reset, where a provider allows it), then expiring credit paced to its date (soonest date first), then free local capacity, then paid budgets.

## Seeing what it will do

`sparetokens status` says in one plain sentence per source what will happen next and why, in the order work is offered, for example "Promo: ahead of the pace that uses this credit by its date (2026-11-30), next task in 1 h 48 min." or "Mac: giving runs 22:00-07:00, next start in 10 h 0 min." `sparetokens status --json` gives the same for agents: for each source its `state` (giving, waiting, stopped, paused, manual or off), `will_run`, `sentence`, `reason`, the layer that blocked it, `next_change_in_s`, `headroom_usd` and any `boost`.

## Previewing a rule

`sparetokens preview SOURCE` simulates the last 7 days under the source's rule and prints what would have been **given**, what **expired** unused and what you **kept**. Your own usage is not recorded by the worker, so the preview runs on an example week and says so on the first line; it also shows what your local ledger recorded as actually given in the last 7 days. The example week is the same one the setup rule studio uses: weekday work hours heavy, evenings light, weekends light, nights quiet. Add `--json` for agents.

## Defaults in setup

`sparetokens setup` offers a safe default for each kind of source, and pressing Enter keeps it:
- **API keys:** a fixed amount of $2 per week (alternative: $10 per month, or manual). Use `sparetokens give` to switch to expiring credit, a share or everything spare with a ceiling.
- **Local models:** idle time, after 10 idle minutes and while plugged in.

API keys stay off unless you choose them, so pressing Enter all the way through spends nothing.

## Choosing models

Per source, choose the best available, the cheapest that qualifies, or specific models. `sparetokens config models NAME` shows which task types each model unlocks and why it does not unlock the others. Best and cheapest are heuristics from tier and price ceiling, not benchmarks.

```
sparetokens config set-models work-api --mode best
```

The older rule types set with `sparetokens config set-rule` (`fixed_budget`, `percentage`, `idle_only`, `use_it_or_lose_it`) keep working.

## How remaining capacity is counted
- **Allowances that reset:** only for a provider whose terms allow automated use. The reading must be fresh (under 30 minutes old) or nothing is given.
- **API keys:** there is no allowance. Your fixed amount, credit balance or ceiling is the limit.
- **Local models:** capacity is time, so the worker tracks wall-clock seconds and idle state.

---
Part of SpareTokens (https://sparetokens.ai/). Full site index for agents: https://sparetokens.ai/llms.txt
