SpareTokens

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 1Other paths

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 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.0

Other systems and installers are on the install page.

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.

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
A terminal showing the nine step setup wizard: choose a username, connect an API key, pick a weekly dollar cap, then a test task that is verified.
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.

A terminal running sparetokens give with an expiring rule and then sparetokens preview, which prints given, expired and kept amounts for an example week.
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, 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 --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.
  • 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, 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.

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