Skip to main content

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.

  1. 01The client sends a request to a Spider endpoint without an API key.
  2. 02The server answers 402 with a PAYMENT-REQUIRED header that carries the price.
  3. 03The client signs a USDC payment and retries with a PAYMENT-SIGNATURE header.
  4. 04The server verifies the payment with the x402 facilitator and returns the data.
  5. 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.

Core endpoints
EndpointEst. creditsEst. USDC
/scrape5$0.0005
/crawl50$0.005
/search20$0.002
/screenshot10$0.001
/links2$0.0002
/unblocker10$0.001
/transform5$0.0005

AI endpoints

These need an AI Studio subscription.

AI endpoints
EndpointEst. creditsEst. USDC
/ai/scrape100$0.01
/ai/crawl500$0.05
/ai/search100$0.01
/ai/browser100$0.01
/ai/links50$0.005
/ai/unblocker50$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.

Protocol details
NetworkBase, eip155:8453 on mainnet and eip155:84532 on testnet
AssetUSDC
Schemeexact, a fixed price per request
Challenge headerPAYMENT-REQUIRED, base64 JSON
Payment headerPAYMENT-SIGNATURE, base64 signed payload
Settlement headerPAYMENT-RESPONSE, base64 transaction receipt
Facilitatordocs.x402.org/core-concepts/facilitator
Verification timeout30s

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.

Resources

The protocol spec and the reference client.