Quickstart for agents

This guide walks through making an x402 paid call from an autonomous agent — a script, an LLM agent, or a browser tab. By the end you will have a Node script that pays a tiny amount of DEMO-USDT for a gated API response, with gas sponsored by the paymaster.

The complete runnable version of this script lives in the repo at examples/learn-nero/.

Prerequisites

• An EOA private key. Generate one with openssl rand -hex 32. The corresponding SCW is derived deterministically from this key plus the canonical SimpleAccount factory.
• A NERO Paymaster API key from the NERO AA Platform dashboard.
• The packages installed (see Installation).

The agent's SCW does not need a NERO native balance. The paymaster sponsors gas. On testnet the SCW does not even need DEMO-USDT to start — the script auto-mints from a public mint() on first run.

The minimal flow

import { ethers } from "ethers";
import { x402Fetch, readSettlementReceipt } from "@nerochain/x402-client";
import { aaNativeSigner } from "@nerochain/x402-aa";

const wallet = new ethers.Wallet(process.env.NERO_PRIVATE_KEY!);

const f = x402Fetch({
  signer: aaNativeSigner({
    signer: wallet,
    rpcUrl:           "https://rpc-testnet.nerochain.io",
    bundlerUrl:       "https://bundler-testnet.nerochain.io",
    paymasterUrl:     "https://paymaster-testnet.nerochain.io",
    paymasterApiKey:  process.env.NERO_PAYMASTER_API_KEY!,
    settlementContract: "0x925dbba44570683ac8da99be08bc5ece8cf5a8c6",
  }),
});

const res = await f("http://localhost:4000/api/nero-knowledge", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ question: "How does the paymaster work?" }),
});

console.log(res.status, await res.json());

const receipt = readSettlementReceipt(res);
if (receipt) {
  console.log("settled:", receipt.transactionHash);
  console.log("paid   :", ethers.formatUnits(receipt.amount, 6), "DEMO-USDT");
}

That is the entire payment loop. x402Fetch is a fetch-API-compatible function that:

1. Issues the request.
2. If it receives a 402 with a PAYMENT-REQUIRED header, asks the signer to construct a paymaster-sponsored UserOp targeting the settlement contract.
3. Re-issues the request with the signed payload in the PAYMENT-SIGNATURE header.
4. Returns the eventual 200 response with a PAYMENT-RESPONSE header that decodes to a structured settlement receipt.

What happens behind the scenes

The agent never sees the bundler or the facilitator directly. They are merchant-side concerns; the agent only signs the UserOp and re-issues the HTTP request.

Pointing at mainnet

Swap the testnet URLs and contract for their mainnet equivalents:

rpcUrl:           "https://rpc.nerochain.io",
bundlerUrl:       "https://bundler-mainnet.nerochain.io",
paymasterUrl:     "https://paymaster-mainnet.nerochain.io",
settlementContract: "0x5eCfc64f2339992668f555918674B604F97B412D",

Mainnet has no auto-mint. Send real USDT to the SCW address before running. The SCW address is deterministic; the script in examples/learn-nero/ prints it so you know where to fund.

Next

• Quickstart for merchants — the other side of the same flow.
• SDK overview — the five packages, when to use which.
• Whitepaper — the protocol's normative specification.