Quickstart

1

Create a paywall & choose mode

Create a paywall in the dashboard and choose your mode. This sets how money flows and cannot be changed later.

Default (App‑scoped wallet) — 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.
Shared (Cross‑app wallet) — 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.

Choose a mode

Compare Default vs Shared mode, trade‑offs, and examples.

2

Configure a model provider

Default mode (required)
Shared mode (optional)

Connect a provider via BYOK. Works with OpenAI, TogetherAI, OpenRouter, or any OpenAI‑compatible API.

Model providers

Model selection & routing

Paywalls Proxy

OpenAI-compatible proxy

3

Configure payments / top‑ups

Default mode
Shared mode

Paste a restricted 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 after you receive funds.

Connect Stripe

Fast path with Stripe test/live keys.

Test keys & environments

How to test end‑to‑end safely.

4

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.

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

Node (OpenAI SDK)
Python (OpenAI SDK)
fetch (JS)
cURL

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);

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)

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();

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!"}]
  }'

Pass user id

All supported methods and client examples.

Client SDKs

Node, Python, Go, .NET, cURL, and more.

5

Understand responses & next steps

Default mode
Shared 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.

Request Lifecycle

How requests are processed, metered, and charged.

Monetization recipes

Common patterns and examples.

Getting started

Core concepts

How‑to guides

SDKs & Integrations

More

Choose a mode

Model providers

Paywalls Proxy

Model providers

Paywalls Proxy

Connect Stripe

Test keys & environments

Pass user id

Client SDKs

Request Lifecycle

Monetization recipes