> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumeus.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Plans and billing

> Plans, prices, the plan catalog, upgrades, overage and when a request is charged.

Build and test on Testnet for free: up to 10,000 requests a day (unlimited on
Enterprise), reset at 00:00 UTC. Credits are for Mainnet. Every workspace starts on Free;
paid plans are self-serve: open **Usage & billing** in the dashboard, choose a
plan and pay with Stripe Checkout. One plan covers your whole workspace on both
networks. Prices are in US dollars.

## Plans

| Plan | Price per month | Included Mainnet credits | Over the included credits | Testnet |
| - | - | - | - | - |
| Free | \$0 | 250,000 | Mainnet requests stop (`402`) until the next period | Free, 10,000 requests a day |
| Starter | \$29 | 3,000,000 | \$0.01 per 1,000 credits | Free, 10,000 requests a day |
| Growth | \$99 | 12,000,000 | \$0.01 per 1,000 credits | Free, 10,000 requests a day |
| Scale | \$499 | 64,000,000 | \$0.01 per 1,000 credits | Free, 10,000 requests a day |
| Enterprise | By agreement | By agreement | By agreement | Free, unlimited |

Mainnet credits are shared by the Activity API, the Assets API, RPC and webhook
deliveries. Testnet requests and Testnet webhook deliveries cost no credits and
are never billed; over the daily cap they return `429` until 00:00 UTC (see
[Testnet is free](/guides/limits.md#testnet-is-free)). Rate limits, page sizes,
credits per route and webhook endpoint caps are in
[usage and limits](/guides/limits.md).

## The plan catalog

The catalog is public and needs no key. Treat it as the source of truth for
prices and limits:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --fail-with-body https://api.lumeus.dev/v1/plans
```

```json Response (trimmed to one plan) theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "catalog_state": "self_serve",
  "credit_formula": "credits = max(base_weight × ceil(rows / 100), ceil(response_bytes / 64 KiB)), minimum 1 block; ...",
  "credit_weights": { "account": 1, "asset": 5, "contract": 5, "activity": 10, "assets-holders": 5, "webhooks": 1 },
  "plans": [
    {
      "name": "starter",
      "monthly_fee_cents": 2900,
      "included_credits": 3000000,
      "overage_per_1k_cents": 1,
      "hard_cap": false,
      "rate_per_minute": 600,
      "rpc_rate_per_minute": 300,
      "max_page_size": 200,
      "account_max_page_size": 1000,
      "max_webhook_endpoints": 10,
      "rpc_method_credits": { "getHealth": 1, "getEvents": 2, "simulateTransaction": 5 },
      "subscribable": true,
      "custom": false,
      "testnet_free": true,
      "testnet_daily_requests": 10000
    }
  ]
}
```

| Field | Meaning |
| - | - |
| `name` | `free`, `starter`, `growth`, `scale` or `enterprise`; the value you send to checkout |
| `monthly_fee_cents`, `included_credits` | Price and Mainnet credits per billing period |
| `overage_per_1k_cents` | Price of each further 1,000 credits; `0` on Free, which has `hard_cap: true` |
| `rate_per_minute`, `rpc_rate_per_minute` | Requests per minute for Activity and Assets together, and for RPC |
| `max_page_size`, `account_max_page_size` | Largest `limit` on collections, and on account activity |
| `max_webhook_endpoints` | Webhook endpoints the plan allows (Free: one Testnet endpoint). `0` means no plan limit (Enterprise), where each network still allows up to 1,000 |
| `rpc_method_credits`, `credit_weights` | What each RPC method and REST route class costs |
| `subscribable` | `true` when you can buy the plan from this catalog |
| `custom` | `true` for Enterprise, whose terms are by agreement |
| `testnet_free` | `true`: Testnet requests cost no credits on this plan |
| `testnet_daily_requests` | Testnet requests per UTC day; `null` means unlimited (Enterprise) |

Buy plans from the Mainnet catalog (`https://api.lumeus.dev/v1/plans`), where
`catalog_state` is `self_serve`. The Testnet host shows the same plans with
`catalog_state: legacy_reference` and `subscribable: false`, for reference
only. The subscription you buy applies to both networks.

## Upgrade

1. In the dashboard, open **Usage & billing** and choose **Compare plans**.
2. Pick Starter, Growth or Scale and complete Stripe Checkout.
3. The plan changes when Stripe confirms the payment, usually within seconds.
   The return to the dashboard alone is not proof of payment.

From code, `POST /billing/checkout` with `{"plan":"starter"}` (full API key or
signed-in session) returns the Checkout `url`. A new checkout expires the
workspace's previous unpaid Checkout session, so only the newest one can be
paid. A new subscription starts a fresh monthly allowance, even when you upgrade
on the day your Free period started.

A workspace has one subscription. A further checkout returns `409` with
`code: conflict` and a `reason`:

* `subscription_exists`: the workspace already has a subscription;
* `subscription_pending`: a paid checkout is still being set up. Refresh in a
  minute.

When present, `portal_url` opens the billing portal.

## Change or cancel a plan

`POST /billing/subscription` with `{"plan":"growth"}` moves the current
subscription to another plan, up or down. Stripe invoices the prorated
difference immediately; if an upgrade's payment fails, the plan does not change.
The plan changes when Stripe confirms the update. Never start a second checkout
to change plans. Cancel in the billing portal (**Manage subscription**, or
`POST /billing/portal`); cancelling returns the workspace to Free.

Upgrading keeps your keys, logs and data. For webhooks on paid plans, see
[webhook plans](/webhooks/overview.md#plans).

## Overage and invoices

Paid plans keep working past their included credits. Each further 1,000 credits
costs \$0.01 and appears on the next monthly invoice. Free never bills: at
250,000 credits, Mainnet requests return `402 payment_required` until the
period resets, while Testnet keeps working up to its daily cap. Check usage at
any time with `GET /v1/usage` or on **Usage & billing**, which shows today's
Testnet requests next to your Mainnet credits:

```json GET /v1/usage (trimmed) theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "plan": "free",
  "monthly_credits_limit": 250000,
  "monthly_credits_used": 5393,
  "monthly_credits_remaining": 244607,
  "testnet": {
    "free": true,
    "day": "2026-10-22",
    "daily_requests_used": 1234,
    "daily_requests_limit": 10000,
    "daily_requests_remaining": 8766,
    "resets_at": "2026-10-23T00:00:00Z"
  }
}
```

## When a request is charged

Testnet requests are never charged; they only count toward the daily Testnet
cap. Each Mainnet request reserves its maximum cost before the read and settles
the actual cost before the response is sent:

* A successful response is charged once, when the server completes it. A client
  that disconnects early is still charged.
* Errors cost 0 credits: 4xx responses, upstream failures, and every 5xx,
  including `503` "billing temporarily unavailable". The one exception is an
  unknown transaction hash: `404 not_found` on `/transactions/{hash}` or
  `/transactions/{hash}/activity` costs 1 credit, because the lookup searched
  the full history.
* On Free (hard cap), a request never costs more than the credits reserved for
  it, so a large response can cost less than the formula. Near the cap a
  request is refused with `402` when its reservation does not fit, even if its
  actual cost would. Assets reads reserve by the requested `limit`, Activity
  pages reserve the plan's maximum page, and RPC calls reserve their method's
  maximum response.
* `monthly_requests` in `/v1/usage` counts settled requests on both networks,
  Testnet included at 0 credits. Refunded requests are not counted.

## Payment problems

If a renewal payment fails, the subscription is past due and Stripe retries the
payment. The workspace keeps its plan limits for 7 days; after that it uses Free
limits until the payment succeeds. If Stripe gives up, or you cancel, the
workspace returns to Free limits. Keys, logs and data are kept. Check
`GET /billing/status` for the payment state.

> **Prepaid offers and retired routes**
>
> `POST /billing/purchases` buys versioned prepaid offers that Lumeus arranges
> with a workspace; it is not part of self-serve billing. For prepaid accounts the
> renewal grace period is 72 hours, and only existing funds can be used during
> it. `POST /billing/topup` is retired and returns `409`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.