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

# Quickstart

<Note>
  Swap your OpenAI client base URL and key, include a stable user id, and you
  can charge for usage in minutes.
</Note>

<Steps>
  <Step title="Create a paywall & choose mode">
    Create a paywall in the [dashboard](https://dashboard.paywalls.ai) and choose your mode. This sets how money flows and cannot be changed later.

    * <strong>Default (App‑scoped wallet)</strong> — You collect payments directly (e.g., Stripe or your own rails). Users’ balances live in your app’s scope. You credit balances via Deposit API and charges deduct from that balance. No end‑user authorization step.

    * <strong>Shared (Cross‑app wallet)</strong> — Paywalls hosts a user‑controlled wallet that can be spent across apps. Users authorize your paywall. You earn per usage and later withdraw. End‑user authorization required.

    <Card title="Choose a mode" href="/how-to-guides/choose-a-mode" icon="wallet">
      Compare Default vs Shared mode, trade‑offs, and examples.
    </Card>
  </Step>

  <Step title="Configure a model provider">
    <Tabs>
      <Tab title="Default mode (required)">
        Connect a provider via BYOK. Works with OpenAI, TogetherAI, OpenRouter, or any OpenAI‑compatible API.

        <Columns cols={2}>
          <Card title="Model providers" href="/core-concepts/model-providers" icon="cpu">
            Model selection & routing
          </Card>

          <Card title="Paywalls Proxy" href="/core-concepts/proxy" icon="cloud">
            OpenAI-compatible proxy
          </Card>
        </Columns>
      </Tab>

      <Tab title="Shared mode (optional)">
        Use the built‑in provider (powered by OpenRouter) with no setup, or connect your own keys.

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

          <Card title="Paywalls Proxy" href="/core-concepts/proxy" icon="cloud">
            OpenAI-compatible proxy
          </Card>
        </Columns>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Configure payments / top‑ups">
    <Tabs>
      <Tab title="Default mode">
        Paste a <em>restricted</em> Stripe API key in the
        dashboard. Paywalls auto‑creates checkout links and subscribes to webhooks to
        credit balances. Or use custom rails and [call Deposit API](/api-reference/user/balance/deposit/post) after you receive
        funds.

        <Columns cols={2}>
          <Card title="Connect Stripe" href="how-to-guides/connect-stripe" icon="credit-card">
            Fast path with Stripe test/live keys.
          </Card>

          <Card title="Test keys & environments" href="more/test-keys-and-environments" icon="flask-round">
            How to test end‑to‑end safely.
          </Card>
        </Columns>
      </Tab>

      <Tab title="Shared mode">
        No payment setup required — Paywalls hosts top‑ups. Users fund their shared wallet; your earnings accrue for withdrawal.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Copy API key & base URL; make your first request">
    Grab your paywall API key (sk‑paywalls‑…) and point your OpenAI client at the Paywalls base URL.

    <Info>
      Always include a stable, pseudonymous user id: body <code>user</code> (recommended) or header <code>X‑Paywall‑User</code>. Keep your key server‑side.
    </Info>

    <Tabs>
      <Tab title="Node (OpenAI SDK)">
        ```ts theme={null}
        import OpenAI from "openai";
        const client = new OpenAI({
          apiKey: process.env.PAYWALLS_API_KEY, // sk-paywalls-...
          baseURL: "https://api.paywalls.ai/v1",
        });
        const resp = await client.chat.completions.create({
          model: "openai/gpt-4o-mini",
          user: "user_123",
          messages: [{ role: "user", content: "Hello!" }],
        });
        console.log(resp.choices[0]?.message?.content);
        ```
      </Tab>

      <Tab title="Python (OpenAI SDK)">
        ```python theme={null}
        from openai import OpenAI
        import os
        client = OpenAI(api_key=os.environ["PAYWALLS_API_KEY"], base_url="https://api.paywalls.ai/v1")
        resp = client.chat.completions.create(
            model="openai/gpt-4o-mini",
            user="user_123",
            messages=[{"role": "user", "content": "Hello!"}],
        )
        print(resp.choices[0].message.content)
        ```
      </Tab>

      <Tab title="fetch (JS)">
        ```js theme={null}
        const r = await fetch("https://api.paywalls.ai/v1/chat/completions", {
          method: "POST",
          headers: {
            Authorization: `Bearer ${process.env.PAYWALLS_API_KEY}`,
            "Content-Type": "application/json",
            "X-Paywall-User": "user_123",
          },
          body: JSON.stringify({
            model: "openai/gpt-4o-mini",
            messages: [{ role: "user", content: "Hello!" }],
          }),
        });
        const json = await r.json();
        ```
      </Tab>

      <Tab title="cURL">
        ```bash theme={null}
        curl https://api.paywalls.ai/v1/chat/completions \
          -H "Authorization: Bearer $PAYWALLS_API_KEY" \
          -H "Content-Type: application/json" \
          -d '{
            "model":"openai/gpt-4o-mini",
            "user":"user_123",
            "messages":[{"role":"user","content":"Hello!"}]
          }'
        ```
      </Tab>
    </Tabs>

    <Columns cols={2}>
      <Card title="Pass user id" href="how-to-guides/pass-user-id" icon="user">
        All supported methods and client examples.
      </Card>

      <Card title="Client SDKs" href="sdk-integrations/client-sdks" icon="boxes">
        Node, Python, Go, .NET, cURL, and more.
      </Card>
    </Columns>
  </Step>

  <Step title="Understand responses & next steps">
    <Tabs>
      <Tab title="Default mode">
        * Paywall‑required flows arrive as normal assistant messages — render them as any chat reply.
        * If the user must top up, the message already includes the link. After completion, the next requests proceed normally.
        * Stripe webhooks auto‑deposit into the app‑scoped balance.
      </Tab>

      <Tab title="Shared mode">
        * Paywall‑required flows arrive as normal assistant messages — render them as any chat reply.
        * If the user must authorize or top up, the message already includes the link. After completion, the next requests proceed normally.
        * Charges deduct from the shared wallet; your earnings accrue for withdrawal.
      </Tab>
    </Tabs>

    <Columns cols={2}>
      <Card title="Request Lifecycle" href="core-concepts/request-lifecycle" icon="git-compare-arrows">
        How requests are processed, metered, and charged.
      </Card>

      <Card title="Monetization recipes" href="how-to-guides/use-case-monetization-recipes" icon="hand-coins">
        Common patterns and examples.
      </Card>
    </Columns>
  </Step>
</Steps>