A dual-chain faucet for distributing native tokens on Cosmos SDK chains with EVM support.
- Dual Environment Support: Simultaneous Cosmos SDK + EVM native token distribution
- Balance-Based Limiting: Only tops up wallets below a configurable threshold
- API Key Authentication: Secure token distribution via authenticated API
- Wallet Support: Keplr (Cosmos) and EIP-6963 compatible wallets (EVM)
- Minimal Frontend: Simple Vue 3 example frontend included
yarn installcp .env.example .envEdit .env:
MNEMONIC="your twelve word mnemonic phrase here"
FAUCET_API_KEY="your-secure-api-key-here"Edit config.js to set your network endpoints and native token:
const config = {
blockchain: {
name: 'your-chain',
ids: {
chainId: 1234, // EVM chain ID
cosmosChainId: 'chain-1', // Cosmos chain ID
},
endpoints: {
rpc_endpoint: 'https://rpc.yourchain.com',
evm_endpoint: 'https://evm-rpc.yourchain.com',
rest_endpoint: 'https://rest.yourchain.com',
},
sender: {
option: {
prefix: 'yourprefix', // Bech32 address prefix
},
},
tx: {
amounts: [{
denom: 'utoken',
symbol: 'TOKEN',
amount: '1000000000000000000',
decimals: 18,
}],
},
balanceThreshold: '1000000000000000000', // 1 token
},
};yarn start # Production server on port 8088
yarn dev # Dev server with hot reload (port 3000)| Endpoint | Auth | Description |
|---|---|---|
GET /send/:address |
API Key | Request tokens (Bech32 or EVM address) |
GET /balance/:type |
No | Query balance (type: cosmos or evm) |
GET /config.json |
No | Network configuration |
GET /health |
No | Health check |
The /send endpoint requires an API key via the X-API-Key header:
curl -H "X-API-Key: your-api-key" http://localhost:8088/send/0x...See API_INTEGRATION.md for full integration documentation.
devnet-faucet/
|-- faucet.js # Express API server
|-- config.js # Network configuration
|-- src/
| |-- App.vue # Frontend example
| |-- main.js # Vue entry
| |-- SecureKeyManager.js # Key derivation
| |-- logRotation.js # Log management
|-- tests/ # Test suite
yarn start # Production server
yarn dev # Development server
yarn build # Build frontend
yarn test # Run tests
yarn lint # Check code
yarn lint:fix # Fix linting issuesdocker build -t faucet .
docker run -p 8088:8088 \
-e MNEMONIC="..." \
-e FAUCET_API_KEY="..." \
faucetfly apps create your-faucet
fly secrets set MNEMONIC="..." FAUCET_API_KEY="..."
fly deployMIT