billing
usage-based billing, built in
metered auto-topup or prepaid credits, team and per-app spending limits, and a wallet ui that opens itself when a request runs out of funds.
import { useWallet } from "@hyperyai/sdk" export function Billing() { const { wallet, addFunds, addPaymentMethod } = useWallet() if (!wallet) return null return wallet.paymentMethod.exists ? <button onClick={() => addFunds(50)}>add $50</button> : <button onClick={addPaymentMethod}>add a card</button>} how it works
two ways to pay, one wallet
pick metered for hands-off billing or prepaid for a fixed budget. either way, credits and limits are enforced before a provider is ever called.
metered auto-topup
the default — keep a small balance and the card is auto-charged when it dips.
prepaid credits
buy credits up front for a fixed, no-surprises budget.
credits at 100 per $1
a simple display unit — $10 shows as 1,000 credits.
team spending limits
a pooled balance with a hard cap for the whole team.
per-app spending limits
cap each authorized app independently of the rest.
auto modals on 402 / 429
the funds modal opens on out-of-funds or limit-hit responses.
react sdk
wallet ui without the plumbing
useWallet reads the balance and payment method and hands you addFunds and addPaymentMethod — no stripe wiring in your app.
- useWallet() returns { wallet, addFunds, addPaymentMethod }
- wallet.paymentMethod.exists tells you whether a card is on file
- addFunds(amount) and addPaymentMethod() open the hosted flows
import { useWallet } from "@hyperyai/sdk" export function Billing() { const { wallet, addFunds, addPaymentMethod } = useWallet() if (!wallet) return null return wallet.paymentMethod.exists ? <button onClick={() => addFunds(50)}>add $50</button> : <button onClick={addPaymentMethod}>add a card</button>} restrictions
modals that open themselves
mount <HyperyModals /> once and hypery handles the interrupt path — a 402 opens the add-funds flow, a 401 re-authenticates the user.
- <HyperyModals /> and <RestrictionModal /> ship with the sdk
- the funds modal opens on a 402 (out of funds)
- re-auth opens on a 401, and 429 surfaces limit-hit prompts
import { HyperyProvider, HyperyModals } from "@hyperyai/sdk" <HyperyProvider config={config}> <HyperyModals /> {/* opens the funds modal on a 402, re-auth on a 401 */} {children}</HyperyProvider> faq
questions
how are credits priced?
credits display at 100 per $1, so a $10 balance shows as 1,000 credits. usage draws down the balance as requests hit providers.
what is metered auto-topup?
the default, vercel-style mode: keep a small credit balance and hypery auto-charges the card on file whenever it dips. prepaid — buy credits up front — is also supported.
can users cap spend per app?
yes. teams get a pooled balance with per-app spending limits, so an authorized app can be hard-capped independently of the rest of your usage.
what happens when funds run out?
a 402 (out of funds) or 429 (limit hit) response triggers the built-in modals — <HyperyModals /> opens the add-funds flow so the user can top up without leaving your app.