Plans and billing

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). Rate limits, page sizes, credits per route and webhook endpoint caps are in usage and limits.

The plan catalog

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

curl --fail-with-body https://api.lumeus.dev/v1/plans

Response (trimmed to one plan)

{
  "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

In the dashboard, open Usage & billing and choose Compare plans.
Pick Starter, Growth or Scale and complete Stripe Checkout.
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.

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:

GET /v1/usage (trimmed)

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

Get started

Activity API

Assets API

Webhooks

RPC

Troubleshooting

Advanced

Plans and billing

Plans

The plan catalog

Upgrade

Change or cancel a plan

Overage and invoices

When a request is charged

Payment problems

​Plans

​The plan catalog

​Upgrade

​Change or cancel a plan

​Overage and invoices

​When a request is charged

​Payment problems

Plans

The plan catalog

Upgrade

Change or cancel a plan

Overage and invoices

When a request is charged

Payment problems