@agent-score/commerce 2.4.0 → 2.6.0

package/README.md

@@ -3,7 +3,7 @@
 [![npm version](https://img.shields.io/npm/v/@agent-score/commerce.svg)](https://www.npmjs.com/package/@agent-score/commerce)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-The full merchant-side SDK for [AgentScore](https://agentscore.sh): agent commerce in one install. Ships identity gating, payment rail helpers, 402 challenge builders, MPP discovery, and Stripe multichain support. Built and maintained by AgentScore; works with any 402/MPP merchant in the ecosystem, AgentScore-gated or not.
+The full merchant-side SDK for [AgentScore](https://www.agentscore.com): agent commerce in one install. Ships identity gating, payment rail helpers, 402 challenge builders, MPP discovery, and Stripe multichain support. Built and maintained by AgentScore; works with any 402/MPP merchant in the ecosystem, AgentScore-gated or not.
 
 ## Install
 
@@ -26,13 +26,13 @@ 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(...)`. The denial helpers (`denialReasonStatus`, `denialReasonToBody`, `buildSignerMismatchBody`, `buildContactSupportNextSteps`, `verificationAgentInstructions`, `isFixableDenial`, `FIXABLE_DENIAL_REASONS`) are exported from the top-level `@agent-score/commerce`, not the adapters. |
 | `/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`, `buildGateFromPolicy`, `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` (opt-in v1↔v2 amount-field shim: adds both `amount` and `maxAmountRequired` to an entry. The 402 builders do NOT apply it by default — strict x402 v2 settlement matches the agent's echoed requirement by exact comparison, so an extra field the server's rebuilt requirement lacks breaks settle; use only when you know a client is hardcoded to read `maxAmountRequired`), `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` (the solana rail's `ataCreationRequired` defaults to `true` so Solana settles work on `@solana/mpp >= 0.6.0` out of the box — opt out only if every recipient's ATA is guaranteed to pre-exist; see `SolanaMppRailSpec.ataCreationRequired` for economics), `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` (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), `createPayToAddressFromStripePI({request, amountCents, stripe, piCache, networks?, staticRecipients?, 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 OR a `staticRecipients` match — the static address is always-accepted because the merchant owns it); on the discovery leg, mints a fresh PI for the rails NOT covered by `staticRecipients`, caches the merged map, registers static addresses with `piCache.cacheAddress` so verify-leg lookups pass. `mintMultichainRecipients({...same opts})` — structured variant that returns `{ recipients: Record<string,string>, paymentIntentId?, reusedFromCredential }`; prefer this when your `mintRecipients` hook needs the full per-rail map (typical multi-rail merchant). Use `staticRecipients: { solana: '<wallet>' }` for low-margin endpoints where the per-call ATA rent on Solana (~$0.50 against MPP spec §13.6) would dominate revenue — the SDK skips Stripe minting for that network, the static recipient is reused forever, and a one-time pre-funding of its USDC ATA from any external wallet makes every settle pay only the ~$0.001 per-tx fee. `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`. |
+| `/payment` | `networks`, `USDC`, `rails` registries; `paymentDirective`, `buildPaymentDirective`, `wwwAuthenticateHeader`, `paymentRequiredHeader`, `aliasAmountFields` (opt-in v1↔v2 amount-field shim: adds both `amount` and `maxAmountRequired` to an entry. The 402 builders do NOT apply it by default, strict x402 v2 settlement matches the agent's echoed requirement by exact comparison, so an extra field the server's rebuilt requirement lacks breaks settle; use only when you know a client is hardcoded to read `maxAmountRequired`), `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` (the solana rail's `ataCreationRequired` defaults to `true` so Solana settles work on `@solana/mpp >= 0.6.0` out of the box, opt out only if every recipient's ATA is guaranteed to pre-exist; see `SolanaMppRailSpec.ataCreationRequired` for economics), `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` (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), `createPayToAddressFromStripePI({request, amountCents, stripe, piCache, networks?, staticRecipients?, 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 OR a `staticRecipients` match, the static address is always-accepted because the merchant owns it); on the discovery leg, mints a fresh PI for the rails NOT covered by `staticRecipients`, caches the merged map, registers static addresses with `piCache.cacheAddress` so verify-leg lookups pass. `mintMultichainRecipients({...same opts})`, structured variant that returns `{ recipients: Record<string,string>, paymentIntentId?, reusedFromCredential }`; prefer this when your `mintRecipients` hook needs the full per-rail map (typical multi-rail merchant). Use `staticRecipients: { solana: '<wallet>' }` for low-margin endpoints where the per-call ATA rent on Solana (~$0.50 against MPP spec §13.6) would dominate revenue, the SDK skips Stripe minting for that network, the static recipient is reused forever, and a one-time pre-funding of its USDC ATA from any external wallet makes every settle pay only the ~$0.001 per-tx fee. `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. |
-| `/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` (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). |
+| `/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` (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
 
@@ -96,7 +96,7 @@ app.post("/purchase", async (c) => {
 
 `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`.
+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";
@@ -144,7 +144,7 @@ const checkout = new Checkout({
 
 // Mount the signed UCP profile + JWKS + OPTIONS preflights in one call.
 // (For Express / Fastify use `mountUcpRoutesExpress` / `mountUcpRoutesFastify`.
-// Next.js / Web Fetch use file-based routing — call buildSignedUcpResponse
+// Next.js / Web Fetch use file-based routing, call buildSignedUcpResponse
 // directly inside the route handler.)
 checkout.mountUcpRoutesHono(app, {
   name: "Merchant",
@@ -156,7 +156,7 @@ checkout.mountUcpRoutesHono(app, {
 app.post("/purchase", (c) => checkout.handleHono(c));
 ```
 
-The 402 body Checkout emits auto-attaches `identity_mode` + `required_signer` + `signer_constraint` (and `linked_wallets` when the gate populated them) when an inbound `X-Wallet-Address` header is present — so agents self-correct at discovery instead of at the 403 retry.
+The 402 body Checkout emits auto-attaches `identity_mode` + `required_signer` + `signer_constraint` (and `linked_wallets` when the gate populated them) when an inbound `X-Wallet-Address` header is present, so agents self-correct at discovery instead of at the 403 retry.
 
 ### Payment helpers
 
@@ -245,7 +245,9 @@ 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. 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).
+Pass `x402: { accepts, version, resource, extensions }` to surface the x402 v2 fields on the body. `resource` is a `ResourceInfo` (`url` plus optional `serviceName` / `tags` / `description` / `mimeType` / `iconUrl`) so spec-compliant crawlers and discovery clients can read what the resource is; `extensions` carries declared x402 extensions (e.g. the Bazaar discovery schema from `createBazaarDiscovery`). `respond402` mirrors the same `resource` into the PAYMENT-REQUIRED header.
+
+`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
 
@@ -292,7 +294,7 @@ const card = buildA2AAgentCard({
 // Google Universal Commerce Protocol; publish at /.well-known/ucp
 // Output shape: { ucp: { version, services, capabilities, payment_handlers,
 // name?, supported_versions? }, signing_keys: [...], signature?: "..." }
-// — services / capabilities / payment_handlers are MAPS keyed by reverse-DNS
+//, services / capabilities / payment_handlers are MAPS keyed by reverse-DNS
 // service / capability / handler name (UCP spec §3 + §6).
 const profile = buildUCPProfile({
   name,
@@ -309,8 +311,8 @@ const profile = buildUCPProfile({
     ...stripeSptPaymentHandler({ spec: { profileId: 'profile_5xKvNqM9BaH' } }),
   },
   signing_keys,
-  // Optional: declare the merchant's gate policy as an `sh.agentscore.identity` capability
-  // binding inside the public profile. Static policy declaration only — no per-operator data.
+  // Optional: declare the merchant's gate policy as an `com.agentscore.identity` capability
+  // binding inside the public profile. Static policy declaration only, no per-operator data.
   // Per-operator identity attestation lives on the AP2 risk-signal endpoint, not here.
   agentscore_gate: { require_kyc: true, min_age: 21, allowed_jurisdictions: ['US'] },
 });
@@ -470,11 +472,11 @@ When `failOpen: true` AND the failure is infra-shape, the gate carries `degraded
 
 For regulated commerce (alcohol, age-gated, sanctioned-jurisdiction-relevant) keep the default `failOpen: false`: outage is the correct posture, and bypassing compliance on infra failure is a compliance gap. For low-stakes commerce or high-uptime SLAs, opt in and use the `degraded` flag as the audit trail.
 
-The `getGateDegradedState` helper is exported by the context-getter adapters (Hono, Express, Fastify). For the wrapper-pattern adapters (Next.js, Web Fetch via `withAgentScoreGate` / `createAgentScoreGate`), the `degraded` + `infraReason` fields land directly on the `gate` object passed to your handler — no separate getter.
+The `getGateDegradedState` helper is exported by the context-getter adapters (Hono, Express, Fastify). For the wrapper-pattern adapters (Next.js, Web Fetch via `withAgentScoreGate` / `createAgentScoreGate`), the `degraded` + `infraReason` fields land directly on the `gate` object passed to your handler, no separate getter.
 
 ## Examples
 
-The [examples/](./examples) directory has 8 runnable single-file Hono apps covering common merchant scenarios; copy-paste templates, not frameworks. See [examples/README.md](./examples/README.md) for the full table.
+The [examples/](./examples) directory has 9 runnable single-file Hono apps covering common merchant scenarios; copy-paste templates, not frameworks. See [examples/README.md](./examples/README.md) for the full table.
 
 ## Vendor profile examples
 
@@ -493,7 +495,7 @@ The full merchant SDK surface is stable. Helpers are protocol translations + con
 
 ## Documentation
 
-Full integration docs at [docs.agentscore.sh/integrations/node-commerce](https://docs.agentscore.sh/integrations/node-commerce).
+Full integration docs at [docs.agentscore.com/integrations/node-commerce](https://docs.agentscore.com/integrations/node-commerce).
 
 ## License
 

package/dist/challenge/index.d.mts

@@ -3,7 +3,8 @@ import { A as AgentInstructions, P as PricingBlock } from '../pricing-KHDqMLd7.m
 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-KHDqMLd7.mjs';
 import { AgentMemoryHint } from '../core.mjs';
 export { buildAgentMemoryHint } from '../core.mjs';
-import { p as paymentRequiredHeader } from '../wwwauthenticate-CVaGUMjU.mjs';
+import { p as paymentRequiredHeader } from '../wwwauthenticate-Dgm-_af9.mjs';
+import '@agent-score/sdk';
 import '../signer-3FAit11j.mjs';
 
 interface TempoMethodEntry {
@@ -118,10 +119,33 @@ declare function buildIdentityMetadata({ mode, wallet, signerMatchResult, linked
  * means `build402Body` cleanly skips the field instead of emitting `agent_memory: null`
  * (which would imply "I tried but failed" rather than "didn't apply").
  */
-declare function firstEncounterAgentMemory({ firstEncounter, }: {
+declare function firstEncounterAgentMemory({ firstEncounter, aipTrustedIssuers, }: {
     firstEncounter: boolean;
+    /** When the merchant accepts AIP, pass its trusted-issuer list (AgentScore's canonical issuer
+     *  plus any externals) so the hint advertises the `agent_identity` path. Omit for non-AIP
+     *  merchants. */
+    aipTrustedIssuers?: string[];
 }): AgentMemoryHint | undefined;
 
+/**
+ * x402 v2 `ResourceInfo`: resource metadata surfaced on the 402 body (and the
+ * PAYMENT-REQUIRED header) so spec-compliant crawlers and discovery clients can
+ * read what the paid resource is. Mirrors `@x402/core`'s `ResourceInfoSchema`.
+ */
+interface X402ResourceInfo {
+    /** Canonical URL of the paid resource. */
+    url: string;
+    /** Human-readable description of what the resource returns. */
+    description?: string;
+    /** MIME type of the response (e.g. 'application/json'). */
+    mimeType?: string;
+    /** Short service name (max 32 printable-ASCII chars). */
+    serviceName?: string;
+    /** Up to 5 capability tags (max 32 printable-ASCII chars each). */
+    tags?: string[];
+    /** Icon URL (max 2048 chars). */
+    iconUrl?: string;
+}
 /**
  * Assemble the full enriched 402 response body. Combines accepted_methods, agent_instructions,
  * identity metadata, pricing, x402 compliance fields, and any vendor-specific extras into a
@@ -163,6 +187,10 @@ declare function build402Body({ acceptedMethods, agentInstructions, identityMeta
     x402?: {
         accepts: unknown[];
         version?: 1 | 2;
+        /** x402 v2 `resource` field: resource metadata (url + serviceName / tags /
+         *  description / mimeType / iconUrl). Surfaces on the 402 body as `resource`
+         *  so spec-compliant crawlers and discovery clients can read what's sold. */
+        resource?: X402ResourceInfo;
         /** x402 spec `extensions` field. Per-endpoint declared extensions (e.g.
          *  `bazaar` discovery schema from `createBazaarDiscovery({...})`). Surfaces
          *  on the 402 body as `extensions` so spec-compliant crawlers can read it. */
@@ -331,4 +359,4 @@ declare function buildValidationError({ code, message, requiredFields, exampleBo
     extra?: Record<string, unknown>;
 }): ValidationErrorBody;
 
-export { type AcceptedMethodEntry, AgentInstructions, AgentMemoryHint, type IdentityMetadataBlock, type IdentityMode, PricingBlock, type Receipt, type Respond402Result, type SignerMatchResultLike, type SolanaMppMethodEntry, type StripeMethodEntry, type TempoMethodEntry, type ValidationErrorBody, type X402MethodEntry, build402Body, buildAcceptedMethods, buildIdentityMetadata, buildValidationError, firstEncounterAgentMemory, respond402 };
+export { type AcceptedMethodEntry, AgentInstructions, AgentMemoryHint, type IdentityMetadataBlock, type IdentityMode, PricingBlock, type Receipt, type Respond402Result, type SignerMatchResultLike, type SolanaMppMethodEntry, type StripeMethodEntry, type TempoMethodEntry, type ValidationErrorBody, type X402MethodEntry, type X402ResourceInfo, build402Body, buildAcceptedMethods, buildIdentityMetadata, buildValidationError, firstEncounterAgentMemory, respond402 };

package/dist/challenge/index.d.ts

@@ -3,7 +3,8 @@ import { A as AgentInstructions, P as PricingBlock } from '../pricing-CytRwhC2.j
 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-CytRwhC2.js';
 import { AgentMemoryHint } from '../core.js';
 export { buildAgentMemoryHint } from '../core.js';
-import { p as paymentRequiredHeader } from '../wwwauthenticate-CVaGUMjU.js';
+import { p as paymentRequiredHeader } from '../wwwauthenticate-Dgm-_af9.js';
+import '@agent-score/sdk';
 import '../signer-3FAit11j.js';
 
 interface TempoMethodEntry {
@@ -118,10 +119,33 @@ declare function buildIdentityMetadata({ mode, wallet, signerMatchResult, linked
  * means `build402Body` cleanly skips the field instead of emitting `agent_memory: null`
  * (which would imply "I tried but failed" rather than "didn't apply").
  */
-declare function firstEncounterAgentMemory({ firstEncounter, }: {
+declare function firstEncounterAgentMemory({ firstEncounter, aipTrustedIssuers, }: {
     firstEncounter: boolean;
+    /** When the merchant accepts AIP, pass its trusted-issuer list (AgentScore's canonical issuer
+     *  plus any externals) so the hint advertises the `agent_identity` path. Omit for non-AIP
+     *  merchants. */
+    aipTrustedIssuers?: string[];
 }): AgentMemoryHint | undefined;
 
+/**
+ * x402 v2 `ResourceInfo`: resource metadata surfaced on the 402 body (and the
+ * PAYMENT-REQUIRED header) so spec-compliant crawlers and discovery clients can
+ * read what the paid resource is. Mirrors `@x402/core`'s `ResourceInfoSchema`.
+ */
+interface X402ResourceInfo {
+    /** Canonical URL of the paid resource. */
+    url: string;
+    /** Human-readable description of what the resource returns. */
+    description?: string;
+    /** MIME type of the response (e.g. 'application/json'). */
+    mimeType?: string;
+    /** Short service name (max 32 printable-ASCII chars). */
+    serviceName?: string;
+    /** Up to 5 capability tags (max 32 printable-ASCII chars each). */
+    tags?: string[];
+    /** Icon URL (max 2048 chars). */
+    iconUrl?: string;
+}
 /**
  * Assemble the full enriched 402 response body. Combines accepted_methods, agent_instructions,
  * identity metadata, pricing, x402 compliance fields, and any vendor-specific extras into a
@@ -163,6 +187,10 @@ declare function build402Body({ acceptedMethods, agentInstructions, identityMeta
     x402?: {
         accepts: unknown[];
         version?: 1 | 2;
+        /** x402 v2 `resource` field: resource metadata (url + serviceName / tags /
+         *  description / mimeType / iconUrl). Surfaces on the 402 body as `resource`
+         *  so spec-compliant crawlers and discovery clients can read what's sold. */
+        resource?: X402ResourceInfo;
         /** x402 spec `extensions` field. Per-endpoint declared extensions (e.g.
          *  `bazaar` discovery schema from `createBazaarDiscovery({...})`). Surfaces
          *  on the 402 body as `extensions` so spec-compliant crawlers can read it. */
@@ -331,4 +359,4 @@ declare function buildValidationError({ code, message, requiredFields, exampleBo
     extra?: Record<string, unknown>;
 }): ValidationErrorBody;
 
-export { type AcceptedMethodEntry, AgentInstructions, AgentMemoryHint, type IdentityMetadataBlock, type IdentityMode, PricingBlock, type Receipt, type Respond402Result, type SignerMatchResultLike, type SolanaMppMethodEntry, type StripeMethodEntry, type TempoMethodEntry, type ValidationErrorBody, type X402MethodEntry, build402Body, buildAcceptedMethods, buildIdentityMetadata, buildValidationError, firstEncounterAgentMemory, respond402 };
+export { type AcceptedMethodEntry, AgentInstructions, AgentMemoryHint, type IdentityMetadataBlock, type IdentityMode, PricingBlock, type Receipt, type Respond402Result, type SignerMatchResultLike, type SolanaMppMethodEntry, type StripeMethodEntry, type TempoMethodEntry, type ValidationErrorBody, type X402MethodEntry, type X402ResourceInfo, build402Body, buildAcceptedMethods, buildIdentityMetadata, buildValidationError, firstEncounterAgentMemory, respond402 };

package/dist/challenge/index.js

@@ -315,6 +315,7 @@ function buildAgentInstructions({
 }
 
 // src/core.ts
+var import_node_crypto = require("crypto");
 var import_sdk = require("@agent-score/sdk");
 
 // src/_response.ts
@@ -347,7 +348,7 @@ var IDENTITY_VERIFICATION_REQUIRED_FALLBACK_INSTRUCTIONS = JSON.stringify({
 var API_ERROR_INSTRUCTIONS = JSON.stringify({
   action: "retry_with_backoff",
   steps: [
-    "Verification is temporarily unavailable. Retry the request after 5\u201330 seconds with exponential backoff.",
+    "Verification is temporarily unavailable. Retry the request after 5-30 seconds with exponential backoff.",
     "This is NOT a compliance denial \u2014 the user does not need to re-verify their identity. Send the same identity headers (X-Wallet-Address or X-Operator-Token) on retry.",
     "If the request continues to fail after 3+ retries (~60 seconds total), surface the error to the user with the merchant's support contact."
   ],
@@ -373,7 +374,7 @@ var TOKEN_EXPIRED_FALLBACK_INSTRUCTIONS = JSON.stringify({
 });
 
 // src/core.ts
-var CANONICAL_AGENTSCORE_API = "https://api.agentscore.sh";
+var CANONICAL_AGENTSCORE_API = "https://api.agentscore.com";
 var WALLET_SIGNER_MISMATCH_INSTRUCTIONS = JSON.stringify({
   action: "resign_or_switch_to_operator_token",
   steps: [
@@ -399,17 +400,22 @@ var INVALID_CREDENTIAL_INSTRUCTIONS = JSON.stringify({
   ],
   user_message: "The operator_token is not recognized. Use a different stored token, or restart the verification session flow to mint a new one."
 });
-function buildAgentMemoryHint() {
+function buildAgentMemoryHint(aipTrustedIssuers) {
   const api = CANONICAL_AGENTSCORE_API;
+  const acceptsAip = aipTrustedIssuers !== void 0 && aipTrustedIssuers.length > 0;
   return {
     save_for_future_agentscore_gates: true,
     pattern_summary: "AgentScore is a cross-merchant identity substrate for agent commerce. Any endpoint that returns 403 missing_identity / identity_verification_required or 402 challenges referencing AgentScore uses the same identity system. One KYC works across all AgentScore merchants \u2014 no re-verification per site. Save this pattern (and the endpoints below) to persistent memory so future AgentScore encounters skip the cold-start session flow.",
-    quickstart: "https://docs.agentscore.sh/guides/agent-identity",
+    quickstart: "https://docs.agentscore.com/guides/agent-identity",
     identity_check_endpoint: `${api}/v1/credentials`,
     identity_paths: {
       wallet: "If paying from a crypto wallet you have used before on any AgentScore merchant, send `X-Wallet-Address: 0x...`. Shortest path; no token lifecycle to manage.",
-      operator_token: "For any rail (Stripe SPT, card, or a wallet you have not linked yet), send `X-Operator-Token: opc_...`. Reusable across merchants until the token expires."
+      operator_token: "For any rail (Stripe SPT, card, or a wallet you have not linked yet), send `X-Operator-Token: opc_...`. Reusable across merchants until the token expires.",
+      ...acceptsAip && {
+        agent_identity: 'If you hold an AIP Agent Identity Token from a trusted issuer (see aip_trusted_issuers), present it: send the JWT in an `Agent-Identity` header plus an RFC 9421 HTTP Message Signature (Signature-Input + Signature over @method @authority @path agent-identity, tag="agent-identity") signed with the token-bound cnf key. The merchant verifies it and applies its policy \u2014 no separate AgentScore credential needed.'
+      }
     },
+    ...acceptsAip && { aip_trusted_issuers: aipTrustedIssuers },
     bootstrap: "If you have neither a linked wallet nor a valid operator_token, follow the session/verify flow in the per-request `agent_instructions` block. This happens at most once per agent identity \u2014 after first verification, the operator_token and any subsequently used wallet are reusable everywhere.",
     do_not_persist_in_memory: ["operator_token", "poll_secret"],
     persist_in_credential_store: ["operator_token"]
@@ -418,10 +424,11 @@ function buildAgentMemoryHint() {
 
 // src/challenge/agent_memory.ts
 function firstEncounterAgentMemory({
-  firstEncounter
+  firstEncounter,
+  aipTrustedIssuers
 }) {
   if (!firstEncounter) return void 0;
-  return buildAgentMemoryHint();
+  return buildAgentMemoryHint(aipTrustedIssuers);
 }
 
 // src/challenge/body.ts
@@ -447,6 +454,7 @@ function build402Body({
   if (x402) {
     body.x402Version = x402.version ?? 2;
     body.accepts = x402.accepts;
+    if (x402.resource !== void 0) body.resource = x402.resource;
     if (x402.extensions !== void 0 && Object.keys(x402.extensions).length > 0) {
       body.extensions = x402.extensions;
     }
@@ -508,9 +516,17 @@ function normalizeHeadersToLowercase(headers) {
 function paymentRequiredHeader({
   x402Version,
   accepts,
-  resource
+  resource,
+  extensions
 }) {
-  return Buffer.from(JSON.stringify({ x402Version, accepts, ...resource ? { resource } : {} })).toString("base64");
+  return Buffer.from(
+    JSON.stringify({
+      x402Version,
+      accepts,
+      ...resource ? { resource } : {},
+      ...extensions && Object.keys(extensions).length > 0 ? { extensions } : {}
+    })
+  ).toString("base64");
 }
 
 // src/challenge/respond_402.ts