x402-community-devkit

⚠️ DISCLAIMER: This is an unofficial, community-built development toolkit for the x402 protocol. This project is NOT affiliated with, endorsed by, or officially supported by Coinbase or the official x402 team.

A community development toolkit for the x402 protocol. x402-community-devkit provides auto-generated wallets and a quick setup for building buyer and seller integrations on the Base Sepolia testnet.

It works as both:

• 📚 A TypeScript library - Import classes and utilities in your codebase (recommended)
• 🔧 A CLI tool - Scaffold projects and manage wallets from the command line

📦 Installation

# As a library dependency
npm install x402-community-devkit

# As a global CLI tool
npm install -g x402-community-devkit

📚 Library Usage (Recommended)

Basic Setup

import { X402DevKit } from "x402-community-devkit";

const devkit = new X402DevKit();
const wallet = await devkit.getWallet();
console.log("Wallet address:", wallet.address);

Check Balances

const balances = await devkit.getBalances();
console.log("ETH:", balances.eth);
console.log("USDC:", balances.usdc);

if (await devkit.needsFunding()) {
  await devkit.showFundingInstructions();
}

Buyer Example

import { withPaymentInterceptor } from "x402-axios";
import axios from "axios";

const devkit = new X402DevKit();
const wallet = await devkit.getWallet();

const client = withPaymentInterceptor(axios.create({ timeout: 30000 }), wallet);

const response = await client.get("https://api.example.com/paid-endpoint");

Seller Example

import express from "express";
import { paymentMiddleware } from "x402-express";

const devkit = new X402DevKit();
const wallet = await devkit.getWallet();

const app = express();
app.use(
  paymentMiddleware(wallet.address, {
    "/api/data": { price: "$0.01", network: "base-sepolia" },
  })
);

🛠️ CLI Usage

Initialize x402 in an existing project

cd your-project
x402-community-devkit init

Create a new x402 project

x402-community-devkit create my-x402-app
cd my-x402-app
npm run fund
npm run dev

Check wallet status and get funding

x402-community-devkit fund

CLI Commands

x402-community-devkit init

Initialize x402 in an existing Node.js project:

• Creates encrypted development wallet
• Updates .env with wallet credentials
• Adds necessary entries to .gitignore
• Provides funding instructions

x402-community-devkit create <name>

Create a new x402 project from scratch:

• Scaffolds complete project structure
• Installs all dependencies
• Generates wallet and configuration
• Includes buyer and seller examples

x402-community-devkit fund

Check wallet balances and show funding instructions:

• Displays current ETH and USDC balances
• Shows funding status and requirements
• Provides links to testnet faucets
• Copies wallet address to clipboard

🔧 Configuration

Options

interface X402DevKitOptions {
  walletPath?: string; // Custom wallet file path
  network?: "base-sepolia"; // Network selection
}

const devkit = new X402DevKit({
  walletPath: "./custom-wallet.json",
  network: "base-sepolia",
});

Environment Variables

# Auto-generated by x402-community-devkit init
X402_PRIVATE_KEY=0x...
X402_WALLET_ADDRESS=0x...

🌐 Network Information

This package works with Base Sepolia testnet:

• Chain ID: 84532
• RPC URL: https://sepolia.base.org
• Explorer: https://sepolia.basescan.org
• USDC Contract: 0x036CbD53842c5426634e7929541eC2318f3dCF7e

Minimum Requirements

• ETH: 0.01 ETH (for gas fees)
• USDC: 0.1 USDC (for payments)

📋 Features

• 🔑 Auto-generated wallets - Secure, encrypted development wallets with cryptographic entropy
• 💰 Funding assistance - Built-in faucet links and balance checking for Base Sepolia
• 🏗️ Project scaffolding - Complete project templates with buyer/seller examples
• 🔧 CLI tools - Simple commands for initialization and wallet management
• 📚 TypeScript library - Importable classes and utilities for programmatic use
• 🧪 Testing support - Comprehensive test suite with unit and integration tests

🔒 Security

Development Wallets

• Wallets are encrypted using AES-256-GCM
• Generated with cryptographic entropy from multiple sources
• Automatically gitignored to prevent commits
• Development only - never use for real funds

Best Practices

• Keep .x402/ directory in .gitignore
• Never commit .env files
• Use different wallets for different environments
• Monitor wallet balances regularly

🧪 Development

Setup

git clone https://github.com/gaurangtorvekar/x402-community-devkit
cd x402-community-devkit
npm install

Scripts

npm run build          # Build TypeScript
npm run dev           # Run CLI in development
npm test              # Run test suite
npm run test:watch    # Watch mode testing
npm run test:coverage # Coverage report
npm run lint          # Run linter

Testing

# Unit tests
npm test -- --testPathPattern="unit"

# Integration tests
npm test -- --testPathPattern="integration"

# Coverage report
npm run test:coverage

📁 Project Structure

x402-community-devkit/
├── src/
│   ├── cli/              # CLI commands
│   ├── lib/              # Core library
│   │   ├── config/       # Constants and configuration
│   │   ├── wallet/       # Wallet management
│   │   ├── faucet/       # Funding instructions
│   │   └── index.ts      # Main X402DevKit class
│   └── __tests__/        # Test suite
├── templates/            # Project scaffolding templates
├── .github/workflows/    # CI/CD
└── dist/                 # Built output

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Use TypeScript with strict mode
• Follow existing code style and patterns
• Add tests for new features
• Update documentation as needed
• Ensure all tests pass

🐛 Issues & Support

• Report issues
• View x402 documentation
• Join discussions

📄 License

MIT License - see LICENSE file for details.

🎯 Roadmap

• [ ] Additional network support (Ethereum mainnet, Polygon)
• [ ] Enhanced wallet management (multiple wallets, import/export)
• [ ] Integration with popular frameworks (Next.js, React)
• [ ] Advanced testing utilities
• [ ] Performance optimizations
• [ ] Enhanced CLI features

Built with ❤️ by Gaurang Torvekar