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.
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 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 first. Need a key? Create one step by step. If you have a Mac or Linux machine with Ollama instead, use the local model guide.
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 shows each console, step by step. OpenAI support suggested this approach for workers like ours. See project and service-account 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.0Other systems and installers are on the install page.
If something goes wrong
command not found: pipx: install it withbrew install pipx(macOS) orsudo 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 theexportline again, or add it to your shell profile.coordinator ... not reachable: check your network, or pass--coordinator URL. See cannot reach the coordinator.
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

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 runsparetokens setupagain.- You pressed Enter on the wrong thing: nothing is final. Run
sparetokens setupagain, or change one rule withsparetokens give(next step). - The live test says it costs about a few cents. Answer
nto 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-30Real 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.

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, with a table to choose between them.
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
--byand--floor. - See what each rule would do right now with
sparetokens statusandsparetokens 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.- No task matched: the queue only hands out types your model can do. Try
--types run_solver re_verify --provider nonefor 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-codefillReal 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, 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 and how each check works.
Fine-tune how you give
Fixed amount, expiring credit, a share, everything spare, idle time or a one-off boost.
See what keeps you in control
Caps, keep-back, the circuit breaker and the protections that cannot be switched off.
Let your AI agent contribute
Give an agent a scoped, expiring token.
Troubleshooting
Every message the worker prints, and what to do about it.
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.