Welcome

Shade402 is a collection of TypeScript libraries for implementing the X402 payment protocol on Solana. X402 enables HTTP 402 Payment Required responses, allowing API providers to request payments for access to their services. This makes it ideal for autonomous AI agents that need to pay for API access automatically.

What is X402?

X402 is a payment protocol that extends HTTP with payment capabilities. When a server requires payment for a resource, it returns a 402 Payment Required status code along with a payment request. Clients can then fulfill the payment and retry the request with proof of payment.

Key Features

  • HTTP 402 Payment Required: Standard HTTP status code for payment requests

  • Solana Blockchain Integration: Native support for Solana and SPL tokens

  • Autonomous AI Agent Support: Built for AI agents that need to make payments automatically

  • TypeScript First: Full TypeScript support with comprehensive type definitions

  • Framework Integrations: Ready-to-use middleware for Express.js and Next.js

  • AI Framework Support: Integrations for LangChain and LangGraph

  • Resource Encryption: Optional RSA encryption for resource field privacy

  • Automatic Payment Verification: On-chain verification of Solana transactions

  • Flexible Client Modes: Both explicit (manual) and automatic payment handling

Use Cases

API Monetization

Charge users for access to premium API endpoints. Perfect for:

  • AI model APIs

  • Data APIs

  • Compute services

  • Webhook endpoints

Autonomous AI Agents

Enable AI agents to autonomously pay for API access:

  • LangChain agents with payment tools

  • LangGraph workflows with payment nodes

  • Custom AI agent implementations

Micro-payments

Process small payments efficiently on Solana:

  • Per-request payments

  • Per-API-call charges

  • Usage-based billing

Architecture Overview

Shade402 is organized as a monorepo with multiple packages:

  • @shade402/core: Core payment protocol models, schemas, and Solana integration

  • @shade402/client: HTTP clients for making X402 requests (explicit and automatic)

  • @shade402/express: Express.js middleware for implementing payment-protected endpoints

  • @shade402/nextjs: Next.js middleware and utilities for payment-protected routes

  • @shade402/langchain: LangChain.js integration with payment tools

  • @shade402/langgraph: LangGraph.js integration with payment nodes

Quick Start

For API Providers (Server-side)

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

const app = express();

initX402({
  paymentAddress: process.env.PAYMENT_WALLET_ADDRESS!,
  tokenMint: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', // USDC
  network: 'solana-devnet',
  autoVerify: true,
});

app.get('/api/premium-data',
  paymentRequired({ amount: '0.01', description: 'Premium data access' }),
  (req, res) => {
    res.json({ data: 'Your premium data here' });
  }
);

For API Consumers (Client-side)

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

const wallet = Keypair.generate();
const client = new X402AutoClient(wallet);

const response = await client.get('https://api.example.com/premium-data');
const data = response.data;

await client.close();

Requirements

  • Node.js >= 18.0.0

  • pnpm >= 8.0.0 (or npm/yarn)

  • TypeScript >= 5.3.0 (for TypeScript projects)

Installation

Install the packages you need:

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

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

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

Next Steps

NextGetting Started

Last updated