Skip to Content
CTRL K
GuidesFund Test Wallets

Fund test wallets

Set or top up native and ERC20 balances for any address on your Stagenet — no faucet drips, no whale impersonation, no mints from the token contract. Use it to prepare addresses before a test run, simulate a user with a specific portfolio, or wipe an account back to zero between scenarios.

For native tokens, addBalance credits the address and setBalance overwrites it. For ERC20s, the equivalents (addERC20Balance, setERC20Balance) write directly to the token’s balanceOf storage slot.

Prerequisites

  • A Stagenet — create one in the dashboard if you don’t have one yet
  • The contract.dev CLI installed and configured at your project root (only required for the CLI snippets below):
npm install contract.dev
npx contract.dev init --rpc-url=<YOUR_STAGENET_RPC_URL>

Fund a fresh wallet

If you don’t have a test address yet, generate one and fund it in a single step:

npx contract.dev generate-wallet

This prints a new address and private key, and credits the address with 1,000,000 of the Stagenet’s native token. Copy the private key from the output — it isn’t stored anywhere.

Generated wallet
  Address:     0xAbC1234567890abcdef1234567890abcdef12345
  Private key: 0x1234567890abcdef...

Funded with 1,000,000 ETH.

Top up native balance

Credit an existing address with native tokens (ETH / MON / POL / HYPE, depending on the Stagenet’s fork chain).

From the CLI — amounts can be wei (decimal or 0x-hex) or carry a unit suffix:

npx contract.dev balance add 0x1111... "1 ether"
npx contract.dev balance add 0x1111... 1000000000000000000   # +1 ETH in wei
npx contract.dev balance add 0x1111... "1000000 wei"

From the SDK — amounts are always in wei:

const alice = "0x1111111111111111111111111111111111111111";
await stagenet.addBalance(alice, 10n ** 18n);   // +1 ETH

Overwrite native balance

balance set / setBalance replace the balance instead of adding to it. Use this to pin an account to an exact amount or wipe it to zero:

npx contract.dev balance set 0x1111... "5 ether"
npx contract.dev balance set 0x1111... 0          # wipe
await stagenet.setBalance(alice, 5n * 10n ** 18n);
await stagenet.setBalance(alice, 0n);

Top up an ERC20 balance

Credit an address with an ERC20 token. Pass the holder, the token contract, and an amount in the token’s smallest unit:

# +1 USDC (6 decimals)
npx contract.dev erc20-balance add 0x1111... \
  0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 \
  1000000
const usdc = "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48";
await stagenet.addERC20Balance(alice, usdc, 1_000_000n); // +1 USDC

The CLI does not look up the token’s decimals(), so amounts are always shown as raw integers.

Overwrite an ERC20 balance

npx contract.dev erc20-balance set 0x1111... 0xA0b8...eB48 0
await stagenet.setERC20Balance(alice, usdc, 0n);

The ERC20 balance helpers write directly to the token’s balanceOf storage slot — they do not adjust totalSupply. If your code reads totalSupply (e.g. for share-price math), set it explicitly with setStorageAt.

Tokens with non-standard balanceOf layouts (e.g. rebasing tokens) may not be writable through these helpers. In that case, write the slot directly.

Seed many wallets in a script

For test fixtures it’s often easiest to drive the funding from the SDK:

import { createStagenet } from "contract.dev";
 
const stagenet = createStagenet("<YOUR_STAGENET_RPC_URL>");
const usdc = "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48";
 
const testers = [
  "0x1111111111111111111111111111111111111111",
  "0x2222222222222222222222222222222222222222",
  "0x3333333333333333333333333333333333333333",
];
 
for (const address of testers) {
  await stagenet.setBalance(address, 10n ** 19n);          // 10 ETH
  await stagenet.setERC20Balance(address, usdc, 10_000_000_000n); // 10,000 USDC
}

Next steps

Last updated on
Impersonate a Mainnet AccountOverride Contract State