Skip to navigation
Integrations

x402

Pay-per-use PostNuvia with the x402 payment protocol

Getting started

x402 is an open payment protocol that enables HTTP-native payments. By integrating x402 with PostNuvia, 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 PostNuvia base URLs and route requests through the x402 payment layer.

ProtocolURL
HTTPx402.api.postnuvia.com
WebSocketx402.ws.postnuvia.com

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 postnuvia @x402/fetch @x402/evm viem

Quickstart

import { privateKeyToAccount } from "viem/accounts";
import { x402Client } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { PostNuviaClient } from "postnuvia";
// 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 PostNuvia client
export const client = new PostNuviaClient({ 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 PostNuviaClient, 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 PostNuvia API (inboxes, messages, threads, attachments) without needing a traditional API key. Payment happens per-request over HTTP.

Resources