ToolRouter Billing Guide: Credits, Fees, and BYOK Pricing

ToolRouter uses a credit-based system powered by Stripe. You purchase credits upfront, and each tool call meters usage against your credit balance. There are no subscriptions or minimum commitments — you only pay for what you use.

How does billing work?

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

Purchase credits — pay via a Stripe-hosted invoice, credits are granted instantly on payment
Use tools — each call meters usage via Stripe meter events (1 unit = $0.001)
Balance decrements — Stripe invoices accrued usage at a $2 threshold, deducting from your credit balance
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.

Credit amount	Fee	Total charged	You get
$5	$0.80 (minimum)	$5.80	$5.00 in credits
$10	$0.80 (minimum)	$10.80	$10.00 in credits
$20	$1.10	$21.10	$20.00 in credits
$100	$5.50	$105.50	$100.00 in credits

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?

Each skill has its own price based on underlying API and infrastructure cost, plus a 5% platform margin. Usage metadata including raw_cost, cost, markup, and credits_remaining is returned on every call so you always know what you paid.

Each skill has its own price based on the underlying API and infrastructure cost, plus a 5% platform margin.

Usage metadata is returned on every call:

json

{
  "usage": {
    "cost": 0.0053,
    "currency": "USD",
    "credits_remaining": 9.9947,
    "raw_cost": 0.005,
    "markup": 1.05
  }
}

raw_cost — the underlying provider/infrastructure cost
cost — what was metered against your credits (raw_cost * markup)
markup — multiplier applied (1.05 = 5% platform fee)
credits_remaining — your balance after the call (accurate within ~$2 due to billing threshold)

What does BYOK pricing look like?

When you pass your own provider API key via an X-Provider-Key-* header, the upstream charges go directly to your provider account. ToolRouter only meters a 5% platform fee against your credit balance, shown as markup: 0.05 in the response.

When you pass your own provider API key via an X-Provider-Key-* header, the upstream API charges go to your provider account directly. ToolRouter still meters a 5% platform fee against your credit balance.

bash

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

For BYOK calls, markup will be 0.05 instead of 1.05, reflecting that only the platform fee is charged from credits.

How do I check my credit balance?

Check your balance from any interface. Balance accuracy is within ~$2 because Stripe issues usage invoices at a $2 threshold.

MCP (agent):

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

REST API:

bash

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

CLI:

bash

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:

bash

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

CLI:

bash

toolrouter billing checkout --amount 20

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

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:

bash

# 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:

bash

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:

json

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