@agent-score/commerce 2.0.2 → 2.1.1

package/README.md

@@ -26,15 +26,31 @@ npm install hono mppx @x402/core @x402/evm @solana/mpp @solana/kit stripe   # wh
 | `/identity/{hono,express,fastify}` | Trust gate middleware: KYC, sanctions (account name + signer wallet), age, jurisdiction. Context-getter pattern: `agentscoreGate(opts)` middleware + `getAgentScoreData(ctx)` / `getGateDegradedState(ctx)` / `getGateQuotaInfo(ctx)` / `getSignerVerdict(ctx)` accessors, `captureWallet(...)`. Plus shared denial helpers: `denialReasonStatus`, `denialReasonToBody`, `buildSignerMismatchBody`, `buildContactSupportNextSteps`, `verificationAgentInstructions`, `isFixableDenial`, `FIXABLE_DENIAL_REASONS`. |
 | `/identity/policy` | Per-product compliance helpers for multi-product merchants (each product carries its own policy: hard gate vs soft vs none, per-product shipping allowlists): `PolicyBlock`, `GateResult`, `EnforcementMode`, `IdentityStatus`, `buildGateOptionsFromPolicy`, `runGateWithEnforcement`, `shippingCountryAllowed`, `shippingStateAllowed`, `validateShippingAgainstPolicy` (one-call country+state validator that raises `CheckoutValidationError` with the canonical envelope on miss). |
 | `/identity/{nextjs,web}` | Same gate, wrapper pattern: `withAgentScoreGate(opts, handler)` / `createAgentScoreGate(opts) => guard(req)`. The `data` + `degraded` + `infraReason` + `getSignerVerdict` fields land directly on the handler arg / guard result (no separate getter). Plus shared `captureWallet`. |
-| `/payment` | `networks`, `USDC`, `rails` registries; `paymentDirective`, `buildPaymentDirective`, `wwwAuthenticateHeader`, `paymentRequiredHeader`, `aliasAmountFields` (v1↔v2 amount field shim: emits both `amount` and `maxAmountRequired` so v1-only x402 parsers like Coinbase awal can read v2 bodies), `settlementOverrideHeader`, `dispatchSettlementByNetwork`, `extractPaymentSigner` (Request-based; recovers signer from x402 EIP-3009 `payload.authorization.from` OR MPP `Authorization: Payment <base64>` `did:pkh:eip155:<chain>:<addr>` / `did:pkh:solana:<genesis>:<addr>` source DID, including Solana `TransferChecked` authority fallback when `@solana/kit` is installed), `extractPaymentSignerFromAuth` (header-string variant for callers that already have the `Authorization` value in hand), `detectRailFromHeaders` (returns `"x402"` / `"mpp"` / `null` from inbound headers); `createX402Server`, `createMppxServer`; drop-in x402 helpers: `validateX402NetworkConfig` (boot-time guard), `verifyX402Request` (parse + validate inbound X-Payment), `processX402Settle` (verify-then-settle with one call), `classifyX402SettleResult` (maps the tagged settle result to a recommended HTTP status / code / nextSteps so merchants get a controlled envelope without coupling to facilitator-specific error text), `classifyOrchestrationError` (same `ClassifiedX402Error` shape but for uncaught exceptions thrown elsewhere in the orchestration; returns `null` for unknown errors so merchants rethrow instead of swallowing); `zeroAmountCarveOut` (skip CDP / mppx upstream verify+settle for $0 settles where the upstream rejects value=0 payloads; parses the credential, lifts signer + network, returns a `ZeroSettleResult` shaped identically to the success path so callers branch on rail, not on result shape); `usdToAtomic` (BigInt-based USD → atomic value, ROUND_HALF_UP — for Tempo / Solana / Base USDC amount construction). |
+| `/payment` | `networks`, `USDC`, `rails` registries; `paymentDirective`, `buildPaymentDirective`, `wwwAuthenticateHeader`, `paymentRequiredHeader`, `aliasAmountFields` (v1↔v2 amount field shim: emits both `amount` and `maxAmountRequired` so v1-only x402 parsers like Coinbase awal can read v2 bodies), `settlementOverrideHeader`, `dispatchSettlementByNetwork`, `extractPaymentSigner` (Request-based; recovers signer from x402 EIP-3009 `payload.authorization.from` OR MPP `Authorization: Payment <base64>` `did:pkh:eip155:<chain>:<addr>` / `did:pkh:solana:<genesis>:<addr>` source DID, including Solana `TransferChecked` authority fallback when `@solana/kit` is installed), `extractPaymentSignerFromAuth` (header-string variant for callers that already have the `Authorization` value in hand), `detectRailFromHeaders` (returns `"x402"` / `"mpp"` / `null` from inbound headers); `createX402Server`, `createMppxServer`, `buildDefaultCheckoutRails({tempo?, x402Base?, solanaMpp?, stripe?})` (canonical 4-rail `rails` dict factory: flipping `network` alone derives the right `token` + `chainId` — Base Sepolia → Sepolia USDC + chainId 84532, Solana devnet → devnet USDC mint. Solana's `network` accepts both CAIP-2 and the raw `@solana/mpp` form `mainnet-beta` / `devnet` / `localnet`. Explicit overrides always win), `buildMppxComposeRails({amountUsd, tempoRecipient?, solanaRecipient?, ...})` (per-call intent factory replacing the hand-rolled `[['tempo/charge',{...}],['solana/charge',{...}],['stripe/charge',{...}]]` array; auto-handles USD→atomic conversion for Solana; auto-drops `stripe/charge` when `amountUsd < 0.50` since Stripe's fixed ~$0.30 fee makes sub-50-cent charges unprofitable — sub-50-cent APIs pass `includeStripe: false` explicitly to silence the warning); drop-in x402 helpers: `validateX402NetworkConfig` (boot-time guard), `verifyX402Request` (parse + validate inbound X-Payment), `processX402Settle` (verify-then-settle with one call), `classifyX402SettleResult` (maps the tagged settle result to a recommended HTTP status / code / nextSteps so merchants get a controlled envelope without coupling to facilitator-specific error text), `classifyOrchestrationError` (same `ClassifiedX402Error` shape but for uncaught exceptions thrown elsewhere in the orchestration; returns `null` for unknown errors so merchants rethrow instead of swallowing); `zeroAmountCarveOut` (skip CDP / mppx upstream verify+settle for $0 settles where the upstream rejects value=0 payloads; parses the credential, lifts signer + network, returns a `ZeroSettleResult` shaped identically to the success path so callers branch on rail, not on result shape); `usdToAtomic` (BigInt-based USD → atomic value, ROUND_HALF_UP — for Tempo / Solana / Base USDC amount construction). |
 | `/discovery` | `isDiscoveryProbeRequest`, `buildDiscoveryProbeResponse` (with optional `x402Sample` for x402-aware crawlers, e.g. `awal x402 details`), `sampleX402AcceptForNetwork` (USDC sample-accept builder for known CAIP-2 networks), `buildWellKnownMpp`, `buildLlmsTxt` + `llmsTxtIdentitySection` + `llmsTxtPaymentSection` (compact + verbose modes), `buildSkillMd` (Claude-Skill-compatible `/skill.md` agent-discovery manifest; strictly agent-facing data only, no internal posture), `buildRedemptionSkillMd` (delivery-neutral redemption-code template — printed mailers, emailed codes, API trial credits all covered; `endpointPath`/`deliveryIntro`/`bodyShape`/`bodyRules`/`extraRecoveryRows` overrides for non-goods shapes), `agentscoreOpenApiSnippets`, `createBazaarDiscovery`, `noindexNonDiscoveryPaths` (Hono middleware emitting `X-Robots-Tag: noindex` on every path except the agent-discovery surfaces; pure helpers `isDiscoveryPath` + `defaultDiscoveryPaths` for non-Hono frameworks), `buildMerchantIndexJson` (canonical `/` discovery body), `standardEndpointDescriptions({kind})` (canonical method+path → description map for goods vs api merchants; optional `includeOrderStatusRoute` for goods), `buildSuccessNextSteps` (universal Passport-active success block), `buildAgentscoreOnboardingSteps` (canonical skill.md onboarding for goods or API merchants). Plus the UCP/JWKS publish surface: `buildSignedUcpResponse`, `buildSignedJwksResponse`, `wellKnownPreflightResponse`, `defaultA2aServices`, `bootstrapUcpSigningKey`, and the framework-neutral `SignedDiscoveryResponse` + per-framework wrappers `signedResponse{Hono,Express,Fastify,Nextjs,Web}`. |
 | `/challenge` | `build402Body`, `buildAcceptedMethods`, `buildIdentityMetadata`, `buildHowToPay`, `buildAgentInstructions` (auto-emits per-rail `compatible_clients`: smoke-verified CLIs the agent should use; vendor override supported; pure helper `compatibleClientsByRails(rails)` returns the same map for vendors building custom 402s), `buildPricingBlock`, `firstEncounterAgentMemory`, `Receipt` + `ReceiptNextSteps` + `ProductInfo` + `ShippingAddress` (canonical 200-receipt shape returned post-settle — universal: goods merchants fill the shipping/fulfillment/product slots, API merchants populate only the universal fields); `respond402`, a drop-in 402 emit that preserves mppx's `WWW-Authenticate` and layers x402's `PAYMENT-REQUIRED`. `buildValidationError`: structured 4xx body builder (`{error: {code, message}, required_fields?, example_body?, next_steps?, ...extra}`) so vendors compose body shapes by name instead of inlining at every validation site. |
-| `/stripe-multichain` | `createMultichainPaymentIntent` (returns `{ paymentIntentId, depositAddresses }` — read `depositAddresses[network]` directly), `simulateCryptoDeposit`, `createMppxStripe`; `createPiCache` (TTL'd PI / deposit-address cache, Redis-backed when `redisUrl` set, in-memory otherwise), `simulateDepositIfTestMode` (gates on `sk_test_` and looks up the PI for you), `STRIPE_TEST_TX_HASH_SUCCESS` / `STRIPE_TEST_TX_HASH_FAILED` constants. Peer dep on `stripe`. |
+| `/stripe-multichain` | `createMultichainPaymentIntent` (returns `{ paymentIntentId, depositAddresses }` — read `depositAddresses[network]` directly), `createPayToAddressFromStripePI({request, amountCents, stripe, piCache, networks?, metadata?, orderId?, preferredNetwork?})` — per-order payTo resolver: on the settle leg, reuses the buyer's signed-against payTo from the MPP credential (after `piCache.hasAddress` check); on the discovery leg, mints a fresh PI and caches it. `simulateCryptoDeposit`, `createMppxStripe`; `createPiCache` (TTL'd PI / deposit-address cache, Redis-backed when `redisUrl` set, in-memory otherwise), `simulateDepositIfTestMode` (gates on `sk_test_` and looks up the PI for you), `STRIPE_TEST_TX_HASH_SUCCESS` / `STRIPE_TEST_TX_HASH_FAILED` constants. Peer dep on `stripe`. |
 | `/api` | Everything from `@agent-score/sdk` re-exported in one place: `AgentScore` + `AgentScoreError`, `AGENTSCORE_TEST_ADDRESSES` + `isAgentScoreTestAddress`. **Don't add `@agent-score/sdk` as a separate dep**; the two can drift versions and cause subtle type mismatches. |
-| `@agent-score/commerce` (top-level) | `Checkout` orchestrator + `CheckoutContext` + `CheckoutGateConfig` + `CheckoutValidationError` + `DiscoveryProbeConfig` + `MountUcpRoutesOptions` + `SettleOutcome` + `MppxComposeOutcome` + `PricingResult` (the 2.0 high-level surface: one config object, hooks for preValidate/computePricing/onSettled/mintRecipients/composeMppx, auto-derived x402+mppx servers, per-framework adapters `handleHono`/`handleExpress`/`handleFastify`/`handleNextjs`/`handleWeb`, signed UCP routes via `mountUcpRoutes{Hono,Express,Fastify}`); `pricingResult` (factory: cents-denominated → typed `PricingResult` with embedded `PricingBlock`); `validationResponse{Hono,Express,Fastify,Nextjs,Web}` (per-framework 4xx envelope wrappers); `loadUCPSigningKeyFromEnv` + `LoadUCPSigningKeyOptions` (cached env-driven loader for the UCP signing key — reads `UCP_SIGNING_KEY_JWK_PRIVATE` JSON JWK, detects alg from shape, falls back to ephemeral when unset, sanitizes errors so key bytes never reach logs, concurrent-safe via Promise-pinned cache); `hashOperatorToken` (sha256 hex of plaintext `opc_...` — for merchants persisting `operator_token_id` to their own DB without ever storing the plaintext); plus the cross-vendor publishers `buildA2AAgentCard` + `buildUCPProfile` (return unsigned payloads: vendor signs + publishes). |
+| `/middleware/{hono,express,fastify,nextjs,web}` | Framework-specific rate-limit middleware. Hono / Express / Fastify expose middleware factories (`rateLimitHono`, `rateLimitExpress`, `rateLimitFastify`); Next.js exposes `withRateLimit(opts, handler)`; Web Fetch exposes `createRateLimit(opts) => guard(req)`. Shared options: `windowSeconds` (default 60), `maxRequests` (default 60), `keyResolver` (default first hop of `x-forwarded-for`), `redisUrl` (lazy-imports `ioredis` when set, in-memory `Map` fallback otherwise), `keyPrefix`. `ioredis` is an optional peer dep — install it only if you want distributed limiting. |
+| `@agent-score/commerce` (top-level) | `Checkout` orchestrator + `CheckoutContext` + `CheckoutGateConfig` + `CheckoutValidationError` + `DiscoveryProbeConfig` + `MountUcpRoutesOptions` + `SettleOutcome` + `MppxComposeOutcome` + `PricingResult` (the 2.0 high-level surface: one config object, hooks for preValidate/computePricing/onSettled/mintRecipients/composeMppx, auto-derived x402+mppx servers, per-framework adapters `handleHono`/`handleExpress`/`handleFastify`/`handleNextjs`/`handleWeb`, signed UCP routes via `mountUcpRoutes{Hono,Express,Fastify}`); `pricingResult` (factory: cents-denominated → typed `PricingResult` with embedded `PricingBlock`); `validationResponse{Hono,Express,Fastify,Nextjs,Web}` (per-framework 4xx envelope wrappers); `loadUCPSigningKeyFromEnv` + `LoadUCPSigningKeyOptions` (cached env-driven loader for the UCP signing key — reads `UCP_SIGNING_KEY_JWK_PRIVATE` JSON JWK, detects alg from shape, falls back to ephemeral when unset, sanitizes errors so key bytes never reach logs, concurrent-safe via Promise-pinned cache); `hashOperatorToken` (sha256 hex of plaintext `opc_...` — for merchants persisting `operator_token_id` to their own DB without ever storing the plaintext); `extractOwnerScope(headers) → { walletAddress?, operatorTokenHash? }` (canonical owner-identity extractor for caller-scoped resource queries — reads `X-Wallet-Address` / `X-Operator-Token`, hashes the token so plaintext never leaves the request); `hasPaymentHeader` / `hasX402Header` / `hasMppxHeader` (request discriminators — any-credential vs x402 vs MPP); `defaultReadOnlyOnDenied(reason)` (canonical `onDenied` for read-only resource gates: 401 + `Cache-Control: no-store` while still spreading `denialReasonToBody`); plus the cross-vendor publishers `buildA2AAgentCard` + `buildUCPProfile` (return unsigned payloads: vendor signs + publishes). |
 
 ## Quick start
 
+### Rate limiting (Hono / Express / Fastify / Next.js / Web)
+
+Mount globally before any payment route so probe and settle legs share the same bucket. Defaults: 60 req / 60s / IP. Redis when `REDIS_URL` is set, in-memory fallback otherwise.
+
+```typescript
+import { Hono } from "hono";
+import { rateLimitHono } from "@agent-score/commerce/middleware/hono";
+
+const app = new Hono();
+app.use("*", rateLimitHono());
+// ... your routes ...
+```
+
+Same factory shape per framework: `rateLimitExpress`, `rateLimitFastify` (preHandler hook), `withRateLimit(opts, handler)` for Next.js App Router, and `createRateLimit(opts) => guard(req)` for Web Fetch. Override `maxRequests` / `windowSeconds` / `keyResolver` / `redisUrl` / `keyPrefix` as needed.
+
 ### Identity gate (Hono)
 
 ```typescript
@@ -60,13 +76,10 @@ const _gate = agentscoreGate({
 // Anonymous discovery (no payment header) flows through to the handler so any spec-
 // compliant x402 wallet can read the 402 challenge with rails + pricing without first
 // proving identity. Identity is verified at settle time on the retry leg.
+import { hasPaymentHeader } from "@agent-score/commerce/payment";
+
 app.use("/purchase", async (c, next) => {
-  const hasPaymentHeader = Boolean(
-    c.req.header("payment-signature") ||
-    c.req.header("x-payment") ||
-    c.req.header("authorization")?.startsWith("Payment "),
-  );
-  if (!hasPaymentHeader) { await next(); return; }
+  if (!hasPaymentHeader(c.req.raw)) { await next(); return; }
   return _gate(c, next);
 });
 
@@ -81,7 +94,9 @@ app.post("/purchase", async (c) => {
 
 ### Checkout orchestrator (the 2.0 high-level surface)
 
-`Checkout` is the canonical merchant surface: one config object, hooks for the merchant-specific pieces, and the SDK handles 402 emit, identity gating, x402 verify+settle, mppx compose, $0 carve-out, and the per-framework adapter. Most merchants reach for `Checkout` first and drop to lower-level helpers only when they need custom flows (variable-cost streaming, multi-protocol composition, etc).
+`Checkout` is the canonical merchant surface for fixed-price one-shot endpoints: one config object, hooks for the merchant-specific pieces, and the SDK handles 402 emit, identity gating, x402 verify+settle, mppx compose, $0 carve-out, and the per-framework adapter. Most fixed-price merchants reach for `Checkout` first.
+
+For **variable-cost pay-per-result** endpoints (per-result search, per-token LLM, per-byte transcoding), reach for `computeFirstCheckout` — same config shape, but the probe leg runs the work, caches by body content-hash, and emits a 402 with the EXACT computed price. The retry pays that exact amount and receives the cached body. Works on every exact-mode rail (x402-exact Base, tempo/charge, solana/charge, Stripe SPT) without upto / Permit2 / Settlement-Overrides. Tradeoff: the work runs on the unpaid probe leg, so mount `rateLimitHono` (from `@agent-score/commerce/middleware/hono`) globally — it's load-bearing. See `examples/compute-first-merchant.ts`.
 
 ```typescript
 import { Checkout, pricingResult } from "@agent-score/commerce";
@@ -230,7 +245,7 @@ const responseBody = build402Body({
 });
 ```
 
-`buildPricingBlock` handles cents → dollar-string conversion (with optional shipping). Pass `discountCents` for redemption codes / coupons: `subtotal` stays the list price, the block surfaces `discount` as a dollar-string, and `total` becomes `subtotal + tax + shipping - discount` (floored at 0). `pricingResult` accepts the same `discountCents` and propagates it to `block.discount` so agents reading the 402 see the savings line. `firstEncounterAgentMemory` returns the canonical hint or `undefined` based on a per-merchant first-seen flag. `Receipt` is a universal TS interface for the post-settlement 200 response shape — goods merchants populate the shipping/fulfillment/tracking slots, API merchants fill only the universal fields (id, created_at, pricing, payment_status, next_steps).
+`buildPricingBlock` handles cents → dollar-string conversion (with optional shipping). Pass `discountCents` for redemption codes / coupons: `subtotal` stays the list price, the block surfaces `discount` as a dollar-string, and `total` becomes `subtotal + tax + shipping - discount` (floored at 0). `pricingResult` accepts the same `discountCents` and propagates it to `block.discount` so agents reading the 402 see the savings line. Pass `decimals: N` (default `2`) on either helper for sub-cent unit pricing — e.g. `decimals: 4` advertises `$0.0005`-precision instead of rounding to two decimals. Set `decimals` on `PricingResult` and the SDK threads it through `buildHowToPay`, `buildPricingBlock`, and the x402 settle `price` string automatically; the `cents` inputs accept fractional values under that mode (per-token / per-byte unit pricing). `firstEncounterAgentMemory` returns the canonical hint or `undefined` based on a per-merchant first-seen flag. `Receipt` is a universal TS interface for the post-settlement 200 response shape — goods merchants populate the shipping/fulfillment/tracking slots, API merchants fill only the universal fields (id, created_at, pricing, payment_status, next_steps).
 
 ### Idempotency-key + multi-rail header bundle
 

package/dist/_core-kI7FRAiZ.d.mts

@@ -0,0 +1,10 @@
+interface RateLimitCoreOptions {
+    windowSeconds?: number;
+    maxRequests?: number;
+    /** Redis connection URL. Default: `process.env.REDIS_URL`. Falls back to in-memory when unset or the lazy `ioredis` import fails. */
+    redisUrl?: string;
+    /** Per-instance key prefix so multiple limiters sharing a Redis don't collide. */
+    keyPrefix?: string;
+}
+
+export type { RateLimitCoreOptions as R };

package/dist/_core-kI7FRAiZ.d.ts

@@ -0,0 +1,10 @@
+interface RateLimitCoreOptions {
+    windowSeconds?: number;
+    maxRequests?: number;
+    /** Redis connection URL. Default: `process.env.REDIS_URL`. Falls back to in-memory when unset or the lazy `ioredis` import fails. */
+    redisUrl?: string;
+    /** Per-instance key prefix so multiple limiters sharing a Redis don't collide. */
+    keyPrefix?: string;
+}
+
+export type { RateLimitCoreOptions as R };

package/dist/challenge/index.d.mts

@@ -1,6 +1,6 @@
-import { T as TempoRailSpec, X as X402BaseRailSpec, S as SolanaMppRailSpec, b as StripeRailSpec } from '../rail_spec-XP0wKgJV.mjs';
-import { A as AgentInstructions, P as PricingBlock } from '../pricing-CxzwyiO6.mjs';
-export { C as CompatibleClients, H as HowToPayBlock, a as HowToPayRailEntry, b as HowToPayRails, c as HowToPayStripeEntry, R as RailKey, d as buildAgentInstructions, e as buildHowToPay, f as buildPricingBlock, g as compatibleClientsByRails } from '../pricing-CxzwyiO6.mjs';
+import { T as TempoRailSpec, X as X402BaseRailSpec, S as SolanaMppRailSpec, b as StripeRailSpec } from '../rail_spec-D6qzh3J0.mjs';
+import { A as AgentInstructions, P as PricingBlock } from '../pricing-4n5Ota0D.mjs';
+export { C as CompatibleClients, H as HowToPayBlock, a as HowToPayRailEntry, b as HowToPayRails, c as HowToPayStripeEntry, R as RailKey, d as buildAgentInstructions, e as buildHowToPay, f as buildPricingBlock, g as compatibleClientsByRails } from '../pricing-4n5Ota0D.mjs';
 import { AgentMemoryHint } from '../core.mjs';
 export { buildAgentMemoryHint } from '../core.mjs';
 import { p as paymentRequiredHeader } from '../wwwauthenticate-D_FMnPgU.mjs';

package/dist/challenge/index.d.ts

@@ -1,6 +1,6 @@
-import { T as TempoRailSpec, X as X402BaseRailSpec, S as SolanaMppRailSpec, b as StripeRailSpec } from '../rail_spec-XP0wKgJV.js';
-import { A as AgentInstructions, P as PricingBlock } from '../pricing-CQ9DIFaw.js';
-export { C as CompatibleClients, H as HowToPayBlock, a as HowToPayRailEntry, b as HowToPayRails, c as HowToPayStripeEntry, R as RailKey, d as buildAgentInstructions, e as buildHowToPay, f as buildPricingBlock, g as compatibleClientsByRails } from '../pricing-CQ9DIFaw.js';
+import { T as TempoRailSpec, X as X402BaseRailSpec, S as SolanaMppRailSpec, b as StripeRailSpec } from '../rail_spec-D6qzh3J0.js';
+import { A as AgentInstructions, P as PricingBlock } from '../pricing-DHfH3ogG.js';
+export { C as CompatibleClients, H as HowToPayBlock, a as HowToPayRailEntry, b as HowToPayRails, c as HowToPayStripeEntry, R as RailKey, d as buildAgentInstructions, e as buildHowToPay, f as buildPricingBlock, g as compatibleClientsByRails } from '../pricing-DHfH3ogG.js';
 import { AgentMemoryHint } from '../core.js';
 export { buildAgentMemoryHint } from '../core.js';
 import { p as paymentRequiredHeader } from '../wwwauthenticate-D_FMnPgU.js';

package/dist/challenge/index.js

@@ -181,10 +181,13 @@ function buildHowToPay({
   totalUsd,
   rails,
   opTokenPlaceholder,
-  maxSpend
+  maxSpend,
+  decimals
 }) {
   const totalNum = typeof totalUsd === "string" ? Number(totalUsd) : totalUsd;
-  const maxSpendStr = String(maxSpend ?? (Math.ceil(totalNum) + 1).toFixed(2));
+  const d = decimals ?? 2;
+  const defaultMaxSpend = totalNum >= 1 ? (Math.ceil(totalNum) + 1).toFixed(d) : totalNum.toFixed(d);
+  const maxSpendStr = String(maxSpend ?? defaultMaxSpend);
   const opToken = opTokenPlaceholder ?? "<your_opc_token>";
   const block = {};
   if (rails.tempo) {
@@ -471,25 +474,32 @@ function buildPricingBlock({
   totalCents,
   taxRate,
   taxState,
-  currency
+  currency,
+  decimals
 }) {
   const shipping = shippingCents ?? 0;
   const discount = discountCents ?? 0;
   const total = totalCents ?? Math.max(0, subtotalCents + taxCents + shipping - discount);
+  const d = decimals ?? 2;
+  const fmt = (cents) => (cents / 100).toFixed(d);
   const block = {
-    subtotal: formatCents(subtotalCents),
-    tax: formatCents(taxCents),
-    total: formatCents(total)
+    subtotal: fmt(subtotalCents),
+    tax: fmt(taxCents),
+    total: fmt(total)
   };
-  if (shippingCents !== void 0) block.shipping = formatCents(shipping);
-  if (discountCents !== void 0) block.discount = formatCents(discount);
+  if (shippingCents !== void 0) block.shipping = fmt(shipping);
+  if (discountCents !== void 0) block.discount = fmt(discount);
   if (taxRate !== void 0) block.tax_rate = taxRate;
   if (taxState !== void 0) block.tax_state = taxState;
   if (currency !== void 0) block.currency = currency;
   return block;
 }
-function formatCents(cents) {
-  return (cents / 100).toFixed(2);
+
+// src/_headers.ts
+function normalizeHeadersToLowercase(headers) {
+  const out = {};
+  for (const [k, v] of Object.entries(headers)) out[k.toLowerCase()] = v;
+  return out;
 }
 
 // src/payment/wwwauthenticate.ts
@@ -507,10 +517,7 @@ function respond402({
   body,
   x402
 }) {
-  const headers = {};
-  for (const [k, v] of Object.entries(mppxChallengeHeaders)) {
-    headers[k.toLowerCase()] = v;
-  }
+  const headers = normalizeHeadersToLowercase(mppxChallengeHeaders);
   headers["content-type"] = "application/json";
   if (x402) {
     headers["payment-required"] = paymentRequiredHeader(x402);