docs(commerce): gate-conditional pattern in examples + README + CLAUDE

Mirror the node-commerce gate-conditional pattern in Python so merchants
supporting non-AgentScore x402 wallets (Coinbase awal, Phantom, Solflare,
...) can return a real 402 challenge from anonymous discovery without an
AgentScore credential. Identity verification fires on the retry leg when
X-Payment / Authorization: Payment arrives.

Updated:
  - examples/multi_rail_merchant.py: AgentScoreGate wrapped in `gate_on_settle` async dependency, used via `Depends(gate_on_settle)`
  - examples/compliance_merchant.py: same wrap with full `on_denied` branching preserved at settle
  - README.md: FastAPI quickstart shows the conditional wrap
  - CLAUDE.md: new "Mount posture: gate-first vs gate-conditional" section, notes the same wrap applies identically across all 6 framework adapters (fastapi, flask, django, aiohttp, sanic, middleware/ASGI)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: vvillait88

CLAUDE.md

@@ -39,6 +39,29 @@ Two identity types: wallet (`X-Wallet-Address`) and operator-token (`X-Operator-
 
 Captured wallets: `capture_wallet(...)` is fire-and-forget — reads `operator_token` stashed during gating and POSTs to `/v1/credentials/wallets`. No-ops for wallet-authenticated requests.
 
+### Mount posture: gate-first vs gate-conditional
+
+`AgentScoreGate(...)` (or `agentscore_gate(app, ...)` on Flask/Sanic) is mounted directly when the route is AgentScore-only — every request runs identity + policy. To support **anonymous discovery by any spec-compliant x402 wallet** (Coinbase awal, Phantom, Solflare, …), wrap the gate so it fires only when a payment credential is attached:
+
+```python
+_gate = AgentScoreGate(api_key=..., require_kyc=True, ...)
+
+async def gate_on_settle(request: Request) -> None:
+    has_payment_header = bool(
+        request.headers.get("payment-signature")
+        or request.headers.get("x-payment")
+        or (request.headers.get("authorization") or "").startswith("Payment ")
+    )
+    if not has_payment_header:
+        return None
+    return await _gate(request)
+
+@app.post("/purchase", dependencies=[Depends(gate_on_settle)])
+async def purchase(...): ...
+```
+
+Anonymous POST flows through to the handler unauthenticated and gets a 402 with all rails + per-order pricing. Identity is verified at settle time on the retry leg (when the agent submits `X-Payment` / `Authorization: Payment`); `create_session_on_missing` still auto-mints a verification session there. The same wrap pattern works identically across all 6 framework adapters (fastapi, flask, django, aiohttp, sanic, middleware/ASGI). See `examples/multi_rail_merchant.py` and `examples/compliance_merchant.py`.
+
 ## Tooling
 
 - **uv** — package manager.

README.md

@@ -35,14 +35,30 @@ from agentscore_commerce.identity.fastapi import (
 )
 
 app = FastAPI()
-gate = AgentScoreGate(
+_gate = AgentScoreGate(
     api_key="as_live_...",
     require_kyc=True,
     min_age=21,
     allowed_jurisdictions=["US"],
 )
 
-@app.post("/purchase", dependencies=[Depends(gate)])
+
+# Run the gate CONDITIONALLY — only when a payment credential is already attached.
+# Anonymous discovery (no payment header) flows through to the handler so any spec-
+# compliant x402 wallet can read the 402 challenge with rails + pricing without first
+# proving identity. Identity is verified at settle time on the retry leg.
+async def gate_on_settle(request: Request) -> None:
+    has_payment_header = bool(
+        request.headers.get("payment-signature")
+        or request.headers.get("x-payment")
+        or (request.headers.get("authorization") or "").startswith("Payment ")
+    )
+    if not has_payment_header:
+        return None
+    return await _gate(request)
+
+
+@app.post("/purchase", dependencies=[Depends(gate_on_settle)])
 async def purchase(request: Request, assess=Depends(get_assess_data)):
     # ... settle payment ...
     # After payment, capture the signer wallet for cross-merchant attribution

examples/compliance_merchant.py

@@ -100,7 +100,7 @@ def _on_denied(_request: Request, reason: DenialReason) -> tuple[dict[str, Any],
 
 
 app = FastAPI()
-gate = AgentScoreGate(
+_gate = AgentScoreGate(
     api_key=os.environ["AGENTSCORE_API_KEY"],
     require_kyc=True,
     require_sanctions_clear=True,
@@ -110,7 +110,22 @@ def _on_denied(_request: Request, reason: DenialReason) -> tuple[dict[str, Any],
 )
 
 
-@app.post("/buy", dependencies=[Depends(gate)])
+# Conditional gate. Fires only when a payment credential is already attached so
+# anonymous discovery returns a 402 challenge (not a 403 missing_identity). Compliance
+# gating + signer-match still run on the retry leg when X-Payment / Authorization:
+# Payment arrives — the full denial branching above triggers there.
+async def gate_on_settle(request: Request) -> None:
+    has_payment_header = bool(
+        request.headers.get("payment-signature")
+        or request.headers.get("x-payment")
+        or (request.headers.get("authorization") or "").startswith("Payment ")
+    )
+    if not has_payment_header:
+        return None
+    return await _gate(request)
+
+
+@app.post("/buy", dependencies=[Depends(gate_on_settle)])
 async def buy(request: Request, assess: dict = Depends(get_assess_data)):
     # Wallet-auth: verify the payment signer matches the claimed wallet (or a same-operator
     # linked wallet). No-ops for operator_token requests. Pass `signer=` from your real x402/MPP

examples/multi_rail_merchant.py

@@ -93,20 +93,38 @@
 pi_cache = create_pi_cache(PiCacheOptions(redis_url=os.environ.get("REDIS_URL")))
 
 app = FastAPI()
-gate = AgentScoreGate(
+_gate = AgentScoreGate(
     api_key=os.environ["AGENTSCORE_API_KEY"],
     require_kyc=True,
     require_sanctions_clear=True,
     min_age=21,
     allowed_jurisdictions=["US"],
 )
 
+
+# Conditional gate: fires only when a payment credential is already attached. Anonymous
+# requests (no payment header) fall through to the handler unauthenticated and receive
+# a clean 402 with all rails advertised — so any spec-compliant x402 wallet (Coinbase
+# awal, Phantom, Solflare, etc.) can discover prices before AgentScore identity exists.
+# Identity is verified at settle time (when X-Payment / Authorization: Payment arrives),
+# and `create_session_on_missing` then auto-mints a verification session.
+async def gate_on_settle(request: Request) -> None:
+    has_payment_header = bool(
+        request.headers.get("payment-signature")
+        or request.headers.get("x-payment")
+        or (request.headers.get("authorization") or "").startswith("Payment ")
+    )
+    if not has_payment_header:
+        return None
+    return await _gate(request)
+
+
 # Vendor-instantiated x402 server + pympp server are stubs in this example —
 # replace with your `create_x402_server(...)` + `create_mppx_server(...)` setup.
 x402_server: object = ...  # type: ignore[assignment]
 
 
-@app.post("/purchase", dependencies=[Depends(gate)])
+@app.post("/purchase", dependencies=[Depends(gate_on_settle)])
 async def purchase(request: Request, assess: dict = Depends(get_assess_data)):
     body = await request.json()