Getting Started

How Tokens Work

The metering gate, what gets charged, and the lifecycle of a paid request.

GTM Tools meters every paid tool in tokens. The unit decouples price from raw infrastructure cost: billing happens in dollars, but a tool may run multiple SMTP probes or LinkedIn scrapes per call, so a flat token price keeps the agent’s reasoning simple.

The basics

Value
Exchange rate$1 = 100 tokens
Minimum top-up$5 (500 tokens)
Free starter balance100 tokens

The lifecycle of a paid call

When your agent calls a paid tool:

  1. Authorize. The auth layer resolves the bearer token to an org.
  2. Validate. Arguments are checked against the tool’s schema.
  3. Meter. The tool’s cost is looked up and debited from the wallet in one step. If the balance doesn’t cover it, the call stops here with 402 and nothing is charged. Concurrent calls see the reduced balance.
  4. Execute. The tool runs. This is where most of the time is spent.

The debit happens before the work, not after, and there is no automatic refund. That single fact tells you what any given error cost you:

OutcomeCharged?
400 invalid arguments, 401 unauthorized, 404 unknown toolNo: rejected before the metering gate
402 insufficient tokensNo: that is the gate declining
Session-required errors (no connected extension session)No: gated ahead of metering
200 with status: "not_found"Yes: the tool did the work and there was nothing to return
429 with status: "try_again_later"Yes: the provider was busy after the gate. Each retry charges again
5xx upstream provider error or timeoutYes

If a tool charged you for something broken on our side, contact support with the tool name and arguments and we’ll credit the balance manually.

What “0 tokens” means

Some tools cost 0, every Billing tool plus a handful elsewhere:

ToolWhy it’s free
list_connected_linkedin_accounts / list_connected_reddit_accountsLocal state read
detect_signalDispatcher; only the detectors it runs are charged
set_signals_order / get_signals_orderLocal config
All Billing tools (get_api_key, get_token_balance, buy_tokens, set_auto_reload, get_billing_portal, list_invoices, list_api_keys, revoke_api_key)Wallet operations

These are intentional; they let your agent orient itself without spending tokens.

Keeping the bill down

Since a call that reaches a provider is charged whether or not the answer is useful, the savings come from calling less, not from recovering charges after the fact:

  • Filter before you hydrate. Narrow the list with a cheap tool, then spend the expensive per-record call only on what survives.
  • Respect retry_after_seconds. A tight retry loop on try_again_later multiplies the cost of one busy provider.
  • Cache what doesn’t change. Company IDs, profile URLs, and verified emails are stable for weeks.

See Token Efficiency for the full set of patterns.

Balance changes show up in get_token_balance immediately. list_invoices covers purchases (one-off top-ups and auto-reload charges), not per-call debits.

When you run out

The next paid tool call returns 402 Insufficient Tokens with no work done. Two options:

  • One-off top-up. Call buy_tokens ({"amount_usd": 25} for 2,500 tokens).
  • Auto-reload. Call set_auto_reload once with a threshold and a top-up amount; the saved card is charged automatically when the balance drops.
$curl -X POST https://api.gtm-tools.sh/api/v0/set_auto_reload \
>  -H "Authorization: Bearer $GTM_TOOLS_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{"enabled": true, "threshold_tokens": 200, "topup_usd": 50}'