npm package: @pricedisco/paywall
Description: Universal payment firewall for Web3 - HTTP 402 done right
Author: Ignotus
Latest version: 1.0.0

# 🔒 Ignotus Paywall SDK

**HTTP 402 Payment Required - Actually Useful**

Universal payment firewall for Web3. Gate any content with crypto payments in 3 lines of code.

```html
<script src="https://cdn.ignotus.ai/paywall.js"></script>
<div data-ignotus-paywall data-amount="5" data-token="USDC">
  Your premium content here...
</div>
```

That's it! 🎉

---

## 🚀 Features

- ✅ **Zero Setup** - Works on any website
- ✅ **Multi-Chain** - Base, Ethereum, Optimism, Arbitrum, BSC, Solana
- ✅ **Auto-Verification** - Payment confirmed on-chain automatically
- ✅ **Session Persistence** - Pay once, access forever (or set expiration)
- ✅ **QR Codes** - Mobile-friendly payments
- ✅ **Wallet Connect** - MetaMask, Coinbase Wallet, etc.
- ✅ **Beautiful UI** - Pre-built payment modal
- ✅ **Framework Agnostic** - Vanilla JS, React, Vue, Svelte - works everywhere

---

## 📦 Installation

### Option 1: CDN (Quickest)

```html
<script src="https://cdn.ignotus.ai/paywall.js"></script>
<script>
  const paywall = window.IgnotusPaywall.create({
    agentId: 'your-agent-id',
    apiKey: 'ak_...',
    amount: '5',
    token: 'USDC',
    chain: 'base'
  });

  paywall.init();
</script>
```

### Option 2: NPM

```bash
npm install @ignotus/paywall ethers
```

```typescript
import IgnotusPaywall from '@ignotus/paywall';

const paywall = new IgnotusPaywall({
  agentId: 'your-agent-id',
  apiKey: 'ak_...',
  amount: '5',
  token: 'USDC',
  chain: 'base'
});

await paywall.init();
```

---

## 🎯 Quick Start

### 1. Get Your API Key

```bash
curl -X POST https://api.ignotusai.xyz/agent/keys/create \
  -H "Content-Type: application/json" \
  -d '{"agentId":"my-website"}'
```

### 2. Create Agent Wallet

```bash
curl -X POST https://api.ignotusai.xyz/agent/wallets/create \
  -H "X-API-Key: ak_..." \
  -H "Content-Type: application/json" \
  -d '{
    "agentId":"my-website",
    "networkId":"base"
  }'
```

### 3. Add to Your Website

```html
<!DOCTYPE html>
<html>
<head>
  <title>Premium Content</title>
</head>
<body>
  <h1>My Blog</h1>

  <!-- Free content -->
  <p>This is free to read...</p>

  <!-- Premium content (gated) -->
  <div data-ignotus-paywall
       data-amount="5"
       data-token="USDC"
       data-description="Premium Article Access">
    <h2>Premium Content 🔒</h2>
    <p>This exclusive content is only visible after payment...</p>
  </div>

  <!-- Include SDK -->
  <script src="https://cdn.ignotus.ai/paywall.js"></script>
  <script>
    const paywall = window.IgnotusPaywall.create({
      agentId: 'my-website',
      apiKey: 'ak_...',
      amount: '5',
      token: 'USDC',
      chain: 'base'
    });
    paywall.init();
  </script>
</body>
</html>
```

---

## 🎨 Use Cases

### Blog/Newsletter Paywall

```html
<article data-ignotus-paywall data-amount="2" data-token="USDC">
  <h1>Premium Article</h1>
  <p>Exclusive content for paying readers...</p>
</article>
```

### API Access Gate

```html
<div data-ignotus-paywall
     data-amount="10"
     data-token="USDC"
     data-description="API Credits - 10,000 requests">
  <pre>API Key: sk_live_abc123...</pre>
  <button>Generate New Key</button>
</div>
```

### Video/Course Content

```html
<video data-ignotus-paywall
       data-amount="49"
       data-token="USDC"
       data-description="Full Course Access">
  <source src="course-video.mp4" type="video/mp4">
</video>
```

### Download Gate

```html
<div data-ignotus-paywall
     data-amount="15"
     data-token="USDC">
  <a href="/downloads/ebook.pdf" download>
    Download Premium Ebook
  </a>
</div>
```

---

## ⚙️ Configuration

### All Options

```typescript
const paywall = new IgnotusPaywall({
  // Required
  agentId: 'your-agent-id',        // Your agent ID
  apiKey: 'ak_...',                 // API key from agent-api
  amount: '5',                      // Default amount

  // Optional
  token: 'USDC',                    // Default: USDC
  chain: 'base',                    // Default: base
  description: 'Premium access',   // Default description
  apiUrl: 'https://api.ignotusai.xyz'  // Default API URL
});
```

### Per-Element Configuration

```html
<!-- Override defaults per element -->
<div data-ignotus-paywall
     data-amount="10"
     data-token="DAI"
     data-description="Special Offer"
     data-content-id="article-123">
  Premium content...
</div>
```

---

## 🎭 Advanced Usage

### React Integration

```tsx
import { useEffect } from 'react';
import IgnotusPaywall from '@ignotus/paywall';

function PremiumArticle() {
  useEffect(() => {
    const paywall = new IgnotusPaywall({
      agentId: 'my-blog',
      apiKey: process.env.NEXT_PUBLIC_IGNOTUS_API_KEY!,
      amount: '5'
    });
    paywall.init();
  }, []);

  return (
    <div data-ignotus-paywall data-amount="5">
      <h1>Premium Article</h1>
      <p>Exclusive content here...</p>
    </div>
  );
}
```

### Programmatic Usage

```typescript
const paywall = new IgnotusPaywall(config);

// Protect specific element
const element = document.getElementById('premium-section');
await paywall.protectContent(element);

// Check if user has paid
const hasPaid = paywall.checkAccess('content-id');

// Manually unlock content
paywall.unlock('content-id');
```

### Custom UI

```typescript
// Use headless mode
const paywall = new IgnotusPaywall({
  ...config,
  headless: true  // Don't inject default UI
});

// Create payment link
const link = await paywall.createPaymentLink({
  amount: '10',
  description: 'Custom purchase'
});

// Build your own UI
document.getElementById('pay-btn').onclick = () => {
  window.open(link.url, '_blank');
};

// Check payment status
const status = await paywall.checkPayment(link.linkId);
```

---

## 🔧 API Reference

### `IgnotusPaywall`

#### Constructor

```typescript
new IgnotusPaywall(config: PaywallConfig)
```

#### Methods

**`init()`** - Initialize paywall on page
```typescript
await paywall.init();
```

**`protectContent(element)`** - Protect specific element
```typescript
await paywall.protectContent(document.getElementById('content'));
```

**`createPaymentLink(params)`** - Create payment link
```typescript
const link = await paywall.createPaymentLink({
  amount: '10',
  token: 'USDC',
  description: 'Premium access'
});
```

**`checkAccess(contentId)`** - Check if user paid
```typescript
const hasPaid = paywall.checkAccess('article-123');
```

**`unlock(contentId)`** - Manually unlock content
```typescript
paywall.unlock('article-123');
```

---

## 💳 Payment Flow

1. **User visits page** → Protected content is hidden
2. **Payment UI shown** → Beautiful modal with QR code + wallet option
3. **User pays** → Via wallet or QR code
4. **On-chain verification** → Payment confirmed automatically
5. **Content unlocked** → Session saved, content revealed
6. **Persistent access** → User can access content anytime (configurable)

---

## 🔐 Security

- ✅ **Non-custodial** - No private keys stored
- ✅ **On-chain verification** - All payments verified on blockchain
- ✅ **Session encryption** - Local sessions use secure storage
- ✅ **API key protection** - Keys scoped to specific agent
- ✅ **Rate limiting** - Built-in DDoS protection

---

## 🎨 Customization

### Custom Styles

```css
/* Override default styles */
.ignotus-paywall-modal {
  background: linear-gradient(135deg, #your-colors);
  border-radius: 24px;
}

.ignotus-btn-primary {
  background: #your-brand-color;
}
```

### Custom Messages

```html
<div data-ignotus-paywall
     data-amount="5"
     data-message="Support independent journalism for $5">
  Premium content...
</div>
```

---

## 📊 Analytics

Track payment events:

```typescript
paywall.on('payment_started', (data) => {
  console.log('Payment initiated:', data);
});

paywall.on('payment_completed', (data) => {
  console.log('Payment successful:', data);
  // Send to analytics
  analytics.track('Premium Content Purchased', data);
});
```

---

## 🌐 Supported Chains

- **Base** (recommended) - Lowest fees
- **Ethereum** - Maximum security
- **Optimism** - Fast & cheap
- **Arbitrum** - Popular L2
- **BSC** - Alternative option
- **Solana** - Coming soon

---

## 💰 Supported Tokens

- **USDC** (recommended)
- **DAI**
- **USDT**
- **ETH**
- **Any ERC20 token**

---

## 🚀 Deploy

### Vercel/Netlify

Just add environment variables:

```bash
NEXT_PUBLIC_IGNOTUS_AGENT_ID=your-agent-id
NEXT_PUBLIC_IGNOTUS_API_KEY=ak_...
```

### WordPress Plugin (Coming Soon)

```php
[ignotus_paywall amount="5" token="USDC"]
  Premium content here
[/ignotus_paywall]
```

---

## 📚 Examples

- [Blog Paywall](https://github.com/ignotus/examples/blog-paywall)
- [Video Platform](https://github.com/ignotus/examples/video-paywall)
- [API Gateway](https://github.com/ignotus/examples/api-gateway)
- [Newsletter](https://github.com/ignotus/examples/newsletter)

---

## 🆚 Comparison

| Feature | Ignotus Paywall | Unlock Protocol | Coil |
|---------|-----------------|-----------------|------|
| Setup Time | 3 minutes | 30 minutes | 10 minutes |
| Multi-Chain | ✅ 6+ chains | ✅ Limited | ❌ |
| Privacy | ✅ Built-in | ❌ | ❌ |
| Agent Support | ✅ Native | ❌ | ❌ |
| Open Source | ✅ | ✅ | ❌ |
| Self-Host | ✅ | ✅ | ❌ |

---

## 🐛 Troubleshooting

**Content not showing after payment:**
- Check browser console for errors
- Verify API key is correct
- Ensure wallet is on correct chain

**Payment not detected:**
- Wait 10-15 seconds for confirmation
- Check transaction on block explorer
- Verify payment amount matches

**Wallet connection fails:**
- Install MetaMask or another Web3 wallet
- Ensure wallet is unlocked
- Switch to correct network

---

## 📞 Support

- **Documentation**: https://docs.ignotus.ai/paywall
- **Discord**: https://discord.gg/ignotus
- **GitHub Issues**: https://github.com/ignotus/paywall-sdk/issues
- **Email**: support@ignotus.ai

---

## 📜 License

MIT License - Free for commercial use

---

## 🎉 Get Started

```bash
npm install @ignotus/paywall
```

**Add 3 lines of code. Start earning crypto. 🚀**