Skip to main content
Prerequisites: - Node.js version 18 or higher - A Solana wallet (Phantom, Solflare, or Backpack) - Basic understanding of TypeScript/JavaScript
Get your local development environment ready for building with CheapPay and testing Solana payments.
1

Clone the CheapPay repository

git clone https://github.com/cheapay/x402-solana
cd x402-solana
2

Install dependencies

CheapPay uses pnpm for workspace management:
npm install -g pnpm
pnpm install
3

Set up environment variables

Create a .env file in your project root:
# Solana network configuration
SOLANA_NETWORK=solana-devnet
SOLANA_RPC_URL=https://api.devnet.solana.com

# Your wallet address (for receiving test payments)
PAYMENT_RECIPIENT=YourSolanaWalletAddressHere

# Optional: Custom facilitator URL for development
FACILITATOR_URL=http://localhost:3011
4

Get devnet tokens

For testing, you’ll need devnet SOL and USDC:
# Get devnet SOL
solana airdrop 2 YourWalletAddress --url devnet

# Get devnet USDC tokens at:
# https://spl-token-faucet.com/?token-name=USDC-Dev

​
Running examples locally

CheapPay includes several working examples you can run immediately: 
cd examples/typescript/servers/express
npm install
npm start
Test your payment-enabled API at http://localhost:3001/api/premium
bash cd examples/typescript/fullstack/next npm install npm run dev Visit http://localhost:3000 to see the complete payment flow
cd typescript/packages/x402-facilitator
npm install
npm run dev
Runs the payment verification service at http://localhost:3011

​
Testing payments

​
Devnet testing workflow

1

Start your development server

Run any of the example applications above.
2

Navigate to a protected endpoint

Try accessing a payment-protected route in your browser.
3

Connect your wallet

Use a Solana wallet with devnet enabled (Phantom recommended).
4

Complete the test payment

Pay with fake devnet USDC - no real money involved!

​
Testing different scenarios

// Test different price points
const routes = {
  '/api/cheap': { price: '$0.001', network: 'solana-devnet' },
  '/api/premium': { price: '$0.01', network: 'solana-devnet' },
  '/api/expensive': { price: '$0.10', network: 'solana-devnet' },
};

// Test different tokens
import { TokenMint } from '@cheapay/x402';

const usdcRoute = { mint: TokenMint.USDC.devnet };
const solRoute = {}; // No mint = native SOL payments

​
Development tools

​
Debugging payments

Enable debug logging to trace payment flows: 
DEBUG=cheapay:* npm start

​
Wallet connections

Test with multiple wallets to ensure compatibility:
  • Phantom: Most popular Solana wallet
  • Solflare: Web and mobile support
  • Backpack: Developer-friendly wallet
  • Coin98: Multi-chain support

​
Network switching

Test across different Solana networks: 
const networks = {
  development: 'solana-devnet',
  staging: 'solana-testnet',
  production: 'solana-mainnet',
};

​
Contributing to CheapPay

​
Development workflow

1

Fork and clone

Fork the repository and create a feature branch:
git checkout -b feature/your-feature-name
2

Make your changes

Follow our coding standards: - Use TypeScript for type safety - Add tests for new features - Update documentation
3

Test thoroughly

# Run unit tests
pnpm test

# Run integration tests with devnet

pnpm test:integration

# Test across all packages

pnpm test:all
4

Submit a pull request

Include a clear description of your changes and test results.

​
Code formatting

We use Prettier and ESLint for consistent code style: 
# Auto-format your code
pnpm format

# Check for linting issues
pnpm lint

# Fix auto-fixable issues
pnpm lint:fix

​
Troubleshooting

Solutions:
  1. Ensure your wallet is set to Solana devnet
  2. Check that you have sufficient SOL for transaction fees
  3. Try refreshing the page and reconnecting
  4. Clear browser cache and wallet cache
Common causes: 1. Insufficient devnet USDC balance 2. Network connectivity issues 3. RPC rate limiting Solutions: - Get more devnet tokens from the faucet - Switch to a different RPC endpoint - Wait a few seconds and retry
Solutions:
  1. Increase timeout settings in your configuration
  2. Check Solana network status
  3. Use a more reliable RPC endpoint
const config = {
  maxTimeoutSeconds: 120, // Increase timeout
  retryAttempts: 3
};

​
Performance optimization

​
RPC endpoint selection

Use reliable RPC providers for better performance: 
const rpcEndpoints = {
  'solana-devnet': [
    'https://api.devnet.solana.com',
    'https://solana-devnet.g.alchemy.com/v2/your-key',
    'https://rpc.ankr.com/solana_devnet',
  ],
};

​
Caching strategies

Implement caching for better user experience: 
// Cache successful payments
const paymentCache = new Map();

// Cache wallet connections
const walletCache = {
  lastConnected: null,
  autoReconnect: true,
};

​
Next steps

Build your first API

Create a payment-enabled Express API from scratch.

Integration guide

Learn about different framework integrations.

Production deployment

Deploy your payment-enabled API to production.

Join our community

Connect with us on all platforms via our Linktree.

Telegram Community

Get help from developers and the CheapPay team.
Ready to start building? Check out our examples repository for complete working implementations.
⌘I