Authentication

Previous Next

Book402 uses the x402 protocol instead of traditional API keys. Your wallet IS your identity.

No API Keys

Unlike traditional APIs, Book402 doesn't use API keys, OAuth tokens, or subscriptions. Instead:

  1. Free endpoints → No authentication needed at all
  2. Paid endpoints → Your EVM wallet signs a USDC payment authorization

How x402 Works

sequenceDiagram participant Client as Your Agent participant Server as Book402 participant Facilitator as x402 Facilitator Note over Client,Server: Step 1: Discovery Client->>Server: GET /search/hybrid?q=stoicism Server-->>Client: 402 Payment Required Note right of Server: PAYMENT-REQUIRED header
(base64 JSON with price,
network, payTo address) Note over Client: Step 2: Sign Payment Note over Client: Signs EIP-3009
transferWithAuthorization
(no on-chain tx yet!) Note over Client,Server: Step 3: Pay & Receive Client->>Server: GET /search/hybrid?q=stoicism
+ X-PAYMENT header (signed payload) Server->>Facilitator: Verify signature Facilitator-->>Server: ✅ Valid signature Server-->>Client: 200 OK + search results Note over Server,Facilitator: Step 4: Settlement (async) Server->>Facilitator: Settle payment Facilitator->>Facilitator: Submit USDC transfer on-chain

The PAYMENT-REQUIRED Header

When you hit a paid endpoint without payment, the response includes:

HTTP/1.1 402 Payment Required
PAYMENT-REQUIRED: <base64-encoded JSON>

Decoded, the header contains:

{
  "x402Version": 2,
  "error": "Payment required",
  "resource": {
    "url": "http://book402.com/search/hybrid?q=stoicism",
    "description": "Hybrid BM25+vector book search"
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "amount": "10000",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "payTo": "0x6B1925e4a1f779797eF51A18A4694B59FFb60Aba",
      "maxTimeoutSeconds": 300,
      "extra": {
        "name": "USD Coin",
        "version": "2"
      }
    }
  ]
}
Field Description
scheme Payment scheme — exact means exact amount
network eip155:8453 = Base mainnet
amount Amount in smallest unit (10000 = $0.01 USDC, 6 decimals)
asset USDC contract address on Base
payTo Book402's wallet address
maxTimeoutSeconds How long the payment authorization is valid

EIP-3009: TransferWithAuthorization

x402 uses EIP-3009 — a gasless token transfer standard. Your agent:

  1. Signs a transfer authorization off-chain (no gas needed!)
  2. Sends the signature to Book402
  3. Book402 submits the transfer on-chain via the facilitator

You don't pay gas

The facilitator pays the gas fee for settlement. You only pay the USDC amount.

Supported Networks

Network Chain ID USDC Address Status
Base Mainnet eip155:8453 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 ✅ Live
Base Sepolia eip155:84532 Testnet USDC ✅ Testing
Quick Start Overview