feat(x402): Integrated payai facilitator

README.md

@@ -14,6 +14,8 @@ The API surface remains focused on BCH infrastructure (BCH full node, Fulcrum, a
 - Pricing is configured in `X402_PRICE_USDC` (USDC amount), not BCH satoshis.
 - x402 network is configured using CAIP-2 format (for example `eip155:8453` for Base mainnet and `eip155:84532` for Base Sepolia).
 - Facilitator auth headers are generated using Coinbase CDP JWT auth (`FACILITATOR_KEY_ID` and `FACILITATOR_SECRET_KEY`) when using CDP endpoints.
+- Optional facilitators: **Dexter** (`PRIMARY_FACILITATOR=dexter`) and **PayAI** (`PRIMARY_FACILITATOR=payai`, default URL `https://facilitator.payai.network`, no API keys).
+- **Bazaar** discovery metadata on payment requirements via `@x402/extensions/bazaar`, and optional **multi-facilitator** mode (`ACTIVE_FACILITATORS=cdp,dexter,payai`) so clients can verify/settle through CDP, Dexter, or PayAI (`@x402/core` picks a matching facilitator).
 
 ## Architecture
 
@@ -85,7 +87,11 @@ All configuration is loaded from environment variables (typically from `.env`).
 - `SERVER_BASE_ADDRESS` (EVM address receiving x402 settlements)
 - `X402_PRICE_USDC` (USDC charged per request)
 - `x402_NETWORK` (CAIP-2 chain ID; e.g. `eip155:8453` or `eip155:84532`)
-- `x402_FACILITATOR_URL` (default: `https://api.cdp.coinbase.com/platform/v2/x402`)
+- `PRIMARY_FACILITATOR` (default: `cdp`) — one of `cdp`, `dexter`, or `payai`. Used for **single-facilitator** mode when `ACTIVE_FACILITATORS` is unset; selects the default facilitator base URL unless `x402_FACILITATOR_URL` is set.
+- `ACTIVE_FACILITATORS` — optional comma-separated list (e.g. `dexter,payai`). When set with multi-facilitator mode, the server registers **multiple** `HTTPFacilitatorClient` instances. **`PRIMARY_FACILITATOR` is always first** in that list (x402 gives earlier facilitators precedence); remaining names follow in the order listed, deduped. Each facilitator uses its default base URL (`x402_FACILITATOR_URL` applies only in **single-facilitator** mode).
+- `X402_BAZAAR_ENABLED` (default: `true`) — attach Bazaar **discovery** extension to protected route payment requirements (for facilitator catalogs). Set `false` to disable.
+- `x402_FACILITATOR_URL` — optional override for the facilitator HTTP base URL (must expose `/verify`, `/settle`, and `/supported` like the x402 reference facilitator). When unset, the URL is derived from `PRIMARY_FACILITATOR`. **Ignored per-facilitator when `ACTIVE_FACILITATORS` lists more than one entry** (each entry uses its provider URL).
+- `PAYAI_FACILITATOR_URL` — optional; when `PRIMARY_FACILITATOR=payai` and `x402_FACILITATOR_URL` is unset, defaults to `https://facilitator.payai.network`.
 - `FACILITATOR_KEY_ID` (required for CDP facilitator auth)
 - `FACILITATOR_SECRET_KEY` (required for CDP facilitator auth)
 
@@ -123,17 +129,30 @@ Authorization: Bearer my-secret-token
 
 ### 3) x402 Payments on Base (USDC)
 
+**Coinbase CDP facilitator**
+
 ```bash
 X402_ENABLED=true
 USE_BASIC_AUTH=false
 SERVER_BASE_ADDRESS=0xYourBaseAddress
 X402_PRICE_USDC=0.1
 x402_NETWORK=eip155:8453
-x402_FACILITATOR_URL=https://api.cdp.coinbase.com/platform/v2/x402
+PRIMARY_FACILITATOR=cdp
 FACILITATOR_KEY_ID=your_key_id
 FACILITATOR_SECRET_KEY=your_secret
 ```
 
+**PayAI facilitator** (no CDP keys; default URL `https://facilitator.payai.network`)
+
+```bash
+X402_ENABLED=true
+USE_BASIC_AUTH=false
+SERVER_BASE_ADDRESS=0xYourBaseAddress
+X402_PRICE_USDC=0.1
+x402_NETWORK=eip155:8453
+PRIMARY_FACILITATOR=payai
+```
+
 Protected endpoints return `402 Payment Required` when no valid payment is attached. x402-capable clients can pay and retry automatically.
 
 ### 4) x402 + Bearer Bypass