x402 Payment Guide — UnlockPDF.dev

Background

What is x402?

x402 is an open payment protocol built on the HTTP 402 Payment Required status code. Instead of API keys, accounts, or subscriptions — clients simply pay per request using USDC on Base network.

This is ideal for AI agents that need to autonomously pay for tools without human intervention, and for developers who want simple pay-per-use access without managing subscriptions.

⚡

UnlockPDF.dev supports x402 natively. The first 10 requests per day per IP are free. After that, each unlock costs $0.05 USDC on Base network — paid automatically via x402, no setup required.

Flow

How it works

1

Send request

POST your PDF to /api/unlock without any payment header. If you're within the free tier, you get the unlocked PDF immediately.

2

Receive 402

Once the free tier is exhausted, the server responds with HTTP 402 and an X-Payment-Required header containing base64-encoded payment details.

HTTP/1.1 402 Payment Required

3

Pay $0.05 USDC on Base

Send exactly $0.05 USDC on Base network to wallet 0x59387E6869A12d76f321Ea609de4e073284F734F. AI agents with a funded wallet do this automatically.

4

Retry with payment proof

Resend your request with the signed payment payload in the X-Payment header. The server verifies on-chain via Coinbase's x402 facilitator.

X-Payment: <base64_signed_payload>

5

Receive unlocked PDF

Payment verified — server returns the unlocked PDF binary. The entire flow happens within two HTTP requests.

Payment Details

x402 parameters

Parameter	Value
Amount	0.05 USDC
Network	base-mainnet
Asset	USDC (ERC-20)
Pay to wallet	0x59387E6869A12d76f321Ea609de4e073284F734F
Facilitator	facilitator.cdp.coinbase.com
Scheme	exact

Examples

Code examples

Check your remaining free unlocks before uploading:

          cURL
curl https://unlockpdf.dev/api/info

# Response:
{
  "free_tier": { "limit": 10, "remaining_today": 3 },
  "paid_tier": {
    "price": "0.05 USDC",
    "network": "base-mainnet",
    "pay_to": "0x59387E...734F",
    "protocol": "x402"
  }
}
        

Unlock with automatic x402 payment handling in Python:

          Python
import requests, base64, json

# Step 1: Try unlock (free tier)
res = requests.post(
    "https://unlockpdf.dev/api/unlock",
    files={"pdf_file": open("document.pdf", "rb")},
    data={"password": "optional_password"}
)

if res.status_code == 200:
    # Free tier — save unlocked PDF
    open("unlocked.pdf", "wb").write(res.content)

elif res.status_code == 402:
    # Step 2: Parse payment requirements
    payment_info = res.json()
    encoded = res.headers.get("X-Payment-Required")
    req = json.loads(base64.b64decode(encoded))

    print(f"Pay {req['maxAmountRequired']} USDC to {req['payTo']}")

    # Step 3: Sign payment with your wallet + retry
    # (use x402-python SDK or sign manually)
    signed_payload = sign_x402_payment(req)  # your signing logic

    res2 = requests.post(
        "https://unlockpdf.dev/api/unlock",
        headers={"X-Payment": signed_payload},
        files={"pdf_file": open("document.pdf", "rb")},
        data={"password": "optional_password"}
    )
    open("unlocked.pdf", "wb").write(res2.content)
        

For AI agents using the MCP server — payment is handled automatically:

          Claude Desktop config
{
  "mcpServers": {
    "unlockpdf": {
      "type": "sse",
      "url": "https://unlockpdf.dev/mcp"
    }
  }
}

# Claude will automatically handle x402 payments
# when it has a funded wallet configured
        

Comparison

x402 vs traditional API keys

Feature	API Keys	x402 (this API)
Setup required	Sign up + billing	None
Works for AI agents	Needs human setup	Autonomous
Pay per use	Subscription	$0.05/unlock
Free tier	Usually no	10/day
Settlement	Days (bank)	Instant (on-chain)
Regional limits	Yes	None