Docs
API Reference
Billing & top-ups

Billing & top-ups

Three calls so an agent that runs out of usage can keep going without anyone opening a browser. Every 402 out_of_usage answer carries the same instructions in its top_up_now field.

Cost: Free

GET /v1/billing

Usage for this period, whether a card is on file, auto-refill state, the packs on sale with prices, and the Max upgrade.

curl https://frontrun.vc/v1/billing \
  -H "X-API-Key: your_api_key"
{
  "plan": "pro",
  "usage": { "used_pct": 100, "resets_at": "2026-11-01T00:00:00Z", "paused": true, "unlimited": false, "topup_active": false },
  "card_on_file": true,
  "auto_refill": { "enabled": false, "pack": null, "last_failed_at": null },
  "packs": [
    { "id": "pack_1000", "label": "Small top-up", "price_usd": 25, "blurb": "A handful more chat answers and lookups", "popular": false },
    { "id": "pack_5000", "label": "Medium top-up", "price_usd": 120, "blurb": "About two Pro months of usage", "popular": true },
    { "id": "pack_10000", "label": "Large top-up", "price_usd": 220, "blurb": "A Max month of usage on top of your plan", "popular": false }
  ],
  "top_up": { "endpoint": "POST /v1/billing/topup", "body": { "pack": "pack_1000", "auto_refill": false }, "mcp_tool": "frontrun_topup", "note": "Charges the card on file and credits this key at once." },
  "upgrade": { "plan": "max", "price_usd": 199, "note": "Max has 4x the usage of Pro plus the stealth founder and accelerator lanes, and costs less per unit of usage than any pack.", "url": "https://frontrun.vc/pricing" }
}

POST /v1/billing/topup

Buy a pack with the card on file. The key is credited in the same call, so the next request succeeds.

curl -X POST https://frontrun.vc/v1/billing/topup \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "pack": "pack_5000", "auto_refill": true }'
FieldTypeDescription
packstringPack id from GET /v1/billing. Omit for the smallest pack.
auto_refillbooleanAlso turn on auto-refill with this pack for this key. Default false.
{
  "purchased": true,
  "pack": { "id": "pack_5000", "label": "Medium top-up", "price_usd": 120 },
  "usage": { "used_pct": 100, "resets_at": "2026-11-01T00:00:00Z", "paused": false, "unlimited": false, "topup_active": true },
  "auto_refill": { "enabled": true, "pack": "pack_5000", "last_failed_at": null },
  "message": "Bought Medium top-up ($120.00). Usage is topped up; retry the original call."
}

This charges money. An agent should name the pack and its price and get a yes from its user before calling. The MCP tool description says the same.

Other answers:

  • 402 no_card_on_file or 402 card_declined, with checkout_url: nothing was charged. Open the link to pay once; the key is credited within a minute of payment and the card is saved for next time.
  • 429 topup_cooldown (with retry_after_seconds): one purchase per key per 10 minutes.
  • 429 topup_daily_limit: at most 3 purchases per key per day. Max is the answer for sustained usage.
  • 400 unknown_pack: the body lists the ids on sale.

PUT /v1/billing/auto-refill

Turn auto-refill on or off. On, a pack is bought with the card on file whenever this key's usage runs low, so an agent never sees out_of_usage.

curl -X PUT https://frontrun.vc/v1/billing/auto-refill \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true, "pack": "pack_5000" }'
FieldTypeDescription
enabledbooleanRequired.
packstringPack to buy each time. Omit to keep the current one, or the smallest.

Answers 402 no_card_on_file when enabling with no card to charge. A failed charge turns auto-refill off and emails the account owner.

The MCP server exposes the same three calls as frontrun_billing, frontrun_topup and frontrun_auto_refill.

GET /v1/statusTrack Accounts