Buyer agent course

Buyer Agent Track: Let an Agent Pay via x402

A buyer agent is just an HTTP client with money. The hard part is not signing; it is deciding when signing is allowed.

Give the agent a bounded wallet

The official buyer quickstart starts with a wallet funded with USDC and a service that requires x402 payment. That is necessary but not sufficient for an agent. Agents need spending boundaries before they receive signing capability.

Start with a testnet wallet, a small balance, and a policy file. Keep the policy in the same repository as the agent code so reviews can see what hosts, networks, and prices are allowed. A useful policy is boring: it says where the agent may pay, how much it may spend, and when a human must approve.

Agent payment policy
{
  "allowedHosts": ["api.example.com", "localhost:4021"],
  "allowedNetworks": ["eip155:84532"],
  "maxPerRequestUsd": "0.005",
  "dailyBudgetUsd": "0.25",
  "requireHumanApprovalAboveUsd": "0.01",
  "dryRun": false
}

Wrap the HTTP client

The buyer SDK examples show payment-aware wrappers for normal HTTP clients. This is the right abstraction for an agent because tools can keep calling fetch while the wrapper handles the x402 negotiation.

Payment-aware fetch
import { wrapFetchWithPayment, x402HTTPClient } from "@x402/fetch";
import { x402Client } from "@x402/core/client";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY);
const client = new x402Client();
client.register("eip155:*", new ExactEvmScheme(signer));

export const paidFetch = wrapFetchWithPayment(fetch, client);
export const paymentInspector = new x402HTTPClient(client);
"A service that requires payment via x402."
Primary source: x402 docs: Quickstart for Buyers

Keep the wrapper small. Put policy checks around it rather than inside every tool. That makes it easier to test the agent's payment decisions independently from the x402 SDK behavior.

Pay only after policy passes

A buyer agent should never treat every 402 as permission to spend. A 402 response is an offer to pay for access. Your agent still needs to compare the payment requirements to policy: host, scheme, network, maximum price, budget, expected MIME type, and the user's instruction.

Guarded paid call
const url = "https://api.example.com/paid-endpoint";

assertHostAllowed(url, policy.allowedHosts);
assertBudgetAvailable(policy, "$0.005");

const response = await paidFetch(url);
const result = await paymentInspector.processResponse(response);

auditLog({
  url,
  status: response.status,
  paymentStatus: result.paymentStatus,
});

Log the decision before and after the paid call. The pre-payment log should explain why the agent believed payment was authorized. The post-payment log should record the payment status exposed by the client helper and the resource returned.

Make retries explicit

Agents retry. Networks fail. Processes restart. The x402 payment-identifier extension provides an idempotency mechanism when the server advertises support. Use one logical payment ID per user task or tool call, persist it across retries, and never generate a new ID just because a response timed out.

If the server does not declare idempotency support, the agent should be conservative. It can ask for human confirmation, check its own audit log, or avoid retrying paid calls automatically. That is slower than blind retries, but it avoids turning flaky networking into accidental duplicate spending.

Sources used

  1. x402 docs: Quickstart for Buyers

    Official buyer setup, client package installation, and fetch/axios payment wrappers.

  2. x402 docs: Client / Server

    Summarizes client and server responsibilities in x402.

  3. x402 docs: Networks and Token Support

    Documents CAIP-2 network identifiers and supported network namespaces.

  4. x402 docs: Payment-Identifier extension

    Documents idempotency support for retries without duplicate payment processing.

  5. x402 Foundation GitHub repository

    Open-source SDKs, examples, and the typical x402 request/payment/settlement flow.

  6. Cloudflare Agents docs: x402

    Cloudflare overview for accepting and making machine-to-machine payments with x402.