Skip to content

guide-localnet.md

Latest commit

 

History

History
177 lines (123 loc) · 3.82 KB

guide-localnet.md

File metadata and controls

177 lines (123 loc) · 3.82 KB

Local Solana Validator Guide

Run the full Ag402 payment flow on a local Solana validator — no network dependency, no devnet instability, real on-chain transactions.

Why Local Validator?

Feature Mock Mode Devnet Localnet
Speed Instant 2-10s ~1s
Stability 100% Variable 100%
Real on-chain TX ✗ ✓ ✓
Explorer link ✗ ✓ ✓ (local)
Network required ✗ ✓ ✗
Cost Free Free Free

Prerequisites

1. Install Solana CLI

sh -c "$(curl -sSfL https://release.anza.xyz/stable/install)"

Verify:

solana --version
solana-test-validator --version

2. Install Ag402

pip install 'ag402-core[crypto]'    # Includes solana-py + solders
ag402 setup

Quick Start

Step 1: Start Local Validator

solana-test-validator --reset

This starts a Solana validator at http://127.0.0.1:8899. Keep this terminal open.

Step 2: Run Localnet Demo

ag402 demo --localnet

This will:

  1. Connect to the local validator
  2. Create test keypairs (buyer + seller)
  3. Airdrop SOL for transaction fees
  4. Create a test USDC token mint
  5. Mint 1000 test USDC to buyer
  6. Execute a real on-chain SPL Token transfer
  7. Show the transaction hash (viewable in Solana Explorer)

Step 3: Verify Transaction

The demo will output a transaction hash like:

TX Hash: 5K4j...abc123

You can view it in a local explorer or via Solana CLI:

solana confirm <tx_hash> --url http://127.0.0.1:8899

Full Gateway Experience (Localnet)

Terminal 1: Start validator

solana-test-validator --reset

Terminal 2: Start gateway

ag402 serve --localnet

Terminal 3: Buyer view

ag402 pay http://127.0.0.1:4020/

This runs the full 6-step x402 protocol with real on-chain transactions on your local validator.

With Claude Code / Cursor / OpenClaw

# Terminal 1: Start validator
solana-test-validator --reset

# Terminal 2: Start localnet gateway
ag402 serve --localnet

# In your AI tool, use the same prompts:
# "Use fetch_with_autopay to access http://127.0.0.1:4020/weather?city=Tokyo"

Demo Modes Reference

Mode Command Description
mock (default) ag402 demo Simulated payments, no chain interaction
localnet ag402 demo --localnet Real on-chain via solana-test-validator
devnet ag402 demo --devnet Real on-chain via Solana devnet

Health Check

Run the Ag402 doctor to verify your localnet setup:

ag402 doctor

It will check:

  • ✓ Solana CLI installed
  • ✓ solana-test-validator available
  • ✓ Validator running on port 8899
  • ✓ Solana dependencies (solana-py, solders) installed

Troubleshooting

Symptom Cause Fix
"solana-test-validator not found" Solana CLI not installed See Prerequisites above
"Cannot connect to 127.0.0.1:8899" Validator not running Run solana-test-validator --reset
"Solana dependencies not installed" Missing packages pip install 'ag402-core[crypto]'
"Airdrop failed" Validator issue Restart with solana-test-validator --reset
Demo hangs Port conflict Check port 8899 is free: lsof -i :8899

How Localnet Setup Works

ag402 demo --localnet
    ↓
1. Connect to solana-test-validator (http://127.0.0.1:8899)
2. Generate buyer + seller keypairs
3. Airdrop 100 SOL to buyer (for tx fees)
4. Airdrop 10 SOL to seller
5. Create SPL Token mint (6 decimals, USDC-like)
6. Create buyer ATA + mint 1000 test USDC
7. Execute SPL Token transfer (buyer → seller)
8. Show real tx_hash + balance changes

All of this runs locally with zero network dependency.