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>
  );
}

Faucet Flow

On this page