Documentation

1npm install @agentpaywall/sdk

1import express from 'express';
2import { agentPaywall } from '@agentpaywall/sdk';
3
4const app = express();
5
6app.get('/api/your-endpoint',
7  agentPaywall({
8    priceUsdc: 0.001,
9    recipientWallet: 'YOUR_SOLANA_WALLET',
10    apiId: 'YOUR_API_ID',
11  }),
12  (req, res) => {
13    res.json({ data: 'protected response' });
14  }
15);
16
17app.listen(3001);

1{
2  "status": 402,
3  "error": "Payment Required",
4  "code": "PAYMENT_REQUIRED",
5  "paymentDetails": {
6    "network": "solana",
7    "currency": "USDC",
8    "amount": 0.001,
9    "recipient": "oEmhqmu9aHuzDDvbnE4SMHb1nMbWthZMKSMpxANy6Dg",
10    "memo": "agentpaywall:your-api-name",
11    "usdcMintAddress": "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU"
12  }
13}

1import { Connection, Keypair, PublicKey } from '@solana/web3.js';
2import {
3  getAssociatedTokenAddress,
4  createTransferInstruction,
5} from '@solana/spl-token';
6
7const USDC_MINT = new PublicKey('4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU');
8
9async function payAndCall(apiUrl: string, recipientWallet: string, amountUsdc: number) {
10  const connection = new Connection('https://api.devnet.solana.com');
11  const payer = Keypair.fromSecretKey(/* your agent keypair */);
12
13  const payerATA = await getAssociatedTokenAddress(USDC_MINT, payer.publicKey);
14  const recipientATA = await getAssociatedTokenAddress(
15    USDC_MINT, new PublicKey(recipientWallet)
16  );
17  const amount = Math.round(amountUsdc * 1_000_000);
18
19  const txSignature = await sendTransaction(
20    connection, payer, payerATA, recipientATA, amount
21  );
22
23  const response = await fetch(apiUrl, {
24    headers: { 'X-Payment-Proof': txSignature },
25  });
26
27  return await response.json();
28}

1# Step 1: Try the API (get 402)
2curl -i https://your-api.com/api/endpoint
3
4# Step 2: Send USDC on Solana (via wallet or CLI)
5# ... send 0.001 USDC to recipient wallet ...
6
7# Step 3: Retry with proof
8curl -H "X-Payment-Proof: <tx_signature>" \
9  https://your-api.com/api/endpoint

1# .env or .env.local
2NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
3SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
4NEXT_PUBLIC_SOLANA_RPC_URL=https://api.devnet.solana.com
5NEXT_PUBLIC_USDC_MINT_ADDRESS=4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU

1agentPaywall({
2  priceUsdc: 0.005,
3  recipientWallet: process.env.SOLANA_WALLET!,
4  apiId: process.env.AGENTPAYWALL_API_ID!,
5
6  network: 'devnet',
7  rpcUrl: process.env.SOLANA_RPC,
8  verifyTimeout: 30000,
9  allowReplay: false,
10
11  onPaymentVerified: (tx) => {
12    console.log(`Payment ${tx.signature} verified: ${tx.amount} USDC`);
13  },
14})

1const baseConfig = {
2  recipientWallet: process.env.SOLANA_WALLET!,
3  network: 'devnet' as const,
4};
5
6// Free: no paywall
7app.get('/api/v1/status', (req, res) => res.json({ status: 'ok' }));
8
9// Cheap: market data
10app.get('/api/v1/prices',
11  agentPaywall({ ...baseConfig, priceUsdc: 0.0001, apiId: 'price-api' }),
12  priceHandler
13);
14
15// Premium: AI analysis
16app.post('/api/v1/analyze',
17  agentPaywall({ ...baseConfig, priceUsdc: 0.05, apiId: 'analyze-api' }),
18  analyzeHandler
19);

1async function callPaidApi(url: string, proofTx: string) {
2  const res = await fetch(url, {
3    headers: { 'X-Payment-Proof': proofTx },
4  });
5
6  switch (res.status) {
7    case 200:
8      return await res.json();
9
10    case 402: {
11      const { paymentDetails } = await res.json();
12      const newTx = await sendPayment(paymentDetails);
13      return callPaidApi(url, newTx);
14    }
15
16    case 400:
17      throw new Error('Invalid or expired transaction');
18    case 403:
19      throw new Error('Transaction already used (replay)');
20    case 408:
21      throw new Error('Verification timeout — try again');
22    default:
23      throw new Error(`Unexpected: ${res.status}`);
24  }
25}