> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paywalls.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Paywalls, Wallets & Ledger

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

<Tabs>
  <Tab title="Default mode">
    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.
  </Tab>

  <Tab title="Shared mode">
    Real funds live in a user‑controlled wallet that works across any
    Paywalls‑enabled app. Users authorize your paywall, top up once, and spend
    anywhere. Best for ecosystems and marketplaces.
  </Tab>
</Tabs>

### Ledger

Every monetary event becomes a **ledger entry** (immutable). Typical entry types:

<Tabs>
  <Tab title="Default mode">
    * `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).
  </Tab>

  <Tab title="Shared mode">
    * `charge` — usage‑based deduction linked to a specific request (request\_id, model, token stats).

    * `withdraw` — developer‑initiated payout of earnings.
  </Tab>
</Tabs>

<Info>
  Each entry records **timestamp, paywall id, user id, amount and metadata**.
</Info>

### Money flow

<Tabs>
  <Tab title="Default mode">
    End‑user pays **you** (Stripe/custom). You pay the model provider via
    **BYOK**. Paywalls meters, enforces pricing, and writes the ledger.
  </Tab>

  <Tab title="Shared mode">
    End‑user funds their **shared wallet**. Paywalls settles the **provider
    cost** (built‑in provider or BYOK) and credits your **developer earnings**;
    you **withdraw** later.
  </Tab>
</Tabs>

### 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.