Quickstart: HTTP API

This guide makes one operation — a merge — against the HTTP API. The base URL is https://api.pdfasyougo.com/v1. There is no Authorization header: the x402 payment is the auth.

Private preview

PDF As You Go is in private preview. Endpoints, retention windows, and supported networks may change. Access is granted on request — see Request preview access.

Before you start

• Preview access — see Request preview access.
• A funded wallet with USDC on a supported network (Base by default).
• An x402-aware HTTP client to sign payments. The TypeScript example below uses x402-fetch; other languages have equivalents.

The short version (with a library)

An x402 client handles the 402 → sign → retry loop for you. You write one request:

TypeScript

merge.ts

import { wrapFetchWithPayment } from 'x402-fetch';
import { privateKeyToAccount } from 'viem/accounts';

// A wallet that can sign payments. Keep this key out of source control.
const account = privateKeyToAccount(process.env.X402_WALLET_PRIVATE_KEY as `0x${string}`);

// Wrap fetch so any 402 is paid and retried automatically.
const fetchWithPay = wrapFetchWithPayment(fetch, account);

const res = await fetchWithPay('https://api.pdfasyougo.com/v1/merge', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    files: ['https://example.com/a.pdf', 'https://example.com/b.pdf'],
  }),
});

const result = await res.json();
console.log(result.output.url); // short-lived download URL

Python

merge.py

import os, httpx
from x402.clients.httpx import x402_payment_hooks
from eth_account import Account

account = Account.from_key(os.environ["X402_WALLET_PRIVATE_KEY"])

client = httpx.Client(base_url="https://api.pdfasyougo.com/v1")
client.event_hooks = x402_payment_hooks(account)  # pays + retries on 402

res = client.post("/merge", json={
    "files": ["https://example.com/a.pdf", "https://example.com/b.pdf"],
})
print(res.json()["output"]["url"])

That’s the whole happy path. The rest of this page shows what the library is doing for you.

What happens underneath

1. Send the request unpaid.

   curl -i -X POST https://api.pdfasyougo.com/v1/merge \
     -H "Content-Type: application/json" \
     -d '{"files":["https://example.com/a.pdf","https://example.com/b.pdf"]}'

2. Receive 402 Payment Required.

   The server quotes the price and how to pay (USDC base units; 50000 = $0.05):

   HTTP/1.1 402 Payment Required
   Content-Type: application/json

   {
     "x402Version": 1,
     "error": "X-PAYMENT header is required",
     "accepts": [
       {
         "scheme": "exact",
         "network": "base",
         "maxAmountRequired": "50000",
         "resource": "https://api.pdfasyougo.com/v1/merge",
         "description": "Merge PDF documents",
         "mimeType": "application/json",
         "payTo": "0xA0b8…receiver",
         "maxTimeoutSeconds": 60,
         "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
         "extra": { "name": "USDC", "version": "2" }
       }
     ]
   }

3. Sign and retry with X-PAYMENT.

   Your client builds a gasless EIP-3009 authorization, base64-encodes it, and resends the identical request with the header:

   curl -i -X POST https://api.pdfasyougo.com/v1/merge \
     -H "Content-Type: application/json" \
     -H "X-PAYMENT: <base64-encoded-payment-payload>" \
     -d '{"files":["https://example.com/a.pdf","https://example.com/b.pdf"]}'

4. Get 200 OK with the result and a settlement receipt.

   HTTP/1.1 200 OK
   X-PAYMENT-RESPONSE: <base64-encoded-settlement-receipt>

   {
     "output": {
       "url": "https://files.pdfasyougo.com/o/3f9a…?token=…",
       "expires_at": "2026-06-29T12:00:00Z",
       "pages": 24,
       "bytes": 184320
     },
     "operation": "merge",
     "cost": "0.05 USDC"
   }

5. Download the output from output.url before it expires (preview default: 60 minutes).

Caution

Constructing the X-PAYMENT header by hand means implementing EIP-3009 signing and x402 encoding — use a client library instead. The full header format lives in The 402 flow.

Next

• The 402 flow — every field and header in detail.
• Conventions — request/response shapes, file inputs, page ranges.
• Operations — every endpoint with parameters and examples.