Set up an agent wallet for x402 payments.
An agent that pays for tools needs three things: a keypair, USDC on Base, and a runtime that answers 402 challenges automatically. The whole setup is an afternoon — most of it is deciding how to store the key.
In x402, the wallet is how an agent buys things. When a priced endpoint answers with HTTP 402, the agent's wallet signs a USDC payment authorization, settlement clears on Base in about two seconds, and the original request succeeds — no account, no card, no API key.
This guide takes you from nothing to an agent that pays for calls: generating the key, funding it, wiring it into your HTTP client, and putting guardrails around what it can spend.
Generate the wallet
An agent wallet is an ordinary Ethereum-style keypair — a private key and the address derived from it. You can generate one with any EVM tooling (viem, cast, a hardware-backed signer) or use a managed wallet service if you'd rather not hold raw keys; either works for x402, since all the protocol needs is something that can sign payment authorizations.
It's non-custodial: whoever holds the key controls the funds. For anything beyond experiments, prefer a dedicated wallet per agent or per workload so a compromised runtime exposes only that workload's budget.
Store the key like a production secret
The private key never belongs in your repository, your prompt, or your agent's context window — an agent that can read its own key can be tricked into revealing it. Inject it through an environment variable or a secrets manager, and keep it out of logs and error traces.
Plan for rotation from day one. Because the wallet is just a keypair, rotating means generating a new one, moving the balance, and updating the secret; if you've kept balances small, rotation is cheap.
Fund it with USDC on Base
x402 payments settle as USDC on the Base network, so that's what the wallet needs. Most exchanges support withdrawing USDC directly on Base — double-check the network selector, because USDC on the wrong chain won't pay a Base settlement. Bridging from another chain works too.
Keep the float small. With a $0.01 minimum per call, even $20 funds thousands of calls; an agent wallet holding a working week's budget rather than a treasury limits the blast radius of any mistake. Whether the wallet also needs gas depends on your facilitator's flow — with most x402 setups the agent signs an authorization and the facilitator handles on-chain submission, but check your facilitator's docs.
Wire it into the agent's HTTP client
The runtime change is small: wrap your HTTP client so 402 responses are paid and retried automatically. The wrapper reads the payment requirements from the challenge, signs with the wallet, and replays the request with the payment attached — your agent code just sees a successful response.
From there, any x402-priced endpoint in the Loomal index is callable: the agent discovers the tool, reads its per-call price, pays, and gets an Ed25519-signed receipt with the result.
import { privateKeyToAccount } from "viem/accounts";
import { wrapFetchWithPayment } from "x402-fetch";
const account = privateKeyToAccount(process.env.AGENT_WALLET_KEY as `0x${string}`);
const payingFetch = wrapFetchWithPayment(fetch, account);
// 402 challenge → sign USDC payment → retry — all transparent:
const res = await payingFetch("https://api.example.com/v1/lookup", {
method: "POST",
body: JSON.stringify({ query: "case 24-1882" }),
});Set spending guardrails
An auto-paying agent needs limits the same way an auto-deploying pipeline needs approvals. Enforce a maximum price per call — so the agent declines any 402 quoting more than, say, $0.50 — plus a per-task and per-day budget cap in your own code.
Log every payment: endpoint, amount, and the signed receipt. Settlement on Base is final, with no chargebacks, so your guardrails and your audit trail are the protections that matter. The receipts double as your cost accounting per task.
FAQ
Does setting this up require blockchain development?
No. The agent side is standard HTTP plus one signing call that a library handles for you — the 402 challenge and payment payload are JSON. The on-chain verification and settlement are the facilitator's job, not yours.
How much USDC should I keep in an agent wallet?
As little as covers your near-term usage. Calls start at $0.01, so a small balance goes far, and a lean wallet bounds the damage from a leaked key or a runaway loop. Top up on a schedule instead of parking a large balance.
What happens if the agent hits an endpoint that costs more than its limit?
The 402 challenge quotes the price before any payment happens, so a well-configured client simply declines and moves on — nothing is spent. That pre-payment quote is what makes per-call budget caps enforceable in client code.
Can multiple agents share one wallet?
Technically yes — payments are just signatures — but you lose per-agent accounting and per-agent blast radius. A wallet per agent or per workload keeps budgets, receipts, and key rotation cleanly separated, and keys are cheap to generate.
Give your agent a wallet.
Then point it at priced tools in the Loomal index.