Plans & Limits

Every tenant is on a plan that sets resource quotas, monthly transaction allowances, rate limits, and whether mainnet is enabled. Quota checks happen at resource creation; hitting a limit returns HTTP 402 with a machine-readable upgrade hint. Current pricing is on the pricing page.

Plans API

GET/v1/plans

Public catalog of the plan ladder with entitlements per tier.

GET/v1/billing/plan

The authenticated tenant's effective plan:

{
  "planCode": "launch",
  "displayName": "Launch",
  "hardCap": false,
  "entitlements": {
    "mainnetEnabled": true,
    "maxVaults": 100, "maxWallets": 5000, "maxSeats": 10,
    "maxSubTenants": 0, "maxTokens": 5,
    "txIncludedMonthly": 10000,
    "rateLimitRpm": 600, "rateLimitBurst": 100,
    "auditRetentionDays": 365,
    "features": { … }
  }
}
// null limit = unlimited

Quota errors (HTTP 402)

{
  "code": "PLAN_LIMIT_WALLETS",
  "numericCode": 1801,
  "message": "wallet limit reached for plan",
  "requestId": "…",
  "current": 25, "limit": 25,
  "planCode": "sandbox", "upgradeTo": "launch"
}

Mainnet gating

Sandbox tenants can exercise the entire API, but creating a transaction against Quantum Chain mainnet (chain ID 20803) requires a plan with mainnetEnabled: true. Otherwise transaction creation returns 402 MAINNET_NOT_IN_PLAN (1810). Upgrade in the dashboard.

Plan rate limits

rateLimitRpm and rateLimitBurst set the tenant-wide request bucket shared by all API keys. The live values are always visible in the X-RateLimit-* headers — see Rate limits.

Build for limits from day one

• Treat 402 as an expected, recoverable condition; surface upgradeTo in your admin tooling.
• Watch transaction.created webhook volume against txIncludedMonthly to anticipate overage.
• Develop against a sandbox tenant; switch credentials for production — the API surface is identical.