x402 Integration

Spider supports the x402 protocol for paying per request with USDC on Base. Requests without an API key receive a 402 Payment Required response. The x402 client SDK handles payment and retries automatically.

Payment flow

The protocol uses standard HTTP headers:

Client sends a request to a Spider endpoint without an API key
Server returns 402 with a PAYMENT-REQUIRED header containing the price
Client signs a USDC payment and retries with a PAYMENT-SIGNATURE header
Server verifies the payment via the x402 facilitator and returns data
Settlement executes in the background

Install

Install the x402 client SDK and a wallet library.

Install x402 client with EVM support

npm install @x402/core @x402/evm @x402/fetch viem

Requires an EVM wallet with USDC on Base. Set your private key as EVM_PRIVATE_KEY in your environment.

Usage

Make a request to any Spider endpoint. The x402 SDK intercepts the 402 response, signs the payment, and retries.

Scrape with x402 in TypeScript

import { x402Client } from "@x402/core/client";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { wrapFetchWithPayment } from "@x402/fetch";
import { privateKeyToAccount } from "viem/accounts";

const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);
const client = new x402Client();
registerExactEvmScheme(client, { signer });

const fetchWithPayment = wrapFetchWithPayment(fetch, client);

const response = await fetchWithPayment("https://api.spider.cloud/scrape", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    url: "https://example.com",
    return_format: "markdown"
  })
});

const data = await response.json();

Supported endpoints

Pricing maps 1:1 with the credit system. 10,000 credits = $1 USD in USDC.

Endpoint	Est. credits	Est. USDC
`/scrape`	5	$0.0005
`/crawl`	50	$0.005
`/search`	20	$0.002
`/screenshot`	10	$0.001
`/links`	2	$0.0002
`/unblocker`	10	$0.001
`/transform`	5	$0.0005

AI endpoints (requires AI Studio subscription)

Endpoint	Est. credits	Est. USDC
`/ai/scrape`	100	$0.01
`/ai/crawl`	500	$0.05
`/ai/search`	100	$0.01
`/ai/browser`	100	$0.01
`/ai/links`	50	$0.005
`/ai/unblocker`	50	$0.005

Estimated costs per request. Actual cost uses the same dynamic credit deduction as API key users.

Protocol details

Spider implements x402 v2.

Network: Base (eip155:84532 testnet, eip155:8453 mainnet)
Asset: USDC
Scheme: exact (fixed price per request)
Challenge header: PAYMENT-REQUIRED (base64 JSON)
Payment header: PAYMENT-SIGNATURE (base64 signed payload)
Settlement header: PAYMENT-RESPONSE (base64 transaction receipt)
Facilitator: x402.org/facilitator
Verification timeout: 30s

x402 vs API keys

x402 is designed for autonomous agents that pay per request without pre-arranged accounts. For applications where you control the client, an API key is simpler and avoids on-chain fees.

Resources

x402 protocol docs | GitHub repo