Quickstart: Licensed Content Access in 5 Minutes

Fetch articles, pages, and other publisher content that is cleaned, optimized for LLM consumption, and fully licensed. No scraping, no legal gray areas — every response is a legitimate content transaction between your wallet and the publisher.

Install the SDK, register your device, fund your wallet, and make your first licensed content fetch — all from the terminal. No dashboard required.

This guide is for developers building AI agents, LLM pipelines, or automated tools that need licensed access to web content through the paywalls.net Web Content Marketplace.

Prerequisites

• Node.js 18+ (for built-in fetch)
• A terminal (macOS, Linux, or Windows)

Step 1: Install

npm install -g @paywalls-net/access

This adds the paywalls command to your PATH. Verify it works:

paywalls --help

Expected output:

paywalls — Developer CLI for paywalls.net Web Content Marketplace
Usage: paywalls <command> [options]

Commands:
  register    Register a new device and obtain an API key
  balance     Check your wallet balance
  topup       Add funds to your wallet (alias: fund)
  receipts    View recent transaction receipts
  doctor      Diagnose configuration and connectivity issues

Options:
  --help      Show this help message
  --version   Show version
  --headless  Disable color, browser auto-open, and interactive prompts
  --json      Output machine-readable JSON (implies --headless)

Get started:
  paywalls register
  paywalls balance

Prefer npx? Every command also works with npx @paywalls-net/access <command> — no global install needed.

Step 2: Register

paywalls register

The CLI generates a device code and opens your browser:

Registering device...
Your code is: WDJB-WNRH
Open this URL to authorize:
  https://paywalls.net/device?code=WDJB-WNRH
Waiting for authorization... (expires in 15 minutes)

Approve the code in your browser. The CLI detects this automatically:

..........
✓ Authorized!
  API Key:  FL0QCW-01-MLYIB66U
  Account:  ABUI8C-01-MLYIB66L
Saved to ~/.config/paywalls/credentials.json
Next steps:
  paywalls balance     Check your wallet balance
  paywalls topup       Add funds to your wallet

Your API key is now stored at ~/.config/paywalls/credentials.json. The SDK loads it automatically — no manual config needed.

Running in CI or SSH? Use --headless to get a URL you can open manually. Headless mode is auto-detected in CI environments, SSH sessions, and GitHub Codespaces.

If it fails:

• paywalls doctor diagnoses exactly what went wrong
• paywalls register --force overwrites existing credentials
• Network issues? Check paywalls doctor --json for detailed connectivity info

Step 3: Verify Setup

paywalls doctor

Expected output:

Paywalls Developer Environment Check
=====================================

✓ Configuration
  Api Key Prefix  :  FL0QCW-0…
  Api Key Source  :  credentials_file
  Base Url        :  https://api.paywalls.net

✓ Connectivity
  Url             :  https://api.paywalls.net
  Status          :  200
  Latency Ms      :  45

✓ Authentication
  Account Id      :  ABUI8C-01-MLYIB66L
  Account Name    :  Developer Account
  Account Status  :  active

✓ Wallet
  Balance         :  500000
  Balance Formatted:  $5.00
  Status          :  active

✓ Agent
  Count           :  1

5/5 checks passed.

Doctor runs five independent checks. If any check fails, it prints a Fix: message with the exact CLI command to resolve it — copy-paste and go.

Step 4: Fund Your Wallet

paywalls topup

Then verify:

paywalls balance

Expected output:

✓ Balance: $5.00
  Account:    ABUI8C-01-MLYIB66L
  Millicents: 500,000
  Currency:   USD

Balances are tracked in millicents (1/1000 of a cent) for precision. $5.00 = 500,000 millicents.

Step 5: First Licensed Fetch

Now make your first licensed content request:

node -e "
const { ApiClient } = require('@paywalls-net/access');
const client = new ApiClient();
client.get('/access/https://example.com/article').then(r => {
  console.log('Status:', r.status);
  console.log('OK:', r.ok);
  console.log('Data:', JSON.stringify(r.data).slice(0, 200));
});
"

Expected output:

Status: 200
OK: true
Data: {"title":"Example Article","content":"..."}

The content is licensed and billed from your wallet automatically. Check your balance or receipts to see the transaction:

paywalls receipts --limit=1

Using the SDK in Your Project

The SDK serves two purposes:

• Manage your account — check your wallet balance, view transaction receipts, and monitor usage programmatically.
• Access web content — fetch articles, pages, and other publisher content that is cleaned, optimized for LLM consumption, and fully licensed. No scraping, no legal gray areas — every response is a legitimate content transaction between your wallet and the publisher.

Add @paywalls-net/access to your project:

npm install @paywalls-net/access

TypeScript / ESM

import { ApiClient } from '@paywalls-net/access';

const client = new ApiClient();  // auto-loads credentials

// Manage your account
const balance = await client.get('/api/wallet/balance');
console.log(balance.data);

// Access licensed web content — cleaned and optimized for LLMs
const page = await client.get('/access/https://example.com/article');
console.log(page.status);  // 200
console.log(page.data);    // article content

CommonJS

const { ApiClient } = require('@paywalls-net/access');

const client = new ApiClient();
const page = await client.get('/access/https://example.com/article');

Configuration Options

// Explicit configuration (overrides credential file)
const client = new ApiClient({
  apiKey: process.env.PAYWALLS_API_KEY,
  baseUrl: 'https://api.paywalls.net',
});

Configuration is resolved in this order:

1. Environment variables: PAYWALLS_API_KEY, PAYWALLS_BASE_URL
2. .env file in your working directory
3. Credentials file: ~/.config/paywalls/credentials.json
4. Constructor params: inline overrides

Headless / CI Mode

For automated pipelines, use --headless for registration and --json for machine-readable output:

# Register in CI (outputs URL to open manually)
paywalls register --headless --json

# Verify setup (parseable by scripts and LLM agents)
paywalls doctor --json

# Check balance programmatically
paywalls balance --json | jq '.balance_formatted'

Headless mode is auto-detected when:

• CI environment variable is set
• Running in an SSH session
• Running in GitHub Codespaces
• stdout is not a TTY

Troubleshooting

Quick Diagnostic

paywalls doctor --json

Every failure includes a suggestedFix field with the exact CLI command to resolve it.

Common Issues

Environment Variables

What's Next

• View receipts: paywalls receipts — see all your content access transactions
• Integration guide: AI Company Integration Guide for deeper integration details
• API reference: API Reference for endpoint documentation