@agent-score/commerce 1.2.0 → 1.3.0

package/README.md

@@ -16,7 +16,7 @@ bun add @agent-score/commerce
 Framework + protocol packages are optional peer deps — install only what you use:
 
 ```bash
-npm install hono mppx @x402/core @x402/evm @x402/svm stripe   # whatever your stack needs
+npm install hono mppx @x402/core @x402/evm @solana/mpp @solana/kit stripe   # whatever your stack needs
 ```
 
 ## What's in the package
@@ -24,7 +24,7 @@ npm install hono mppx @x402/core @x402/evm @x402/svm stripe   # whatever your st
 | Subpath | What it provides |
 |---|---|
 | `/identity/{hono,express,fastify,nextjs,web}` | Trust gate middleware: KYC, sanctions, age, jurisdiction. `agentscoreGate(...)`, `getAgentScoreData(c)`, `captureWallet(...)`, `verifyWalletSignerMatch(...)`. Plus shared denial helpers: `denialReasonStatus`, `denialReasonToBody`, `buildSignerMismatchBody`, `buildContactSupportNextSteps`, `verificationAgentInstructions`, `isFixableDenial`, `FIXABLE_DENIAL_REASONS`. |
-| `/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` (returns `{address, network}`); `createX402Server`, `createMppxServer`; drop-in x402 helpers: `validateX402NetworkConfig` (boot-time guard), `verifyX402Request` (parse + validate inbound X-Payment), `processX402Settle` (verify-then-settle with one call). |
+| `/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` (returns `{address, network}`); `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). |
 | `/discovery` | `isDiscoveryProbeRequest`, `buildDiscoveryProbeResponse` (with optional `x402Sample` for x402-aware crawlers — `awal x402 details` etc.), `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), `agentscoreOpenApiSnippets`, `createBazaarDiscovery`, `noindexNonDiscoveryPaths` (Hono middleware that emits `X-Robots-Tag: noindex` on every path except the agent-discovery surfaces — defaults cover `/openapi.json`, `/llms.txt`, `/skill.md`, `/.well-known/{mpp.json,agent-card.json,ucp}`, `/favicon.{png,ico}`; pure helpers `isDiscoveryPath` + `defaultDiscoveryPaths` for non-Hono frameworks). |
 | `/challenge` | `build402Body`, `buildAcceptedMethods`, `buildIdentityMetadata`, `buildHowToPay`, `buildAgentInstructions` (auto-emits per-rail `compatible_clients` — smoke-verified CLIs the agent should use; vendor override supported), `buildPricingBlock`, `firstEncounterAgentMemory`, `OrderReceipt`; `respond402` — 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`, `getDepositAddress`, `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`. |
@@ -89,13 +89,16 @@ import {
 
 // Build paymentauth.org directives by symbolic rail name (decimals + currency from registry)
 const directives = [
-  buildPaymentDirective({ rail: "tempo-mainnet",       id: "chg_t", realm: "ex.com", recipient: TEMPO_ADDR, amountUsd: 0.01 }),
-  buildPaymentDirective({ rail: "x402-base-mainnet",   id: "chg_b", realm: "ex.com", recipient: BASE_ADDR,  amountUsd: 0.01 }),
-  buildPaymentDirective({ rail: "x402-solana-mainnet", id: "chg_s", realm: "ex.com", recipient: SOL_ADDR,   amountUsd: 0.01 }),
+  buildPaymentDirective({ rail: "tempo-mainnet",     id: "chg_t", realm: "ex.com", recipient: TEMPO_ADDR, amountUsd: 0.01 }),
+  buildPaymentDirective({ rail: "x402-base-mainnet", id: "chg_b", realm: "ex.com", recipient: BASE_ADDR,  amountUsd: 0.01 }),
+  buildPaymentDirective({ rail: "mpp-solana-mainnet", id: "chg_s", realm: "ex.com", recipient: SOL_ADDR,  amountUsd: 0.01 }),
 ];
 const wwwAuth = wwwAuthenticateHeader(directives);
 
-// Recover the on-chain signer from the inbound credential — returns {address, network}
+// Recover the on-chain signer from the inbound credential — returns {address, network}.
+// Covers x402 EIP-3009 (EVM `from` address), Tempo MPP (`did:pkh:eip155` source),
+// and Solana MPP `solana/charge` (via `did:pkh:solana` source when set, else by
+// decoding the credential's signed-tx payload — `@solana/kit` optional peer).
 const signer = await extractPaymentSigner(req, req.headers.get("x-payment") ?? undefined);
 ```
 
@@ -106,12 +109,17 @@ import { createX402Server, createMppxServer } from "@agent-score/commerce/paymen
 
 const x402 = await createX402Server({
   facilitator: "coinbase",  // or "http", or pass a custom facilitator instance
-  rails: ["x402-base-mainnet", "x402-solana-mainnet", "x402-base-mainnet-upto"],
+  rails: ["x402-base-mainnet", "x402-base-mainnet-upto"],
 });
 
 const mppx = await createMppxServer({
   rails: {
     tempo: { recipient: process.env.TEMPO_RECIPIENT! },
+    solana: {
+      recipient: process.env.SOLANA_RECIPIENT!,
+      // Optional fee sponsor — pass any `TransactionPartialSigner` from `@solana/kit`.
+      // signer: solanaFeePayerSigner,
+    },
     stripe: { profileId: process.env.STRIPE_PROFILE_ID!, secretKey: process.env.STRIPE_SECRET_KEY! },
   },
   secretKey: process.env.MPP_SECRET_KEY!,
@@ -132,7 +140,7 @@ import {
 const acceptedMethods = buildAcceptedMethods({
   tempo: { recipient: TEMPO_ADDR },
   x402_base: { recipient: BASE_ADDR },
-  x402_solana: { recipient: SOL_ADDR },
+  solana_mpp: { recipient: SOL_ADDR, feePayerKey: SOLANA_FEE_PAYER },
   stripe: { profileId: STRIPE_PROFILE_ID },
 });
 
@@ -236,6 +244,7 @@ await simulateDepositIfTestMode({
 
 ```typescript
 import {
+  classifyX402SettleResult,
   processX402Settle,
   validateX402NetworkConfig,
   verifyX402Request,
@@ -243,7 +252,7 @@ import {
 import { respond402 } from "@agent-score/commerce/challenge";
 
 // Boot-time guard — raises if a configured network isn't supported.
-validateX402NetworkConfig({ baseNetwork: X402_BASE, svmNetwork: X402_SVM });
+validateX402NetworkConfig({ baseNetwork: X402_BASE });
 
 app.post("/purchase", async (c) => {
   // Path A — agent presented an x402 X-Payment header
@@ -251,7 +260,7 @@ app.post("/purchase", async (c) => {
     const verified = await verifyX402Request({
       request: c.req.raw,
       isCachedAddress: piCache.hasAddress,
-      acceptedNetworks: { base: X402_BASE, svm: X402_SVM },
+      acceptedNetwork: X402_BASE,
     });
     if (!verified.ok) return c.json(verified.body, verified.status);
 
@@ -261,7 +270,13 @@ app.post("/purchase", async (c) => {
       resourceConfig: { scheme: "exact", network: verified.signedNetwork, price: `$${total}`, payTo: verified.signedPayTo, maxTimeoutSeconds: 300 },
       resourceMeta: { url: c.req.url, mimeType: "application/json" },
     });
-    if (!settle.success) return c.json({ error: { code: "payment_proof_invalid", phase: settle.phase } }, 400);
+    const classified = classifyX402SettleResult(settle);
+    if (classified) {
+      // Log raw `settle` server-side; return controlled phase-based response to the agent.
+      console.error("[x402-settle]", { phase: settle.success ? null : settle.phase, raw: settle });
+      return c.json({ error: { code: classified.code, message: classified.message }, next_steps: classified.nextSteps }, classified.status);
+    }
+    if (!settle.success) throw new Error("unreachable: classified covers every non-success phase");
 
     const headers: Record<string, string> = {};
     if (settle.paymentResponseHeader) headers["payment-response"] = settle.paymentResponseHeader;

package/dist/{_response-RpEB7-vl.d.ts → _response-C2yFQoIA.d.ts}

@@ -77,7 +77,7 @@ declare function buildSignerMismatchBody(input: SignerMismatchBodyInput): Record
  *   return c.json({
  *     error: { code: 'compliance_denied', message: '...' },
  *     reasons,
- *     next_steps: buildContactSupportNextSteps('support@martinestate.com'),
+ *     next_steps: buildContactSupportNextSteps('support@example.com'),
  *   }, 403);
  */
 declare function buildContactSupportNextSteps(supportEmail: string, message?: string): {

package/dist/{_response-DS-LR590.d.mts → _response-DpB-cm2c.d.mts}

@@ -77,7 +77,7 @@ declare function buildSignerMismatchBody(input: SignerMismatchBodyInput): Record
  *   return c.json({
  *     error: { code: 'compliance_denied', message: '...' },
  *     reasons,
- *     next_steps: buildContactSupportNextSteps('support@martinestate.com'),
+ *     next_steps: buildContactSupportNextSteps('support@example.com'),
  *   }, 403);
  */
 declare function buildContactSupportNextSteps(supportEmail: string, message?: string): {

package/dist/{agent_instructions-d3UWTdam.d.mts → agent_instructions-DiMSGkdm.d.mts}

@@ -16,7 +16,7 @@ interface HowToPayStripeEntry {
 interface HowToPayBlock {
     tempo?: HowToPayRailEntry;
     x402_base?: HowToPayRailEntry;
-    x402_solana?: HowToPayRailEntry;
+    solana_mpp?: HowToPayRailEntry;
     stripe?: HowToPayStripeEntry;
 }
 interface BuildHowToPayInput {
@@ -38,7 +38,7 @@ interface BuildHowToPayInput {
             recipient: string;
             network?: string;
         };
-        x402_solana?: {
+        solana_mpp?: {
             recipient: string;
             network?: string;
         };
@@ -77,6 +77,10 @@ interface BuildAgentInstructionsInput {
     timeoutSeconds?: number;
     /** Warnings about common footguns. Defaults include tempo wallet transfer + raw on-chain x402 deposits. */
     warnings?: string[];
+    /** Additional warnings appended to the default protocol-footgun set. Use this when you want
+     *  to keep the SDK's protocol warnings AND add merchant-specific notes (e.g., a per-order
+     *  rail-availability message). Ignored when `warnings` is set explicitly. */
+    extraWarnings?: string[];
     /** Recommended rail (e.g., 'tempo', 'x402_base'). Surfaced for agents to default to. */
     recommended?: string;
     /** Per-rail list of client names the merchant has verified work end-to-end. Vendors set
@@ -109,7 +113,7 @@ interface AgentInstructions {
  */
 /** Symbolic rail keys agent-facing surfaces use to talk about a rail without spelling out
  *  network/scheme details. Same keys as `CompatibleClients` map keys. */
-type RailKey = 'tempo_mpp' | 'x402_base' | 'x402_solana' | 'stripe';
+type RailKey = 'tempo_mpp' | 'x402_base' | 'solana_mpp' | 'stripe';
 /** Returns the smoke-verified client list for a set of rail keys. The single source of
  *  truth for "which CLIs we've verified end-to-end on each rail" — consumed both by the
  *  402-body builder (`defaultCompatibleClients`) and by discovery surfaces (skill.md,
@@ -120,10 +124,10 @@ declare function compatibleClientsByRails(rails: readonly RailKey[]): Compatible
  * recommended tools, warnings, wallet-compatibility note, and timeout.
  *
  * Defaults adapt to the rails declared in `howToPay`: only tempo-relevant warnings/tools
- * appear if `howToPay.tempo` is set, only x402-relevant ones if `x402_base`/`x402_solana`
- * are set. Stripe-only merchants get neither rail-specific warning. Vendors override
+ * appear if `howToPay.tempo` is set, only x402-relevant ones if `x402_base` is set.
+ * Stripe-only merchants get neither rail-specific warning. Vendors override
  * `warnings`/`recommendedTools` for full control.
  */
 declare function buildAgentInstructions(input: BuildAgentInstructionsInput): AgentInstructions;
 
-export { type AgentInstructions as A, type BuildAgentInstructionsInput as B, type CompatibleClients as C, type HowToPayBlock as H, type RailKey as R, type BuildHowToPayInput as a, type HowToPayRailEntry as b, compatibleClientsByRails as c, type HowToPayStripeEntry as d, buildAgentInstructions as e, buildHowToPay as f };
+export { type AgentInstructions as A, type BuildAgentInstructionsInput as B, type CompatibleClients as C, type HowToPayBlock as H, type RailKey as R, type BuildHowToPayInput as a, type HowToPayRailEntry as b, type HowToPayStripeEntry as c, buildAgentInstructions as d, buildHowToPay as e, compatibleClientsByRails as f };

package/dist/{agent_instructions-d3UWTdam.d.ts → agent_instructions-DiMSGkdm.d.ts}

@@ -16,7 +16,7 @@ interface HowToPayStripeEntry {
 interface HowToPayBlock {
     tempo?: HowToPayRailEntry;
     x402_base?: HowToPayRailEntry;
-    x402_solana?: HowToPayRailEntry;
+    solana_mpp?: HowToPayRailEntry;
     stripe?: HowToPayStripeEntry;
 }
 interface BuildHowToPayInput {
@@ -38,7 +38,7 @@ interface BuildHowToPayInput {
             recipient: string;
             network?: string;
         };
-        x402_solana?: {
+        solana_mpp?: {
             recipient: string;
             network?: string;
         };
@@ -77,6 +77,10 @@ interface BuildAgentInstructionsInput {
     timeoutSeconds?: number;
     /** Warnings about common footguns. Defaults include tempo wallet transfer + raw on-chain x402 deposits. */
     warnings?: string[];
+    /** Additional warnings appended to the default protocol-footgun set. Use this when you want
+     *  to keep the SDK's protocol warnings AND add merchant-specific notes (e.g., a per-order
+     *  rail-availability message). Ignored when `warnings` is set explicitly. */
+    extraWarnings?: string[];
     /** Recommended rail (e.g., 'tempo', 'x402_base'). Surfaced for agents to default to. */
     recommended?: string;
     /** Per-rail list of client names the merchant has verified work end-to-end. Vendors set
@@ -109,7 +113,7 @@ interface AgentInstructions {
  */
 /** Symbolic rail keys agent-facing surfaces use to talk about a rail without spelling out
  *  network/scheme details. Same keys as `CompatibleClients` map keys. */
-type RailKey = 'tempo_mpp' | 'x402_base' | 'x402_solana' | 'stripe';
+type RailKey = 'tempo_mpp' | 'x402_base' | 'solana_mpp' | 'stripe';
 /** Returns the smoke-verified client list for a set of rail keys. The single source of
  *  truth for "which CLIs we've verified end-to-end on each rail" — consumed both by the
  *  402-body builder (`defaultCompatibleClients`) and by discovery surfaces (skill.md,
@@ -120,10 +124,10 @@ declare function compatibleClientsByRails(rails: readonly RailKey[]): Compatible
  * recommended tools, warnings, wallet-compatibility note, and timeout.
  *
  * Defaults adapt to the rails declared in `howToPay`: only tempo-relevant warnings/tools
- * appear if `howToPay.tempo` is set, only x402-relevant ones if `x402_base`/`x402_solana`
- * are set. Stripe-only merchants get neither rail-specific warning. Vendors override
+ * appear if `howToPay.tempo` is set, only x402-relevant ones if `x402_base` is set.
+ * Stripe-only merchants get neither rail-specific warning. Vendors override
  * `warnings`/`recommendedTools` for full control.
  */
 declare function buildAgentInstructions(input: BuildAgentInstructionsInput): AgentInstructions;
 
-export { type AgentInstructions as A, type BuildAgentInstructionsInput as B, type CompatibleClients as C, type HowToPayBlock as H, type RailKey as R, type BuildHowToPayInput as a, type HowToPayRailEntry as b, compatibleClientsByRails as c, type HowToPayStripeEntry as d, buildAgentInstructions as e, buildHowToPay as f };
+export { type AgentInstructions as A, type BuildAgentInstructionsInput as B, type CompatibleClients as C, type HowToPayBlock as H, type RailKey as R, type BuildHowToPayInput as a, type HowToPayRailEntry as b, type HowToPayStripeEntry as c, buildAgentInstructions as d, buildHowToPay as e, compatibleClientsByRails as f };

package/dist/challenge/index.d.mts

@@ -1,5 +1,5 @@
-import { A as AgentInstructions } from '../agent_instructions-d3UWTdam.mjs';
-export { B as BuildAgentInstructionsInput, a as BuildHowToPayInput, C as CompatibleClients, H as HowToPayBlock, b as HowToPayRailEntry, d as HowToPayStripeEntry, R as RailKey, e as buildAgentInstructions, f as buildHowToPay, c as compatibleClientsByRails } from '../agent_instructions-d3UWTdam.mjs';
+import { A as AgentInstructions } from '../agent_instructions-DiMSGkdm.mjs';
+export { B as BuildAgentInstructionsInput, a as BuildHowToPayInput, C as CompatibleClients, H as HowToPayBlock, b as HowToPayRailEntry, c as HowToPayStripeEntry, R as RailKey, d as buildAgentInstructions, e as buildHowToPay, f as compatibleClientsByRails } from '../agent_instructions-DiMSGkdm.mjs';
 import { AgentMemoryHint } from '../core.mjs';
 export { buildAgentMemoryHint } from '../core.mjs';
 import { P as PaymentRequiredHeaderInput } from '../wwwauthenticate-CU1eNvMQ.mjs';
@@ -22,12 +22,21 @@ interface X402MethodEntry {
     decimals: number;
     pay_to: string;
 }
+interface SolanaMppMethodEntry {
+    method: 'solana/charge';
+    network: string;
+    token: string;
+    symbol: string;
+    decimals: number;
+    pay_to: string;
+    fee_payer_key?: string;
+}
 interface StripeMethodEntry {
     method: 'stripe/charge';
     rails: ('card' | 'link' | 'shared_payment_token')[];
     profile_id: string | null;
 }
-type AcceptedMethodEntry = TempoMethodEntry | X402MethodEntry | StripeMethodEntry;
+type AcceptedMethodEntry = TempoMethodEntry | X402MethodEntry | SolanaMppMethodEntry | StripeMethodEntry;
 interface BuildAcceptedMethodsInput {
     tempo?: {
         recipient: string;
@@ -45,12 +54,13 @@ interface BuildAcceptedMethodsInput {
         symbol?: string;
         decimals?: number;
     };
-    x402_solana?: {
+    solana_mpp?: {
         recipient: string;
         network?: string;
         token?: string;
         symbol?: string;
         decimals?: number;
+        feePayerKey?: string;
     };
     stripe?: {
         profileId?: string | null;
@@ -259,10 +269,9 @@ declare function build402Body(input: Build402BodyInput): Record<string, unknown>
 /**
  * Canonical order-receipt shape returned to agents on the 200 after a successful settlement.
  *
- * Merchants own their order schema, but converging on this shape across every AgentScore-gated
- * merchant (Martin Estate today; Commerce7 / WooCommerce / Shopify plugins tomorrow) means
- * agents can render and post-process orders consistently. Lift this type, fill the fields you
- * care about, and ignore (or extend via `extras`) what you don't.
+ * Merchants own their order schema, but converging on this shape across AgentScore-gated
+ * merchants means agents can render and post-process orders consistently. Lift this type,
+ * fill the fields you care about, and ignore (or extend via `extras`) what you don't.
  *
  * All money fields are dollar-strings (e.g. `"250.00"`). Use `buildPricingBlock` from
  * `@agent-score/commerce/challenge` to compose the pricing fields from cents.
@@ -413,4 +422,4 @@ interface ValidationErrorBody {
  */
 declare function buildValidationError(input: BuildValidationErrorInput): ValidationErrorBody;
 
-export { type AcceptedMethodEntry, AgentInstructions, AgentMemoryHint, type Build402BodyInput, type BuildAcceptedMethodsInput, type BuildPricingBlockInput, type BuildValidationErrorInput, type FirstEncounterAgentMemoryInput, type IdentityMetadataBlock, type IdentityMetadataInput, type IdentityMode, type OrderReceipt, type PricingBlock, type Respond402Input, type SignerMatchResultLike, type StripeMethodEntry, type TempoMethodEntry, type ValidationErrorBody, type X402MethodEntry, build402Body, buildAcceptedMethods, buildIdentityMetadata, buildPricingBlock, buildValidationError, firstEncounterAgentMemory, respond402 };
+export { type AcceptedMethodEntry, AgentInstructions, AgentMemoryHint, type Build402BodyInput, type BuildAcceptedMethodsInput, type BuildPricingBlockInput, type BuildValidationErrorInput, type FirstEncounterAgentMemoryInput, type IdentityMetadataBlock, type IdentityMetadataInput, type IdentityMode, type OrderReceipt, type PricingBlock, type Respond402Input, type SignerMatchResultLike, type SolanaMppMethodEntry, type StripeMethodEntry, type TempoMethodEntry, type ValidationErrorBody, type X402MethodEntry, build402Body, buildAcceptedMethods, buildIdentityMetadata, buildPricingBlock, buildValidationError, firstEncounterAgentMemory, respond402 };

package/dist/challenge/index.d.ts

@@ -1,5 +1,5 @@
-import { A as AgentInstructions } from '../agent_instructions-d3UWTdam.js';
-export { B as BuildAgentInstructionsInput, a as BuildHowToPayInput, C as CompatibleClients, H as HowToPayBlock, b as HowToPayRailEntry, d as HowToPayStripeEntry, R as RailKey, e as buildAgentInstructions, f as buildHowToPay, c as compatibleClientsByRails } from '../agent_instructions-d3UWTdam.js';
+import { A as AgentInstructions } from '../agent_instructions-DiMSGkdm.js';
+export { B as BuildAgentInstructionsInput, a as BuildHowToPayInput, C as CompatibleClients, H as HowToPayBlock, b as HowToPayRailEntry, c as HowToPayStripeEntry, R as RailKey, d as buildAgentInstructions, e as buildHowToPay, f as compatibleClientsByRails } from '../agent_instructions-DiMSGkdm.js';
 import { AgentMemoryHint } from '../core.js';
 export { buildAgentMemoryHint } from '../core.js';
 import { P as PaymentRequiredHeaderInput } from '../wwwauthenticate-CU1eNvMQ.js';
@@ -22,12 +22,21 @@ interface X402MethodEntry {
     decimals: number;
     pay_to: string;
 }
+interface SolanaMppMethodEntry {
+    method: 'solana/charge';
+    network: string;
+    token: string;
+    symbol: string;
+    decimals: number;
+    pay_to: string;
+    fee_payer_key?: string;
+}
 interface StripeMethodEntry {
     method: 'stripe/charge';
     rails: ('card' | 'link' | 'shared_payment_token')[];
     profile_id: string | null;
 }
-type AcceptedMethodEntry = TempoMethodEntry | X402MethodEntry | StripeMethodEntry;
+type AcceptedMethodEntry = TempoMethodEntry | X402MethodEntry | SolanaMppMethodEntry | StripeMethodEntry;
 interface BuildAcceptedMethodsInput {
     tempo?: {
         recipient: string;
@@ -45,12 +54,13 @@ interface BuildAcceptedMethodsInput {
         symbol?: string;
         decimals?: number;
     };
-    x402_solana?: {
+    solana_mpp?: {
         recipient: string;
         network?: string;
         token?: string;
         symbol?: string;
         decimals?: number;
+        feePayerKey?: string;
     };
     stripe?: {
         profileId?: string | null;
@@ -259,10 +269,9 @@ declare function build402Body(input: Build402BodyInput): Record<string, unknown>
 /**
  * Canonical order-receipt shape returned to agents on the 200 after a successful settlement.
  *
- * Merchants own their order schema, but converging on this shape across every AgentScore-gated
- * merchant (Martin Estate today; Commerce7 / WooCommerce / Shopify plugins tomorrow) means
- * agents can render and post-process orders consistently. Lift this type, fill the fields you
- * care about, and ignore (or extend via `extras`) what you don't.
+ * Merchants own their order schema, but converging on this shape across AgentScore-gated
+ * merchants means agents can render and post-process orders consistently. Lift this type,
+ * fill the fields you care about, and ignore (or extend via `extras`) what you don't.
  *
  * All money fields are dollar-strings (e.g. `"250.00"`). Use `buildPricingBlock` from
  * `@agent-score/commerce/challenge` to compose the pricing fields from cents.
@@ -413,4 +422,4 @@ interface ValidationErrorBody {
  */
 declare function buildValidationError(input: BuildValidationErrorInput): ValidationErrorBody;
 
-export { type AcceptedMethodEntry, AgentInstructions, AgentMemoryHint, type Build402BodyInput, type BuildAcceptedMethodsInput, type BuildPricingBlockInput, type BuildValidationErrorInput, type FirstEncounterAgentMemoryInput, type IdentityMetadataBlock, type IdentityMetadataInput, type IdentityMode, type OrderReceipt, type PricingBlock, type Respond402Input, type SignerMatchResultLike, type StripeMethodEntry, type TempoMethodEntry, type ValidationErrorBody, type X402MethodEntry, build402Body, buildAcceptedMethods, buildIdentityMetadata, buildPricingBlock, buildValidationError, firstEncounterAgentMemory, respond402 };
+export { type AcceptedMethodEntry, AgentInstructions, AgentMemoryHint, type Build402BodyInput, type BuildAcceptedMethodsInput, type BuildPricingBlockInput, type BuildValidationErrorInput, type FirstEncounterAgentMemoryInput, type IdentityMetadataBlock, type IdentityMetadataInput, type IdentityMode, type OrderReceipt, type PricingBlock, type Respond402Input, type SignerMatchResultLike, type SolanaMppMethodEntry, type StripeMethodEntry, type TempoMethodEntry, type ValidationErrorBody, type X402MethodEntry, build402Body, buildAcceptedMethods, buildIdentityMetadata, buildPricingBlock, buildValidationError, firstEncounterAgentMemory, respond402 };

package/dist/challenge/index.js

@@ -59,14 +59,15 @@ function buildAcceptedMethods(input) {
       pay_to: input.x402_base.recipient
     });
   }
-  if (input.x402_solana) {
+  if (input.solana_mpp) {
     out.push({
-      method: "x402/exact",
-      network: input.x402_solana.network ?? "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
-      token: input.x402_solana.token ?? "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
-      symbol: input.x402_solana.symbol ?? "USDC",
-      decimals: input.x402_solana.decimals ?? 6,
-      pay_to: input.x402_solana.recipient
+      method: "solana/charge",
+      network: input.solana_mpp.network ?? "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
+      token: input.solana_mpp.token ?? "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
+      symbol: input.solana_mpp.symbol ?? "USDC",
+      decimals: input.solana_mpp.decimals ?? 6,
+      pay_to: input.solana_mpp.recipient,
+      ...input.solana_mpp.feePayerKey ? { fee_payer_key: input.solana_mpp.feePayerKey } : {}
     });
   }
   if (input.stripe) {
@@ -126,7 +127,7 @@ function buildHowToPay(input) {
       prerequisite: `Run \`tempo wallet whoami\` and confirm USDC.e balance on ${networkName} (chain ${chainId}) is at least $${maxSpend}. If the tempo CLI is not installed, run the setup commands above first.`,
       command: recommend === "agentscore-pay" ? payCommand : tempoCommand,
       ...recommend === "both" ? { alternative_command: payCommand } : recommend === "agentscore-pay" ? { alternative_command: tempoCommand } : {},
-      what_it_does: `Hits this endpoint, receives this same 402, signs the MPP challenge on ${networkName}, and submits the credential back via Authorization: Payment. Either client (tempo request or agentscore-pay pay --chain tempo) works \u2014 both run the full MPP handshake.`
+      what_it_does: `Pays via Tempo USDC on ${networkName}.`
     };
   }
   if (input.rails.x402_base) {
@@ -135,16 +136,16 @@ function buildHowToPay(input) {
       setup: PAY_SETUP_BASE,
       prerequisite: `Run \`agentscore-pay balance --chain base\` and confirm USDC balance on Base (${network}) is at least $${maxSpend}. If the CLI is not installed, run the setup commands above first.`,
       command: `agentscore-pay pay POST ${input.url} --chain base -H 'X-Operator-Token: ${opToken}' -H 'Content-Type: application/json' -d '${input.retryBodyJson}' --max-spend ${maxSpend}`,
-      what_it_does: "Hits this endpoint, receives this same 402, signs an EIP-3009 USDC TransferWithAuthorization on Base, submits via X-Payment header. Server verifies + settles via the Coinbase facilitator + returns 200 with the completed order."
+      what_it_does: "Pays via USDC on Base."
     };
   }
-  if (input.rails.x402_solana) {
-    const network = input.rails.x402_solana.network ?? "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
-    block.x402_solana = {
+  if (input.rails.solana_mpp) {
+    const network = input.rails.solana_mpp.network ?? "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
+    block.solana_mpp = {
       setup: PAY_SETUP_SOLANA,
       prerequisite: `Run \`agentscore-pay balance --chain solana\` and confirm USDC balance on Solana (${network}) is at least $${maxSpend}. If the CLI is not installed, run the setup commands above first.`,
       command: `agentscore-pay pay POST ${input.url} --chain solana -H 'X-Operator-Token: ${opToken}' -H 'Content-Type: application/json' -d '${input.retryBodyJson}' --max-spend ${maxSpend}`,
-      what_it_does: "Hits this endpoint, receives this same 402, signs an SPL Token TransferChecked transaction on Solana, submits via X-Payment header. Server verifies + settles via the Coinbase facilitator + returns 200 with the completed order."
+      what_it_does: "Pays via USDC on Solana."
     };
   }
   if (input.rails.stripe) {
@@ -167,7 +168,7 @@ function buildHowToPay(input) {
         `SPEND_ID=$(link-cli spend-request create --payment-method-id <csmrpd_id_from_payment_methods_list> --credential-type shared_payment_token --network-id ${stripeCfg.profileId} --amount ${amountCents} --context "${sptContext}" --request-approval --output-json | jq -r .id)`,
         `link-cli mpp pay ${input.url} --spend-request-id $SPEND_ID --method POST --data '${input.retryBodyJson}' --header 'X-Operator-Token: ${opToken}' --output-json`
       ];
-      stripe.what_it_does_link_cli = "For users who have a Stripe Link wallet: step 1 mints a one-time-use SharedPaymentToken scoped to this purchase and pushes a notification to the user for approval (blocks until approved); step 2 submits the SPT via the MPP handshake along with your AgentScore operator credential.";
+      stripe.what_it_does_link_cli = "Mints a one-time-use SharedPaymentToken scoped to this purchase (user approves in Link wallet), then submits it as the payment credential.";
     } else if (linkCliBlocked) {
       stripe.note = `link-cli SPT path not available for this purchase \u2014 Stripe link-cli caps spend requests at $500.00 ($50000 cents); your total is $${totalNum}. Use your own Stripe account with the SharedPaymentToken API instead.`;
     }
@@ -177,27 +178,27 @@ function buildHowToPay(input) {
 }
 
 // src/challenge/agent_instructions.ts
-var TEMPO_WARNING = "Do NOT use `tempo wallet transfer` to pay to the address above. That moves USDC on-chain but does not notify this server, leaving your order in pending_identity state. Use `tempo request` instead \u2014 it performs the full MPP handshake (signs, submits Authorization: Payment, waits for server confirmation).";
-var X402_WARNING = "Do NOT send USDC manually to the x402 deposit addresses (e.g. via a bare wallet `transfer`). Use `agentscore-pay pay` so the X-Payment credential is signed and submitted; otherwise the order stays in pending_identity even though the deposit lands.";
-var TEMPO_TOOL = "`tempo request` for Tempo USDC (installs via `tempo add request`)";
-var AGENTSCORE_PAY_TOOL = "`agentscore-pay` (npm: `@agent-score/pay`) \u2014 single CLI for x402 on Base + Solana, also speaks tempo MPP via `--chain tempo`";
-var DEFAULT_WALLET_COMPATIBILITY = "No specific wallet stack required. The 402 challenge is rail-neutral: any client that can produce a valid MPP credential (Authorization: Payment) or x402 X-Payment header is accepted. The CLI commands above are the easiest path; sign-it-yourself is fine too.";
+var TEMPO_WARNING = "Do NOT use `tempo wallet transfer`. That moves USDC on-chain without completing the protocol handshake, so the order will not complete. Use `tempo request` instead.";
+var X402_WARNING = "Do NOT send USDC manually to the deposit addresses. Use `agentscore-pay pay` so the credential is signed and submitted; otherwise the order will not complete even though the deposit lands.";
+var TEMPO_TOOL = "`tempo request` for Tempo USDC";
+var AGENTSCORE_PAY_TOOL = "`agentscore-pay` \u2014 Base + Solana + Tempo from one CLI";
+var DEFAULT_WALLET_COMPATIBILITY = "Any client that can produce a valid MPP credential (Authorization: Payment) or x402 X-Payment header. Use the CLI commands above; sign-it-yourself is also fine.";
 function defaultRecommendedTools(howToPay) {
   const tools = [];
   if (howToPay.tempo) tools.push(TEMPO_TOOL);
-  if (howToPay.tempo || howToPay.x402_base || howToPay.x402_solana) tools.push(AGENTSCORE_PAY_TOOL);
+  if (howToPay.tempo || howToPay.x402_base || howToPay.solana_mpp) tools.push(AGENTSCORE_PAY_TOOL);
   return tools;
 }
 function defaultWarnings(howToPay) {
   const w = [];
   if (howToPay.tempo) w.push(TEMPO_WARNING);
-  if (howToPay.x402_base || howToPay.x402_solana) w.push(X402_WARNING);
+  if (howToPay.x402_base) w.push(X402_WARNING);
   return w;
 }
 var RAIL_CLIENTS = {
   tempo_mpp: ["agentscore-pay", "tempo request", "x402-proxy"],
   x402_base: ["agentscore-pay", "x402-proxy", "purl (omit --network flag)"],
-  x402_solana: ["agentscore-pay"],
+  solana_mpp: ["agentscore-pay"],
   stripe: ["link-cli"]
 };
 function compatibleClientsByRails(rails) {
@@ -209,7 +210,7 @@ function defaultCompatibleClients(howToPay) {
   const rails = [];
   if (howToPay.tempo) rails.push("tempo_mpp");
   if (howToPay.x402_base) rails.push("x402_base");
-  if (howToPay.x402_solana) rails.push("x402_solana");
+  if (howToPay.solana_mpp) rails.push("solana_mpp");
   if (howToPay.stripe) rails.push("stripe");
   return compatibleClientsByRails(rails);
 }
@@ -220,7 +221,7 @@ function buildAgentInstructions(input) {
     recommended_tools: input.recommendedTools ?? defaultRecommendedTools(input.howToPay),
     wallet_compatibility: input.walletCompatibility ?? DEFAULT_WALLET_COMPATIBILITY,
     timeout_seconds: input.timeoutSeconds ?? 300,
-    warnings: input.warnings ?? defaultWarnings(input.howToPay),
+    warnings: input.warnings ?? [...defaultWarnings(input.howToPay), ...input.extraWarnings ?? []],
     ...input.recommended ? { recommended: input.recommended } : {},
     ...compatibleClients ? { compatible_clients: compatibleClients } : {},
     ...input.extra ?? {}