Billing Tools

The Billing category is the auth and wallet layer behind every paid tool. It gets you an API key, tracks your token 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 tokens.

get_token_balance

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

$
curl https://api.gtm-tools.sh/api/v0/get_token_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_tokens

Charge a saved card and credit tokens.

$
curl -X POST https://api.gtm-tools.sh/api/v0/buy_tokens \
>
  -H "Authorization: Bearer $GTM_TOOLS_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{"amount_usd": 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_tokens": 200, "topup_usd": 50}'

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_..."}'

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