X402 Agent Free

x402 Agent Skill (Free)

Automatically detect and pay x402 crypto paywalls when your AI agent encounters HTTP 402 Payment Required responses.

This is the free community edition. It covers basic x402 detect-and-pay using the upstream @x402/fetch package. For the full kit with policy engine, spending limits, domain filtering, payment logging, Express middleware, and a demo app, see x402 Paywall Kit on ClawMart.

When to Activate

Activate this skill when an HTTP response returns status 402 Payment Required and the response body contains an x402Version field with an accepts array describing payment options.

Detection pattern:

• HTTP status code: 402
• Response body: JSON with x402Version (number) and accepts (array of payment requirements)
• Response header: PAYMENT-REQUIRED (base64-encoded payment requirements)

How to Use

Step 1: Install

npm install @x402/fetch @x402/evm viem

Step 2: Set Up the x402 Fetch Wrapper

import { createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { base } from "viem/chains";
import { wrapFetchWithPayment } from "@x402/fetch";
import { toClientEvmSigner, ExactEvmScheme } from "@x402/evm";

// Load wallet from environment (never hardcode!)
const account = privateKeyToAccount(process.env.X402_WALLET_PRIVATE_KEY as `0x${string}`);

const walletClient = createWalletClient({
  account,
  chain: base,
  transport: http(),
});

const signer = toClientEvmSigner(
  {
    address: account.address,
    signTypedData: (message) => walletClient.signTypedData(message),
  },
  walletClient,
);

const x402Fetch = wrapFetchWithPayment(fetch, {
  schemes: [new ExactEvmScheme(signer)],
});

Step 3: Use as a Drop-in Fetch Replacement

// x402Fetch handles 402 responses automatically:
// detects paywall → signs payment → retries with X-PAYMENT header
const response = await x402Fetch("https://api.example.com/premium/data");
const data = await response.json();

What Happens Internally

1. The initial request is made normally
2. If the server returns HTTP 402 with x402 payment requirements:
   • Parses the payment requirements from the response
   • Signs an EIP-3009 USDC transfer authorization
   • Retries the request with the signed X-PAYMENT header
3. Returns the successful response

Configuration

Environment Variables

Supported Networks

Example

// Agent calls a paid API — payment happens automatically
const response = await x402Fetch("https://api.example.com/premium/weather");

if (response.ok) {
  const data = await response.json();
  console.log("Got premium data:", data);
} else if (response.status === 402) {
  console.log("Payment failed — check wallet balance");
} else {
  console.log("Request failed:", response.status);
}

Safety Rules

1. Never expose the private key. Always load X402_WALLET_PRIVATE_KEY from environment variables.
2. Start with testnet. Use Base Sepolia during development. Switch to mainnet for production.
3. Monitor spending. This free edition does not include spending limits. Monitor your wallet balance manually.

Want More Control?

The x402 Paywall Kit ($29) adds:

• Policy engine — per-request limits, daily spending caps, domain allow/deny lists
• Payment logging — JSONL audit trail for every transaction
• Express middleware — add USDC paywalls to your own APIs in minutes
• Demo app — working paywalled API + agent on testnet
• Domain filtering — restrict which services your agent can pay

NPM packages: @x402-kit/agent, @x402-kit/express, @x402-kit/shared

Available on ClawMart and taraquinn.ai.