agentscore-commerce 2.2.0__tar.gz → 2.3.0__tar.gz

{agentscore_commerce-2.2.0 → agentscore_commerce-2.3.0}/CLAUDE.md

@@ -14,7 +14,7 @@ Every helper is extracted from a real consumer, not speculated.
 | `agentscore_commerce.payment` | Networks/USDC/rails registries, paymentauth.org directive builders, `create_x402_server` (wraps `x402[evm]>=2.9` + `cdp-sdk` for `facilitator="coinbase"`; install via the `coinbase` extra), `build_x402_accepts_for_402` (build the 402's `accepts[]` from the registered scheme; derives the right `extra.name` per network), `build_default_checkout_rails(tempo=, x402_base=, solana_mpp=, stripe=)` (canonical 4-rail `rails` dict factory: merchants pass per-rail overrides instead of redeclaring the recipient sentinel + network/chain_id/token boilerplate. When a caller flips `network` without pinning `token` / `chain_id`, the underlying dataclass derives them from the network: Base Sepolia → Sepolia USDC + chain_id 84532, Solana devnet → devnet USDC mint. Explicit overrides always win. Solana's `network` field accepts both CAIP-2 (`solana:5eykt4UsFv8…` / `solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1`) AND the raw `@solana/mpp` form (`mainnet-beta` / `devnet` / `localnet`)), `build_mppx_compose_rails(amount_usd=, tempo_recipient=, solana_recipient=, ...)` (per-call intent factory replacing the hand-rolled `[("tempo/charge", {...}), ("solana/charge", {...}), ("stripe/charge", {...})]` list; auto-handles USD→atomic conversion for Solana; auto-drops the `stripe/charge` rail with a one-time `logging.warning` when `amount_usd < 0.50` since Stripe's fixed ~$0.30 fee makes sub-50-cent charges unprofitable — many Stripe accounts also reject PI creation below the floor with `amount_too_small`; sub-50-cent APIs pass `include_stripe=False` explicitly to silence the warning), `process_x402_settle` (verify+settle in one call), `create_mppx_server` (wraps `pympp[server,tempo,stripe]>=0.6`), `is_evm_network`/`is_solana_network` (CAIP-2 discriminators that hide the `startswith("eip155:")` / `startswith("solana:")` prefix matching), `has_payment_header` (settle-leg vs discovery-leg discriminator), `parse_did_pkh_address` (parses ``did:pkh:<family>:<chain>:<addr>`` into a `PaymentSigner`), dispatch-by-network, signer extraction, WWW-Authenticate header, Settlement-Overrides header |
 | `agentscore_commerce.discovery` | Discovery probe (`is_discovery_probe_request`, `build_discovery_probe_response`), Bazaar wrapper, `/.well-known/mpp.json`, `llms.txt` builder, `skill.md` builder (Claude-Skill-compatible agent-discovery manifest), `build_redemption_skill_md` (delivery-neutral; printed/emailed/API-trial codes all covered via `delivery_intro`/`body_shape`/`body_rules`/`extra_recovery_rows` overrides), `build_merchant_index_json` + `standard_endpoint_descriptions(kind=)` (canonical `/` discovery body for goods or API merchants), `build_success_next_steps` (universal Passport-active success block), `build_agentscore_onboarding_steps`, OpenAPI snippets, `NoindexNonDiscoveryMiddleware` ASGI middleware. Plus the UCP/JWKS publish surface: `build_signed_ucp_response`, `build_signed_jwks_response`, `well_known_preflight_response`, `default_a2a_services`, `bootstrap_ucp_signing_key`, framework-neutral `SignedDiscoveryResponse` + per-framework wrappers `signed_response_{fastapi,flask,django,aiohttp,sanic}` |
 | `agentscore_commerce.challenge` | 402-body builders: accepted_methods, identity_metadata (auto-attached by `Checkout` when wallet header present), how_to_pay, agent_instructions, build_402_body, pricing, agent_memory, `build_validation_error` (4xx body builder), `Receipt`/`ReceiptNextSteps`/`ProductInfo`/`ShippingAddress` (canonical 200-receipt dataclasses) |
-| `agentscore_commerce.stripe_multichain` | Multichain PaymentIntent helper (`create_multichain_payment_intent` returns `MultichainPaymentIntentResult`; read `result.deposit_addresses[network]` directly), `create_pay_to_address_from_stripe_pi(authorization_header=, amount_cents=, stripe=, pi_cache=, networks=, metadata=, order_id=, preferred_network=)` — one-call per-order payTo resolver matching `Checkout.mint_recipients`: on the settle leg, reuses the buyer's signed-against payTo from the MPP credential (after `pi_cache.has_address` check); on the discovery leg, mints a fresh PI via `create_multichain_payment_intent` and caches the addresses + PI mapping. Testnet simulator (`simulate_crypto_deposit`, `simulate_deposit_if_test_mode`), `simulate_deposit_for_outcome(outcome=, deposit_address=, get_payment_intent_id=, stripe_secret_key=, stripe_version=)` (dispatches the simulator based on a Checkout / compute_first_checkout settle outcome; replaces the per-merchant rail-switch + thin `simulate_deposit_if_testnet(addr, network)` wrapper), `network_for_outcome` (outcome → simulator network arg, handles both Checkout-shaped `rail_key` and compute-first-shaped `mpp_method`, accepts bare scheme names AND `<scheme>/charge` forms), `create_pi_cache`, `create_mppx_stripe` |
+| `agentscore_commerce.stripe_multichain` | Multichain PaymentIntent helper (`create_multichain_payment_intent` returns `MultichainPaymentIntentResult`; read `result.deposit_addresses[network]` directly), `create_pay_to_address_from_stripe_pi(authorization_header=, amount_cents=, stripe=, pi_cache=, networks=, static_recipients=, metadata=, order_id=, preferred_network=)` — one-call per-order payTo resolver matching `Checkout.mint_recipients`: on the settle leg, reuses the buyer's signed-against payTo from the MPP credential (after `pi_cache.has_address` check OR a `static_recipients` 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 `static_recipients`, caches the merged map, registers static addresses with `pi_cache.cache_address`. `mint_multichain_recipients(...same kwargs) -> MintMultichainRecipientsResult(recipients, payment_intent_id, reused_from_credential)` — structured variant returning the full per-rail map; prefer this when the merchant's `mint_recipients` hook needs all rail addresses (typical multi-rail merchant), and to avoid the "returned-string-is-ambiguous" trap on the settle leg when `static_recipients` is configured. Use `static_recipients={"solana": "<wallet>"}` for low-margin endpoints where rotating per-PI Solana addresses can't absorb MPP spec §13.6's ~$0.50 ATA rent per call — the SDK skips Stripe minting on that network and reuses the static recipient forever; pair with a one-time external USDC pre-funding of the recipient's ATA and every settle pays only the per-tx fee. `SolanaMppRailSpec.ata_creation_required` defaults to `True` (data-only — solana method registration through `create_mppx_server` is a follow-up; merchants building the solana method directly via `pympp` should pass the flag themselves to the charge factory). Testnet simulator (`simulate_crypto_deposit`, `simulate_deposit_if_test_mode`), `simulate_deposit_for_outcome(outcome=, deposit_address=, get_payment_intent_id=, stripe_secret_key=, stripe_version=)` (dispatches the simulator based on a Checkout / compute_first_checkout settle outcome; replaces the per-merchant rail-switch + thin `simulate_deposit_if_testnet(addr, network)` wrapper), `network_for_outcome` (outcome → simulator network arg, handles both Checkout-shaped `rail_key` and compute-first-shaped `mpp_method`, accepts bare scheme names AND `<scheme>/charge` forms), `create_pi_cache`, `create_mppx_stripe` |
 | `agentscore_commerce.api` | Re-exports `AgentScore` from `agentscore` SDK |
 | `agentscore_commerce.middleware.{fastapi,flask,django,aiohttp,sanic,asgi}` | Framework-specific rate-limit middleware. FastAPI exposes `rate_limit_fastapi(...)` (FastAPI dependency) plus the ASGI `RateLimitMiddleware` re-export; Flask exposes `rate_limit_flask(app, ...)` (installs a `before_request` hook); Django exposes a class-based async `RateLimitMiddleware` configured via `settings.AGENTSCORE_RATE_LIMIT`; aiohttp exposes `rate_limit_aiohttp(...)` middleware factory; Sanic exposes `rate_limit_sanic(app, ...)` installer; `asgi.RateLimitMiddleware` is a generic ASGI middleware that works with any starlette-compatible app. Shared options: `window_seconds` (default 60), `max_requests` (default 60), `key_resolver` (default first hop of `x-forwarded-for`), `redis_url` (lazy-imports `redis.asyncio` when set, in-memory `dict` fallback otherwise), `key_prefix`. `redis` is an optional peer dep (install via the `redis` extra). |
 

{agentscore_commerce-2.2.0 → agentscore_commerce-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentscore-commerce
-Version: 2.2.0
+Version: 2.3.0
 Summary: Agent commerce SDK for Python — identity middleware (FastAPI, Flask, Django, AIOHTTP, Sanic, ASGI) + payment helpers + 402 builders + discovery + Stripe multichain. The full merchant-side toolkit for AgentScore-powered agent commerce.
 Project-URL: Homepage, https://agentscore.sh
 Project-URL: Repository, https://github.com/agentscore/python-commerce
@@ -78,7 +78,7 @@ pip install 'agentscore-commerce[fastapi,x402,coinbase]'
 | `agentscore_commerce.payment` | `networks`, `USDC`, `rails` registries; `payment_directive`, `build_payment_directive`, `www_authenticate_header`, `payment_required_header`, `alias_amount_fields` (v1↔v2 amount field shim that emits both `amount` and `maxAmountRequired` so v1-only x402 parsers like Coinbase awal can read v2 bodies), `settlement_override_header`, `dispatch_settlement_by_network`, `extract_payment_signer` (accepts positional `x402_payment_header` AND/OR `authorization_header=` kwarg; 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), `detect_rail_from_headers` (returns `"x402"` / `"mpp"` / `None` from inbound headers), `register_x402_schemes_v1_v2`; drop-in x402 helpers: `validate_x402_network_config` (boot-time guard), `verify_x402_request` (parse + validate inbound X-Payment), `process_x402_settle` (verify-then-settle with one call), `classify_x402_settle_result` (maps the tagged settle result to a recommended HTTP status / code / next_steps so merchants get a controlled envelope without coupling to facilitator-specific error text), `classify_orchestration_error` (same `ClassifiedX402Error` shape but for uncaught exceptions thrown elsewhere in the orchestration; returns `None` for unknown errors so merchants rethrow instead of swallowing); `zero_amount_carve_out` (skip CDP / pympp 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); `usd_to_atomic` (Decimal-based USD → atomic int, ROUND_HALF_UP — for Tempo / Solana / Base USDC amount construction). |
 | `agentscore_commerce.discovery` | `is_discovery_probe_request`, `build_discovery_probe_response` (with optional `x402_sample` for x402-aware crawlers like `awal x402 details`), `sample_x402_accept_for_network` (USDC sample-accept builder for known CAIP-2 networks), `build_well_known_mpp`, `build_llms_txt` + `llms_txt_identity_section` + `llms_txt_payment_section` (compact + verbose modes), `build_skill_md` (Claude-Skill-compatible `/skill.md` agent-discovery manifest; strictly agent-facing data only, no internal posture), `build_redemption_skill_md` (delivery-neutral redemption-code template — printed mailers, emailed codes, API trial credits all covered; `endpoint_path`/`delivery_intro`/`body_shape`/`body_rules`/`extra_recovery_rows` overrides for non-goods shapes), `build_merchant_index_json` (canonical `/` discovery body), `standard_endpoint_descriptions(kind=)` (canonical method+path → description map for goods vs api merchants; optional `include_order_status_route` for goods), `build_success_next_steps` (universal Passport-active success block), `build_agentscore_onboarding_steps` (canonical skill.md onboarding for goods or API merchants), `agentscore_openapi_snippets`, `build_bazaar_discovery_payload`, `NoindexNonDiscoveryMiddleware` (ASGI middleware emitting `X-Robots-Tag: noindex` on every path except the agent-discovery surfaces; pure helpers `is_discovery_path` + `DEFAULT_DISCOVERY_PATHS` for non-ASGI frameworks). Plus the UCP/JWKS publish surface: `build_signed_ucp_response`, `build_signed_jwks_response`, `well_known_preflight_response`, `default_a2a_services`, `bootstrap_ucp_signing_key`, framework-neutral `SignedDiscoveryResponse` + per-framework wrappers `signed_response_{fastapi,flask,django,aiohttp,sanic}`. |
 | `agentscore_commerce.challenge` | `build_402_body`, `build_accepted_methods`, `build_identity_metadata` (auto-attached by `Checkout` when an inbound `X-Wallet-Address` header is present), `build_how_to_pay`, `build_agent_instructions` (auto-emits per-rail `compatible_clients`: smoke-verified CLIs the agent should use; vendor override supported; pure helper `compatible_clients_by_rails(rails)` returns the same map for vendors building custom 402s), `build_pricing_block` (cents to dollar-string with optional shipping/tax), `first_encounter_agent_memory` (cross-merchant hint, returns the canonical block or `None` based on a per-merchant first-seen flag), `Receipt` + `ReceiptNextSteps` + `ProductInfo` + `ShippingAddress` (canonical 200-receipt dataclasses — universal across goods + API merchants); `respond_402`, a drop-in 402 emit that preserves pympp's `WWW-Authenticate` and layers x402's `PAYMENT-REQUIRED`. `build_validation_error`: 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. |
-| `agentscore_commerce.stripe_multichain` | `create_multichain_payment_intent` (returns `MultichainPaymentIntentResult(payment_intent_id, deposit_addresses)`; read `result.deposit_addresses[network]` directly), `create_pay_to_address_from_stripe_pi(authorization_header=, amount_cents=, stripe=, pi_cache=, networks=, metadata=, order_id=, preferred_network=)` — per-order payTo resolver: on the settle leg, reuses the buyer's signed-against payTo from the MPP credential (after `pi_cache.has_address` check); on the discovery leg, mints a fresh PI and caches it. `simulate_crypto_deposit`; `create_pi_cache` (TTL'd PI / deposit-address cache, Redis-backed when `redis_url` set, in-memory otherwise), `simulate_deposit_if_test_mode` (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`. |
+| `agentscore_commerce.stripe_multichain` | `create_multichain_payment_intent` (returns `MultichainPaymentIntentResult(payment_intent_id, deposit_addresses)`; read `result.deposit_addresses[network]` directly), `create_pay_to_address_from_stripe_pi(authorization_header=, amount_cents=, stripe=, pi_cache=, networks=, static_recipients=, metadata=, order_id=, preferred_network=)` — per-order payTo resolver: on the settle leg, reuses the buyer's signed-against payTo from the MPP credential (after `pi_cache.has_address` check OR a `static_recipients` 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 `static_recipients`, caches the merged map, registers static addresses with `pi_cache.cache_address` so verify-leg lookups pass. `mint_multichain_recipients(...same kwargs)` — structured variant returning `MintMultichainRecipientsResult(recipients, payment_intent_id, reused_from_credential)` for the full per-rail map (typical multi-rail merchant hook). Use `static_recipients={"solana": "<wallet>"}` for low-margin endpoints where Solana per-call ATA rent (~$0.50 against MPP spec §13.6) dominates revenue — the SDK skips Stripe minting on that network, reuses the static recipient forever, and (with a one-time external pre-funding of the recipient's USDC ATA) lets every settle pay only the ~$0.001 per-tx fee. `SolanaMppRailSpec.ata_creation_required` defaults to `True` (data-only; solana method registration through `create_mppx_server` is a follow-up — merchants building the solana method directly via `pympp` should pass the flag themselves to the charge factory). `simulate_crypto_deposit`; `create_pi_cache` (TTL'd PI / deposit-address cache, Redis-backed when `redis_url` set, in-memory otherwise), `simulate_deposit_if_test_mode` (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`. |
 | `agentscore_commerce.api` | Everything from `agentscore-py` re-exported in one place: `AgentScore` + `AgentScoreError`, `AGENTSCORE_TEST_ADDRESSES` + `is_agentscore_test_address`. **Don't add `agentscore-py` as a separate dep**: the two can drift versions and cause subtle type mismatches. |
 | `agentscore_commerce.middleware.{fastapi,flask,django,aiohttp,sanic,asgi}` | Framework-specific rate-limit middleware. FastAPI: `rate_limit_fastapi(...)` (FastAPI dependency) plus the ASGI `RateLimitMiddleware` re-export. Flask: `rate_limit_flask(app, ...)` installer. Django: class-based async `RateLimitMiddleware` configured via `settings.AGENTSCORE_RATE_LIMIT`. aiohttp: `rate_limit_aiohttp(...)` middleware factory. Sanic: `rate_limit_sanic(app, ...)` installer. `asgi.RateLimitMiddleware` works with any starlette-compatible app. Shared options: `window_seconds` (default 60), `max_requests` (default 60), `key_resolver` (default first hop of `x-forwarded-for`), `redis_url` (lazy-imports `redis.asyncio` when set, in-memory `dict` fallback otherwise), `key_prefix`. `redis` is an optional peer dep (install via the `redis` extra). |
 

{agentscore_commerce-2.2.0 → agentscore_commerce-2.3.0}/README.md

@@ -30,7 +30,7 @@ pip install 'agentscore-commerce[fastapi,x402,coinbase]'
 | `agentscore_commerce.payment` | `networks`, `USDC`, `rails` registries; `payment_directive`, `build_payment_directive`, `www_authenticate_header`, `payment_required_header`, `alias_amount_fields` (v1↔v2 amount field shim that emits both `amount` and `maxAmountRequired` so v1-only x402 parsers like Coinbase awal can read v2 bodies), `settlement_override_header`, `dispatch_settlement_by_network`, `extract_payment_signer` (accepts positional `x402_payment_header` AND/OR `authorization_header=` kwarg; 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), `detect_rail_from_headers` (returns `"x402"` / `"mpp"` / `None` from inbound headers), `register_x402_schemes_v1_v2`; drop-in x402 helpers: `validate_x402_network_config` (boot-time guard), `verify_x402_request` (parse + validate inbound X-Payment), `process_x402_settle` (verify-then-settle with one call), `classify_x402_settle_result` (maps the tagged settle result to a recommended HTTP status / code / next_steps so merchants get a controlled envelope without coupling to facilitator-specific error text), `classify_orchestration_error` (same `ClassifiedX402Error` shape but for uncaught exceptions thrown elsewhere in the orchestration; returns `None` for unknown errors so merchants rethrow instead of swallowing); `zero_amount_carve_out` (skip CDP / pympp 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); `usd_to_atomic` (Decimal-based USD → atomic int, ROUND_HALF_UP — for Tempo / Solana / Base USDC amount construction). |
 | `agentscore_commerce.discovery` | `is_discovery_probe_request`, `build_discovery_probe_response` (with optional `x402_sample` for x402-aware crawlers like `awal x402 details`), `sample_x402_accept_for_network` (USDC sample-accept builder for known CAIP-2 networks), `build_well_known_mpp`, `build_llms_txt` + `llms_txt_identity_section` + `llms_txt_payment_section` (compact + verbose modes), `build_skill_md` (Claude-Skill-compatible `/skill.md` agent-discovery manifest; strictly agent-facing data only, no internal posture), `build_redemption_skill_md` (delivery-neutral redemption-code template — printed mailers, emailed codes, API trial credits all covered; `endpoint_path`/`delivery_intro`/`body_shape`/`body_rules`/`extra_recovery_rows` overrides for non-goods shapes), `build_merchant_index_json` (canonical `/` discovery body), `standard_endpoint_descriptions(kind=)` (canonical method+path → description map for goods vs api merchants; optional `include_order_status_route` for goods), `build_success_next_steps` (universal Passport-active success block), `build_agentscore_onboarding_steps` (canonical skill.md onboarding for goods or API merchants), `agentscore_openapi_snippets`, `build_bazaar_discovery_payload`, `NoindexNonDiscoveryMiddleware` (ASGI middleware emitting `X-Robots-Tag: noindex` on every path except the agent-discovery surfaces; pure helpers `is_discovery_path` + `DEFAULT_DISCOVERY_PATHS` for non-ASGI frameworks). Plus the UCP/JWKS publish surface: `build_signed_ucp_response`, `build_signed_jwks_response`, `well_known_preflight_response`, `default_a2a_services`, `bootstrap_ucp_signing_key`, framework-neutral `SignedDiscoveryResponse` + per-framework wrappers `signed_response_{fastapi,flask,django,aiohttp,sanic}`. |
 | `agentscore_commerce.challenge` | `build_402_body`, `build_accepted_methods`, `build_identity_metadata` (auto-attached by `Checkout` when an inbound `X-Wallet-Address` header is present), `build_how_to_pay`, `build_agent_instructions` (auto-emits per-rail `compatible_clients`: smoke-verified CLIs the agent should use; vendor override supported; pure helper `compatible_clients_by_rails(rails)` returns the same map for vendors building custom 402s), `build_pricing_block` (cents to dollar-string with optional shipping/tax), `first_encounter_agent_memory` (cross-merchant hint, returns the canonical block or `None` based on a per-merchant first-seen flag), `Receipt` + `ReceiptNextSteps` + `ProductInfo` + `ShippingAddress` (canonical 200-receipt dataclasses — universal across goods + API merchants); `respond_402`, a drop-in 402 emit that preserves pympp's `WWW-Authenticate` and layers x402's `PAYMENT-REQUIRED`. `build_validation_error`: 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. |
-| `agentscore_commerce.stripe_multichain` | `create_multichain_payment_intent` (returns `MultichainPaymentIntentResult(payment_intent_id, deposit_addresses)`; read `result.deposit_addresses[network]` directly), `create_pay_to_address_from_stripe_pi(authorization_header=, amount_cents=, stripe=, pi_cache=, networks=, metadata=, order_id=, preferred_network=)` — per-order payTo resolver: on the settle leg, reuses the buyer's signed-against payTo from the MPP credential (after `pi_cache.has_address` check); on the discovery leg, mints a fresh PI and caches it. `simulate_crypto_deposit`; `create_pi_cache` (TTL'd PI / deposit-address cache, Redis-backed when `redis_url` set, in-memory otherwise), `simulate_deposit_if_test_mode` (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`. |
+| `agentscore_commerce.stripe_multichain` | `create_multichain_payment_intent` (returns `MultichainPaymentIntentResult(payment_intent_id, deposit_addresses)`; read `result.deposit_addresses[network]` directly), `create_pay_to_address_from_stripe_pi(authorization_header=, amount_cents=, stripe=, pi_cache=, networks=, static_recipients=, metadata=, order_id=, preferred_network=)` — per-order payTo resolver: on the settle leg, reuses the buyer's signed-against payTo from the MPP credential (after `pi_cache.has_address` check OR a `static_recipients` 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 `static_recipients`, caches the merged map, registers static addresses with `pi_cache.cache_address` so verify-leg lookups pass. `mint_multichain_recipients(...same kwargs)` — structured variant returning `MintMultichainRecipientsResult(recipients, payment_intent_id, reused_from_credential)` for the full per-rail map (typical multi-rail merchant hook). Use `static_recipients={"solana": "<wallet>"}` for low-margin endpoints where Solana per-call ATA rent (~$0.50 against MPP spec §13.6) dominates revenue — the SDK skips Stripe minting on that network, reuses the static recipient forever, and (with a one-time external pre-funding of the recipient's USDC ATA) lets every settle pay only the ~$0.001 per-tx fee. `SolanaMppRailSpec.ata_creation_required` defaults to `True` (data-only; solana method registration through `create_mppx_server` is a follow-up — merchants building the solana method directly via `pympp` should pass the flag themselves to the charge factory). `simulate_crypto_deposit`; `create_pi_cache` (TTL'd PI / deposit-address cache, Redis-backed when `redis_url` set, in-memory otherwise), `simulate_deposit_if_test_mode` (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`. |
 | `agentscore_commerce.api` | Everything from `agentscore-py` re-exported in one place: `AgentScore` + `AgentScoreError`, `AGENTSCORE_TEST_ADDRESSES` + `is_agentscore_test_address`. **Don't add `agentscore-py` as a separate dep**: the two can drift versions and cause subtle type mismatches. |
 | `agentscore_commerce.middleware.{fastapi,flask,django,aiohttp,sanic,asgi}` | Framework-specific rate-limit middleware. FastAPI: `rate_limit_fastapi(...)` (FastAPI dependency) plus the ASGI `RateLimitMiddleware` re-export. Flask: `rate_limit_flask(app, ...)` installer. Django: class-based async `RateLimitMiddleware` configured via `settings.AGENTSCORE_RATE_LIMIT`. aiohttp: `rate_limit_aiohttp(...)` middleware factory. Sanic: `rate_limit_sanic(app, ...)` installer. `asgi.RateLimitMiddleware` works with any starlette-compatible app. Shared options: `window_seconds` (default 60), `max_requests` (default 60), `key_resolver` (default first hop of `x-forwarded-for`), `redis_url` (lazy-imports `redis.asyncio` when set, in-memory `dict` fallback otherwise), `key_prefix`. `redis` is an optional peer dep (install via the `redis` extra). |
 

{agentscore_commerce-2.2.0 → agentscore_commerce-2.3.0}/agentscore_commerce/payment/rail_spec.py

@@ -124,6 +124,30 @@ class SolanaMppRailSpec:
     rpc_url: str | None = None
     signer: Any | None = None
     token_program: str | None = None
+    # Whether the recipient's ATA may be auto-created on first payment. Default True.
+    # When True (default), the SDK passes
+    # ``splits=[{"recipient": recipient, "amount": "0", "ataCreationRequired": True}]``
+    # to ``solana.charge``, putting the recipient in the MPP spec §13.6
+    # ``allowedAtaOwners`` allow-list. Required on ``@solana/mpp >= 0.6.0`` /
+    # ``pympp[solana] >= 0.6`` with a sponsored (fee-payer) setup — without it,
+    # every settle that emits a ``CreateIdempotent`` ATA instruction is rejected.
+    # On older runtimes the field is unknown and silently ignored, so the
+    # default is safe across versions.
+    #
+    # Opt out (``False``) only when every recipient's ATA is guaranteed to
+    # exist out-of-band (typically when the merchant pre-creates the ATA from
+    # an external wallet and refuses to let the fee-payer fund creation).
+    #
+    # Economic note: with rotating recipients (Stripe-multichain per-PI deposit
+    # addresses), the sponsor pays ~0.002 SOL (~$0.50) of rent per call into
+    # accounts the merchant can't close. Acceptable when settle amounts
+    # dominate ($50+); not viable for sub-dollar merchants.
+    #
+    # NOTE: python-commerce doesn't yet wire SolanaMppRailSpec through
+    # ``create_mppx_server`` (node parity gap); this field is data-only here
+    # today. Merchants building the solana method directly via ``pympp``
+    # should pass ``ata_creation_required`` themselves to the charge factory.
+    ata_creation_required: bool = True
 
     def __post_init__(self) -> None:
         # Mirror X402BaseRailSpec: when ``network`` flips to the devnet CAIP-2 (or the

{agentscore_commerce-2.2.0 → agentscore_commerce-2.3.0}/agentscore_commerce/stripe_multichain/__init__.py

@@ -5,7 +5,9 @@ from agentscore_commerce.stripe_multichain.mppx_stripe import (
     create_mppx_stripe,
 )
 from agentscore_commerce.stripe_multichain.pay_to_address import (
+    MintMultichainRecipientsResult,
     create_pay_to_address_from_stripe_pi,
+    mint_multichain_recipients,
 )
 from agentscore_commerce.stripe_multichain.payment_intent import (
     MultichainPaymentIntentResult,
@@ -31,6 +33,7 @@ __all__ = [
     "DEFAULT_PAYMENT_METHOD_TYPES",
     "STRIPE_TEST_TX_HASH_FAILED",
     "STRIPE_TEST_TX_HASH_SUCCESS",
+    "MintMultichainRecipientsResult",
     "MultichainPaymentIntentResult",
     "PiCache",
     "SimulateNetwork",
@@ -39,6 +42,7 @@ __all__ = [
     "create_multichain_payment_intent",
     "create_pay_to_address_from_stripe_pi",
     "create_pi_cache",
+    "mint_multichain_recipients",
     "network_for_outcome",
     "simulate_crypto_deposit",
     "simulate_deposit_for_outcome",

agentscore_commerce-2.3.0/agentscore_commerce/stripe_multichain/pay_to_address.py

@@ -0,0 +1,280 @@
+"""Per-order Stripe-multichain ``pay_to`` resolver.
+
+Stripe-multichain merchants need ONE function for their ``mint_recipients``
+(or per-request payTo) hook that does the right thing on both legs:
+
+- **Discovery leg** (no payment header): mint a fresh PaymentIntent so the 402
+  advertises a stable per-order deposit address.
+- **Settle leg** (MPP credential attached): reuse the buyer's signed-against
+  payTo from the credential (after verifying it's in the local cache OR matches
+  a configured ``static_recipients`` entry) — otherwise the verify leg would
+  compare against a freshly-rotated address and reject the credential.
+
+Stripe SPT and card methods don't carry an on-chain recipient, so the settle
+leg still mints a fresh PaymentIntent for them.
+
+Mirrors node-commerce ``src/stripe-multichain/pay_to_address.ts``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from agentscore_commerce.errors import CheckoutValidationError
+from agentscore_commerce.stripe_multichain.payment_intent import (
+    create_multichain_payment_intent,
+)
+
+if TYPE_CHECKING:
+    from agentscore_commerce.stripe_multichain.pi_cache import PiCache
+
+
+async def _maybe_await(value: Any) -> Any:
+    if asyncio.iscoroutine(value) or asyncio.isfuture(value):
+        return await value
+    return value
+
+
+async def create_pay_to_address_from_stripe_pi(
+    *,
+    authorization_header: str | None,
+    amount_cents: int,
+    stripe: Any,
+    pi_cache: PiCache,
+    networks: list[str] | None = None,
+    static_recipients: dict[str, str] | None = None,
+    metadata: dict[str, str] | None = None,
+    order_id: str | None = None,
+    preferred_network: str = "tempo",
+) -> str:
+    """Resolve the on-chain ``pay_to`` for a Stripe-multichain order.
+
+    On the settle leg, when ``authorization_header`` carries an MPP credential
+    binding a ``tempo`` or ``solana`` recipient, returns THAT address (after
+    verifying it's in ``pi_cache`` OR matches a configured ``static_recipients``
+    entry — static addresses are always-accepted because the merchant owns
+    them). Otherwise mints a fresh :func:`create_multichain_payment_intent`
+    for the rails NOT covered by ``static_recipients``, caches the merged
+    address map, and registers static recipients with ``pi_cache.cache_address``
+    so future verify-leg lookups pass. Returns the address on the
+    ``preferred_network`` (default ``"tempo"``, falling back to ``base`` then
+    ``tempo``).
+
+    ``static_recipients`` (optional, keyed by network) lets the merchant pin a
+    fixed receive wallet on chains where per-call rotation is expensive — Solana
+    in particular, since MPP spec §13.6 charges ~0.002 SOL of ATA rent per
+    new recipient into accounts the merchant can't close. Example:
+    ``static_recipients={"solana": "FR96wd96urH..."}``. The SDK skips Stripe
+    minting for that network so the static address is reused forever; pair
+    with a one-time external USDC transfer to pre-create the recipient's USDC
+    ATA and every settle pays only the per-tx fee.
+    """
+    if authorization_header:
+        recipient = await _try_resolve_from_credential(
+            authorization_header=authorization_header,
+            pi_cache=pi_cache,
+            static_recipients=static_recipients or {},
+        )
+        if recipient is not None:
+            return recipient
+
+    result_payto, _ = await _mint_and_cache(
+        amount_cents=amount_cents,
+        stripe=stripe,
+        pi_cache=pi_cache,
+        networks=networks or ["tempo", "base", "solana"],
+        static_recipients=static_recipients or {},
+        metadata=metadata,
+        order_id=order_id,
+        preferred_network=preferred_network,
+    )
+    return result_payto
+
+
+@dataclass
+class MintMultichainRecipientsResult:
+    """Structured result for :func:`mint_multichain_recipients`.
+
+    Exposes the full per-network deposit map plus the PI id, so merchants don't
+    have to guess "is the returned string the tempo address or the solana
+    static?" when ``static_recipients`` is configured.
+    """
+
+    recipients: dict[str, str]
+    """Per-network deposit address map (merges Stripe-minted + static_recipients)."""
+
+    payment_intent_id: str | None
+    """Stripe PI id, or None if all networks were covered by ``static_recipients``."""
+
+    reused_from_credential: bool
+    """True when the settle leg short-circuited to the credential-bound recipient."""
+
+
+async def mint_multichain_recipients(
+    *,
+    authorization_header: str | None,
+    amount_cents: int,
+    stripe: Any,
+    pi_cache: PiCache,
+    networks: list[str] | None = None,
+    static_recipients: dict[str, str] | None = None,
+    metadata: dict[str, str] | None = None,
+    order_id: str | None = None,
+    preferred_network: str = "tempo",
+) -> MintMultichainRecipientsResult:
+    """Structured variant of :func:`create_pay_to_address_from_stripe_pi`.
+
+    Returns the full per-rail deposit map. Prefer this when the merchant's
+    ``mint_recipients`` hook needs every rail's address (typical multi-rail
+    merchant) — avoids the "returned string is ambiguous" trap when
+    ``static_recipients`` is configured (settle leg's bound recipient may be
+    the solana static rather than the tempo per-PI address).
+    """
+    static = static_recipients or {}
+    if authorization_header:
+        from agentscore_commerce.stripe_multichain.pi_cache import PiCache  # noqa: F401
+
+        recipient = await _try_resolve_from_credential(
+            authorization_header=authorization_header,
+            pi_cache=pi_cache,
+            static_recipients=static,
+        )
+        if recipient is not None:
+            pi_id = pi_cache.get_payment_intent_id(recipient)
+            network_map: dict[str, str] = {}
+            if pi_id:
+                for net in ("tempo", "base", "solana"):
+                    addr = pi_cache.get_network_deposit_address(pi_id, net)
+                    if addr:
+                        network_map[net] = addr
+            merged = {**network_map, **static}
+            return MintMultichainRecipientsResult(
+                recipients=merged,
+                payment_intent_id=pi_id,
+                reused_from_credential=True,
+            )
+
+    _, merged = await _mint_and_cache(
+        amount_cents=amount_cents,
+        stripe=stripe,
+        pi_cache=pi_cache,
+        networks=networks or ["tempo", "base", "solana"],
+        static_recipients=static,
+        metadata=metadata,
+        order_id=order_id,
+        preferred_network=preferred_network,
+    )
+    pi_id = pi_cache.get_payment_intent_id(next(iter(merged.values()), ""))
+    return MintMultichainRecipientsResult(
+        recipients=merged,
+        payment_intent_id=pi_id,
+        reused_from_credential=False,
+    )
+
+
+async def _try_resolve_from_credential(
+    *,
+    authorization_header: str,
+    pi_cache: PiCache,
+    static_recipients: dict[str, str],
+) -> str | None:
+    """Parse the MPP credential and return the bound recipient when valid.
+
+    Returns the address when it's cached OR matches a configured
+    ``static_recipients`` entry, or None to fall through to the mint path.
+    Raises CheckoutValidationError on malformed credentials.
+    """
+    if not authorization_header.startswith("Payment "):
+        return None
+    from mpp import Credential  # type: ignore[import-untyped]
+
+    try:
+        credential = Credential.from_authorization(authorization_header)
+    except Exception as err:
+        raise CheckoutValidationError(
+            code="invalid_credential",
+            message="The Authorization: Payment header is not a valid MPP credential.",
+            action="retry_without_credential",
+            status=401,
+        ) from err
+    method = getattr(credential.challenge, "method", None)
+    if method not in ("tempo", "solana"):
+        return None
+    recipient = getattr(credential.challenge.request, "recipient", None)
+    if not isinstance(recipient, str) or not recipient:
+        raise CheckoutValidationError(
+            code="invalid_credential",
+            message="The MPP credential is missing its recipient field.",
+            action="retry_without_credential",
+            status=401,
+        )
+    static_for_method = static_recipients.get(method)
+    if static_for_method and static_for_method == recipient:
+        return recipient
+    if not await _maybe_await(pi_cache.has_address(recipient)):
+        raise CheckoutValidationError(
+            code="invalid_credential",
+            message=(
+                "The signed-against payTo recipient is not in this merchant's cache "
+                "(unknown or expired). Retry without the Authorization: Payment header "
+                "to receive a fresh 402 challenge."
+            ),
+            action="retry_without_credential",
+            status=401,
+        )
+    return recipient
+
+
+async def _mint_and_cache(
+    *,
+    amount_cents: int,
+    stripe: Any,
+    pi_cache: PiCache,
+    networks: list[str],
+    static_recipients: dict[str, str],
+    metadata: dict[str, str] | None,
+    order_id: str | None,
+    preferred_network: str,
+) -> tuple[str, dict[str, str]]:
+    """Mint a fresh PI for rails not covered by static_recipients.
+
+    Registers everything in the cache and returns (preferred_address, merged_map).
+    """
+    stripe_networks = [n for n in networks if n not in static_recipients]
+    idempotency_key = f"pi-{order_id}-{amount_cents}" if order_id else None
+    result = create_multichain_payment_intent(
+        stripe=stripe,
+        amount=amount_cents,
+        networks=stripe_networks,
+        metadata=metadata,
+        idempotency_key=idempotency_key,
+    )
+    for address in result.deposit_addresses.values():
+        await _maybe_await(pi_cache.cache_address(address))
+        pi_cache.cache_payment_intent(address, result.payment_intent_id)
+    for address in static_recipients.values():
+        await _maybe_await(pi_cache.cache_address(address))
+    merged: dict[str, str] = {**result.deposit_addresses, **static_recipients}
+    pi_cache.cache_network_addresses(result.payment_intent_id, merged)
+
+    pay_to = merged.get(preferred_network) or merged.get("base") or merged.get("tempo")
+    if not pay_to:
+        raise CheckoutValidationError(
+            code="payment_provider_unavailable",
+            message=(
+                "Stripe returned deposit addresses but none matched the requested network (tempo / base / solana). "
+                "The account may have only a subset of multichain networks enabled."
+            ),
+            action="retry_later",
+            status=503,
+        )
+    return pay_to, merged
+
+
+__all__ = [
+    "MintMultichainRecipientsResult",
+    "create_pay_to_address_from_stripe_pi",
+    "mint_multichain_recipients",
+]

{agentscore_commerce-2.2.0 → agentscore_commerce-2.3.0}/examples/README.md

@@ -7,7 +7,7 @@ Runnable, copy-pasteable example integrations covering the most common merchant
 | [`identity_only.py`](./identity_only.py) | Compliance gate without payment | Minimal: wraps any endpoint with KYC + age + jurisdiction checks. Vendor handles their own payment. |
 | [`api_provider.py`](./api_provider.py) | API provider (Exa-style) | Per-call billing on multiple rails: Tempo MPP + x402 (Base + Solana), all driven by `Checkout`. No identity gate. Demos `Checkout(discovery_probe=...)` for x402-crawler auto-routing, `build_merchant_index_json` + `standard_endpoint_descriptions(kind="api")` for `GET /` discovery, and `build_redemption_skill_md` with the trial-credit body shape on `GET /redemption.md`. |
 | [`multi_rail_merchant.py`](./multi_rail_merchant.py) | Full agent-commerce merchant | Identity gate + Tempo MPP + x402 (Base + Solana) + Stripe SPT via `Checkout`. Demos `pricing_result` (cents → typed PricingResult), `Receipt` + `ReceiptNextSteps` + `build_success_next_steps` in `on_settled`, per-order Stripe-multichain deposit minting via `mint_recipients`, and `simulate_deposit_if_test_mode`. |
-| [`stripe_multichain_merchant.py`](./stripe_multichain_merchant.py) | Stripe-anchored multi-chain | Stripe PaymentIntent with deposit_options for tempo/base/solana; crypto deposits flow through Stripe. Read `result.deposit_addresses[network]` directly. Includes testnet `simulate_crypto_deposit` helper. |
+| [`stripe_multichain_merchant.py`](./stripe_multichain_merchant.py) | Stripe-anchored multi-chain | Stripe PaymentIntent with deposit_options for tempo/base/solana; crypto deposits flow through Stripe. Read `result.deposit_addresses[network]` directly. Includes testnet `simulate_crypto_deposit` helper. For low-margin endpoints (sub-dollar APIs), use `create_pay_to_address_from_stripe_pi` / `mint_multichain_recipients` with `static_recipients={"solana": "<wallet>"}` — see the `stripe_multichain` row in the main `README.md` for the full pattern and economics. |
 | [`variable_cost_merchant.py`](./variable_cost_merchant.py) | Pay-per-actual-usage (LLM, transcode, etc.) | Same use case on **two protocols**: x402 upto (Permit2 authorize-max → `Settlement-Overrides` settle-actual) AND MPP tempo session (channel + SSE + mid-stream vouchers). Stays on lower-level helpers (`payment_directive`, `www_authenticate_header`, `settlement_override_header`) because variable-cost flows don't fit the one-shot `Checkout` model. |
 | [`compliance_merchant.py`](./compliance_merchant.py) | Regulated-goods merchant (wine, cannabis, etc.) | Full compliance gate via `Checkout(gate=CheckoutGateConfig(...))` + custom `on_denied` composing commerce helpers: `verification_agent_instructions`, `is_fixable_denial`, `build_contact_support_next_steps`, `denial_reason_to_body`/`denial_reason_status`. Shows how vendors write only the business-specific denial branches and let commerce handle the rest. |
 | [`per_product_policy_merchant.py`](./per_product_policy_merchant.py) | Multi-product merchant with mixed compliance needs | One product carries a hard gate (wine: KYC + 21 + US-state allowlist), another has no gate at all (anonymous merch, ships anywhere), a third uses `enforcement="soft"` (request KYC as a fraud signal but accept anonymous sales, stamping `identity_status="unverified"` on the order). Uses `PolicyBlock`, the one-call `validate_shipping_against_policy`, and `Checkout(gate=CheckoutGateConfig(per_request_policy=...))`. |

{agentscore_commerce-2.2.0 → agentscore_commerce-2.3.0}/examples/multi_rail_merchant.py

@@ -60,8 +60,8 @@ from agentscore_commerce.discovery import build_success_next_steps
 from agentscore_commerce.middleware.fastapi import RateLimitMiddleware
 from agentscore_commerce.payment import networks, validate_x402_network_config
 from agentscore_commerce.stripe_multichain import (
-    create_multichain_payment_intent,
     create_pi_cache,
+    mint_multichain_recipients,
     simulate_deposit_for_outcome,
 )
 
@@ -104,22 +104,35 @@ async def _compute_pricing(ctx: Any) -> PricingResult:
 
 
 async def _mint_recipients(ctx: Any) -> dict[str, str]:
-    """Per-order recipient mint: Stripe multichain PI → per-network deposit addresses."""
+    """Per-order recipient mint: Stripe multichain PI → per-network deposit addresses.
+
+    ``mint_multichain_recipients`` returns the full per-rail map and registers
+    everything in the PI cache in one call. On the settle leg it short-circuits
+    to the buyer's signed-against payTo from the MPP credential; on the discovery
+    leg it mints a fresh multichain PI.
+
+    For low-margin endpoints (sub-dollar per call), pass
+    ``static_recipients={"solana": os.environ["MERCHANT_SOLANA_RECIPIENT"]}`` to
+    skip Stripe minting on Solana — at $0.01/call MPP spec §13.6's ~$0.50 per-PI
+    ATA rent dominates revenue. With a stable merchant-owned recipient + one-time
+    external pre-funding of its USDC ATA, every settle pays only the per-tx fee.
+    """
     total_cents = round(ctx.pricing.amount_usd * 100)
-    result = create_multichain_payment_intent(
+    result = await mint_multichain_recipients(
+        authorization_header=ctx.request.headers.get("authorization"),
+        amount_cents=total_cents,
         stripe=stripe_client,
-        amount=total_cents,
+        pi_cache=pi_cache,
         networks=["tempo", "base", "solana"],
     )
-    for addr in result.deposit_addresses.values():
-        await pi_cache.cache_address(addr)
-        pi_cache.cache_payment_intent(addr, result.payment_intent_id)
-    pi_cache.cache_network_addresses(result.payment_intent_id, result.deposit_addresses)
-    return {
-        "tempo": result.deposit_addresses["tempo"],
-        "x402_base": result.deposit_addresses["base"],
-        "solana_mpp": result.deposit_addresses["solana"],
-    }
+    out: dict[str, str] = {}
+    if "tempo" in result.recipients:
+        out["tempo"] = result.recipients["tempo"]
+    if "base" in result.recipients:
+        out["x402_base"] = result.recipients["base"]
+    if "solana" in result.recipients:
+        out["solana_mpp"] = result.recipients["solana"]
+    return out
 
 
 async def _on_settled(ctx: Any, outcome: SettleOutcome) -> dict[str, Any]:

{agentscore_commerce-2.2.0 → agentscore_commerce-2.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agentscore-commerce"
-version = "2.2.0"
+version = "2.3.0"
 description = "Agent commerce SDK for Python — identity middleware (FastAPI, Flask, Django, AIOHTTP, Sanic, ASGI) + payment helpers + 402 builders + discovery + Stripe multichain. The full merchant-side toolkit for AgentScore-powered agent commerce."
 readme = "README.md"
 license = "MIT"

{agentscore_commerce-2.2.0 → agentscore_commerce-2.3.0}/tests/test_pay_to_address.py

@@ -9,7 +9,9 @@ from unittest.mock import patch
 import pytest
 
 from agentscore_commerce.stripe_multichain.pay_to_address import (
+    MintMultichainRecipientsResult,
     create_pay_to_address_from_stripe_pi,
+    mint_multichain_recipients,
 )
 
 
@@ -196,3 +198,121 @@ async def test_mints_fresh_when_credential_method_is_stripe() -> None:
             pi_cache=cache,  # type: ignore[arg-type]
         )
     assert result == "0xFRESH"
+
+
+# ---------------------------------------------------------------------------
+# static_recipients + mint_multichain_recipients
+# ---------------------------------------------------------------------------
+
+
+class _StripeRecordingNetworks:
+    """Stripe stub that records which networks were requested on PI creation.
+
+    Lets us assert that ``static_recipients``-covered networks are excluded
+    from the underlying ``create_multichain_payment_intent`` call.
+    """
+
+    def __init__(self, addresses: dict[str, str]) -> None:
+        self.payment_intents = self
+        self._addresses = addresses
+        self.last_networks: list[str] | None = None
+        self.last_idempotency_key: str | None = None
+
+    def create(self, params: dict[str, Any], idempotency_key: str | None = None) -> Any:
+        self.last_networks = list(params["payment_method_options"]["crypto"]["deposit_options"]["networks"])
+        self.last_idempotency_key = idempotency_key
+        deposits = {n: {"address": a} for n, a in self._addresses.items()}
+
+        class _PI:
+            id = "pi_test_456"
+            next_action = {"crypto_display_details": {"deposit_addresses": deposits}}
+
+        return _PI()
+
+
+@pytest.mark.asyncio
+async def test_static_recipients_excluded_from_stripe_pi_networks() -> None:
+    cache = FakePiCache()
+    stripe = _StripeRecordingNetworks({"tempo": "0xTEMPO", "base": "0xBASE"})
+    await create_pay_to_address_from_stripe_pi(
+        authorization_header=None,
+        amount_cents=100,
+        stripe=stripe,  # type: ignore[arg-type]
+        pi_cache=cache,  # type: ignore[arg-type]
+        static_recipients={"solana": "STATIC123"},
+    )
+    assert stripe.last_networks == ["tempo", "base"]
+
+
+@pytest.mark.asyncio
+async def test_static_recipients_registered_in_cache_and_merged_map() -> None:
+    cache = FakePiCache()
+    stripe = _fake_stripe({"tempo": "0xTEMPO", "base": "0xBASE"})
+    await create_pay_to_address_from_stripe_pi(
+        authorization_header=None,
+        amount_cents=100,
+        stripe=stripe,
+        pi_cache=cache,  # type: ignore[arg-type]
+        static_recipients={"solana": "STATIC123"},
+    )
+    assert "STATIC123" in cache.cached_addresses
+    assert cache.cached_network_addresses == [
+        ("pi_test_123", {"tempo": "0xTEMPO", "base": "0xBASE", "solana": "STATIC123"}),
+    ]
+
+
+@pytest.mark.asyncio
+async def test_settle_leg_accepts_static_recipient_without_cache_check() -> None:
+    """A bound recipient that matches static_recipients is always accepted,
+    even if the local PI cache wouldn't know about it (e.g. cold start).
+    """
+    cache = FakePiCache(has_address_result=False)
+    with patch("mpp.Credential", FakeCredential):
+        result = await create_pay_to_address_from_stripe_pi(
+            authorization_header="Payment solana:STATIC123",
+            amount_cents=100,
+            stripe=_fake_stripe({}),
+            pi_cache=cache,  # type: ignore[arg-type]
+            static_recipients={"solana": "STATIC123"},
+        )
+    assert result == "STATIC123"
+    assert cache.cached_addresses == []
+
+
+@pytest.mark.asyncio
+async def test_settle_leg_rejects_attacker_recipient_when_static_configured() -> None:
+    """Attacker forges a credential bound to a different solana address;
+    static_recipients match check fails, then the cache check fails, then
+    the SDK raises invalid_credential.
+    """
+    from agentscore_commerce.errors import CheckoutValidationError
+
+    cache = FakePiCache(has_address_result=False)
+    with (
+        patch("mpp.Credential", FakeCredential),
+        pytest.raises(CheckoutValidationError) as exc,
+    ):
+        await create_pay_to_address_from_stripe_pi(
+            authorization_header="Payment solana:ATTACKER456",
+            amount_cents=100,
+            stripe=_fake_stripe({}),
+            pi_cache=cache,  # type: ignore[arg-type]
+            static_recipients={"solana": "STATIC123"},
+        )
+    assert exc.value.code == "invalid_credential"
+
+
+@pytest.mark.asyncio
+async def test_mint_multichain_recipients_returns_full_merged_map() -> None:
+    cache = FakePiCache()
+    stripe = _fake_stripe({"tempo": "0xTEMPO", "base": "0xBASE"})
+    out = await mint_multichain_recipients(
+        authorization_header=None,
+        amount_cents=100,
+        stripe=stripe,
+        pi_cache=cache,  # type: ignore[arg-type]
+        static_recipients={"solana": "STATIC123"},
+    )
+    assert isinstance(out, MintMultichainRecipientsResult)
+    assert out.recipients == {"tempo": "0xTEMPO", "base": "0xBASE", "solana": "STATIC123"}
+    assert out.reused_from_credential is False