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

# Proxy

The **proxy** is the drop‑in, OpenAI‑compatible layer that **enforces pricing and authorization**, **meters usage**, and **returns paywall‑aware assistant messages**. It dramatically simplifies setup because you **don’t need to build billing branches** in your app.

<Note>
  **Optional but recommended:** You can call Paywalls APIs directly for non‑chat
  features (e.g., manual charges). For chat usage, the proxy gives you the
  fastest path to a working, billable flow without custom billing code.
</Note>

### Why use the proxy?

* **Zero‑branching UX** — When a user must authorize or top up, the proxy replies with a **normal assistant message** containing the correct link. You just render what you get.
* **One client surface** — Keep using OpenAI SDKs and tools; change only the **base URL** and **key**.
* **Consistent metering** — Requests are normalized, streamed tokens are measured, and pricing is applied centrally.
* **Provider flexibility** — Swap models/providers without rewriting your app or pricing logic.
* **Central guardrails** — Spend caps, token caps, and rate limits enforce your rules before provider calls.

### What the proxy does

* **Compatibility** — Accepts OpenAI‑style Chat Completions (incl. streaming, function/tool calls, JSON modes). *(Modalities beyond text are roadmap‑dependent.)*
* **Decisioning** — Checks authorization (Shared), balance, and limits; decides whether to **return a link** or **execute** the request.
* **Routing** — Forwards eligible requests to the selected provider (BYOK or built‑in) and proxies the stream back to you.
* **Metering & pricing** — Counts tokens, computes charges, and writes **ledger** entries.
* **Observability** — Attaches a **request id** and correlates ledger entries and events for support/analytics.

### Request lifecycle

<Steps>
  <Step title="Request">
    Your app calls the OpenAI‑compatible endpoint with a **paywall key** and a
    user id.
  </Step>

  <Step title="Decision">
    The proxy evaluates **authorization** (Shared), **balance**, **limits**, and
    **pricing** rules.
  </Step>

  <Step title="If action is needed">
    The response is a normal **assistant message** containing an **authorization**
    or **checkout** link. You render it as‑is; no special branching.
  </Step>

  <Step title="Execution">
    If authorized & funded, the request is forwarded to the configured
    **provider** (BYOK or built‑in). Streaming is passed through.
  </Step>

  <Step title="Meter & bill">
    — Token usage is measured; the applicable pricing rule computes the charge. A
    **charge** entry is written to the **ledger**.
  </Step>
</Steps>

### Security expectations

* Your **paywall API key** must remain **server‑side**.
* Always include a stable `user` id to prevent cross‑account leakage and enable correct limits.
* Use **idempotency keys** for your own side‑effecting calls (e.g., manual charges) to avoid duplicates.

### Performance & limits

* Streaming is proxied with minimal overhead; if a stream drops, clients may reconnect and retry safely.
* Rate limits and concurrency caps protect your app and budget. *(soon)*

<Card title="Model providers" href="/how-to-guides/byok-vs-built-in-provider" icon="cpu">
  BYOK vs Built-in Provider
</Card>