Getting Started

How Tokens Work

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. Look up cost. The cost for that tool is fetched.
  3. Reserve. The cost is debited from the wallet immediately. Concurrent calls see the reduced balance.
  4. Execute. The tool runs. This is where most of the time is spent.
  5. Settle.
    • On success: the reservation is committed.
    • On failure (5xx upstream): the reservation is refunded.
    • On client-side failure (400, 401, 402, 404, 429): no charge applied (the reservation never happened in those cases).

What “0 tokens” means

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

ToolWhy it’s free
ping (every server)Health check
connect_linkedinSession bind — no provider call
list_connected_linkedin_accountsLocal state read
detect_signalDispatcher — only the detectors it runs are charged
set_signals_order / get_signals_orderLocal config
All Admin toolsWallet operations

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

Refunds

Token reservations are refunded when:

  • An upstream provider (LinkedIn proxy, email verifier, web-tools) returns a 5xx.
  • The tool times out.
  • A request fails mid-execution after the reservation but before settlement.

You’ll see refunds reflected in get_token_balance immediately. They’re not surfaced in list_invoices (which shows charge/refund activity).

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}'