Building Paid API Endpoints with x402 and agentwallet-sdk: A Developer Guide

#ai #webdev #typescript #blockchain

Building Paid API Endpoints with x402 and agentwallet-sdk: A Developer Guide

AI Disclosure: This article was drafted with AI assistance and reviewed for technical accuracy.

The HTTP spec has a status code that has gone mostly unused for 30 years: 402 Payment Required. The x402 protocol finally puts it to work -- and if you are building APIs that autonomous agents will consume, this changes everything.

What x402 Actually Is

x402 is an HTTP-native payment protocol. When a client hits a paid endpoint without funds attached, the server returns a 402 response with a machine-readable payment payload. The client pays, retries the request with proof of payment, and gets the resource. No redirects. No OAuth dance. No separate billing API.

Coinbase has run x402 in production for several months. The numbers are public: over 115 million micropayments processed. Stripe recently announced integration support, which means x402 is crossing from "experimental Web3 thing" into mainstream infrastructure.

The protocol works at the HTTP layer, which means it is language-agnostic and works with any existing HTTP client. If your agent can make a fetch() call, it can pay for API access.

Why Non-Custodial Is the Right Architecture

Most payment integrations store your money for you. A custodial wallet means a third party holds your keys. For human users, that is a minor inconvenience. For autonomous agents running 24/7, it is a single point of failure and a trust bottleneck.

The agentwallet-sdk takes a different approach: the agent holds its own private key and signs payments locally. Nothing leaves the agent except a cryptographic proof. This means:

No API calls to a wallet service to authorize spending
No rate limits or outages from a custodial provider
The agent can operate fully autonomously without phoning home
You can audit every payment because it is on-chain

This matters most in agentic workflows where agents are hiring other agents, paying for data, or settling microtransactions every few seconds. Custodial solutions simply do not scale to that pattern.

Code Walkthrough

Install

npm install agentwallet-sdk

Initialize the Agent Wallet

import { AgentWallet } from "agentwallet-sdk";

const wallet = new AgentWallet({
  // Agent generates and holds its own key
  privateKey: process.env.AGENT_PRIVATE_KEY,
  // Base is recommended for low fees
  defaultChain: "base",
});

console.log("Agent address:", wallet.address);

Create a Paid API Endpoint (Server Side)

import express from "express";
import { x402Middleware } from "agentwallet-sdk/middleware";

const app = express();

// Protect this endpoint with a $0.001 payment requirement
app.use(
  "/api/premium-data",
  x402Middleware({
    price: "0.001",
    currency: "USDC",
    chain: "base",
    receiverAddress: process.env.MY_WALLET_ADDRESS,
  })
);

app.get("/api/premium-data", (req, res) => {
  res.json({ data: "This is paid content", timestamp: Date.now() });
});

Call the Paid Endpoint (Agent Side)

import { AgentWallet } from "agentwallet-sdk";

const wallet = new AgentWallet({ privateKey: process.env.AGENT_PRIVATE_KEY });

// The SDK handles the 402 -> pay -> retry cycle automatically
const response = await wallet.fetch("https://api.example.com/api/premium-data");
const data = await response.json();

Test with curl

First call hits the 402:

curl -i https://api.example.com/api/premium-data
# HTTP/1.1 402 Payment Required
# x402-payment-payload: {...}

With the SDK handling payment automatically, agents never see the 402 -- the retry is transparent.

Supported Chains

The SDK currently supports 17 networks. The primary ones:

Chain	Notes
Base	Recommended -- low fees, fast finality
Ethereum	Full support
Polygon	Low-cost alternative
Arbitrum	L2 speed + security
Etherlink	Tezos EVM rollup

The full list of 17 chains is in the SDK documentation.

The Bigger Picture

x402 plus non-custodial wallets is the right primitive for the agent economy. Agents can discover paid APIs, pay for exactly what they consume, and do it all without a human in the loop.

You do not need a billing department. You do not need a subscription system. The API charges per call, the agent pays per call, and the whole thing runs on-chain with no intermediary.