x402 CASH Facilitator

A forkable code sample for x402 facilitators to receive CASH payments on Solana.

This project includes:

• Facilitator service — Verifies and settles CASH payments on-chain
• Protected API server — Express server with endpoints gated behind x402 CASH payments

How it works

1. Client requests a protected endpoint on the server
2. Server responds with HTTP 402 and CASH payment requirements
3. Client signs a Solana transaction to transfer CASH and retries with a PAYMENT-SIGNATURE header
4. Server asks the facilitator to verify the payment
5. Facilitator settles the transaction on-chain
6. Server returns the protected resource

Prerequisites

• Node.js 20+
• A Solana wallet with SOL (for transaction fees)
• CASH tokens (mint: CASHx9KJUStyftLFWGvEVf59SGeG9sh5FfcnZMVPCASH)

Quick Start

# Clone the repo
git clone <your-fork-url>
cd x402-cash-facilitator

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env with your wallet keys and addresses

# Run both facilitator + server
npm run dev

Run individually

# Start the facilitator (port 4402)
npm run dev:facilitator

# Start the API server (port 3000)
npm run dev:server

Configuration

Copy .env.example to .env and fill in:

Variable	Description
SOLANA_RPC_URL	Solana RPC endpoint (default: devnet)
SOLANA_NETWORK	solana-devnet or solana for mainnet
FACILITATOR_PRIVATE_KEY	Base58 private key for the facilitator wallet (pays gas)
RESOURCE_WALLET_ADDRESS	Wallet address that receives CASH payments
FACILITATOR_PORT	Facilitator service port (default: 4402)
SERVER_PORT	API server port (default: 3000)
CASH_MINT	CASH token mint address
PAYMENT_AMOUNT	Price per request in atomic units (1000000 = 1 CASH)

API Endpoints

Server (port 3000)

Method	Path	Auth	Description
GET	/api/health	None	Health check
GET	/api/premium-data	CASH payment	Returns premium data after payment

Facilitator (port 4402)

Method	Path	Description
GET	/health	Health check
GET	/fee-payer	Returns the facilitator's fee payer address
POST	/verify	Verify a CASH payment transaction
POST	/settle	Settle a payment on-chain

Testing

# Check the server is running
curl http://localhost:3000/api/health

# Hit the protected endpoint (returns 402 with payment requirements)
curl -i http://localhost:3000/api/premium-data

To make a paid request, use an x402 client that handles the 402 flow automatically:

import { createX402Client } from "x402-solana";

const client = createX402Client({
  wallet: yourWalletAdapter,
  network: "solana-devnet",
});

const response = await client.fetch("http://localhost:3000/api/premium-data");
const data = await response.json();

Resources

• x402 Protocol
• x402-solana npm package
• Phantom CASH
• Solana x402 Guide
• Coinbase x402 Examples