Getting Started

This guide will help you get started with Shade402, whether you're building an API that requires payments or creating a client that consumes paid APIs.

Prerequisites

Before you begin, ensure you have:

• Node.js 18.0.0 or higher

• pnpm 8.0.0 or higher (or npm/yarn)

• A Solana wallet (for testing, you can generate one)

• Access to a Solana RPC endpoint (devnet for testing, mainnet for production)

Installation

Install Shade402 packages using your preferred package manager:

# For API providers (server-side)
pnpm add @shade402/express @shade402/core

# For API consumers (client-side)
pnpm add @shade402/client @shade402/core

# For AI agent integrations
pnpm add @shade402/langchain @shade402/langgraph

Quick Start: API Provider

Create a simple Express.js server that requires payment for an endpoint.

Step 1: Install Dependencies

pnpm add express @shade402/express @shade402/core
pnpm add -D @types/express typescript

Step 2: Create Server

Create a file server.ts:

import express from 'express';
import { initX402, paymentRequired, x402ErrorMiddleware } from '@shade402/express';

const app = express();
app.use(express.json());

// Initialize X402 configuration
initX402({
  paymentAddress: process.env.PAYMENT_WALLET_ADDRESS!,
  tokenMint: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', // USDC devnet
  network: 'solana-devnet',
  rpcUrl: process.env.SOLANA_RPC_URL,
  defaultAmount: '0.01',
  paymentTimeout: 300,
  autoVerify: true,
});

// Public endpoint
app.get('/', (req, res) => {
  res.json({ message: 'Welcome to X402 API' });
});

// Protected endpoint
app.get('/api/premium-data',
  paymentRequired({
    amount: '0.01',
    description: 'Premium data access',
  }),
  (req, res) => {
    res.json({
      data: 'This is premium content',
      paymentId: req.payment?.paymentId,
    });
  }
);

// Error handling
app.use(x402ErrorMiddleware());

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

Step 3: Set Environment Variables

Create a .env file:

PAYMENT_WALLET_ADDRESS=YourSolanaWalletAddress
SOLANA_RPC_URL=https://api.devnet.solana.com
PORT=3000

Step 4: Run the Server

ts-node server.ts

Quick Start: API Consumer

Create a client that automatically pays for API access.

Step 1: Install Dependencies

pnpm add @shade402/client @shade402/core @solana/web3.js

Step 2: Create Client

Create a file client.ts:

import { X402AutoClient } from '@shade402/client';
import { Keypair } from '@solana/web3.js';

async function main() {
  // Load or generate a wallet
  const wallet = Keypair.generate(); // In production, load from secure storage
  
  // Create client with automatic payment handling
  const client = new X402AutoClient(wallet, process.env.SOLANA_RPC_URL, {
    maxPaymentAmount: '1.0', // Safety limit
    autoRetry: true,
  });

  try {
    // Make request - payment is handled automatically
    const response = await client.get('http://localhost:3000/api/premium-data');
    console.log('Response:', response.data);
  } catch (error) {
    console.error('Error:', error);
  } finally {
    // Always close the client to cleanup connections
    await client.close();
  }
}

main();

Step 3: Set Environment Variables

SOLANA_RPC_URL=https://api.devnet.solana.com

Step 4: Run the Client

ts-node client.ts

Testing with Devnet

For testing, use Solana devnet:

1. Get devnet SOL from the faucet: https://faucet.solana.com

2. Get devnet USDC tokens (if needed)

3. Use devnet RPC: https://api.devnet.solana.com

Production Setup

For production:

1. Use mainnet RPC endpoint (consider using a provider like Helius, QuickNode, or Alchemy)

2. Use real USDC token mint: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v

3. Set network: 'solana-mainnet'

4. Store wallet private keys securely (environment variables, key management service)

5. Enable auto-verification for payment security

6. Monitor payment transactions and set up alerts

Next Steps

• Learn about Core Concepts

• Explore Express Integration for servers

• Check out Client Usage for clients

• See Examples for more complex use cases