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

parate verification nodes or manage distinct settlement logic. The facilitator handles signature validation and on-chain confirmation for both chains. 2. Route-Level Payment Definitions: Each API route defines its price and the chains it accepts. This allows granular control; some routes might accept only Base, while others accept both. 3. Fallback Header Support: Implement a custom header fallback (e.g., X-Solana-Tx) for agents that do not support the x402 protocol natively. This ensures backward compatibility while maintaining the benefits of on-chain verification. 4. Discovery Endpoints: Expose /.well-known JSON files to allow agents to auto-discover payment capabilities, pricing, and chain configurations without hardcoding gateway details.

Implementation Example

The following TypeScript example demonstrates a PaymentOrchestrator class that registers routes with multiple payment options. This implementation abstracts the x402 protocol details into a declarative configuration.

import { PaymentOrchestrator, RouteConfig, PaymentOption } from '@x402/orchestrator';
import { CoinbaseFacilitator } from '@x402/facilitators';
import { EvmExactScheme } from '@x402/evm';
import { SvmExactScheme } from '@x402/svm';

// Initialize the facilitator for cross-chain verification
const facilitator = new CoinbaseFacilitator({
  apiKey: process.env.CDP_API_KEY,
  environment: 'production'
});

// Define payment options for a specific route
const oracleRouteConfig: RouteConfig = {
  path: '/v1/data/oracle',
  price: '0.008',
  currency: 'USDC',
  options: [
    {
      chainId: 'eip155:8453',
      payee: '0x7a2B8c9D1e3F5A6b4C8d7E9f0A1b2C3d4E5f6a7b',
      scheme: new EvmExactScheme()
    },
    {
      chainId: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
      payee: '9WhWE8YgY5QBWyLowEHuaZiWdwDM3SrgDk36xYBNvYNS',
      scheme: new SvmExactScheme()
    }
  ]
};

// Create the orchestrator and register routes
const gateway = new PaymentOrchestrator({
  facilitator,
  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.

{
  "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.