Hanzo Faucet

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 ba...

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

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

On this page