docs / setup

Paste this into your agent.

We upload token counts, cost, and hashed message IDs. Prompts and paths stay on your machine.

recommended setup

Give this prompt to your agent.

It installs the collector, uploads your usage, and keeps it synced every 15 minutes. You approve one browser prompt.

Use an agent with terminal access.

Set up tokenburnmarket on this machine. Work until every check below passes.

1. Check `node --version`. Install Node 20 or newer if needed, then run `npm install --global tokenburnmarket@latest` with a user-owned npm prefix. Never use sudo. Run `command -v tokenburnmarket` and fix the prefix until it resolves outside an npx cache.
2. Run `tokenburnmarket connect --server https://tokenburnmarket.vercel.app`. Show me the approval URL, code, and fingerprint, then wait for approval. Keep the device token and private key on this machine.
3. Run `tokenburnmarket sync`. Then run `tokenburnmarket daemon install --interval 15m`; it installs and starts the service itself. Use the installed CLI path, not an npx cache path.
4. Run `tokenburnmarket mcp setup`. If this agent supports MCP, merge the server into its user config. Keep existing settings and tell me if a restart is needed.
5. Run `tokenburnmarket status`. Finish only when "Synced to" and "Last sync" have values, the service is running, and its latest log has no errors. Call `my_stats` through MCP if available. Fix any failed check.

Report the handle, device, last sync, service status, and MCP status. Omit secrets.

Privacy boundary: upload token totals, cost, and hashed message IDs only. Keep prompts, paths, tokens, and private keys local.

Manual setup

connect

npm install --global tokenburnmarket@latest

tokenburnmarket connect

The CLI prints an approval URL, fingerprint, and 10-minute code. Match the browser fingerprint to the terminal, then approve. The private key stays on your machine.

Verify command -v tokenburnmarket first. If it does not resolve, use a user-owned npm prefix whose bin directory is already on your PATH.

Approval starts the first sync. A large history can take about 30 seconds.

Reconnecting replaces the local device. Revoke the old one in settings. Separate devices that read the same transcripts are counted once.

Sync

A sync uploads changed daily totals and receipt hashes.

tokenburnmarket sync

tokenburnmarket sync --since 7

tokenburnmarket sync --dry-run

tokenburnmarket status

sync: The days since the last sync.
--since 7: The last seven days instead, whatever the watermark says.
--dry-run: Prints what would go up and sends nothing.
--quiet: Prints nothing unless something went wrong. For cron lines and scripts.
status: Handle, device, server, and the last day synced from this machine.

Keep it synced

Add the MCP server to Claude Code or Codex. It syncs when your agent starts and adds the trading tools below.

claude mcp add tokenburnmarket -- npx -y tokenburnmarket mcp

Codex gets the same from ~/.codex/config.toml:

[mcp_servers.tokenburnmarket]
command = "npx"
args = ["-y", "tokenburnmarket", "mcp"]

A startup sync skips work if another sync ran in the past ten minutes. This keeps two open agents from reading the same transcripts twice. npx tokenburnmarket mcp setup prints both of these again when the terminal has scrolled away.

no agent on this machine

Run the daemon. Its lock file allows one copy per machine.

tokenburnmarket daemon install --interval 15m

tokenburnmarket daemon install --dry-run

daemon install creates and starts the per-user LaunchAgent, systemd service, or Windows scheduled task. The dry run previews the service definition and changes nothing.

MCP tools

tool	what it does
sync_usage	uploads this machine's usage and reports what the server made of it
my_stats	today, this week and this month of spend and tokens, credits, trust
my_communities	the communities you belong to
list_markets	open markets you can trade, with the price of every outcome
place_bet	quotes a trade, and places it only with confirm: true

place_bet never spends without confirm: true. Called without it, it prices the trade against the live book, writes nothing, and returns the cost, the average price and where the price would land. See markets for what happens when the price moves between the quote and the fill.

Where things are stored

Config lives in the platform config directory: ~/Library/Application Support/tokenburnmarket on macOS, %APPDATA%\tokenburnmarket on Windows, $XDG_CONFIG_HOME/tokenburnmarket elsewhere. It holds a device token and a private key, and is written owner-only.

TBM_SERVER points the collector at another server, the same as --server. TBM_CCUSAGE names a local ccusage command to run instead of npx -y ccusage@latest. npx tokenburnmarket --help lists every command.