x402 integration
Pay per request in USDC on Base. No account, no API key, no signup. 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. That is one wrapper around fetch, so an agent never waits on a human to add credits.
Payment flow
The protocol runs on plain HTTP headers.
- 01The client sends a request to a Spider endpoint without an API key.
- 02The server answers
402with aPAYMENT-REQUIREDheader that carries the price. - 03The client signs a USDC payment and retries with a
PAYMENT-SIGNATUREheader. - 04The server verifies the payment with the x402 facilitator and returns the data.
- 05Settlement runs 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
You need an EVM wallet holding USDC on Base. Put its private key in EVM_PRIVATE_KEY.
Usage
Call any Spider endpoint. The x402 SDK catches the 402, 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
Prices map 1:1 to 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
These need an 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 |
Estimates per request. The actual charge follows the same credit deduction as a request made with an API key.
Protocol details
Spider implements x402 v2.
| Network | Base, eip155:8453 on mainnet and eip155:84532 on testnet |
|---|---|
| Asset | USDC |
| Scheme | exact, a 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 | docs.x402.org/core-concepts/facilitator |
| Verification timeout | 30s |
x402 or an API key
x402 fits an autonomous agent that pays per request with no account set up ahead of time. When you control the client, an API key is simpler and skips the on-chain fees.