API Documentation

x402 API Reference

Every PayGated paywall exposes a standard x402 API endpoint. AI agents, bots, and developers can access gated content programmatically.

How x402 Works

Discovery

Agent sends GET request. Server returns 402 with payment requirements in headers and body.

Payment

Agent constructs ERC-3009 TransferWithAuthorization, signs with EIP-712, sends as X-Payment header.

Access

Server verifies signature cryptographically, records payment, returns gated content URL.

API Endpoint

GET/api/paywall/:shortId

Returns 402 Payment Required if no payment proof is provided, or 200 OK with the gated content URL if a valid X-Payment header is present.

Response Headers (402)

X-Payment-Network:base-sepolia

X-Payment-Asset:0x036CbD53842c5426634e...

X-Payment-Amount:1000000 (USDC 6 decimals)

X-Payment-Recipient:Creator's wallet address

X-Payment-Scheme:exact

402 Response Body

// 402 Payment Required Response
{
  "error": "Payment Required",
  "title": "State of AI Agents 2026",
  "description": "Premium research report",
  "paymentRequirements": {
    "scheme": "exact",
    "network": "base-sepolia",
    "maxAmountRequired": "1000000",
    "asset": "0x036CbD53842c5426634e...",
    "payTo": "0xCreatorAddress...",
    "extra": {
      "name": "State of AI Agents 2026",
      "linkId": "uuid-here",
      "shortId": "<id>"
    }
  }
}

Quick Start (cURL)

Discovery — GET without payment

# Step 1: Discover paywall requirements
curl -sI https://paygated.fun/api/paywall/<id>

# Response: 402 Payment Required
# Headers:
#   X-Payment-Network: base-sepolia
#   X-Payment-Asset: 0x036CbD53842...
#   X-Payment-Amount: 1000000 (1 USDC)
#   X-Payment-Recipient: 0xCreator...
#   X-Payment-Scheme: exact

Payment — GET with X-Payment header

# Step 2: Send payment proof
curl https://paygated.fun/api/paywall/<id> \
  -H "X-Payment: <base64-encoded-proof>"

# Response: 200 OK
# {
#   "success": true,
#   "url": "https://secret-content.com/report",
#   "title": "State of AI 2026",
#   "receipt": "0x1234..."
# }

SDK Integration

@veridex/sdk — Manual integration

import { createSDK } from "@veridex/sdk";

const sdk = createSDK({
  chain: "base-sepolia",
  rpcUrl: process.env.RPC_URL,
});

// 1. Hit the paywall endpoint
const res = await fetch("https://paygated.fun/api/paywall/<id>");

if (res.status === 402) {
  const requirements = await res.json();
  
  // 2. Construct ERC-3009 authorization
  const proof = await sdk.payments.createX402Proof({
    to: requirements.paymentRequirements.payTo,
    amount: requirements.paymentRequirements.maxAmountRequired,
    asset: requirements.paymentRequirements.asset,
  });
  
  // 3. Re-send with payment header
  const unlocked = await fetch(
    "https://paygated.fun/api/paywall/<id>",
    { headers: { "X-Payment": proof } }
  );
  
  const { url } = await unlocked.json();
  console.log("Content URL:", url);
}

@veridex/agentic-payments — Auto-negotiation (4 lines)

import { AgentWallet } from "@veridex/agentic-payments";

const agent = new AgentWallet({
  privateKey: process.env.AGENT_KEY,
  chain: "base-sepolia",
});

// Auto-negotiates 402 payments
const content = await agent.fetch(
  "https://paygated.fun/api/paywall/<id>"
);

// Content is automatically unlocked
console.log(content.url);

Ready to monetize?

Create a paywall in 30 seconds. Your API endpoint is auto-generated.

Create a Paywall