fix(x402): enforce cap on selected payment requirement

[mattzcarey]

withX402Client checked maxPaymentValue against the first advertised payment requirement, but x402 picks the requirement it signs afterwards, after applying scheme support and network preference. A server could advertise a cheap first offer on a network the client doesn't prefer and a second, expensive one it does. The client would then sign the expensive one without the cap ever applying to it.

The cap now runs in x402's pre-signing hook, on the requirement that will actually be signed:

paymentClient.onBeforePaymentCreation(async ({ selectedRequirements }) => {
  const { scheme, amount } = selectedRequirements;
  if (scheme !== "exact") throw new PaymentPassthroughError();
  let value: bigint;
  try {
    value = BigInt(amount);
  } catch {
    throw new PaymentPassthroughError(); // malformed amount
  }
  if (value < 0n) throw new PaymentPassthroughError();
  if (value > maxPaymentValue) {
    throw new PaymentCapError(`Payment exceeds client cap: ${value} > ${maxPaymentValue}`);
  }
});

• x402 runs beforePaymentCreation hooks outside its own try, from 2.0.0 onwards, so the typed errors reach withX402Client unchanged across the whole @x402/core ^2.0.0 peer range. Returning { abort: true } would have been rewrapped as a plain Error.
• An over-cap selection returns Payment exceeds client cap: … without signing or retrying. A malformed, negative or non-exact selection returns the server's original 402 result, as before.
• When nothing offered can be signed (no exact offer, or only ones on networks the EVM client can't sign), the original 402 comes back with the server's payment options. x402 selects before it runs any hook, so a request that fails without reaching the cap hook is exactly that case.
• The advertised requirements are snapshotted once, and the confirmation callback gets its own deep copies, so nothing outside can change what is cap-checked or signed.
• No API or dependency changes.

[changeset-bot]

🦋 Changeset detected

Latest commit: c8fd906

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
agents	Patch
@cloudflare/agent-think	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[agent-think]

✅ agents import sizes: no significant changes (e8379676 → c8fd906d, workflow run)

[devin-ai-integration]

Note

This report is out of date. Scroll down for Devin Review's latest report on this PR.

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.

[pkg-pr-new]

Open in StackBlitz

agents

npm i https://pkg.pr.new/agents@2272

@cloudflare/ai-chat

npm i https://pkg.pr.new/@cloudflare/ai-chat@2272

@cloudflare/codemode

npm i https://pkg.pr.new/@cloudflare/codemode@2272

hono-agents

npm i https://pkg.pr.new/hono-agents@2272

@cloudflare/shell

npm i https://pkg.pr.new/@cloudflare/shell@2272

@cloudflare/think

npm i https://pkg.pr.new/@cloudflare/think@2272

@cloudflare/voice

npm i https://pkg.pr.new/@cloudflare/voice@2272

@cloudflare/worker-bundler

npm i https://pkg.pr.new/@cloudflare/worker-bundler@2272

commit: c8fd906