The Subscription Model & Tiers

What you’ll get here

how a subscription comes into existence, the deposit-backed model behind it, and the four real tiers with the exact per-service allowances the code enforces.

You don’t “buy minutes” on Smart Engines. You pick a tier, lock a deposit in HSUITE that acts as collateral and balance, and the cluster mints you a subscription NFT. From then on the tier’s rules govern what you can do. This page explains the model, then lays out the tiers exactly as they’re defined in code.

Note

Pricing is monthly USD. Each tier carries a monthlyPriceUsd headline price; the HSUITE deposit is the USD price converted to HSUITE at request time. The four tiers form the ladder builder → growth → scale → enterprise. There is no free tier — every connection is paid.

🧠 For Normies

A deposit isn’t a fee you lose — it’s collateral that doubles as your prepaid balance. Your tier sets the rules (how many calls a day, how much storage and bandwidth); the deposit funds the work.

---

How a subscription is created

A developer calls POST /api/v3/subscription/request (or runs hsuite subscribe) with an appId, a tier, the deposit chain, the networks they want, and optionally a paymentAsset. Every tier is paid, so there is a single path:

• All tiers (builder | growth | scale | enterprise) — the cluster spins up a TSS-controlled deposit wallet and returns deposit instructions. The subscription sits at PENDING_DEPOSIT until the HSUITE deposit is confirmed on-chain, then it can be activated and the NFT minted.

Note

The legacy “create ACTIVE immediately, no deposit” testnet on-ramp has been removed. Builder (the lowest tier, $49/mo) is the entry point.

🧠 For Normies

TSS-controlled means the deposit wallet isn’t held by any one machine’s private key. It’s controlled by a threshold of validators signing together, so no single operator can run off with your collateral.

flowchart LR
    A["request(tier)"] --> D["create TSS deposit wallet<br/>amount = monthlyPriceUsd → HSUITE"]
    D --> E["PENDING_DEPOSIT"]
    E -->|"deposit confirmed"| F["DEPOSIT_CONFIRMED"]
    F -->|"activate → mint NFT"| G["ACTIVE"]

The deposit amount for a tier is the tier’s monthlyPriceUsd converted to an HSUITE amount at request time (on XRPL in whole HSUITE: HST has no decimals), using the platform’s single canonical HSUITE/USD rate (see One rate for the whole platform). That conversion is locked into a price-locked order at request time (see The price-locked order), so the HSUITE amount you owe is fixed until the order expires.

The XRPL reserve surcharge

When the deposit chain is XRPL, the deposit wallet is a real on-chain account, and XRPL requires every account to hold a small base reserve in XRP just to exist. The protocol Treasury fronts that reserve when it creates the account — but the cost is borne by the payer (the developer opening the subscription), not absorbed by the Treasury.

It’s billed as an HST surcharge inside the single deposit payment. The deposit instructions quote one amount to send, with the reserve broken out as its own line item (baseAmount plus reserveSurcharge). The surcharge is priced at the chain edge — the Treasury’s measured XRP outlay (the reserve plus the multisig-account creation fee) converted at the live AMM HST-per-XRP rate — so this layer never hard-codes XRPL reserve arithmetic. You still make one HST payment.

The surcharge is not customer credit. It is subtracted before the deposit funds your float — fundedAmount and remainingBalance are seeded from the base amount only — and on settlement it is paid 100% to the Treasury, outside the 40/40/20 burn/runners/treasury split, because it reimburses an XRP cost the Treasury actually spent. The CLI (hsuite subscribe) prints the base and the surcharge as separate lines so the breakdown is visible before you pay.

🧠 For Normies

Opening an XRPL account costs a tiny bit of XRP that the account must always keep on hand. The platform pays that up front, then adds the equivalent in HSUITE to your deposit as a clearly-labelled line item — you pay once, in HSUITE. That piece isn’t spending money for you (it doesn’t go into your prepaid balance); it just pays back what the platform laid out to create your account.

---

The price-locked order (quote)

When you call POST /api/v3/subscription/request, the cluster doesn’t just hand back a wallet address and a number — it mints a price-locked order (a quote) and returns its details inside the deposit instructions. The order locks the HSUITE/USD rate at order time, so the fiat-equivalent price you owe is fixed until the order expires. These fields are frozen at quote time and never change afterward:

Locked field	What it fixes
priceUsd	The USD figure the quote was priced against (the full tier price for subscribe/topup, the tier delta for upgrade).
rate	The HSUITE/USD snapshot used — its decimal value, its source (amm | book | fallback), and when it was sampled.
hsuiteDue	The base HSUITE owed (smallest units), derived from priceUsd at the locked rate.
pay.amount	The total to send — base hsuiteDue plus any reserve surcharge.
destinationTag	A unique tag your payment must carry so the cluster can match it to this order.
expiresAt	When the quote lapses — default 30 minutes after it’s created.

Caution

The payment you send must carry the order’s destinationTag. Verification matches an incoming payment to an order by that tag and by the amount actually delivered — never by the amount the transaction claims to send (on XRPL a partial payment can claim one figure and deliver less, so the delivered amount is the only honest measure). A payment that reaches the locked total activates the subscription; a short payment leaves the order underpaid; a quote whose window passes with nothing (or too little) attributed goes expired.

An expired or underpaid order isn’t a dead end. You can re-quote it (POST /api/v3/subscription/orders/:orderId/requote): that creates a fresh order at the current rate for the same locked priceUsd, inheriting the original destinationTag, so whatever you’d already paid still counts toward the new quote and you only owe the remainder. Re-running the subscribe flow for the same app does the same thing automatically — a lapsed quote is re-quoted rather than handing you stale, untagged instructions.

Reading or re-quoting an order is owner-only: the caller must own the order’s app (resolved against the app’s registered developer wallet), and an order you don’t own answers exactly like an unknown order id — a flat “not found”, never a hint that it exists.

🧠 For Normies

A quote is a 30-minute price hold. The moment you ask to subscribe, the platform works out how much HSUITE your plan costs at today’s rate and locks that number in — it won’t move while the quote is alive. Your payment has to carry a little reference number (the destination tag) so the platform knows which quote it’s for. If the 30 minutes run out before you pay, you don’t start over from scratch: the platform re-prices the same plan at the current rate, keeps your reference number, and only asks for whatever’s still owed.

---

Reading your billing history

Every deposit you make — the initial subscribe, an upgrade top-up, a same-tier topup, a renew — is an order, and GET /api/v3/subscription/billing/:appId projects those orders into a durable billing history for the app. Each entry carries what was paid and against which locked quote:

Field	What it holds
operation	subscribe, upgrade, topup, renew, or credit (an operator-recorded credit for a payment no order counted).
status	The order’s status (fulfilled, underpaid, paid/converting for an XRP order awaiting conversion, quoted/awaiting_payment), or credited.
tier / priceUsd	The tier the quote was priced for and its locked USD price (absent on a credit).
asset / amount	What was paid in (HSUITE, or XRP for an XRP order) and the exact amount that reached the deposit account.
hsuiteCredited	For an XRP order, the HST its conversion delivered into the deposit account.
txHashes / account / timestamp	The ledger transactions behind the entry, the deposit account that received it, and when the last payment closed.

This is durable and replicated, not an in-memory tally: it is projected from the app’s order records (each replicated to every cluster, its payments re-checked against the receiving cluster’s own ledger read before storage) plus any operator float credits recorded on the subscription.

Note this is the deposit/order billing history — what you paid in. Per-op usage charges are a separate thing: they are metering, kept in each validator’s charge ledger, not part of this replicated billing record (see Gating & quotas → Balance debiting).

🧠 For Normies

This is your receipt book: every payment you made to top up or renew your plan, with the amount, the token, and the on-chain transaction behind it. It’s stored durably and the same on every server — not a scratchpad that disappears when a server restarts. (What you spent on usage is tracked separately.)

---

One rate for the whole platform

Every part of the platform that needs to know what one HSUITE is worth in USD reads the same canonical rate — the one the validator derives from the XRPL on-ledger market: an AMM time-weighted price first (source: amm), the order book next (source: book), and a configured fallback only if neither is reachable (source: fallback). The host and gateway tiers fetch that value from the validator rather than computing their own.

This matters because it removes disagreement: the rate that prices your deposit, the rate that prices per-op usage, and the rate the host and gateway use are now one and the same number, cached briefly and served fail-soft (a stale-but-recent value, then the fallback, is served rather than failing a pricing call). There is no third-party price feed in the loop.

🧠 For Normies

Everything that converts between HSUITE and dollars now looks at one shared price ticker instead of each piece guessing on its own. So the number you see when you subscribe, the number behind your usage charges, and the numbers the rest of the platform uses all agree.

---

Paying in something other than HSUITE

Subscriptions are priced in USD and paid in HSUITE today; paying in XRP is built, not yet enabled. The request accepts an optional paymentAsset (either { "symbol": "HSUITE" } or the bare string "HSUITE"), and HSUITE is accepted only on the chains the asset registry lists it for (XRPL today). If you name any other asset, the request is refused with an honest “not yet supported” error rather than silently accepting it and then handing you HSUITE payment instructions. Omitting paymentAsset entirely is the normal path and bills in HSUITE.

🧠 For Normies

Right now you pay in HSUITE, full stop. If you ask to pay in something else, the platform tells you plainly that it isn’t supported yet — it won’t take the request and then quietly switch you to HSUITE behind your back.

---

The four tiers

These are the only tiers the system recognizes: builder, growth, scale and enterprise. GET /api/v3/subscription/tiers returns them.

Each tier carries a USD headline price and a per-service allowance block (services) covering validator, host, gateway, ipfs, harbor, and smartAgents. Allowances are expressed per month.

	Builder	Growth	Scale	Enterprise
Tier id	builder	growth	scale	enterprise
Monthly price (USD)	$49	$199	$999	$2,500
Support level	community	email	priority	dedicated
Allowed networks (declared)	mainnet, testnet, previewnet	mainnet, testnet, previewnet	mainnet, testnet, previewnet	mainnet, testnet, previewnet

Per-service allowances (services, monthly)

Service / allowance	Builder	Growth	Scale	Enterprise
validator · txns / mo	250,000	2,500,000	25,000,000	Unlimited
validator · entities	10	100	1,000	Unlimited
validator · signs / mo	500,000	5,000,000	50,000,000	Unlimited
host · db ops / mo	5,000,000	50,000,000	500,000,000	Unlimited
host · storage (GB)	25	250	2,048	Unlimited
host · fn invocations / mo	2,000,000	25,000,000	250,000,000	Unlimited
host · app slots	3	25	250	Unlimited
gateway · bandwidth (GB)	250	2,048	20,480	Unlimited
gateway · domains	1	10	50	Unlimited
ipfs · pinned (GB)	50	500	5,120	Unlimited
harbor · private repos	5	25	100	Unlimited
harbor · image storage (GB)	10	100	1,024	Unlimited
smartAgents · agents	2	20	200	Unlimited
smartAgents · executions / mo	50,000	1,000,000	20,000,000	Unlimited

Note

The numeric allowances are first-pass and tunable. “Unlimited” means no cap: every Enterprise allowance is unlimited. gateway.domains is a count of attachable custom domains: any tier with domains > 0 may attach BYO custom domains (Builder onward, since Builder grants 1). The ipfs pinned allowance is declared but not enforced: app storage never goes to IPFS, and the storage allowance that is enforced is host storage.

Per-day rate limits are derived from these monthly allowances: the monthly figure divided by 30 (see Gating & quotas).

Feature flags per tier

Each tier also declares a features array, returned by GET /api/v3/subscription/tiers. These flags describe the tier; no request is gated on them today. The capability limits that are enforced are listed in Gating & quotas.

Feature flag	Builder	Growth	Scale	Enterprise
testnet_access	✓	✓	✓	✓
mainnet_access	✓	✓	✓	✓
basic_api	✓	✓	—	—
advanced_api	—	—	✓	✓
usage_analytics	—	✓	✓	✓
webhook_notifications	—	—	✓	✓
custom_rate_limits	—	—	✓	✓
sla_guarantee	—	—	—	✓
dedicated_infrastructure	—	—	—	✓
custom_integrations	—	—	—	✓
Support flag	community_support	email_support	priority_support	dedicated_support

🧠 For Normies

The tier is more than a price. It’s a bundle of per-service allowances: how many transactions and signatures the validator handles, how much you can store and how many functions you can run on the host, how much bandwidth and how many domains on the gateway, your Harbor repos, and your smart-agent budget — plus what kind of support you get. Pick the bundle, not just a number.

---

Networks: who reaches mainnet

Every tier — Builder included — declares mainnet, testnet, and previewnet in its allowedNetworks, and no request is checked against that list today. So there is no network fence between tiers: the entry tier is a paid connection on the same footing as the others. Mainnet itself has no launch date yet.

🧠 For Normies

The tiers differ on how much you can do (per-service allowances) and what support you get, not on which networks you can reach.

---

What the deposit funds

The confirmed deposit is a prepaid float — it stays in the deposit account and seeds the subscription’s fundedAmount and remainingBalance (on XRPL, net of the reserve surcharge, which is not credit). The monthly tier price is the credit that funds that float, not a separate charge; only per-op usage draws it down.

Per-request metering accrues usage and debits the balance (see Gating & quotas), and accrued usage is settled out of the deposit account in batched 40/40/20 sweeps rather than draining the whole deposit up front.

Unspent float rolls over at renewal, capped at 3× the tier’s monthly credit (see Renewal lifecycle). A float that drains mid-period can also be re-funded in place — same tier, no renewal — via a same-tier top-up (hsuite topup), which adds spendable balance without moving the deposit bond (see Same-tier top-up).

When the lock period lapses, the subscription stops being valid (see Gating & quotas) — a drained balance alone does not: per-request admission is not balance-gated, only overage charging is. There is no route yet to cancel a paid subscription and release its collateral (see Renewal lifecycle → Cancel).

🧠 For Normies

Think of the deposit as a prepaid wallet that the monthly price tops up. You spend it as you use the platform; what you don’t use rolls over (up to three months’ worth). It isn’t a fee that’s gone the moment you pay it.

---

Next steps

NFT membershipsSee the proof object.

Gating & quotasSee how the tier is enforced at runtime.

Renewal lifecycleSee how it stays alive over time.

TokenomicsHSUITE economics.