x402-cli

A command-line tool for automating x402 project lifecycle management

About

x402-cli is a Rust-based command-line tool designed to automate the lifecycle of an x402 project. It acts as a bridge between a developer's local code, the Aptos blockchain, and the x402 facilitator.

Features

• 🚀 Project Initialization - Scaffold new x402-enabled projects with configurable frameworks
• 💰 Wallet Management - Create, save, and fund wallets for testnet/mainnet
• 🔄 Facilitator Server - Start/stop local development facilitator with health checks
• 🧪 Payment Testing - End-to-end payment flow testing with detailed output
• 🚀 Deployment - Deploy facilitators to platforms like Vercel
• 📝 Configuration - TOML-based project and environment configuration
• 🎨 Multiple Frameworks - Support for Next.js, React, and other frameworks
• ⛓ Blockchain Support - Built-in Aptos blockchain integration

Installation

Prerequisites

• Rust: 1.70 or higher
• Cargo: Rust package manager (comes with Rust)
• Node.js & npm: Required for project initialization (for web frameworks)
• Operating System: macOS, Linux, or Windows

Build from Source

Clone the repository and build the CLI:

# Clone the repository
git clone https://github.com/sambhuyadav/x402-Developer-CLI.git
cd x402-Developer-CLI

# Build in release mode for optimal performance
cargo build --release

# The binary will be available at:
# target/release/x402-cli

Install System-Wide (Optional)

To make the CLI available system-wide:

# Copy to a directory in your PATH
sudo cp target/release/x402-cli /usr/local/bin/x402-cli

# Or create a symlink
sudo ln -s target/release/x402-cli /usr/local/bin/x402-cli

Verify Installation

# Check if CLI is installed
x402-cli --version

# Show help
x402-cli --help

Getting Started

Quick Start

Here's the fastest way to get started with x402-cli:

# 1. Initialize a new x402 project
x402-cli init my-weather-api --chain aptos --framework next

# 2. Create a test wallet
x402-cli wallet create --network testnet

# 3. Start the local facilitator
x402-cli facilitator start --port 3001

# 4. Test the payment flow
x402-cli test payment --api http://localhost:3000/weather --amount 1000

# 5. Deploy to production
x402-cli deploy --provider vercel

Command Reference

init - Initialize a new project

Create a new x402-enabled project with the specified framework.

x402-cli init --name <NAME> --chain <CHAIN> --framework <FRAMEWORK>

Options:

• -n, --name <NAME>: Project name (required)
• -c, --chain <CHAIN>: Blockchain network (e.g., aptos)
• -f, --framework <FRAMEWORK>: Framework to use (e.g., next, react, vanilla)

Example:

x402-cli init --name my-api --chain aptos --framework next

Output:

• Creates project directory structure (src/, config/, tests/, docs/)
• Generates configuration files (x402.toml, .env.example, .gitignore)
• Installs framework dependencies
• Generates README with x402-specific commands

wallet - Manage wallets

Create and manage wallets for x402 transactions.

x402-cli wallet create [OPTIONS]

Subcommands:

• create: Create a new wallet

Options for create:

• -n, --network <NETWORK>: Network to use (default: testnet)

Example:

# Create a wallet on testnet
x402-cli wallet create --network testnet

# Create a wallet on mainnet
x402-cli wallet create --network mainnet

Output:

• Generates a new Ed25519 key pair
• Creates a 12-word BIP39 seed phrase
• Saves wallet to ~/.x402/wallets/<address>.json
• Funds wallet from faucet (testnet only)

facilitator - Manage facilitator server

Start and stop the local development facilitator server.

x402-cli facilitator <COMMAND>

Subcommands:

• start: Start the facilitator server
• stop: Stop all facilitator processes

Options for start:

• -p, --port <PORT>: Port to listen on (default: 3001)

Examples:

# Start facilitator on default port (3001) with auto-detected wallet
x402-cli facilitator start

# Start facilitator on custom port
x402-cli facilitator start --port 8080

# Start facilitator on mainnet
x402-cli facilitator start --network mainnet

# Start facilitator with specific wallet address
x402-cli facilitator start --wallet 0xe910ad0506573009839aa55ad8211ad01ba3f7394d93d849378d342449df09

# Start facilitator with private key and custom network
x402-cli facilitator start --private-key 0x<private_key> --network testnet

# Stop facilitator
x402-cli facilitator stop

Options for start:

• -p, --port <PORT>: Port to listen on (default: 3001)
• --wallet <ADDRESS>: Use wallet with this address (optional)
• --private-key <KEY>: Use wallet from this private key (optional)
• -n, --network <NETWORK>: Network to use (default: testnet)

Output:

• Starts a TCP server on the specified port
• Health check endpoint at http://localhost:<port>/health
• Handles payment facilitation requests
• Uses specified wallet for payment transactions (defaults to first found wallet)

test - Test payment flows

Test end-to-end payment flows to verify functionality.

x402-cli test payment [OPTIONS]

Subcommands:

• payment: Test a payment flow

Options for payment:

• -a, --api <API>: API endpoint to test (required)
• -a, --amount <AMOUNT>: Amount to pay in micro-APT (default: 1000)

Example:

x402-cli test payment --api http://localhost:3000/weather --amount 1000

Output:

• Step-by-step payment flow progress
• Transaction hash and timing information
• Detailed error messages if failures occur

deploy - Deploy to production

Deploy your facilitator to production platforms.

x402-cli deploy --provider <PROVIDER>

Options:

• -p, --provider <PROVIDER>: Deployment platform (e.g., vercel)

Example:

x402-cli deploy --provider vercel

Output:

• Builds the project
• Checks for provider CLI installation
• Initiates deployment process
• Provides deployment URL

Configuration

Project Configuration (config/x402.toml)

project_name = "my-project"
chain = "aptos"
framework = "next"
version = "0.1.0"

[server]
port = 3000
host = "localhost"

[blockchain]
network = "aptos"

[facilitator]
enabled = true
port = 3001

Environment Variables (.env)

NODE_ENV=development
X402_CHAIN=aptos
X402_PROJECT=my-project

Wallet Storage

Wallets are stored securely in:

• Location: ~/.x402/wallets/<address>.json
• Format: JSON with address, private_key, network, and seed_phrase
• Security: Files are not encrypted - ensure system security

Supported Frameworks

• Next.js: Full-featured React framework
• React: React library support
• Vanilla: Basic HTML/JavaScript setup

Architecture

User Input (CLI) 
    → Command Parsing (Clap)
    → Command Routing (main.rs)
    → Module Handler (x402/mod.rs)
    → Domain Logic (project.rs/wallet.rs/facilitator.rs/test.rs/deploy.rs)
    → External Services (blockchain, file system, HTTP)

Development

Building

# Debug build
cargo build

# Release build
cargo build --release

Running Tests

# Run all tests
cargo test

# Run specific test
cargo test test_name

Adding New Features

1. Create new module in src/x402/
2. Add command enum in src/main.rs
3. Export from src/lib.rs
4. Add handler in src/x402/mod.rs
5. Test functionality

Troubleshooting

Wallet Funding Fails

If faucet funding fails with 405 Method Not Allowed:

• The Aptos faucet API may have changed
• Fund the wallet manually using the Aptos explorer
• Check the faucet service status

Facilitator Won't Start

If the facilitator fails to start:

• Check if the port is already in use: lsof -i :3001
• Use a different port: x402-cli facilitator start --port 3002
• Check firewall settings

Payment Flow Fails

If payment testing fails:

• Ensure the API endpoint is accessible
• Verify the facilitator is running
• Check network connectivity
• Review error messages for specific issues

License

MIT License - see LICENSE file for details

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Resources

• Aptos TypeScript SDK
• x402 Protocol Documentation
• Aptos Developer Portal

Changelog

v1.0.0 (2025-02-01)

• Initial release
• Project scaffolding with framework support
• Wallet creation and management
• Facilitator server management
• Payment flow testing
• Vercel deployment support
• Aptos blockchain integration