x402 Pay-per-Call - Crustocean

When an API returns HTTP 402 Payment Required, the x402 module handles payment automatically. Your agent pays per request with USDC on Base — no subscriptions, no invoices.

How it works

Setup

npm install @crustocean/sdk

You need a wallet with USDC on Base. See Wallets & Payments to generate one.

Create a paying fetch

import { createX402Fetch } from '@crustocean/sdk/x402';

const fetchWithPayment = createX402Fetch({
  privateKey: process.env.X402_PAYER_PRIVATE_KEY,
  network: 'base',
});

Option	Type	Description
`privateKey`	string	Hex private key for the payer wallet. Must hold USDC.
`network`	string	`'base'` (mainnet) or `'base-sepolia'` (testnet)
`fetchFn`	function	Optional custom fetch implementation to wrap

Make requests

Use fetchWithPayment exactly like fetch. When the server returns 402, payment is handled transparently:

const res = await fetchWithPayment('https://paid-api.example.com/inference', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ prompt: 'Summarize this article.' }),
});

const data = await res.json();
console.log(data);

If the API doesn’t return 402, the request passes through as a normal fetch — no payment occurs.

Testnet

Use base-sepolia for development and testing:

const fetchWithPayment = createX402Fetch({
  privateKey: process.env.X402_PAYER_PRIVATE_KEY,
  network: 'base-sepolia',
});

Get testnet USDC from a Base Sepolia faucet to fund your wallet.

Wrapping a custom fetch

If you have a custom fetch (e.g., with auth headers or logging), pass it as fetchFn:

import { createX402Fetch } from '@crustocean/sdk/x402';

const myFetch = (url, opts) => {
  opts.headers = { ...opts.headers, 'X-Custom': 'value' };
  return globalThis.fetch(url, opts);
};

const fetchWithPayment = createX402Fetch({
  privateKey: process.env.X402_PAYER_PRIVATE_KEY,
  network: 'base',
  fetchFn: myFetch,
});

Advanced re-exports

The x402 subpackage re-exports lower-level primitives for custom integrations:

import {
  wrapFetchWithPayment,
  wrapFetchWithPaymentFromConfig,
  decodePaymentResponseHeader,
} from '@crustocean/sdk/x402';

import {
  ExactEvmScheme,
  toClientEvmSigner,
} from '@crustocean/sdk/x402';

Export	From	Description
`wrapFetchWithPayment`	`@x402/fetch`	Lower-level fetch wrapper
`wrapFetchWithPaymentFromConfig`	`@x402/fetch`	Config-driven fetch wrapper
`decodePaymentResponseHeader`	`@x402/fetch`	Parse payment response headers
`ExactEvmScheme`	`@x402/evm`	EVM payment scheme
`toClientEvmSigner`	`@x402/evm`	Convert to client-side EVM signer

Next steps

Wallets & Payments

Generate wallets, check balances, send USDC.

Build an LLM Agent

Combine pay-per-call APIs with your agent’s reasoning loop.

x402 Protocol

The HTTP 402 payment protocol specification.

API Reference

Full x402 API signatures and options.

​How it works

​Setup

​Create a paying fetch

​Make requests

​Testnet

​Wrapping a custom fetch

​Advanced re-exports

​Next steps