hanzo-faucet

Hanzo Faucet is a token distribution service for Hanzo Network (the AI Compute L1 blockchain).

Hanzo Faucet - Hanzo Network Token Faucet

Category: Hanzo Ecosystem Related Skills: hanzo/hanzo-explorer.md, hanzo/hanzo-contracts.md

Overview

Hanzo Faucet is a token distribution service for Hanzo Network (the AI Compute L1 blockchain). It distributes test $AI tokens on both Testnet (Chain ID: 36962) and Mainnet (Chain ID: 36963). The backend is an Express/TypeScript server using the luxfi SDK for EVM transactions. The frontend is a Next.js 16 app with RainbowKit wallet integration. Includes Solidity smart contracts built with Foundry. Rate limiting and Google reCAPTCHA v3 protect against abuse.

What it actually is

Express backend (port 8000) that signs and sends $AI token transactions
Next.js 16 frontend (port 3000) with RainbowKit wallet connect
pnpm workspace monorepo: root backend + app/ frontend
Uses luxfi SDK (not ethers/web3 directly) for chain interaction
Solidity contracts in contracts/ built with Foundry
Google reCAPTCHA v3 verification middleware
Per-address and global rate limiting
Supports ERC20 token drips in addition to native $AI
Dockerized deployment

Hanzo Network details

Mainnet: Chain ID 36963, RPC https://rpc.hanzo.network, 1 AI per drip, 48h rate limit
Testnet: Chain ID 36962, RPC https://rpc-testnet.hanzo.network, 10 AI per drip, 24h rate limit
Token: $AI (18 decimals)
Explorer: https://explorer.hanzo.network / https://explorer-testnet.hanzo.network

When to use

Getting test tokens for Hanzo Network development
Deploying a faucet for a new Hanzo Network chain or subnet
Adding new ERC20 token drips to the faucet

Quick reference

| Item | Value | |------|-------| | Repo | github.com/hanzoai/faucet | | Package | @hanzo/faucet | | Version | 1.0.0 | | Branch | main | | Backend | Express + TypeScript (port 8000) | | Frontend | Next.js 16 + React 19 (port 3000) | | Web3 | luxfi SDK, RainbowKit, wagmi v2, viem v2 | | Contracts | Solidity 0.8.28, Foundry | | Package Manager | pnpm (workspace) | | License | BSD-3-Clause |

Quickstart

git clone https://github.com/hanzoai/faucet.git
cd faucet
pnpm install

# Configure
cp .env.example .env
# Set PK (private key), CAPTCHA_SECRET

# Generate a new wallet
pnpm generate

# Start backend (port 8000)
pnpm dev

# Start frontend (port 3000)
pnpm dev:app

# Start both
pnpm dev:all

# Build for production
pnpm build
pnpm start

Architecture

 Browser (port 3000) Express API (port 8000)
 ┌──────────────────┐ ┌───────────────────────┐
 │ Next.js 16 App │────────>│ /api/sendToken │
 │ RainbowKit │ │ /api/faucetAddress │
 │ wagmi/viem │ │ /api/getBalance │
 └──────────────────┘ │ /api/getChainConfigs │
 │ /health │
 └──────────┬────────────┘
 │
 ┌──────────▼────────────┐
 │ EVM Instance (luxfi) │
 │ Signs & sends tx │
 │ Per-chain private keys│
 └───────────────────────┘

API endpoints

| Method | Path | Description | |--------|------|-------------| | POST | /api/sendToken | Send tokens (requires captcha) | | GET | /api/faucetAddress?chain=C | Get faucet wallet address | | GET | /api/getBalance?chain=C | Get faucet balance | | GET | /api/getChainConfigs | Get all chain configurations | | GET | /health | Health check | | GET | /ip | Client IP (Cloudflare aware) |

Directory structure

hanzoai/faucet/
 package.json # @hanzo/faucet v1.0.0 (root workspace)
 server.ts # Express backend entry point
 config.json # Chain configs (testnet/mainnet), rate limits
 types.ts # TypeScript type definitions
 middlewares/ # Rate limiter, captcha, URI parser
 vms/
 evm.ts # EVM chain instance (luxfi SDK)
 client/ # Legacy frontend (being replaced by app/)
 app/ # Next.js 16 frontend (pnpm workspace)
 src/ # React components
 e2e/ # Playwright tests
 package.json # @hanzo/faucet-app
 contracts/ # Solidity smart contracts
 src/ # Contract source
 test/ # Foundry tests
 script/ # Deploy scripts
 foundry.toml # Foundry config
 scripts/
 generateKey.ts # Wallet key generation
 Dockerfile # Container build

Environment variables

| Variable | Required | Purpose | |----------|----------|---------| | PK | Yes | Default faucet wallet private key | | HANZO_TESTNET | No | Testnet-specific private key (overrides PK) | | HANZO_MAINNET | No | Mainnet-specific private key (overrides PK) | | CAPTCHA_SECRET | Yes | Google reCAPTCHA v3 secret | | V2_CAPTCHA_SECRET | No | reCAPTCHA v2 fallback secret | | PORT | No | Backend port (default: 8000) |

Rate limiting

Global: 40 requests per minute across all endpoints
Per-chain testnet: 1 request per 24 hours per address
Per-chain mainnet: 1 request per 48 hours per address
Uses cf-connecting-ip header for Cloudflare deployments
REVERSE_PROXIES config controls trusted proxy hop count

Contracts (Foundry)

cd contracts
forge build # Compile
forge test # Run tests
forge test --gas-report

Related Skills

hanzo/hanzo-explorer.md -- Block explorer for Hanzo Network
hanzo/hanzo-contracts.md -- Smart contract patterns

Last Updated: 2026-03-13 Category: Hanzo Ecosystem Related: faucet, blockchain, hanzo-network, tokens, evm, web3 Prerequisites: Node.js 17+, pnpm 8+, funded wallet with AI tokens, reCAPTCHA keys