💧 Spraay x402 Gateway Now Accepts Solana USDC — Dual-Chain AI Agent Payments Are Live

tator, routes: [oracleRouteConfig] });

// Express middleware integration gateway.applyMiddleware(app);

// The gateway now automatically returns a 402 challenge with dual accepts // when a request hits /v1/data/oracle without payment.

**Rationale:**
*   **Declarative Configuration:** Defining routes as data structures simplifies maintenance and allows dynamic updates without code changes.
*   **Scheme Abstraction:** Using `EvmExactScheme` and `SvmExactScheme` encapsulates chain-specific verification logic, keeping the core gateway code chain-agnostic.
*   **Middleware Pattern:** Integrating as middleware allows the payment logic to sit cleanly between the router and the business logic handler, ensuring that only paid requests reach the application code.

#### Payment Flow

1.  **Challenge:** The agent requests `/v1/data/oracle`. The gateway returns a `402 Payment Required` response with a JSON body containing an `accepts` array listing both Base and Solana options.
2.  **Selection:** The agent inspects its wallet balances and selects the chain where it holds USDC.
3.  **Authorization:** The agent signs a transaction on the selected chain and includes the signed payload in the `X-PAYMENT` header of a retry request.
4.  **Verification:** The gateway forwards the payment proof to the Coinbase CDP facilitator. The facilitator verifies the transaction on-chain and confirms settlement.
5.  **Access:** Upon successful verification, the gateway returns a `200 OK` response with the requested data.

### Pitfall Guide

Implementing multi-rail payments introduces specific technical challenges. The following pitfalls and best practices are derived from production deployments.

1.  **Pitfall: Replay Attacks on Fallback Headers**
    *   **Explanation:** When using custom headers like `X-Solana-Tx` for non-x402 agents, malicious actors may replay a valid transaction signature to access the endpoint multiple times.
    *   **Fix:** Implement a nonce or memo validation mechanism. Require agents to include a unique nonce in the transaction memo, and track used nonces in a short-lived cache to prevent reuse.

2.  **Pitfall: Facilitator Latency Spikes**
    *   **Explanation:** Relying on an external facilitator introduces a dependency. If the facilitator experiences latency, gateway response times degrade, potentially causing agent timeouts.
    *   **Fix:** Implement circuit breakers and timeout handling. If the facilitator is slow, queue the verification asynchronously and return a `402` with a `retry-after` header, or use a local verification cache for recently confirmed transactions.

3.  **Pitfall: Price Drift and Configuration Mismatch**
    *   **Explanation:** If the price defined in the route configuration differs from the price in the discovery endpoints, agents may refuse to pay or overpay.
    *   **Fix:** Centralize pricing configuration. Use a single source of truth for route prices and automatically generate discovery JSON files from this configuration to ensure consistency.

4.  **Pitfall: Insufficient Gas Estimation for EVM**
    *   **Explanation:** Agents may fail to settle payments if they underestimate gas costs, leading to failed transactions and wasted fees.
    *   **Fix:** While x402 handles exact payments, ensure the gateway documentation provides clear gas estimation guidelines for agents. For Base, gas is sub-cent, but agents should still account for it in their budgeting.

5.  **Pitfall: Agent Wallet Key Management**
    *   **Explanation:** Agents require secure key management to sign transactions. Storing private keys in plain text or environment variables is insecure.
    *   **Fix:** Recommend or integrate with secure wallet solutions such as smart contract wallets, MPC (Multi-Party Computation) wallets, or hardware security modules (HSMs) for agent key management.

6.  **Pitfall: Chain ID Formatting Errors**
    *   **Explanation:** Using incorrect chain IDs in the `accepts` payload can cause agents to reject the payment options.
    *   **Fix:** Strictly adhere to CAIP-2 standards for chain IDs. Use `eip155:8453` for Base and `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp` for Solana mainnet. Validate chain IDs against a registry during initialization.

7.  **Pitfall: Ignoring Solana Finality Differences**
    *   **Explanation:** Solana offers faster finality (~400ms) compared to some EVM chains, but confirmation levels vary. Assuming instant finality without verification can lead to double-spending risks.
    *   **Fix:** Configure the facilitator to wait for the appropriate confirmation level. For micro-transactions, the Coinbase CDP facilitator handles this automatically, but custom implementations should enforce finality checks.

### Production Bundle

#### Action Checklist

- [ ] **Define Multi-Rail Accepts:** Configure each route to include payment options for all supported chains, ensuring prices and payee addresses are accurate.
- [ ] **Integrate Coinbase CDP:** Set up the Coinbase CDP facilitator with API keys and configure it for both EVM and SVM verification.
- [ ] **Implement Fallback Handler:** Add middleware to parse custom payment headers (e.g., `X-Solana-Tx`) and verify transactions for non-x402 agents.
- [ ] **Generate Discovery Endpoints:** Create `/.well-known/x402.json` and `/.well-known/solana.json` files that reflect the current route configuration and pricing.
- [ ] **Test with x402 Clients:** Validate the payment flow using tools like `pay.sh` and `xpay` to ensure agents can successfully negotiate and settle payments.
- [ ] **Monitor Facilitator Health:** Set up alerts for facilitator latency and error rates to detect issues before they impact agent operations.
- [ ] **Secure Agent Wallets:** Audit key management practices for agents accessing the gateway, ensuring private keys are stored securely.

#### Decision Matrix

| Scenario | Recommended Approach | Why | Cost Impact |
| :--- | :--- | :--- | :--- |
| **High-Volume Micro-Transactions** | Multi-Rail x402 | Enables agents to pay with existing liquidity, minimizing bridging costs and latency. | Low (Sub-cent fees) |
| **Legacy Agent Integration** | Custom Header Fallback | Allows agents without x402 support to pay via direct USDC transfers. | Medium (Verification overhead) |
| **Cross-Chain Arbitrage** | Single-Chain Gateway | Simplifies settlement when agents are expected to bridge funds intentionally. | High (Bridge fees for agents) |
| **Enterprise API Access** | MPP/Stripe via x402 | Supports fiat payments alongside crypto for enterprise clients. | Variable (Stripe fees) |

#### Configuration Template

Use this template to configure a multi-rail x402 gateway. Adjust the `routes` array to match your API endpoints and pricing.

```json
{
  "gateway": {
    "facilitator": "coinbase-cdp",
    "routes": [
      {
        "path": "/v1/inference",
        "price": "0.005",
        "currency": "USDC",
        "options": [
          {
            "chainId": "eip155:8453",
            "payee": "0xYourEvmPayeeAddress",
            "scheme": "exact"
          },
          {
            "chainId": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
            "payee": "YourSolanaPayeeAddress",
            "scheme": "exact"
          }
        ]
      }
    ],
    "discovery": {
      "x402": "/.well-known/x402.json",
      "solana": "/.well-known/solana.json",
      "mpp": "/.well-known/mpp.json"
    }
  }
}

Quick Start Guide

1. Install Dependencies: Add @x402/orchestrator, @x402/evm, @x402/svm, and @x402/facilitators to your project.
2. Initialize Facilitator: Create a Coinbase CDP facilitator instance with your API credentials.
3. Define Routes: Configure your API routes with multi-chain payment options using the RouteConfig structure.
4. Deploy Gateway: Start the gateway server and verify that /.well-known/x402.json returns the correct payment configuration.
5. Test Payment Flow: Use pay.sh or a custom x402 client to request an endpoint and complete the payment on either Base or Solana.