A Paywall is a named, versioned configuration that defines how usage turns into money for a given product or assistant. It binds together:
  • Mode (Default or Shared) — where balances live and who controls funds.
  • Pricing rules — per‑request, per‑token, hybrid, and optional free credits.
  • Provider access — BYOK keys and routing, or the built‑in provider (Shared mode).
  • Payment rails — automated Stripe checkout (Default) or hosted top‑ups (Shared).
  • Runtime rules — spend caps, token caps, concurrency, and rate limits.

​
Wallet

Each user gets a virtual balance. Credits live in your app’s scope. You decide when/how to top up (Stripe or custom rails), and charges deduct from this balance. Best for single‑app products, B2B contracts, and cases where you own refund policies.

​
Ledger

Every monetary event becomes a ledger entry (immutable). Typical entry types:
  • deposit (developer‑initiated) — credit a user after your custom PSP confirms payment.
  • charge — usage‑based deduction linked to a specific request (request_id, model, token stats).
Each entry records timestamp, paywall id, user id, amount and metadata.

​
Money flow

End‑user pays you (Stripe/custom). You pay the model provider via BYOK. Paywalls meters, enforces pricing, and writes the ledger.

​
Limits & controls (soon)

Apply per‑user or per‑paywall controls: daily spend caps, per‑request token caps, and concurrency caps. These guard your margins and keep UX predictable.