Integrations

x402

Pay-per-use AgentMail with the x402 payment protocol

Getting started

x402 is an open payment protocol that enables HTTP-native payments. By integrating x402 with AgentMail, your agents can pay for API usage directly over HTTP without managing API keys or subscriptions.

Supported chains

Agents can pay for API usage directly over HTTP via x402 on any of the following chains:

  • Polygon: an EVM-compatible network offering high throughput and low gas fees.
  • Base: an Ethereum Layer 2 network incubated by Coinbase.
  • Solana: a high-throughput, low-fee non-EVM network.

EVM chains (Polygon and Base) share the same client setup, while Solana uses the Solana-specific setup shown below.

Base URLs

To authenticate with x402 instead of an API key, you must use the x402-specific base URLs below. These replace the default AgentMail base URLs and route requests through the x402 payment layer.

ProtocolURL
HTTPx402.api.agentmail.to
WebSocketx402.ws.agentmail.to

Prerequisites

  • A crypto wallet with USDC funds (EVM-compatible wallet on Polygon or Base, or a Solana wallet)
  • Node.js installed

The x402 client applies a default spend control of 1perpayment.Inboxcreationispricedat1 per payment. Inbox creation is priced at 2.00, so raise the cap with setSpendControls before your first request or the client will reject the payment before it is sent.

Install dependencies

$npm install agentmail @x402/fetch @x402/evm viem

Quickstart

1import { privateKeyToAccount } from "viem/accounts";
2import { x402Client } from "@x402/fetch";
3import { ExactEvmScheme } from "@x402/evm/exact/client";
4
5import { AgentMailClient } from "agentmail";
6
7
8// setup x402 client
9
10const PRIVATE_KEY = "0x...";
11
12const signer = privateKeyToAccount(PRIVATE_KEY);
13
14const x402 = new x402Client();
15x402.register("eip155:*", new ExactEvmScheme(signer));
16
17// inbox creation is priced at $2.00, above the client's $1 default cap
18x402.setSpendControls({ maxAmountPerPayment: "$2" });
19
20
21// setup AgentMail client
22
23export const client = new AgentMailClient({ x402 });
24
25
26// create inbox
27
28const inboxRes = await client.inboxes.create({
29  username: `x402-${Date.now()}`,
30});
31console.log("Created inbox: ", inboxRes.inboxId);
32
33
34// subscribe to inbox
35
36const socket = await client.websockets.connect();
37console.log("Connected to websocket");
38
39socket.on("message", async (event) => {
40  if (event.type === "subscribed") {
41    console.log("Subscribed to", event.inboxIds);
42  } else if (event.type === "event" && event.eventType === "message.received") {
43    console.log("Received message from: ", event.message.from);
44  }
45});
46
47socket.sendSubscribe({
48  type: "subscribe",
49  inboxIds: [inboxRes.inboxId],
50});

How it works

When you pass an x402 client to AgentMailClient, the SDK automatically handles payment negotiation for each API request. If the server responds with a 402 Payment Required status, the x402 client signs a payment using your wallet and retries the request with the payment attached.

This means your agent can use the full AgentMail API (inboxes, messages, threads, attachments) without needing a traditional API key. Payment happens per-request over HTTP.

Resources