Base dev environment setup: Foundry, Hardhat, and RPC

30 minutes from now, you'll have Foundry installed, Base networks configured, testnet ETH in your wallet, and a local fork of Base mainnet running -- with $10B of real protocol state to test against.

Here's every step.

Prerequisites

You need these installed before starting:

• Node.js v18+ -- nodejs.org (check with node --version)
• Git -- git-scm.com
• A code editor -- VS Code recommended, with the Solidity extension
• A wallet -- MetaMask, Coinbase Wallet, or Base App for testnet interactions

Step 1: install Foundry

If you've only used Hardhat, Foundry will feel like upgrading from a bicycle to a motorcycle. Rust-based, compiles in seconds, and forge test runs against a forked mainnet with real liquidity.

Install

curl -L https://foundry.paradigm.xyz | bash
foundryup

Verify the installation:

forge --version
cast --version
anvil --version

You should see version numbers for all three. If foundryup isn't found, restart your terminal or add ~/.foundry/bin to your PATH.

What you get

forge compiles, tests, and deploys contracts. cast interacts with contracts from the command line. anvil runs a local Ethereum node (like Ganache, but faster). chisel is a Solidity REPL for quick experiments.

Initialize a Foundry project

forge init my-base-project
cd my-base-project

This creates a project with src/ for contracts, test/ for tests, script/ for deployment scripts, lib/ for dependencies, and foundry.toml for configuration.

Step 2: install Hardhat

If you prefer JavaScript/TypeScript tooling, or need Hardhat-specific plugins:

mkdir my-base-project-hardhat
cd my-base-project-hardhat
npm init -y
npm install --save-dev hardhat @nomicfoundation/hardhat-toolbox
npx hardhat init

Select "Create a TypeScript project" when prompted.

Install Base-relevant plugins

npm install --save-dev @nomicfoundation/hardhat-verify dotenv

Step 3: install OnchainKit (for frontend development)

If you're building a consumer app on Base, OnchainKit is the official React component library from Coinbase. It handles wallet connection (including Smart Wallet), identity, and transactions.

The fastest way to start a full app:

npx create-onchain@latest

This scaffolds a Next.js app with Smart Wallet integration, Base configuration, and OnchainKit components pre-configured.

For a Base App mini app (runs inside Base App and Farcaster clients):

npx create-onchain --mini

This scaffolds a MiniKit project -- mini apps that run within Farcaster Frames across Base App, Warpcast, and other clients. MiniKit provides hooks like useMiniKit, useAuthenticate, and useComposeCast for the Base App environment.

For existing projects:

npm install @coinbase/onchainkit wagmi viem@2.x @tanstack/react-query

See the Coinbase Smart Wallet guide for full integration details including MiniKit.

Step 4: configure Base networks

Base network details

Base Mainnet: Chain ID 8453, RPC URL https://mainnet.base.org, explorer at basescan.org.

Base Sepolia (testnet): Chain ID 84532, RPC URL https://sepolia.base.org, explorer at sepolia.basescan.org.

Alternative RPC providers

The public RPCs work for development but have rate limits. For production or heavy testing:

Alchemy offers 300M compute units per month free at https://base-mainnet.g.alchemy.com/v2/YOUR_KEY. Infura provides 100K requests per day at https://base-mainnet.infura.io/v3/YOUR_KEY. QuickNode has a generous free tier with custom endpoints. Ankr offers both public and premium at https://rpc.ankr.com/base.

Recommendation: sign up for Alchemy -- their free tier is generous and their Base support is solid.

Foundry configuration

Edit foundry.toml:

[profile.default]
src = "src"
out = "out"
libs = ["lib"]
solc = "0.8.24"

[rpc_endpoints]
base = "https://mainnet.base.org"
base_sepolia = "https://sepolia.base.org"

[etherscan]
base = { key = "${BASESCAN_API_KEY}", url = "https://api.basescan.org/api" }
base_sepolia = { key = "${BASESCAN_API_KEY}", url = "https://api-sepolia.basescan.org/api" }

Hardhat configuration

Edit hardhat.config.ts:

import { HardhatUserConfig } from "hardhat/config";
import "@nomicfoundation/hardhat-toolbox";
import "@nomicfoundation/hardhat-verify";
import * as dotenv from "dotenv";

dotenv.config();

const config: HardhatUserConfig = {
  solidity: "0.8.24",
  networks: {
    base: {
      url: process.env.BASE_RPC_URL || "https://mainnet.base.org",
      accounts: process.env.PRIVATE_KEY ? [process.env.PRIVATE_KEY] : [],
      chainId: 8453,
    },
    baseSepolia: {
      url: process.env.BASE_SEPOLIA_RPC_URL || "https://sepolia.base.org",
      accounts: process.env.PRIVATE_KEY ? [process.env.PRIVATE_KEY] : [],
      chainId: 84532,
    },
  },
  etherscan: {
    apiKey: {
      base: process.env.BASESCAN_API_KEY || "",
      baseSepolia: process.env.BASESCAN_API_KEY || "",
    },
    customChains: [
      {
        network: "base",
        chainId: 8453,
        urls: {
          apiURL: "https://api.basescan.org/api",
          browserURL: "https://basescan.org",
        },
      },
      {
        network: "baseSepolia",
        chainId: 84532,
        urls: {
          apiURL: "https://api-sepolia.basescan.org/api",
          browserURL: "https://sepolia.basescan.org",
        },
      },
    ],
  },
};

export default config;

Environment variables

Create a .env file (and add it to .gitignore):

PRIVATE_KEY=your_private_key_here
BASE_RPC_URL=https://mainnet.base.org
BASE_SEPOLIA_RPC_URL=https://sepolia.base.org
BASESCAN_API_KEY=your_basescan_api_key_here

Never commit your private key. Use a dedicated dev wallet with only testnet funds during development.

Step 5: get testnet ETH

You need Base Sepolia ETH to deploy and test contracts on the testnet.

Faucets

The Coinbase Developer Faucet at portal.cdp.coinbase.com/products/faucet provides up to 0.5 ETH and requires a Coinbase account. The Alchemy Faucet at alchemy.com/faucets/base-sepolia provides 0.5 ETH per day with an Alchemy account. The QuickNode Faucet at faucet.quicknode.com/base/sepolia provides varying amounts.

Bridge from Sepolia

If you have Ethereum Sepolia ETH, get it from sepoliafaucet.com and bridge to Base Sepolia via bridge.base.org in testnet mode.

Verify your balance

cast balance YOUR_WALLET_ADDRESS --rpc-url https://sepolia.base.org

Step 6: get a Basescan API key

You need this to verify contracts on Basescan so users can read your source code.

1. Go to basescan.org
2. Create an account
3. Go to API Keys in your profile
4. Create a new API key
5. Add it to your .env as BASESCAN_API_KEY

The same API key works for both mainnet and Sepolia Basescan.

Step 7: local fork testing

Forking Base locally lets you test against real mainnet state without spending real ETH. Essential for testing interactions with deployed protocols (Aerodrome, Uniswap, Morpho, etc.).

Anvil (Foundry)

# Fork Base mainnet
anvil --fork-url https://mainnet.base.org

# Fork at a specific block
anvil --fork-url https://mainnet.base.org --fork-block-number 20000000

Anvil starts a local node at http://127.0.0.1:8545 with 10 pre-funded accounts. You can deploy contracts locally, interact with real Base mainnet contracts, test without gas costs, and manipulate block timestamps and state.

Hardhat fork

Add to your hardhat.config.ts:

networks: {
  hardhat: {
    forking: {
      url: "https://mainnet.base.org",
    },
  },
}

Testing with the fork

A Foundry test that interacts with real USDC on your Base fork:

// test/ForkTest.t.sol
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

import "forge-std/Test.sol";

interface IERC20 {
    function balanceOf(address) external view returns (uint256);
    function decimals() external view returns (uint8);
}

contract BaseForkTest is Test {
    IERC20 usdc = IERC20(0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913);

    function testUsdcExists() public view {
        uint8 decimals = usdc.decimals();
        assertEq(decimals, 6);
    }

    function testWhaleBalance() public view {
        address whale = 0xAEf566ca7E84d1E736f999765a804687f39D9094;
        uint256 balance = usdc.balanceOf(whale);
        assertGt(balance, 0);
    }
}

Run it:

forge test --fork-url https://mainnet.base.org -vvv

Step 8: add Base to your wallet

MetaMask

Go to any Base dApp (like Aerodrome) and it'll prompt you to add the network. Or add manually: Network Name "Base", RPC URL https://mainnet.base.org, Chain ID 8453, Currency Symbol ETH, Block Explorer https://basescan.org.

Base App

Base is supported natively -- no setup needed. Base App (which replaced Coinbase Wallet) comes with Base pre-configured.

Other wallets

Most EVM wallets (Rainbow, Trust Wallet, Rabby) support Base natively or can add it via chainlist.org.

Quick reference checklist

• Node.js v18+ installed
• Foundry installed (forge --version works)
• Hardhat installed (if using)
• OnchainKit scaffolded (if building frontend)
• Base Mainnet RPC configured
• Base Sepolia RPC configured
• .env file created with private key and API keys
• .env added to .gitignore
• Basescan API key obtained
• Testnet ETH received on Base Sepolia
• Local fork tested with anvil or Hardhat
• Wallet configured with Base networks

Common issues and fixes

forge command not found after install: add ~/.foundry/bin to your PATH. Add export PATH="$PATH:$HOME/.foundry/bin" to ~/.zshrc or ~/.bashrc.

RPC rate limiting on public endpoints: switch to Alchemy or Infura. The public RPCs throttle heavy usage, especially during fork testing.

Basescan verification fails: wait 30-60 seconds after deployment before verifying. Basescan needs time to index the transaction. Double-check your compiler version matches exactly.

"Nonce too high" errors on testnet: reset your MetaMask account for that network under Settings, Advanced, Clear activity tab data.

Next steps

Your environment is ready. Here's where to go:

1. Deploy your first contract on Base -- write, deploy, and verify a real contract
2. Integrate Coinbase Smart Wallet -- add gasless onboarding for consumer apps
3. Build DeFi on Base -- integrate with Aerodrome, Morpho, and the DeFi stack
4. Discover what's shipping on Base with Sonarbot -- a curated feed of the best projects and agents building onchain

You've got the tools. Now build something.