xforth 0.1.0

CLI tool for bootstrapping x402 Solana projects.
Documentation

Author's bio: Hi, I'm CryptoPatrick! I'm currently enrolled as an Undergraduate student in Mathematics, at Chalmers & the University of Gothenburg, Sweden. If you have any questions or need more info, then please join my Discord Channel: AiMath

Important Notices

  • This tool is designed for Solana Devnet development and testing
  • Not intended for production mainnet deployments
  • Automatically generates keypairs and configuration files

What is xforth

xforth is a Rust-based CLI tool that automates the complete setup process for x402 projects on the Solana blockchain. Through intelligent automation of keypair generation, wallet funding, token minting, and payment flow validation - the whole process is much smoother.

Use Cases

  • Rapid Prototyping: Spin up x402 payment projects instantly for testing and development
  • Blockchain Education: Quickly set up demo environments for learning Solana development
  • Testing Environments: Create isolated test configurations with funded wallets and tokens
  • Agent Development: Bootstrap AI agent payment infrastructure on Solana Devnet
  • Workshop & Training: Enable multiple developers to get started simultaneously

Architecture

The tool provides three core commands that handle the complete setup lifecycle:

  1. Init: Generates keypairs, creates project structure, deploys placeholder programs, and configures environment
  2. Fund: Airdrops SOL to wallets and mints test SPL tokens with automatic retry logic
  3. Test: Validates the entire setup by executing a test payment transaction

Features

Instant Project Initialization

  • Keypair Generation: Automatically creates Agent/Payer and Facilitator/Receiver keypairs
  • Project Scaffolding: Sets up complete project directory with Cargo configuration
  • Environment Configuration: Generates .env file with all necessary keys and program IDs
  • Program Deployment: Deploys placeholder facilitator program to Devnet

Automated Funding

  • SOL Airdrops: Automatically requests 0.5 SOL for each wallet with exponential backoff retries
  • Token Minting: Creates and mints test SPL tokens for payment testing
  • Rate Limit Handling: Intelligent retry logic handles Devnet rate limiting gracefully
  • Balance Verification: Confirms successful funding before proceeding

Payment Validation

  • Transaction Testing: Executes end-to-end test payment to verify complete setup
  • Balance Checks: Validates wallet balances before and after test transactions
  • Transaction Logging: Provides detailed transaction IDs and explorer links
  • Error Diagnostics: Clear error messages with troubleshooting guidance

Developer Experience

  • Color-Coded Output: Enhanced terminal output with colored status indicators
  • JSON Mode: Machine-readable output for CI/CD integration
  • Flexible RPC Configuration: Support for custom RPC endpoints and local validators
  • Progress Tracking: Real-time feedback on all operations
  • Zero Configuration: Works out-of-the-box with sensible defaults

How to Use

Requirements

xforth requires:

  • Rust 1.70 or higher
  • Cargo package manager
  • Internet connection for Devnet access

Installation

Install directly from crates.io:

cargo install xforth

Or build from source:

git clone https://github.com/cryptopatrick/xforth.git
cd xforth
cargo build --release

Quick Start

Bootstrap a complete x402 project in three commands:

# 1. Initialize your project (creates keypairs, config, and project structure)
xforth init my-payment-agent

# 2. Fund the wallets with SOL and mint test tokens
xforth fund

# 3. Validate the setup with a test payment transaction
xforth test

That's it! Your x402 project is now fully configured and ready for development.

Command Reference

Init Command

Initialize a new x402 project:

xforth init [PROJECT_NAME]

Options:

  • PROJECT_NAME: Optional project name (default: "my-x402-agent")
  • --rpc <URL>: Override default Devnet RPC endpoint
  • --local: Use local Solana validator (http://127.0.0.1:8899)
  • --json: Output results in JSON format
  • --no-color: Disable colored output

What it does:

  • Generates two keypairs (Agent/Payer and Facilitator/Receiver)
  • Creates project directory with template Cargo.toml
  • Deploys placeholder facilitator program
  • Generates .env file with configuration

Example output:

[ACTION] Initializing project: my-payment-agent
[LOG] Generated Agent/Payer keypair: 5Xr7...Abc
[LOG] Generated Facilitator/Receiver keypair: 9Yt3...Def
[LOG] Created project directory
[LOG] Generated .env configuration
[SUCCESS] Project initialized successfully!

Fund Command

Fund wallets and mint test tokens:

xforth fund

Options:

  • --rpc <URL>: Override default Devnet RPC endpoint
  • --local: Use local Solana validator
  • --json: Output results in JSON format
  • --no-color: Disable colored output

What it does:

  • Airdrops 0.5 SOL to Agent/Payer wallet (with retries)
  • Airdrops 0.5 SOL to Facilitator/Receiver wallet (with retries)
  • Mints test SPL tokens to Agent wallet
  • Verifies all balances

Example output:

[ACTION] Funding wallets...
[LOG] Airdropping 0.5 SOL to Agent: 5Xr7...Abc
[LOG] Retry 1/5 due to rate limit...
[LOG] Airdrop successful! Balance: 0.5 SOL
[LOG] Minting test tokens...
[SUCCESS] All wallets funded successfully!

Test Command

Validate setup with test transaction:

xforth test

Options:

  • --rpc <URL>: Override default Devnet RPC endpoint
  • --local: Use local Solana validator
  • --json: Output results in JSON format
  • --no-color: Disable colored output

What it does:

  • Checks wallet balances
  • Executes test payment transaction
  • Verifies transaction success
  • Provides transaction explorer link

Example output:

[ACTION] Running test payment...
[LOG] Agent balance: 0.5 SOL
[LOG] Facilitator balance: 0.5 SOL
[LOG] Executing payment transaction...
[TX] 3Kp9...Xyz
[SUCCESS] Test payment completed successfully!
View transaction: https://explorer.solana.com/tx/3Kp9...Xyz?cluster=devnet

Advanced Usage

Using Custom RPC Endpoint

xforth init my-project --rpc https://my-custom-rpc.com
xforth fund --rpc https://my-custom-rpc.com
xforth test --rpc https://my-custom-rpc.com

Using Local Validator

# Start local Solana validator in another terminal
solana-test-validator

# Use xforth with local validator
xforth init my-project --local
xforth fund --local
xforth test --local

CI/CD Integration

# Use JSON output for parsing in scripts
xforth init my-project --json --no-color > init-result.json
xforth fund --json --no-color > fund-result.json
xforth test --json --no-color > test-result.json

Project Structure

After running xforth init my-project, you'll have:

my-payment-agent/
├── Cargo.toml          # Rust project configuration
├── .env                # Environment variables (keypairs, program IDs)
└── src/
    └── main.rs         # Template for your x402 agent

Environment Variables

The .env file contains:

AGENT_KEYPAIR=<base58-encoded-keypair>
FACILITATOR_KEYPAIR=<base58-encoded-keypair>
PROGRAM_ID=<deployed-program-address>
RPC_URL=https://api.devnet.solana.com

Security Note: Never commit your .env file to version control. Add it to .gitignore immediately.

Documentation

Comprehensive documentation is available at docs.rs/xforth, including:

  • Complete API reference
  • Detailed command options
  • Troubleshooting guide
  • Integration examples
  • Best practices for x402 development

Author

CryptoPatrick

Keybase Verification: https://keybase.io/cryptopatrick/sigs/8epNh5h2FtIX1UNNmf8YQ-k33M8J-Md4LnAN

Support

I'm just a lone dev, silently hacking away, in a place far far away. Please don't hesitate to tweet at me https://x.com/cryptopatrick/ if you found this project helpful in any way. You can also support me with Solana: 8uCGFmXRQPJQ8r16d9a1DroRcmmtzus3SFfTkteSt2Xj or Ethereum: 0x52a361c89ebF05C8ea3fA72fc43aDF30f53e2D21

Cheers!

Contributing

Found a bug? Missing a specific feature? Contributions are welcome! Please see our contributing guidelines for details on:

  • Code style and testing requirements
  • Submitting bug reports and feature requests
  • Development setup and workflow

License

This project is licensed under MIT. See LICENSE for details.