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

Source: Dev.to

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 receives the resource—no redirects, no OAuth dance, no separate billing API.

Coinbase has run x402 in production for several months, processing over 115 million micropayments. Stripe recently announced integration support, moving x402 from an experimental Web3 concept toward mainstream infrastructure.

Because the protocol operates at the HTTP layer, 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 this is a minor inconvenience; for autonomous agents running 24/7 it creates 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”
• Every payment is auditable on‑chain

This architecture is essential for agentic workflows where agents hire other agents, pay for data, or settle 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: {...}

When the SDK handles payment automatically, agents never see the 402—the retry is transparent.

Supported Chains

The SDK currently supports 17 networks. The primary ones are:

The full list of supported chains is available in the SDK documentation.

The Bigger Picture

x402 combined with non‑custodial wallets provides the right primitive for the agent economy. Agents can discover paid APIs, pay exactly for what they consume, and do so without any human in the loop.

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

Get Started

npm install agentwallet-sdk

The SDK is MIT‑licensed. Source code, examples, and chain documentation are hosted on npm. Questions and pull requests are welcome.