Source: https://sparetokens.ai/start/api-credit
Description: Use expiring or prepaid API credit for open science: create a capped key, run setup, preview your giving rule and see a verified result. About ten minutes.

# API credit guide

Expiring promo credit, prepaid credit or an API budget you do not fully use. About ten minutes, a cap you choose, and a verified result at the end.

[Start at step 1](#step-1)[Other paths](https://sparetokens.ai/start)
- **Time**: About 10 minutes
- **Cost**: $0 to set up. Your first task costs what the model costs, capped by the limit you choose (this guide uses $2).
- **You need**: Python 3.10 or newer, and an API key with a spend limit. Prepaid or expiring credit is a good fit.
- **You get**: A verified result in your history, and a giving rule you can preview and change.

**Where things stand.** SpareTokens is a private pilot. The worker is not public yet, so the install commands are marked [Available at launch] and start working on launch day. Everything else on this page is how the worker behaves today. The [waitlist](https://sparetokens.ai/join) is how you get an invite.

## Before you start

This guide is for people with API credit: a promo grant that expires, prepaid credit, or an API budget you set high and do not fully use. Not sure you have any? [Find your unused API credit](https://sparetokens.ai/credits) first. Need a key? [Create one step by step](https://sparetokens.ai/start/api-key). If you have a Mac or Linux machine with Ollama instead, use the [local model guide](https://sparetokens.ai/start/local-model).

Consumer subscriptions (Claude, ChatGPT and Gemini plans) are not supported, because the providers’ terms restrict automated use. The worker refuses a subscription login and points you here. Use an API key or a local model.

## Step 1: Create a dedicated key with a spend limit

About 2 minutes

Where your provider offers projects or workspaces, create one just for SpareTokens and make a key inside it. Set a spend limit there too. A dedicated key has its own usage and limit and can be revoked on its own without touching your other tools. The [API key guide](https://sparetokens.ai/start/api-key) shows each console, step by step. OpenAI support suggested this approach for workers like ours. See [project and service-account keys](https://sparetokens.ai/docs/providers#project-keys).

Keep the key out of the SpareTokens config. The worker reads it by name from your environment. In a new terminal:

```
export ANTHROPIC_API_KEY="paste-your-key-here"
```

For OpenAI, xAI or OpenRouter, use `OPENAI_API_KEY`, `XAI_API_KEY` or `OPENROUTER_API_KEY`. To keep the key in the macOS Keychain instead, use `--key-ref keychain:ITEM` later.

## Step 2: Install the worker [Available at launch]

About 2 minutes

Python 3.10 or newer is required. On Linux, install `bubblewrap` first (`sudo apt install bubblewrap`) so shell tasks have a sandbox. macOS has one built in.

```
pipx install sparetokens
```

```
sparetokens --version
```

You will see

```
sparetokens 0.1.0
```

Other systems and installers are on the [install page](https://sparetokens.ai/install).

### If something goes wrong
- `command not found: pipx`: install it with `brew install pipx` (macOS) or `sudo apt install pipx` (Debian and Ubuntu), then open a new terminal.
- Python older than 3.10: install a newer one, then run `pipx install --python python3.12 sparetokens`.

## Step 3: Run the self-check

About 1 minute

This is read-only. It prints your system, whether a sandbox is available and which providers are ready, and it never prints a key.

```
sparetokens doctor
```

You will see

```
SpareTokens 0.1.0 self-check
  os:          Darwin 27.2.0 (arm64)
  python:      3.12.8
  sandbox:     available (macOS sandbox-exec)
  providers:
    anthropic-api  ready
    openai-api     not ready: OPENAI_API_KEY is not set in the environment (it stays on this machine)
    xai            not ready: XAI_API_KEY is not set in the environment (it stays on this machine)
    openrouter     not ready: OPENROUTER_API_KEY is not set in the environment (it stays on this machine)
    local          not ready: no local OpenAI-compatible server reachable at http://127.0.0.1:11434/v1 (start Ollama, LM Studio or an MLX server first)
  terms:       subscription logins are not used (API keys and local models only); https://sparetokens.ai/docs/providers
  config dir:  ~/.config/sparetokens (not created yet); registered as: not registered
  coordinator: http://127.0.0.1:18795 reachable (HTTP 200)

All good.
```

Real output from the real worker, captured against a throwaway coordinator with throwaway signing keys. Paths are shortened to `~`. The key in this capture is a placeholder, not a real key. The lines for Claude and ChatGPT subscription logins are left out, because those are never used.

Your provider should read `ready`. The other providers reading `not ready` is normal.

### If something goes wrong
- `anthropic-api not ready: no Anthropic API key found`: the variable is not set in this terminal. Run the `export` line again, or add it to your shell profile.
- `coordinator ... not reachable`: check your network, or pass `--coordinator URL`. See [cannot reach the coordinator](https://sparetokens.ai/docs/troubleshooting#cannot-reach).

## Step 4: Run setup

About 4 minutes

Setup is nine short questions. Every question has a safe default, and pressing Enter keeps it. API keys are off unless you pick one, and the live test is a clear yes or no that tells you the cost first.

```
sparetokens setup
```
 The setup wizard, start to finish. Each step asks one question and shows its default. Captured against a throwaway coordinator with a test model that costs nothing.

### Text version of this walkthrough

```

SpareTokens setup. Every question has a safe default; pressing Enter keeps it. Nothing here spends money unless you say so.

Step 1 of 9: sign in or stay anonymous
  Signing in with GitHub is not available yet. You will get a random contributor ID stored on this machine; it can be linked to an account later.
  Registered a new anonymous contributor (contributor-2349a7c4).

Step 2 of 9: how you appear publicly
  How should you appear on the leaderboard?
  1. Anonymous (Contributor #N)
  2. My handle (a username I choose, no real name)
  3. First name and last initial (Paul F.)
  4. Full name
Choose [1] 2
  Handle (3-24 letters, digits, _ or -) [contributor-2349a7c4] rowan_lab
  Show a link (GitHub or website)? (y/n) [n] 
  Show a country? (y/n) [n] 
  Make models used public? (y/n) [n] 
  Make providers used public? (y/n) [n] 
  Make hardware type public? (y/n) [n] 
  Make tokens donated public? (y/n) [n] 
  You will appear as: rowan_lab

Step 3 of 9: connect what you have
  1. local-ollama: ollama is running with 1 model(s) (models: fake-codefill)
  API keys are off unless you pick them; only free local models are pre-selected. Consumer subscriptions are not offered (provider terms).
  Your provider account and API key are yours to protect: use your own account, keep keys on your machine, follow your provider's terms, and set a spend limit at the provider too.
  Numbers to use, comma separated, or 'none' [1] 

Step 4 of 9: how much to give from local-ollama
  Pick a rule:
  1. idle only: when idle 10 minutes and plugged in (default)
  2. manual only
Choose [1] 

Step 5 of 9: which models for local-ollama
  Pick:
  1. Best available (default)
  2. Cheapest that qualifies
Choose [1] 
  That picks: fake-codefill (strongest listed model)
  unlocks: computation checks, small coding tasks, search heuristics, solver runs, re-checking earlier results; not larger searches (needs a stronger model); not literature checks (needs a stronger model); not Lean proofs (needs a stronger model); not refereeing (needs a stronger model)

Step 6 of 9: what to work on
  Default: wherever it is needed most (all task types).
  Opt out of any task type? (y/n) [n] 

Step 7 of 9: when it may run
  Never run on battery? (y/n) [y] 
  Quiet hours as HH:MM-HH:MM, or none [none] 
  Your own Claude Code and Codex sessions always take priority. These times are recorded now and applied by the background service.

Step 8 of 9: test run
  Run one tiny test task now with local-ollama? It costs about a few seconds of compute. (y/n) [y] 
  Claimed, worked, submitted, verified in 0s. Cost $0.0000, 1000 tokens.

Step 9 of 9: turn it on
  Run in the background now (a launchd or systemd user service)? (y/n) [n] 
  The background service is off. Turn it on any time with `sparetokens service install`, or donate by hand with `sparetokens run --source NAME`.

Your setup, in one paragraph:
  You appear as rowan_lab. local-ollama: only when the machine has been idle 10 minutes and is plugged in. Working wherever needed most. Never on battery.
  Every source also has a per-task and a per-day cap, three failures in a row pause it, and your own sessions always come first. Look at the rules with `sparetokens config explain`, see spend with `sparetokens budget`, and pause with `sparetokens pause 2h`. To remove everything: `sparetokens uninstall`.
```

You will see

```

SpareTokens setup. Every question has a safe default; pressing Enter keeps it. Nothing here spends money unless you say so.

Step 1 of 9: sign in or stay anonymous
  Signing in with GitHub is not available yet. You will get a random contributor ID stored on this machine; it can be linked to an account later.
  Registered a new anonymous contributor (contributor-6e113e7a).

Step 2 of 9: how you appear publicly
  How should you appear on the leaderboard?
  1. Anonymous (Contributor #N)
  2. My handle (a username I choose, no real name)
  3. First name and last initial (Paul F.)
  4. Full name
Choose [1] 2
  Handle (3-24 letters, digits, _ or -) [contributor-6e113e7a] mira_codes
  Show a link (GitHub or website)? (y/n) [n] 
  Show a country? (y/n) [n] 
  Make models used public? (y/n) [n] 
  Make providers used public? (y/n) [n] 
  Make hardware type public? (y/n) [n] 
  Make tokens donated public? (y/n) [n] 
  You will appear as: mira_codes

Step 3 of 9: connect what you have
  1. anthropic-api: Anthropic API key found in $ANTHROPIC_API_KEY
  API keys are off unless you pick them; only free local models are pre-selected. Consumer subscriptions are not offered (provider terms).
  Your provider account and API key are yours to protect: use your own account, keep keys on your machine, follow your provider's terms, and set a spend limit at the provider too.
  Numbers to use, comma separated, or 'none' [none] 1

Step 4 of 9: how much to give from anthropic-api
  Pick a rule:
  1. fixed budget: $2 per week (default)
  2. fixed budget: $10 per month
  3. manual only
Choose [1] 

Step 5 of 9: which models for anthropic-api
  Pick:
  1. Best available (default)
  2. Cheapest that qualifies
Choose [1] 
  That picks: opus (best anthropic-api model (alias opus))
  unlocks: computation checks, small coding tasks, search heuristics, larger searches, solver runs, re-checking earlier results, literature checks, refereeing; not Lean proofs (needs lean, which is not available here)

Step 6 of 9: what to work on
  Default: wherever it is needed most (all task types).
  Opt out of any task type? (y/n) [n] 

Step 7 of 9: when it may run
  Never run on battery? (y/n) [y] 
  Quiet hours as HH:MM-HH:MM, or none [none] 
  Your own Claude Code and Codex sessions always take priority. These times are recorded now and applied by the background service.

Step 8 of 9: test run
  Run one tiny test task now with anthropic-api? It costs about a few cents. (y/n) [n] n
  Skipped.

Step 9 of 9: turn it on
  Run in the background now (a launchd or systemd user service)? (y/n) [n] 
  The background service is off. Turn it on any time with `sparetokens service install`, or donate by hand with `sparetokens run --source NAME`.

Your setup, in one paragraph:
  You appear as mira_codes. anthropic-api: up to $2 per week. Working wherever needed most. Never on battery.
  Every source also has a per-task and a per-day cap, three failures in a row pause it, and your own sessions always come first. Look at the rules with `sparetokens config explain`, see spend with `sparetokens budget`, and pause with `sparetokens pause 2h`. To remove everything: `sparetokens uninstall`.
```

Real output from the real worker, captured against a throwaway coordinator with throwaway signing keys. Paths are shortened to `~`.

On the connect step, type the number next to your key. On the rule step, the default is $2 per week, a hard ceiling checked before every task. You can change it in the next step.

### If something goes wrong
- `Nothing usable was found`: setup saved your other choices but no key or local model was visible. Set the key and run `sparetokens setup` again.
- You pressed Enter on the wrong thing: nothing is final. Run `sparetokens setup` again, or change one rule with `sparetokens give` (next step).
- The live test says it costs about a few cents. Answer `n` to skip it, and your first task in step 6 is the real check.

## Step 5: Choose how you give, and preview it

About 3 minutes

Pick a giving style for your key. For credit that expires, tell the worker the balance, the date and a floor to keep. It paces giving evenly so nothing arrives in a burst and nothing is wasted:

```
sparetokens give promo --provider anthropic-api --expiring 30 --by 2026-11-30 --floor 2 --key-ref env:ANTHROPIC_API_KEY
```

You will see

```
Saved promo: use up $30 of credit by 2026-11-30, keeping $2. Rules are in ~/.config/sparetokens/rules.toml. Check what it will do with `sparetokens status`, or preview it with `sparetokens preview promo`.
```

Real output from the real worker, captured against a throwaway coordinator with throwaway signing keys. Paths are shortened to `~`.

Preview what the rule would have done over an example week. Nothing runs and nothing is spent:

```
sparetokens preview promo
```

You will see

```
Preview for promo (expiring): the last 7 days as an example week.
Example week, not your data: your own use is not recorded, so this shows what the setting would do on a typical week.
  given   $16.80
  expired $0.00   (unused by anyone)
  kept    $2.00   (stays with you)
  your own use in the example: $2.80
  paced evenly over the 10 days until 2026-11-30
```

Real output from the real worker, captured against a throwaway coordinator with throwaway signing keys. Paths are shortened to `~`. The preview uses an example week and says so on its second line. Choose a rule, then preview it. The numbers are an example week, not a forecast.

Prefer something simpler? A fixed amount is the easiest rule: `sparetokens give promo --provider anthropic-api --fixed 5 --key-ref env:ANTHROPIC_API_KEY` gives up to $5 a month. All seven styles are on [giving styles](https://sparetokens.ai/docs/giving-styles), with a table to [choose between them](https://sparetokens.ai/docs/giving-styles#which-style).

### If something goes wrong
- `worst case of one extra turn on this model is $2.70, but only $0.76 is available right now`: expiring credit is paced evenly, so early in the window there is little room and a large model’s worst case does not fit yet. The message ends with the command to run, `sparetokens config set-models promo --mode cheapest`. You can also wait, raise the balance, or use a fixed amount for your first run. This is the worker being careful, not a fault.
- A date in the past, or a floor larger than the balance, is refused with a plain message. Check `--by` and `--floor`.
- See what each rule would do right now with `sparetokens status` and `sparetokens config explain`.

## Step 6: Run one task

About 2 minutes

Run a single task with a hard cap of two dollars. The worker claims a task, verifies its signature and the public log entry, works on it in a sandboxed temporary folder, scans the result for credentials and submits it.

```
sparetokens run --budget-usd 2 --max-tasks 1 --allow-bash
```

You will see

```
SpareTokens worker: provider local (local), tier 1, capabilities ['bash', 'solver', 'lean'], budget n/a, max tasks 1
No giving rule for local (it is not a configured source), so only these limits apply: --max-tasks 1.
Task 1 [code_fill] Write a small function: abundant count (instance 0) (cap n/a)
  submitted as result 2 (cost $0.0000, tokens 2000, spend flag: none)
  verification: verified: all 8 answers recomputed exactly
Done. Tasks submitted: 1. Dollars: $0.0000, tokens: 2000, wall: 0s.
```

Real output from the real worker, captured against a throwaway coordinator with throwaway signing keys. Paths are shortened to `~`. This capture used a scripted test model, so the cost reads $0.0000. With your key, the same lines show what the task cost in dollars and tokens.

### If something goes wrong
- `No giving rule ... only these limits apply`: that is fine. A run you start yourself is limited by its flags and by your rules for that source.
- `Not donating: ...`: a rule is holding the run and the sentence says why and when it changes. See [Not donating](https://sparetokens.ai/docs/troubleshooting#not-donating).
- No task matched: the queue only hands out types your model can do. Try `--types run_solver re_verify --provider none` for work that needs no model.
- A blocked submission means the worker found something shaped like a key in the result and kept it on your machine. That is the protection working.

## Your first verified result

Look at your history. The line ending in `verified` is your first verified result:

```
sparetokens history --limit 5
```

You will see

```
2026-11-21 06:34  local          task 1  code_fill        verified   $0.0000  2000 tokens  fake-codefill
2026-11-21 06:34  local-ollama   task 13  canary           verified   $0.0000  1000 tokens  fake-codefill
```

Real output from the real worker, captured against a throwaway coordinator with throwaway signing keys. Paths are shortened to `~`.

Your result also counts toward your public profile (as your username, if you chose one) and the [leaderboard](https://sparetokens.ai/leaderboard), which refreshes hourly. Spend is shown only if you opt in.

**What “verified” means.** A machine check written and owned by SpareTokens passed. It does not by itself mean a result is new or important, and no discovery has been claimed. See [what has been verified so far](https://sparetokens.ai/results) and [how each check works](https://sparetokens.ai/docs/verification).
- [

### Fine-tune how you give

Fixed amount, expiring credit, a share, everything spare, idle time or a one-off boost.](https://sparetokens.ai/docs/giving-styles)
- [

### See what keeps you in control

Caps, keep-back, the circuit breaker and the protections that cannot be switched off.](https://sparetokens.ai/docs/limits-and-protections)
- [

### Let your AI agent contribute

Give an agent a scoped, expiring token.](https://sparetokens.ai/start/agent)
- [

### Troubleshooting

Every message the worker prints, and what to do about it.](https://sparetokens.ai/docs/troubleshooting)

## Be told when the worker is ready

Create an account and you are in line for the private beta. We email you when it is your turn.

[Get started](https://sparetokens.ai/join)

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