> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://docs.agentmail.to/llms.txt.

# x402

> AgentMail's x402 integration for HTTP-native payments

## Getting started

[x402](https://www.x402.org/) 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](https://polygon.technology/):** an EVM-compatible network offering high throughput and low gas fees.
* **[Base](https://www.base.org/):** an Ethereum Layer 2 network incubated by Coinbase.
* **[Solana](https://solana.com/):** 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.

| Protocol  | URL                     |
| --------- | ----------------------- |
| HTTP      | `x402.api.agentmail.to` |
| WebSocket | `x402.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 $1 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

**`EVM`**

```bash title="EVM"
npm install agentmail @x402/fetch @x402/evm viem
```

**`Solana`**

```bash title="Solana"
npm install agentmail @x402/fetch @x402/svm @solana/kit @scure/base
```

### Quickstart

**`EVM`**

```typescript title="EVM"
import { privateKeyToAccount } from "viem/accounts";
import { x402Client } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm/exact/client";

import { AgentMailClient } from "agentmail";


// setup x402 client

const PRIVATE_KEY = "0x...";

const signer = privateKeyToAccount(PRIVATE_KEY);

const x402 = new x402Client();
x402.register("eip155:*", new ExactEvmScheme(signer));

// inbox creation is priced at $2.00, above the client's $1 default cap
x402.setSpendControls({ maxAmountPerPayment: "$2" });


// setup AgentMail client

export const client = new AgentMailClient({ x402 });


// create inbox

const inboxRes = await client.inboxes.create({
  username: `x402-${Date.now()}`,
});
console.log("Created inbox: ", inboxRes.inboxId);


// subscribe to inbox

const socket = await client.websockets.connect();
console.log("Connected to websocket");

socket.on("message", async (event) => {
  if (event.type === "subscribed") {
    console.log("Subscribed to", event.inboxIds);
  } else if (event.type === "event" && event.eventType === "message.received") {
    console.log("Received message from: ", event.message.from);
  }
});

socket.sendSubscribe({
  type: "subscribe",
  inboxIds: [inboxRes.inboxId],
});
```

**`Solana`**

```typescript title="Solana"
import { createKeyPairSignerFromBytes } from "@solana/kit";
import { base58 } from "@scure/base";
import { x402Client } from "@x402/fetch";
import { ExactSvmScheme } from "@x402/svm/exact/client";
import { toClientSvmSigner } from "@x402/svm";

import { AgentMailClient } from "agentmail";


// setup x402 client

const PRIVATE_KEY = "base58-encoded-private-key...";

const keypair = await createKeyPairSignerFromBytes(
  base58.decode(PRIVATE_KEY)
);

const x402 = new x402Client();
x402.register("solana:*", new ExactSvmScheme(toClientSvmSigner(keypair)));

// inbox creation is priced at $2.00, above the client's $1 default cap
x402.setSpendControls({ maxAmountPerPayment: "$2" });


// setup AgentMail client

export const client = new AgentMailClient({ x402 });


// create inbox

const inboxRes = await client.inboxes.create({
  username: `x402-${Date.now()}`,
});
console.log("Created inbox: ", inboxRes.inboxId);


// subscribe to inbox

const socket = await client.websockets.connect();
console.log("Connected to websocket");

socket.on("message", async (event) => {
  if (event.type === "subscribed") {
    console.log("Subscribed to", event.inboxIds);
  } else if (event.type === "event" && event.eventType === "message.received") {
    console.log("Received message from: ", event.message.from);
  }
});

socket.sendSubscribe({
  type: "subscribe",
  inboxIds: [inboxRes.inboxId],
});
```

## 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

* [x402 documentation](https://www.x402.org/)
* [AgentMail API reference](/api-reference)
* [WebSockets overview](/websockets)