# Welcome

<figure><img src="https://864708576-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnW3qNOO2raPKEFx67ShZ%2Fuploads%2FQA8wIYQDphOw6ntElUTI%2Fimage.png?alt=media&#x26;token=b679e57b-d952-4feb-99e3-1a931c933d8a" alt=""><figcaption></figcaption></figure>

\
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)

```typescript
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)

```typescript
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:

```bash
# 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

* [Getting Started](https://docs.shade402.xyz/getting-started) - Set up your first X402 payment flow
* [Core Concepts](https://docs.shade402.xyz/core-concepts) - Understand the X402 protocol
* [Express Integration](https://docs.shade402.xyz/server-side-integration/express-integration) - Implement payment-protected APIs
* [Client Usage](https://docs.shade402.xyz/client-side-usage/client-usage) - Make X402 requests from your applications
* [AI Agent Integration](https://docs.shade402.xyz/ai-agent-integration/ai-agent-integration) - Enable payments in AI workflows