# Billing & top-ups

> Source: https://www.frontrun.vc/docs/endpoints/billing
> Raw markdown: https://www.frontrun.vc/raw/docs/endpoints/billing.md
> Full docs (single file): https://www.frontrun.vc/llms-full.txt

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.

```bash
curl https://frontrun.vc/v1/billing \
  -H "X-API-Key: your_api_key"
```

```json
{
  "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.

```bash
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 }'
```

| Field | Type | Description |
|---|---|---|
| `pack` | string | Pack id from `GET /v1/billing`. Omit for the smallest pack. |
| `auto_refill` | boolean | Also turn on auto-refill with this pack for this key. Default `false`. |

```json
{
  "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`.

```bash
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" }'
```

| Field | Type | Description |
|---|---|---|
| `enabled` | boolean | Required. |
| `pack` | string | Pack 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`.