Skip to main content

Faucet

The local devnet faucet provides unlimited test ADA for development.

CLI Usage​

# Fund an address with default amount (1000 ADA)
npx cardano-devkit topup addr_test1qz...

# Fund with specific amount (in lovelace)
npx cardano-devkit topup addr_test1qz... --amount 5000000000

# Fund multiple addresses
npx cardano-devkit topup addr1... addr2... addr3...

Programmatic Usage​

Using DevnetManager​

import { createDevnetManager } from 'cardano-devkit';

const devnet = createDevnetManager();

// Fund with specific amount (in lovelace)
const txHash = await devnet.topup(address, 1000_000_000n); // 1000 ADA
console.log('Funded:', txHash);

// Fund multiple addresses
const addresses = [address1, address2, address3];
for (const addr of addresses) {
  await devnet.topup(addr, 100_000_000n);
}

Using HTTP API​

// Direct API call
const response = await fetch('http://localhost:10080/api/v1/faucet', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    address: 'addr_test1qz...',
    amount: 1000_000_000 // 1000 ADA in lovelace
  })
});

const { txHash } = await response.json();
console.log('Transaction:', txHash);

Rate Limiting​

The faucet includes rate limiting to prevent abuse (even in local development):

SettingValue
Requests per address10 per minute
Maximum amount10,000 ADA per request
Cooldown60 seconds

Bypassing Rate Limits (Development Only)​

// For testing scenarios that need many funds
const devnet = createDevnetManager({
  faucetRateLimit: false // Disable rate limiting
});

Pre-funded Addresses​

The devnet genesis includes pre-funded addresses for immediate testing:

import { PREFUNDED_WALLETS } from 'cardano-devkit';

// Each wallet has 1,000,000 ADA
const wallet1 = PREFUNDED_WALLETS[0];
console.log('Address:', wallet1.address);
console.log('Seed:', wallet1.seed);

// Use in your app
lucid.selectWallet.fromSeed(wallet1.seed);

Checking Balance​

After funding, verify the balance:

const utxos = await lucid.utxosAt(address);
const balance = utxos.reduce(
  (sum, utxo) => sum + utxo.assets.lovelace,
  0n
);

console.log('Balance:', Number(balance) / 1_000_000, 'ADA');

Common Patterns​

Setup Test Accounts​

async function setupTestAccounts(count: number): Promise<string[]> {
  const devnet = createDevnetManager();
  const addresses: string[] = [];

  for (let i = 0; i < count; i++) {
    const seed = WalletHelper.generateSeed();
    lucid.selectWallet.fromSeed(seed);
    const address = await lucid.wallet().address();

    await devnet.topup(address, 1000_000_000n);
    addresses.push(address);
  }

  return addresses;
}

const testAccounts = await setupTestAccounts(5);

Wait for Funding Confirmation​

async function fundAndWait(address: string, amount: bigint) {
  const devnet = createDevnetManager();
  const txHash = await devnet.topup(address, amount);

  // Wait for confirmation
  await lucid.awaitTx(txHash);

  return txHash;
}

Batch Funding​

async function batchFund(
  addresses: string[],
  amountEach: bigint
): Promise<string[]> {
  const devnet = createDevnetManager();
  const txHashes: string[] = [];

  // Fund in parallel (rate limits permitting)
  const promises = addresses.map(addr =>
    devnet.topup(addr, amountEach)
  );

  return Promise.all(promises);
}

Faucet vs Testnet Faucets​

FeatureLocal FaucetTestnet Faucet
Rate limit10/min (configurable)Very strict
Amount limit10,000 ADA~1,000 ADA
AvailabilityAlwaysSometimes down
Confirmation100ms-1s~20 seconds
APIRESTWeb form

Troubleshooting​

"Rate limit exceeded"​

# Wait 60 seconds, or
npx cardano-devkit reset  # Reset rate limits

"Invalid address"​

# Ensure address starts with addr_test1 for testnet format
# Or addr_ for mainnet format

"Connection refused"​

# Check devnet is running
npx cardano-devkit status

# Restart if needed
npx cardano-devkit stop
npx cardano-devkit start

Next Steps​