Billing

Failed paid calls don’t charge. Free tools never charge. Paid tools start at $0.005.

ToolRouter uses a credit-based system powered by Stripe. You purchase credits upfront, and each paid tool call meters usage against your credit balance. Free tools stay free. You only pay when a paid tool works. Optional Lite ($9/mo) and Plus ($19/mo) add monthly credits and higher limits; team plans add a seat fee plus shared credits.

How does billing work?#

ToolRouter uses prepaid credits powered by Stripe. Purchase credits upfront, and each paid tool call meters usage against your balance. Credits are granted instantly on payment, and usage is tracked via Stripe meter events (1 unit = $0.001).

1. Purchase credits — pay via a Stripe-hosted invoice, credits are granted instantly on payment
2. Use tools — each paid call meters usage via Stripe meter events (1 unit = $0.001); free tools never charge
3. Balance decrements — successful paid calls meter usage against your credit balance
4. Top up anytime — buy more credits when your balance runs low

Behind the scenes, ToolRouter creates a metered Stripe subscription with no flat fee. Usage is reported as meter events, and Stripe's billing engine applies your credits against usage invoices automatically.

How do I buy credits?#

Purchase credits through the billing dashboard or via POST /v1/billing/checkout. Each top-up creates a Stripe invoice with two line items: the credit amount and a 5.5% processing fee (minimum $0.80). For example, a $10 top-up costs $10.80 and gives you exactly $10.00 in usable credits.

Credits are purchased through the billing page or programmatically via the API. Each top-up creates a one-time Stripe invoice with two line items: the credit amount and a purchase fee.

Purchase fee: 5.5% of the credit amount, with a minimum of $0.80. This covers Stripe processing costs.

The fee is separate from your credits — a $10 top-up gives you exactly $10.00 in usable credits.

How much does each tool call cost?#

Paid tools start at $0.005. Each paid skill call is billed at max($0.005, raw_cost) — the underlying provider cost with a $0.005 platform floor. Failed paid calls don’t charge. Free tools never charge. Usage metadata (raw_cost, cost, markup, credits_remaining) is returned on every call so you always know what you paid.

How raw_cost is resolved#

Every provider client is responsible for returning the true USD cost on its result, so consumers never do cost math themselves:

Tool authors just pass result.raw_cost through — the provider client has already done the work.

Usage metadata is returned on every call:

{
  "usage": {
    "cost": 0.005,
    "currency": "USD",
    "credits_remaining": -1,
    "raw_cost": 0.005,
    "markup": 0
  }
}

• raw_cost — the underlying provider/infrastructure cost
• cost — what was metered against your credits
• markup — legacy ratio between metered and raw cost; use cost for the charged amount
• credits_remaining — -1 for cloud calls; use check_balance for the current balance

What does BYOK pricing look like?#

When the selected provider credential is yours—saved personally, shared by your team, or supplied through an X-Provider-Key-* header—the upstream charges go directly to that provider account. ToolRouter meters 5% of the provider cost against your credit balance, with a $0.001 minimum. Unused credentials for alternative providers do not change the call's billing.

X-Provider-Key-Firecrawl: fc-...
X-Provider-Key-Serper: sp-...
X-Provider-Key-Gemini: AI...

For BYOK calls, use the response cost field as the ToolRouter charge; raw_cost is the provider cost paid through your own account.

How do I check my credit balance?#

Check your current balance from any interface. Recent metered calls can take a moment to appear.

MCP (agent):

check_balance
→ { "available_usd": 9.50, "message": "Balance: $9.50 USD available." }

REST API:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.toolrouter.com/v1/billing/balance

CLI:

toolrouter billing balance

Dashboard: Visit the Billing page at /dashboard/billing.

How do I purchase credits?#

Purchase credits from any interface. Each top-up creates a Stripe invoice — the user must open the link and pay to receive credits. Requests are idempotent within a 5-minute window.

MCP (agent):

top_up_credits { "amount_usd": 20 }
→ { "url": "https://invoice.stripe.com/...", "credit_usd": 20, "fee_usd": 1.10, "total_usd": 21.10 }

REST API:

curl -X POST https://api.toolrouter.com/v1/billing/checkout \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{ "amount_usd": 20 }'

CLI:

toolrouter billing checkout --amount 20

Dashboard: Click "Top Up" on the Billing page.

How can an agent buy credits without a human? (machine payments)#

Agents with their own payment credential can top up through the Machine Payments Protocol (MPP) with no browser or hosted invoice. POST /v1/billing/machine-topup answers with HTTP 402 and a payment challenge; the agent pays it and retries, and the credits land on the account that owns the API key. An agent with no account can pay too: the account is created when the payment settles.

1. Send your ToolRouter API key and the amount. The response is 402 Payment Required with a WWW-Authenticate: Payment ... challenge (method stripe, intent charge, realm api.toolrouter.com). With no API key, the challenge is for a new account instead. An empty body asks for the $1 minimum.
2. Pay the challenge with an MPP wallet (for example mppx) and retry the request with the payment credential in the Authorization header. No API key is needed on the retry; the credential identifies the account.
3. The response is 200 with the new balance, and a Payment-Receipt header. If you paid without an API key, it also carries api_key (shown once), account_id and a claim_url for your user. If the account can't be created or funded, the payment is refunded automatically. If you paid but never received the response, email support@toolrouter.com with the Payment-Receipt header.

curl -X POST https://api.toolrouter.com/v1/billing/machine-topup \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "amount_usd": 5 }'
# → 402 with WWW-Authenticate: Payment id="..." realm="api.toolrouter.com" method="stripe" intent="charge" ...

The amount is credits in US dollars, $1 to $500 per payment, with whole cents only. The charge is the credit amount plus the purchase fee, so a $5 top-up charges $5.80 and grants $5.00 of credits. Card payments are accepted via Stripe; stablecoin payment is not available yet.

How does auto-reload work?#

Auto-reload automatically tops up your credits when your balance drops below a threshold. Configure it from any interface.

MCP (agent):

get_billing_preferences
→ { "auto_reload_enabled": false, "auto_reload_threshold": 5, "auto_reload_amount": 20, "budget_limit": null }

set_billing_preferences { "auto_reload_enabled": true, "auto_reload_threshold": 5, "auto_reload_amount": 20, "budget_limit": 100 }
→ { "message": "Billing preferences updated." }

REST API:

# Get current preferences
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.toolrouter.com/v1/billing/preferences

# Update preferences
curl -X PUT https://api.toolrouter.com/v1/billing/preferences \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{ "autoReloadEnabled": true, "autoReloadThreshold": 5, "autoReloadAmount": 20, "budgetLimit": 100 }'

Dashboard: Configure on the Billing page under "Auto-Reload Settings".

Settings:

• Auto-reload enabled — turn on/off
• Threshold — balance (USD) that triggers a reload
• Reload amount — how much to add per reload ($1–$500)
• Budget limit — optional monthly spending cap (hard stop)

How do I manage payment methods?#

Open the Stripe billing portal to manage payment methods, view invoices, and update billing details.

MCP (agent):

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

REST API:

curl -X POST https://api.toolrouter.com/v1/billing/portal \
  -H "Authorization: Bearer YOUR_API_KEY"

Dashboard: Click "Manage Billing" on the Billing page.

What happens when I run out of credits?#

Calls are rejected before the handler runs with an INSUFFICIENT_CREDITS error and a resolution_hint pointing to the billing page. No partial execution occurs — either you have enough credits for the full call or it doesn't start.

If your balance is too low for a call, it is rejected before the handler runs:

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "type": "billing",
    "message": "Usage limit reached or insufficient credits",
    "resolution_hint": "Top up your credits at toolrouter.com/billing"
  }
}