Billing Tools

The Billing category is the auth and wallet layer behind every paid tool. It gets you an API key, tracks your credit balance, tops up via card, and lists invoice history. Every paid tool consults this layer to authorize requests and meter usage.

Tools

get_api_key

Get a new API key. A verification email is sent to the address you provide; calling get_api_key again with the code finalizes the key.

$
curl -X POST https://api.gtm-tools.sh/api/v0/get_api_key \
>
  -H "Content-Type: application/json" \
>
  -d '{"email": "you@yourcompany.com"}'

1
{
2
  "status": "verification_sent",
3
  "email": "you@yourcompany.com"
4
}

After verification, the key (prefixed sk_) is returned. New accounts receive 100 free credits.

get_credit_balance

Returns the current balance and the cost of every tool, grouped by server.

$
curl https://api.gtm-tools.sh/api/v0/get_credit_balance \
>
  -H "Authorization: Bearer $GTM_TOOLS_API_KEY"

1
{
2
  "balance": 412,
3
  "tools": {
4
    "socials": {
5
      "get_linkedin_company_url": { "cost": 2 },
6
      "list_linkedin_company_employees": { "cost": 30 }
7
    },
8
    "data": {
9
      "get_email": { "cost": 5 }
10
    },
11
    "signals": {
12
      "signal_socials_spike": { "cost": 5 }
13
    }
14
  }
15
}

buy_credits

Charge a saved card and credit credits.

$
curl -X POST https://api.gtm-tools.sh/api/v0/buy_credits \
>
  -H "Authorization: Bearer $GTM_TOOLS_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{"amount": 25}'

set_auto_reload

Configure automatic top-ups when the balance falls below a threshold.

$
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": 200, "reload_to": 5000}'

list_invoices

Returns purchase and charge history.

$
curl https://api.gtm-tools.sh/api/v0/list_invoices \
>
  -H "Authorization: Bearer $GTM_TOOLS_API_KEY"

1
{
2
  "invoices": [
3
    {
4
      "id": "in_1NkX...",
5
      "created_at": "2026-04-21T10:14:00Z",
6
      "amount_usd": 25,
7
      "tokens_credited": 2500,
8
      "status": "paid"
9
    }
10
  ]
11
}

get_billing_portal

Returns a short-lived Stripe billing-portal URL where you can update the saved card, download receipts, and manage payment details in Stripe’s hosted UI.

$
curl -X POST https://api.gtm-tools.sh/api/v0/get_billing_portal \
>
  -H "Authorization: Bearer $GTM_TOOLS_API_KEY"

1
{ "url": "https://billing.stripe.com/p/session/..." }

Managing API keys

list_api_keys shows every key in the workspace with its value obfuscated, so you can audit what exists without exposing secrets. revoke_api_key deletes a specific key by api_key_id, with a belongs-to check so a key can only revoke keys in its own workspace. The CLI wraps these as gtm-tools admin keys list and gtm-tools admin keys revoke <id>.

$
# List keys (values obfuscated)
$
curl https://api.gtm-tools.sh/api/v0/list_api_keys \
>
  -H "Authorization: Bearer $GTM_TOOLS_API_KEY"
$
$
# Revoke a specific key by ID
$
curl -X POST https://api.gtm-tools.sh/api/v0/revoke_api_key \
>
  -H "Authorization: Bearer $GTM_TOOLS_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{"api_key_id": "key_..."}'

Usage, and what to do when it runs out

There are no seats here. Every plan is a flat subscription over ONE shared pool of credits — a workspace’s members and its API keys all draw on the same balance — so there is no per-member pack to size, no seat to assign, and no per-member top-up to request. The billing engine reads that from the plan catalogue and simply does not register the tools that would only ever refuse: list_seats, assign_seat_type, request_seat_change and the whole *_top_up group are absent from GET /api/v0 on this deployment. If you have seen them in another product built on the same engine, that product sells seats and this one does not.

get_usage returns what the workspace has spent this cycle, optionally filtered by caller. get_usage_limits answers the more useful question — every limit that applies to you right now, what is left of each, when it resets, and a next_step naming what to do if something is refusing you. get_org_usage breaks the pool down by member: each row is that person’s share, limit_shared: true because the ceiling is the workspace’s rather than theirs, and shared_pool carries the pool once so nothing invites you to add the rows up.

$
# Usage this cycle (optionally filter by caller kind, or look back N days)
$
curl -X POST https://api.gtm-tools.sh/api/v0/get_usage \
>
  -H "Authorization: Bearer $GTM_TOOLS_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{"caller_kind": "api"}'
$
$
# What is left, and what to do about it
$
curl -X POST https://api.gtm-tools.sh/api/v0/get_usage_limits \
>
  -H "Authorization: Bearer $GTM_TOOLS_API_KEY" \
>
  -H "Content-Type: application/json" -d '{}'

When the pool is spent, the overage draws the prepaid wallet rather than stopping an agent mid-run — so the answer is credits, and get_usage_limits says so in next_step:

1
{ "next_step": { "rung": "credits", "actor": "admin", "action": "buy_credits" } }

action is the name of the tool to call next. On a plan with nothing above it the rung becomes plan, and a member without the standing to buy gets request_plan_change instead — the same answer, addressed to whoever can act on it.

The CLI wraps these as gtm-tools admin usage, admin limits and admin team-usage.

The wallet model

Every paid tool publishes its cost. When a tool is called, the cost is debited up front, before the tool runs.

Next steps