APN x402 purchases

Agent Payment Node (APN) pays x402 sellers from a local wallet or a supported provider wallet, under limits the owner sets first. This page covers the payment mechanisms APN supports, how it picks an offer from a seller's challenge, what it checks before signing, and the policy that must exist before an agent can buy anything.

Updated

What is x402 and where does APN fit?

x402 is an open standard for internet payments built on HTTP. According to x402.org, a server that receives a request without payment answers with HTTP 402, and the client pays and retries. APN is the client side of that exchange: it is a runtime an AI agent uses to pay x402 sellers. APN does not run a seller and does not operate a facilitator.

The wider picture, including MCP and AP2, is on the x402, AP2 and APN page. For the agent-facing server, see APN MCP.

Which x402 payment mechanisms does APN support?

The README names three standard families: EIP-3009 USDC, Permit2 and ERC-20 transfer-proof merchants. Solana exact offers have their own command.

MechanismCommandsApproval
EIP-3009 (USDC and other admitted tokens)x402 inspect, x402 fetch prepare, x402 fetch approveUnattended under the profile x402 policy, CLI and MCP
Permit2, unattendedx402 fetch when the seller offers only Permit2Unattended under the profile x402 policy, local wallet only
Permit2, foregroundx402 permit2 preflight, approve, observe, statusCLI with foreground approval; MCP gives a handoff
ERC-20 transfer-proof merchantsx402 merchant prepare, approve, observe, status, retire-unsentForeground approval; prepare, observe, status and retire-unsent are also MCP tools, approve returns the handoff
Solana exact (SPL)x402 solana pay, observe, statusUnattended, CLI or MCP, under the Solana x402 policy and an allowlist row

For EVM fetch, APN uses EIP-3009 when the seller offers it for the selected chain and token, and otherwise Permit2. The choice is deterministic, and an operation never changes method after prepare.

How does an APN x402 purchase work?

The first step is the owner's policy. Creating a policy or raising a limit needs the foreground terminal. A pure decrease does not.

apn wallet policy set --profile agent --max-balance-usdc-atomic <limit> --max-x402-amount-atomic <limit> \
  [--max-balance-eth-wei <limit>] [--x402-payees <address,...|unrestricted>]
apn x402 inspect --url https://seller.example/resource
apn x402 fetch prepare --profile agent --url https://seller.example/resource \
  --idempotency-key buy-0001 --rpc-url https://mainnet.base.org
apn x402 fetch approve --operation <operation-id> --rpc-url https://mainnet.base.org
apn operation resume --operation <operation-id> --rpc-url https://mainnet.base.org --wait-seconds 60
  • x402 inspect reads the seller's challenge and shows which offers APN would accept.
  • x402 fetch prepare uses the owner's maximum amount. --max-amount-atomic can only lower it for one call.
  • x402 fetch approve creates exactly one frozen authorization.
  • operation resume owns the paid request, settlement observation and seller-result recovery.
  • --method, --headers-json and --body-base64 send POST and other requests, with opaque body bytes bound into the operation.
  • --x402-payees optionally pins which sellers may be paid.

How does APN select an x402 offer?

A seller's x402 v2 PAYMENT-REQUIRED challenge lists one or more offers. APN accepts any nonempty, schema-valid offer list within a header budget of 64 KiB encoded and 48 KiB decoded. There is no separate limit on the number of offers.

  • Unsupported networks and payment mechanisms may sit beside a supported offer. Selection keeps the offer's original index and exact requirements, and the seller's challenge is never rewritten.
  • The selected offer must match the selected network, an owner-admitted asset, a supported mechanism, the on-chain token domain, the timeout, the balance and the amount and policy caps.
  • maxTimeoutSeconds must be from 30 through 3,600 seconds. Offers asking for more are refused as x402_offer_timeout_exceeds_bound.
  • The challenge's resource.url must name the requested endpoint with the same scheme, host, port and path. Another origin or path is refused as x402_resource_url_mismatch.
  • A longer offer list does not enable unadmitted tokens or other wallet-provider capabilities. Unknown optional extensions are not authorization to run their protocols.

A refusal names the reason per offer: the deciding field, the seller's value and what APN accepts. Seller text is treated as untrusted, so seller values appear only in structured details, and unusual values are shown as a length and SHA-256 digest instead of raw text. The full rules are in the repository's offer selection guide.

Can APN pay any x402 seller, and in tokens other than USDC?

APN pays a seller's exact offer from a local wallet on any EVM network and token the owner admitted, and on Solana for an admitted classic SPL mint. The seller supplies only the payee, the amount and the resource. Nothing is inferred from the seller's words alone: the token's identity is read from the chain at prepare.

  • Without --asset, --chain means USDC on Base, Ethereum or Arbitrum. On any other chain the command refuses with x402_asset_required.
  • Omitting --chain selects Base. Each chain and token has its own policy record, and none inherits another's limits.
  • Foreground Permit2 (x402 permit2 *) works on any chain and token the owner's allowlist policy admits for Permit2, USDC included. Native coins cannot be paid through Permit2.
  • Allowlist rows for Solana can name only inventory assets, which are USDC and USDT. Token-2022 mints are refused.
  • ERC-20 transfer-proof merchants (x402 merchant *) pin one asset: USDm on MegaETH (eip155:4326). The payer signs a plain ERC-20 transfer and pays gas. This is not EIP-3009 and not gasless.

APN never sends an onchain approval to Permit2 unattended. If the wallet's allowance to Permit2 is too small, x402 fetch refuses with x402_permit2_allowance_required and names the owner's x402 permit2 allowance set command, which runs in the foreground and never grants an unlimited amount.

What does APN check before it signs an x402 payment?

Prepare proves the token's identity on the chain. For EIP-3009 it checks the EIP-712 domain separator built from the offer's name and version, a fresh authorization nonce, the decimals and the balance, all in one batch pinned to one block. For a Permit2-only seller it checks the canonical Permit2 contract and the x402 exact Permit2 proxy by runtime code hash, plus the wallet's allowance.

  • The eth_chainId of your RPC must equal the offer's chain. A wrong-chain RPC is refused with APN_CHAIN_MISMATCH.
  • --rpc-url is explicit for every EVM x402 command. A missing one is refused with x402_rpc_required, and APN substitutes no endpoint.
  • The per-payment cap is read again before signing and before the first paid request. If the owner lowered it below the frozen cap, APN signs and sends nothing and answers APN_X402_PROFILE_LIMIT_EXCEEDED.
  • A wallet that holds more than the owner's balance cap is refused for unattended x402. The Solana lane reports this as APN_WALLET_OVERFUNDED_FOR_UNATTENDED_X402.

How does APN prove settlement?

HTTP success alone never completes a payment. Settlement is proven on chain at the chain's proof tag, either safe or finalized, which is frozen in the record when the operation is prepared. A seller's PAYMENT-RESPONSE header can name the settlement transaction, and APN accepts two field names for it:

  • transaction, the canonical x402 field.
  • txHash, an alias some sellers use.
  • At least one must hold a non-zero, lowercase, 32-byte hexadecimal hash. If both are present they must be valid and identical, or the response is refused.
  • A malformed transaction cannot be rescued by a valid txHash, and the reverse.

The header is only a hint. Several copies of PAYMENT-RESPONSE count as one hint only when they are byte-identical, and settlement is proven on chain, never by the header. A paid body that was kept without a hint is never paid for again. See recovery for what happens when the outcome is unclear.

What x402 policy does the owner need?

Every lane needs an owner admission. Which one depends on the lane:

LaneOwner admission
Standard EVM x402 (EIP-3009, or Permit2 when that is all the seller offers)The profile x402 policy for the exact chain and token
Foreground Permit2The active allowlist row for that chain and token with the x402 rail, its caps and the Permit2 mechanism pin
Solana exactThe profile x402 policy for the mint, plus an active allowlist row for the mint with the x402 rail

APN never fills in a missing cap, account, recipient or amount. Caps are in atomic units of the token. Provider balance is never spending authority: the owner allowlist and the profile policy still apply. See security for the allowlist and wallets for which profiles can pay x402.

Questions

Does APN support x402?

Yes. APN pays standard x402 purchases with EIP-3009 USDC, Permit2 and ERC-20 transfer-proof merchants, and pays Solana exact offers.

Which tokens can APN pay on x402?

Any EVM token the owner admitted that the seller offers through EIP-3009 or Permit2, USDm on MegaETH for transfer-proof merchants, and USDC or USDT on Solana. Without --asset, the default is USDC on Base, Ethereum or Arbitrum.

Can an AI agent buy from an x402 seller without a human approving each payment?

For standard EVM x402 and Solana exact, yes, but only inside the limits the owner set in advance in a foreground terminal. The foreground Permit2 lane (x402 permit2 approve) and the merchant lane need foreground approval.

Does APN need a facilitator?

APN does not query a facilitator in the Permit2 lane. The seller chooses the facilitator, and a facilitator that cannot settle leaves the signature to expire unused at its deadline.

What happens if the seller returns an error after I paid?

APN keeps the settled payment on record and recovers the result only if the seller supports an idempotent result-recovery contract. Otherwise it may report the result as unavailable instead of paying again.

Sources
  1. README: x402 purchases
  2. docs/x402-offer-selection.md
  3. docs/x402-any-seller.md
  4. docs/x402-non-usdc.md
  5. docs/x402-merchant-usdm.md
  6. docs/x402-settlement-compatibility.md
  7. x402.org, checked 2026-11-18