Get Started in 5 Minutes

Follow this guide to add PaywallOS to your application.

1Get the PaywallOS Client

Copy lib/paywall-sdk.ts from the PaywallOS repo into your project. It uses @openverb/sdk under the hood. For external apps, pass baseUrl: 'https://paywallos.openverb.org' in the config.

npm install @openverb/sdk

2Get Your API Keys

Sign up at PaywallOS
Create a new app in the dashboard
Copy your API Key and App ID

3Add Environment Variables

Create a .env.local file:

NEXT_PUBLIC_PAYWALLOS_API_KEY=pk_live_...
NEXT_PUBLIC_PAYWALLOS_APP_ID=app_...

4Initialize PaywallOS

Call initPaywallOS once at app startup (e.g. in your root layout or main component):

import { initPaywallOS } from '@/lib/paywall-sdk'
import { useEffect } from 'react'

export default function RootLayout({ children }) {
  useEffect(() => {
    if (user) {
      initPaywallOS(
        process.env.NEXT_PUBLIC_PAYWALLOS_API_KEY,
        process.env.NEXT_PUBLIC_PAYWALLOS_APP_ID,
        user.id,
        user.tier ?? 'free'
      )
    }
  }, [user])
  
  return (
    <html>
      <body>{children}</body>
    </html>
  )
}

5Create Your Verb Library

Upload an OpenVerb JSON file in the dashboard:

{
  "namespace": "myapp.core",
  "version": "1.0.0",
  "verbs": [
    {
      "name": "export_data",
      "category": "file_system",
      "description": "Export user data to CSV"
    },
    {
      "name": "generate_report",
      "category": "analysis",
      "description": "Generate analytics report"
    }
  ]
}

💡 Tip: Use the AI Assistant in the dashboard to generate this automatically!

6Add Verb Attributes

Add verb= to any element:

// Buttons
<button verb="export_data">
  Export to CSV
</button>

// Links
<a href="/reports" verb="generate_report">
  Generate Report
</a>

// Divs (entire sections)
<div verb="premium_features">
  <AdvancedDashboard />
</div>

✓Done!

PaywallOS now automatically enforces access based on user tiers. No additional code needed!