How to Request NEON Tokens Programmatically: The Complete Guide to Neon Faucet API

Introduction

Building on Neon EVM and need NEON tokens for gas fees? There're two options for you to consider: the Neon Faucet API and the Neon Faucet website (https://neonfaucet.org/). This guide provides a comprehensive walkthrough on integrating the Neon Faucet API into your development workflow and using the website to request tokens, saving you time, money, and resources.

Why Use the Neon Faucet?

Traditional Approach (Expensive)

• Resource-intensive: Running a local Neon node demands significant computational power.

• High costs: Electricity and hardware expenses add up quickly.

• Complex setup: Node configuration and maintenance are time-consuming.

• Impractical for testing: Not ideal for development workflows.

Neon Faucet Approach (Recommended by the Neon Docs)

• Free and efficient: Instantly acquire NEON tokens via API or website.

• Programmatic access: Seamlessly integrate API into scripts.

• User-friendly website: Connect wallet and request tokens directly.

• Rate-limited but reliable: Perfect for development and testing.

• Zero infrastructure costs: No need to maintain a node.

Neon Faucet API Endpoints

Devnet

• URL: https://api.neonfaucet.org/request_neon

• Method: POST

• Amount: 100 NEON per request

• Rate Limit: Yes (implement retry logic)

Testnet (Curve Stand)

• URL: https://curve-stand.neontest.xyz/request_neon

• Method: POST

• Amount: 10,000 NEON per request

Using the Neon Faucet Website

You can request NEON tokens directly through the Neon Faucet website (https://neonfaucet.org/) by connecting a wallet like MetaMask. Follow these steps:

1. Set Up MetaMask:

   • Install the MetaMask browser extension from https://metamask.io/.

   • Create a new wallet or import an existing one using your recovery phrase.

   • Add the Neon EVM Devnet to MetaMask:

     • Open MetaMask, click the network dropdown, and select "Add Network."

     • Enter the following details:

       • Network Name: Neon EVM Devnet

       • RPC URL: https://devnet.neonevm.org

       • Chain ID: 245022926

       • Currency Symbol: NEON

       • Block Explorer URL: https://neon-devnet.blockscout.com/

     • Save the network.

2. Visit the Neon Faucet Website:

   • Navigate to https://neonfaucet.org/.

3. Connect Your Wallet:

   • Click the "CONNECT WALLET" button.

   • In the MetaMask pop-up, select the account(s) you want to use and click "Next."

   • Click "Connect" to confirm the connection.

4. Request NEON Tokens:

   • In the form that appears, select "NEON" as the token.

   • Enter the amount (up to 100 NEON per request on Devnet).

   • Click the "SEND TEST TOKENS" button.

   • Wait for the transaction to be processed (typically a few seconds).

   • Check your wallet balance or the Neon Devnet explorer to confirm receipt.

Note: The website is rate-limited, so you may need to wait before making additional requests.

Implementation Guide for Neon Faucet API

1. Basic JavaScript Implementation

This script handles airdrop requests with retry logic for reliability.

async function airdropNEON(address, amount = 100) {
    const FAUCET_URL = "https://api.neonfaucet.org/request_neon";
    const MAX_RETRIES = 3;
    const RETRY_DELAY = 2000; // 2 seconds

    let retryCount = 0;

    while (retryCount < MAX_RETRIES) {
        try {
            console.log(`Attempting to airdrop ${amount} NEON to ${address} (Attempt ${retryCount + 1}/${MAX_RETRIES})`);

            const response = await fetch(FAUCET_URL, {
                method: 'POST',
                headers: {
                    'Content-Type': 'application/json',
                },
                body: JSON.stringify({
                    wallet: address,
                    amount: amount
                })
            });

            if (!response.ok) {
                throw new Error(`HTTP error! status: ${response.status}`);
            }

            const result = await response.json();
            console.log("Airdrop response:", result);

            // Wait for transaction to be mined
            await new Promise(resolve => setTimeout(resolve, 5000));

            return true;
        } catch (error) {
            console.error(`Airdrop attempt ${retryCount + 1} failed:`, error.message);
            retryCount++;

            if (retryCount < MAX_RETRIES) {
                console.log(`Waiting ${RETRY_DELAY/1000} seconds before next attempt...`);
                await new Promise(resolve => setTimeout(resolve, RETRY_DELAY));
            }
        }
    }

    console.warn(`Failed to airdrop NEON after ${MAX_RETRIES} attempts.`);
    return false;
}

2. Hardhat Integration

Configure Hardhat to support Neon Faucet API in hardhat.config.js.

const config = {
    neon_faucet: {
        neondevnet: {
            url: "https://api.neonfaucet.org/request_neon",
            min_balance: "100",
        },
        curvestand: {
            url: "https://curve-stand.neontest.xyz/request_neon",
            min_balance: "10000",
        }
    }
}

3. Test Automation Integration

Automate balance checks and airdrops during contract deployment.

export async function deployContract(deployer, user, contractName, contractAddress = null) {
    const { network } = await import("hardhat");
    const ethers = (await network.connect()).ethers;

    // Get minimum required balance
    const minBalance = ethers.parseEther("100.0");

    // Check balances and airdrop if needed
    const deployerBalance = await ethers.provider.getBalance(deployer.address);
    if (deployerBalance < minBalance) {
        await airdropNEON(deployer.address, 100);
    }

    const userBalance = await ethers.provider.getBalance(user.address);
    if (userBalance < minBalance) {
        await airdropNEON(user.address, 100);
    }

    // Continue with contract deployment...
}

4. Command Line Usage

Request NEON tokens directly via curl.

curl -X POST https://api.neonfaucet.org/request_neon \
  -H "Content-Type: application/json" \
  -d '{
    "wallet": "0xYourWalletAddressHere",
    "amount": 100
  }'

Best Practices

1. Implement Retry Logic

Handle rate limits with retries.

const MAX_RETRIES = 3;
const RETRY_DELAY = 2000; // 2 seconds between retries

2. Balance Checking

Verify account balances before requesting airdrops.

const balance = await ethers.provider.getBalance(address);
const minBalance = ethers.parseEther("100.0");

if (balance < minBalance) {
    await airdropNEON(address, 100);
}

3. Transaction Confirmation

Ensure transactions are mined before proceeding.

// Wait for transaction to be mined
await new Promise(resolve => setTimeout(resolve, 5000));

// Verify balance
const newBalance = await ethers.provider.getBalance(address);
console.log("New balance:", ethers.formatEther(newBalance), "NEON");

4. Error Handling

Robustly manage network and API errors.

try {
    const response = await fetch(FAUCET_URL, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ wallet: address, amount: 100 })
    });

    if (!response.ok) {
        throw new Error(`HTTP error! status: ${response.status}`);
    }
} catch (error) {
    console.error("Airdrop failed:", error.message);
    // Handle error appropriately
}

Integration Examples

1. Automated Testing

Ensure test accounts have sufficient NEON before running tests.

describe("Contract Tests", function() {
    beforeEach(async function() {
        // Ensure all test accounts have sufficient NEON
        const accounts = await ethers.getSigners();
        for (const account of accounts) {
            const balance = await ethers.provider.getBalance(account.address);
            if (balance < ethers.parseEther("50")) {
                await airdropNEON(account.address, 100);
            }
        }
    });

    // Your tests here...
});

2. CI/CD Pipeline

Integrate airdrop functionality into your CI/CD workflow.

# .github/workflows/test.yml
- name: Setup Node.js
  uses: actions/setup-node@v3
  with:
    node-version: '20'

- name: Install dependencies
  run: npm install

- name: Run tests with airdrop
  run: |
    # The airdrop function will automatically handle NEON distribution
    npm run test

3. Development Scripts

Set up development environments with automated airdrops.

// scripts/setup-dev.js
async function setupDevelopmentEnvironment() {
    const accounts = await ethers.getSigners();

    console.log("Setting up development environment...");

    for (let i = 0; i < accounts.length; i++) {
        const account = accounts[i];
        const balance = await ethers.provider.getBalance(account.address);

        if (balance < ethers.parseEther("50")) {
            console.log(`Airdropping NEON to account ${i}: ${account.address}`);
            await airdropNEON(account.address, 100);
        }
    }

    console.log("Development environment setup complete!");
}

Troubleshooting

Common Issues

1. Rate Limiting

   • Solution: Use retry logic with exponential backoff or wait before retrying on the website.

   • Wait 2-5 seconds between API requests or check website prompts.

2. Network Errors

   • Solution: Verify network connectivity.

   • Ensure the faucet URL or website is accessible.

3. Insufficient Balance After Airdrop

   • Solution: Wait longer for transaction confirmation.

   • Check transaction status on Neon Devnet explorer.

4. Invalid Address Format

   • Solution: Confirm wallet address is a valid Ethereum address.

   • Ensure proper 0x prefix.

5. Wallet Connection Issues

   • Solution: Ensure MetaMask is unlocked and set to Neon EVM Devnet.

   • Clear browser cache or try a different browser if the website fails to connect.

Debug Information

Enable debug logging for API troubleshooting.

const DEBUG = process.env.DEBUG || false;

if (DEBUG) {
    console.log("Request payload:", JSON.stringify({
        wallet: address,
        amount: 100
    }));
    console.log("Response:", result);
}

Security Considerations

1. Protect private keys: Never include them in airdrop requests or expose them on the website.

2. Use environment variables: Store sensitive data securely for API usage.

3. Rate limit requests: Avoid overwhelming the faucet to prevent bans.

4. Validate addresses: Ensure addresses are correctly formatted.

5. Monitor usage: Stay within faucet limits for both API and website requests.

6. Secure wallet connections: Only connect to trusted websites like https://neonfaucet.org/.

Real-World Implementation

This guide draws from hands-on experience I have gained as a result of my learning(s) during the neon evm bootcamp 2025. The provided code and steps have been tested by me and found more convenient during my course of trying out or experimenting the knowledge from the resources granted by the neon evm organization.

What This Guide Delivers

• Programmatic access: Streamlined token acquisition via API.

• Website access: Simple token requests through https://neonfaucet.org/.

• Production-ready code: Tested in real projects.

• Best practices: Robust handling of rate limits and errors.

• Integration examples: Tailored for diverse development needs.

Conclusion

The Neon Faucet, accessible via API and the website (https://neonfaucet.org/), offers a cost-effective, efficient, and scalable alternative to running a local node for obtaining NEON tokens. By adopting the techniques in this guide, you can:

• Reduce costs: Eliminate infrastructure expenses.

• Accelerate development: Gain instant token access.

• Automate testing: Ensure reliable airdrop functionality.

• Scale effortlessly: Focus on building, not node maintenance.

This approach has powered successful Neon EVM projects and is the go-to method for developers on the platform.

Resources

• Neon EVM Documentation

• Neon Devnet Explorer

• Neon Faucet API

• Neon Faucet Website

• GitHub Repository - Full implementation examples

This guide is based on personal preferences and theoretical knowledge rather than practical experience with Neon EVM development. The Neon Faucet API and website methods are suggested for convenience.