@x402/core

x402OS

The first Solana-powered operating system where every action requires payment

Built on HTTP 402 principles for Web3

🌟 What is x402OS?

x402OS is a revolutionary operating system concept where every action has value and is directly paid through microtransactions on Solana. The name comes from HTTP 402 "Payment Required" — reimagined for Web3.

Instead of free API calls, every click, query, or command requires a verified Solana payment (typically 0.001–0.005 USDC). It's "Web3's version of API metering," running like a futuristic OS.

✨ Key Features

• ⚡ Pay-per-action model — Micropayments for every operation
• 🔗 Solana-native — Ultra-fast, low-fee blockchain payments
• 🎮 Built-in app suite — xPay, xAI, xVault, xFetch, xScan, and more
• 📊 XP & Leveling system — Gamified user experience
• 🔌 Extensible — Build your own x402 apps
• 🛡️ Type-safe — Full TypeScript support
• 📦 Zero config — Works out of the box

📦 Installation

npm install @x402/core @solana/web3.js

or

yarn add @x402/core @solana/web3.js

🚀 Quick Start

Basic Setup

import { createX402OS } from '@x402/core';

// Initialize x402OS
const x402 = createX402OS('https://api.mainnet-beta.solana.com');

// Start a user session
const session = await x402.startSession('YOUR_WALLET_ADDRESS');

// Execute an app (requires payment)
const result = await x402.executeApp(
  'xfetch',
  session.sessionId,
  { 
    action: 'fetch_json',
    url: 'https://api.example.com/data'
  },
  'TRANSACTION_SIGNATURE' // Solana payment proof
);

console.log(result);

Advanced Configuration

import { initializeX402OS } from '@x402/core';

const x402 = initializeX402OS({
  rpcEndpoint: 'https://api.mainnet-beta.solana.com',
  cluster: 'mainnet-beta',
  debug: true,
  protocolFee: 10, // 10% protocol fee
  defaultToken: 'USDC',
  openaiApiKey: 'your-openai-key', // For xAI
  birdeyeApiKey: 'your-birdeye-key', // For xScan
});

// Listen to events
x402.on('payment_confirmed', (event) => {
  console.log('Payment confirmed:', event.data);
});

x402.on('app_executed', (event) => {
  console.log('App executed:', event.data);
});

🎮 Built-in Apps

xPay — Instant Solana Payments

const payment = await x402.executeApp('xpay', sessionId, {
  action: 'create_payment',
  fromAddress: 'YOUR_ADDRESS',
  toAddress: 'RECIPIENT_ADDRESS',
  amount: 0.1, // SOL
}, txSignature);

xAI — AI Assistant

const aiResponse = await x402.executeApp('xai', sessionId, {
  action: 'chat',
  prompt: 'Explain Solana to me',
  maxTokens: 500,
}, txSignature);

console.log(aiResponse.response);

xFetch — Web Data Fetcher

const data = await x402.executeApp('xfetch', sessionId, {
  action: 'fetch_json',
  url: 'https://api.coingecko.com/api/v3/simple/price?ids=solana&vs_currencies=usd',
}, txSignature);

xVault — User Dashboard

// Check user stats (free)
const stats = await x402.executeApp('xvault', sessionId, {
  action: 'get_stats',
  walletAddress: 'YOUR_ADDRESS',
});

console.log(`Level: ${stats.level}, XP: ${stats.totalXP}`);

xScan — Token Analyzer

const tokenData = await x402.executeApp('xscan', sessionId, {
  action: 'analyze_token',
  tokenAddress: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', // USDC
}, txSignature);

console.log(`Price: $${tokenData.price}`);

💰 Pricing Model

| App | Price per Action | Description | | --------- | ---------------- | ---------------------------------- | | xPay | $0.001 USDC | Payment operations | | xAI | $0.005 USDC | AI responses | | xFetch| $0.002 USDC | Data fetching | | xScan | $0.003 USDC | Token/wallet analysis | | xVault| Free | View stats and history |

Protocol Fee: 10% of each transaction goes to x402OS treasury.

🔧 Advanced Usage

Building Custom Apps

import { X402App } from '@x402/core';

const myCustomApp: X402App = {
  id: 'my-app',
  name: 'My Custom App',
  description: 'Does something cool',
  pricePerUse: 0.002,
  version: '1.0.0',
  enabled: true,
  execute: async (params) => {
    // Your app logic here
    return { success: true, data: params };
  },
};

// Register your app
x402.registerApp(myCustomApp);

// Execute it
const result = await x402.executeApp('my-app', sessionId, {
  foo: 'bar',
}, txSignature);

Payment Verification

import { SolanaPaymentHandler } from '@x402/core';

const paymentHandler = new SolanaPaymentHandler(
  'https://api.mainnet-beta.solana.com'
);

// Verify a transaction
const verification = await paymentHandler.verifyTransaction(
  'YOUR_TX_SIGNATURE'
);

console.log(`Confirmed: ${verification.confirmed}`);
console.log(`Fee: ${verification.fee} lamports`);

Using API Integrations

import { X402APIClient } from '@x402/core';

const apiClient = new X402APIClient({
  birdeyeApiKey: 'your-key',
});

// Get token price from Birdeye
const price = await apiClient.birdeye?.getTokenPrice('TOKEN_ADDRESS');

// Get Jupiter quote
const quote = await apiClient.jupiter.getQuote(
  'INPUT_MINT',
  'OUTPUT_MINT',
  1000000
);

// Search pools on GeckoTerminal
const pools = await apiClient.geckoTerminal.searchPools('BONK', 'solana');

📊 Event System

x402OS emits events for all major actions:

x402.on('session_started', (event) => {
  console.log('Session started:', event.data);
});

x402.on('payment_initiated', (event) => {
  console.log('Payment initiated:', event.data);
});

x402.on('payment_confirmed', (event) => {
  console.log('Payment confirmed:', event.data);
});

x402.on('app_executed', (event) => {
  console.log('App executed:', event.data);
});

x402.on('xp_earned', (event) => {
  console.log('XP earned:', event.data);
});

🎯 Architecture

┌──────────────────────┐
│    User Wallet       │
└──────────┬───────────┘
           │ Connects
┌──────────▼───────────┐
│   x402OS Frontend    │ (Your App)
└──────────┬───────────┘
           │ Command sent
┌──────────▼───────────┐
│  XCoreController     │ (@x402/core)
└──────────┬───────────┘
           │ Verifies payment
┌──────────▼───────────┐
│ Solana Blockchain    │
└──────────┬───────────┘
           │ Confirmation
┌──────────▼───────────┐
│ App Executes + Logs  │
└──────────────────────┘

🛠️ API Reference

XCoreController

class XCoreController {
  registerApp(app: X402App): void;
  getApp(appId: string): X402App | undefined;
  listApps(): X402App[];
  startSession(walletAddress: string): Promise<X402Session>;
  executeApp(appId: string, sessionId: string, params: any, paymentSignature?: string): Promise<any>;
  endSession(sessionId: string): Promise<X402Session>;
  getSessionLogs(sessionId: string): AppExecutionLog[];
}

SolanaPaymentHandler

class SolanaPaymentHandler {
  getBalance(walletAddress: string): Promise<number>;
  createPaymentTransaction(from: string, to: string, amount: number): Promise<Transaction>;
  verifyTransaction(signature: string): Promise<PaymentResult>;
  waitForConfirmation(signature: string, timeout?: number): Promise<PaymentResult>;
}

🔐 Environment Variables

SOLANA_RPC_ENDPOINT=https://api.mainnet-beta.solana.com
OPENAI_API_KEY=your-openai-key
BIRDEYE_API_KEY=your-birdeye-key
PROTOCOL_FEE=10
DEBUG=false

🧪 Testing

npm test

📝 Examples

Check out the examples directory for:

• Basic usage
• Custom app development
• Payment integration
• Event handling
• Full app implementations

🌐 Links

• Website: https://x402os.com
• Twitter: @x402OS
• Discord: Join our community
• GitHub: x402/core

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details.

📄 License

MIT © x402OS Team

⚠️ Disclaimer

x402OS is experimental software. Use at your own risk. Always test on devnet before using on mainnet.

Built with ❤️ by the x402OS Team

"You don't download x402OS, you connect to it."