x402 Integration

Pay per request in USDC on Base with no account, no API key, and no signup. Paying is the whole onboarding, which makes this the fastest way to give an autonomous agent access to live web data. Spider implements the x402 protocol: a request without an API key gets a 402 Payment Required carrying the price, and the x402 client SDK signs and retries it for you. In practice that is one wrapper around fetch, and your agent never blocks on a human.

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 keyis simpler and avoids on-chain fees.

Resources

x402 protocol docs | GitHub repo