Client and Agent Guide

Client policy comes first

The buyer quickstart focuses on installing wrappers and signers, but production clients need a policy layer. An agent should know the maximum price per call, allowed networks, allowed assets, allowed recipients or services, daily spend, retry budget, and whether it is allowed to pay for a resource that was not explicitly requested by a user.

This is where x402 intersects with wallet governance. A signer that can technically authorize a payment should still be wrapped by controls. Without them, a compromised tool, misleading endpoint, or pricing bug can drain a hot wallet through perfectly valid signatures.

• Compare the server price against a local budget before signing.
• Pin or validate trusted domains for high-value services.
• Log the decoded requirements and decoded settlement response for later audit.
• Persist payment identifiers when retrying the same logical purchase.

Signer setup

The official buyer docs show EVM private-key signers, Solana signers, Python signers, and Go signers. Those examples are development starting points. In production, prefer delegated wallets, policy-governed wallet APIs, hardware-backed keys, or scoped account infrastructure over unprotected environment variables on shared machines.

For agent use, the wallet should be able to sign without prompting a human for every low-value request, but that does not mean unlimited authority. A better pattern is a budgeted wallet or delegated session with capped spend and a narrow allowlist.

// Buyer-side policy gates before signing.
if (offer.amountUsd > policy.maxUsdPerRequest) reject("price_too_high");
if (!policy.allowedNetworks.includes(offer.network)) reject("network_not_allowed");
if (!policy.allowedHosts.includes(new URL(resourceUrl).host)) reject("host_not_allowed");

// Only after policy passes should the client create and sign PaymentPayload.

Retry safety

A paid HTTP request can fail at several points: network loss after signing, facilitator timeout, resource-server crash after settlement, or client crash before reading the response. Retrying without an idempotency plan can duplicate work, duplicate settlement attempts, or make a client think it needs to buy again.

The payment-identifier extension exists for this reason. It lets a client attach a stable payment ID to a logical request and lets the server cache a response keyed by that ID. Even if a deployment does not adopt the extension, it should define an equivalent retry policy for paid operations.

• Use one payment ID per logical purchase, not per TCP attempt.
• Cache successful paid responses long enough for client retries.
• Expose machine-readable errors so agents know whether to retry, choose another offer, or stop.