Faucet Flow
Pre-built and customizable flow for interacting with token faucets on test networks.
Faucet Flow
The Faucet flow provides a complete interface for requesting test tokens from faucets on Avalanche test networks.
Backend Requirements
The Faucet flow requires a backend API to handle token distribution and rate limiting. You'll need to implement the following endpoints:
// Required API Endpoints
POST /api/faucet/request
body: {
address: string; // Recipient address
token: string; // Token symbol
chainId: number; // Network ID
}
response: {
requestId: string; // Unique request identifier
}
GET /api/faucet/status/:requestId
response: {
status: 'pending' | 'completed' | 'failed';
txHash?: string; // Transaction hash if completed
error?: string; // Error message if failed
}We provide an example implementation using Next.js API routes, but you can use any backend technology. Note that the example implementation uses in-memory storage and is for demonstration purposes only. For production use, you should:
- Implement persistent storage for request tracking
- Add proper rate limiting per address/IP
- Include security measures (API keys, CORS, etc.)
- Handle concurrent requests appropriately
- Manage token distribution limits
Basic Usage
import { Faucet } from '@avalabs/builderkit';
function App() {
const tokens = [
// Array of tokens following the BaseToken interface
// See /docs/builderkit/tokens for configuration details
...
];
return (
<Faucet
chainId={43113} // Fuji Testnet
tokens={tokens}
/>
);
}Configuration
Required Props
| Prop | Type | Description |
|---|---|---|
chainId | number | ID of the test network |
tokens | Token[] | List of supported tokens |
Token Configuration
Each token in the tokens array should have the following structure:
interface Token {
address: string; // Contract address or "native" for native token
name: string; // Token name
symbol: string; // Token symbol
decimals: number; // Token decimals
chain_id: number; // Chain ID where token exists
}Optional Props
| Prop | Type | Default | Description |
|---|---|---|---|
className | string | - | Additional CSS classes |
Features
The Faucet flow includes:
- Token selection interface
- Balance display
- Request handling
- Status tracking
- Timeout management
Building Custom Flows
The Faucet flow exposes individual components that you can use to build your own custom faucet interface:
import {
FaucetProvider,
TokenSelector,
FaucetButton,
RequestStatus,
BalanceDisplay
} from '@avalabs/builderkit/faucet/components';
function CustomFaucet() {
const tokens = [
// Array of tokens following the BaseToken interface
// See /docs/builderkit/tokens for configuration details
...
];
return (
<FaucetProvider
chainId={43113}
tokens={tokens}
>
<div className="space-y-4">
<TokenSelector onSelect={handleTokenSelect} />
<BalanceDisplay token={selectedToken} address={userAddress} />
<FaucetButton token={selectedToken} />
<RequestStatus requestId={currentRequestId} />
</div>
</FaucetProvider>
);
}Last updated on 3/7/2025