# x402-cli
> A command-line tool for automating x402 project lifecycle management
[](https://shields.io/)
[](https://opensource.org/licenses/MIT)
[](https://www.rust-lang.org)
## 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:
```bash
# 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:
```bash
# 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
```bash
# 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:
```bash
# 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.
```bash
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:**
```bash
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.
```bash
x402-cli wallet create [OPTIONS]
```
**Subcommands:**
- `create`: Create a new wallet
**Options for `create`:**
- `-n, --network <NETWORK>`: Network to use (default: testnet)
**Example:**
```bash
# 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.
```bash
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:**
```bash
# Start facilitator on default port (3001)
x402-cli facilitator start
# Start facilitator on custom port
x402-cli facilitator start --port 8080
# Stop facilitator
x402-cli facilitator stop
```
**Output:**
- Starts a TCP server on the specified port
- Health check endpoint at `http://localhost:<port>/health`
- Handles payment facilitation requests
### `test` - Test payment flows
Test end-to-end payment flows to verify functionality.
```bash
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:**
```bash
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.
```bash
x402-cli deploy --provider <PROVIDER>
```
**Options:**
- `-p, --provider <PROVIDER>`: Deployment platform (e.g., vercel)
**Example:**
```bash
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`)
```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`)
```bash
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
```bash
# Debug build
cargo build
# Release build
cargo build --release
```
### Running Tests
```bash
# 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](https://github.com/aptos-labs/aptos-ts-sdk)
- [x402 Protocol Documentation](https://x402.org)
- [Aptos Developer Portal](https://developers.aptoslabs.com)
## 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