Step 9: Get Testnet Funds

Phase: implement

Context

You have the build_plan confirmed. If payment_network is "base-sepolia" (testnet), you need free test USDC before creating the project. If mainnet, skip this step.

What to do

If using testnet (default)

You need a wallet address on Base Sepolia to receive test USDC. If you (the agent) have wallet capabilities, use your own wallet. If not, you'll need the user to provide a wallet address.

Step 1: Check existing USDC balance first. The wallet may already have funds from a previous faucet drip. Only call the faucet if the balance is insufficient.

// USDC on Base Sepolia
const USDC_ADDRESS = "0x036CbD53842c5426634e7929541eC2318f3dCF7e";

// Check balance via viem readContract
const balance = await publicClient.readContract({
  address: USDC_ADDRESS,
  abi: [{ name: 'balanceOf', type: 'function', stateMutability: 'view',
           inputs: [{ name: 'account', type: 'address' }],
           outputs: [{ name: '', type: 'uint256' }] }],
  functionName: 'balanceOf',
  args: [walletAddress],
});

// USDC has 6 decimals — $0.15 covers project ($0.10) + deploy ($0.05)
const MIN_REQUIRED = 150000n; // 0.15 USDC
if (balance >= MIN_REQUIRED) {
  // Skip faucet — wallet already has sufficient funds
} else {
  // Call the faucet (Step 2 below)
}

Step 2: Call the faucet (only if balance < $0.15):

POST https://api.run402.com/faucet/v1
Content-Type: application/json

{
  "address": "0x...user_or_agent_wallet_address"
}

Response (success):

{
  "transactionHash": "0x...",
  "amount": "0.25",
  "token": "USDC",
  "network": "base-sepolia"
}

Rate limit: 1 faucet drip per 24 hours per IP address. If you get a 429 response, tell the user: "We need to wait before getting more test funds. Let's try again in a bit."

What to tell the user:

"I'm grabbing some free test funds to set up your project. This is completely free — just test money for trying things out."

If using mainnet

Skip this step. The user will pay with real USDC when creating the project. Proceed directly to Step 10.

Expected output

  • wallet_address — The wallet address that received test USDC
  • faucet_tx — Transaction hash from the faucet (or "skipped" if mainnet)

Memory directive