You've deployed your contract. The address works, transactions go through, and yet on a block explorer, all anyone sees is a wall of bytecode. Verification fixes that. It proves that the deployed bytecode was produced from a specific piece of source code, and the explorer then shows your source, your ABI and a "Read/Write contract" interface. For anyone deciding whether to trust your contract, an unverified one is a red flag.
In this post I'll walk through verification with Hardhat 3: the setup, the commands, how to handle constructor arguments, what the common failures mean, and one 2026 catch about which chains work on Etherscan's free plan. I also need to be upfront about what I tested, and I've said it in the box at the top of the post: I tested the configuration and the CLI, but I did not verify a real contract.
What verification really does
The Hardhat documentation puts it plainly: verification proves that a deployed contract's bytecode comes from specific source code, so users and tools can inspect the original source on explorers like Etherscan and Blockscout, or on a verification service like Sourcify. The explorer recompiles your source with the settings you submit and checks that the result matches the code on-chain. If a single compiler setting differs, the bytecode differs and verification fails. That is why most verification problems are really about reproducing the build exactly.
Step 1: the plugin and the configuration
If you created your project with npx hardhat --init and chose anything other than the minimal template, hardhat-verify is already included. Otherwise install it and add it to the plugins array. Then tell it where your Etherscan API key lives. The Hardhat docs mention that this plugin uses Etherscan's API v2, so a single key works across every supported chain.
The config below also shows the part people get wrong. The documentation's own example puts the key as a string in the config file and warns that it is a security risk. Instead, Hardhat 3 provides configVariable("NAME"), which reads the value from an environment variable or from the encrypted keystore (npx hardhat keystore set NAME), so secrets never land in Git.
hardhat.config.ts
import hardhatToolboxMochaEthersPlugin from "@nomicfoundation/hardhat-toolbox-mocha-ethers";
import { configVariable, defineConfig } from "hardhat/config";
export default defineConfig({
plugins: [hardhatToolboxMochaEthersPlugin],
solidity: {
profiles: {
default: {
version: "0.8.34",
},
production: {
version: "0.8.34",
settings: {
optimizer: {
enabled: true,
runs: 200,
},
},
},
},
},
verify: {
etherscan: {
apiKey: configVariable("ETHERSCAN_API_KEY"),
},
},
networks: {
hardhatMainnet: {
type: "edr-simulated",
chainType: "l1",
},
hardhatOp: {
type: "edr-simulated",
chainType: "op",
},
sepolia: {
type: "http",
chainType: "l1",
url: configVariable("SEPOLIA_RPC_URL"),
accounts: [configVariable("SEPOLIA_PRIVATE_KEY")],
},
},
});
With this config, I ran a verify command without setting any variables. Hardhat stopped immediately with Error HHE7: Configuration Variable "SEPOLIA_RPC_URL" not found and told me I could define it through a plugin like hardhat-keystore or as an environment variable. That is the behavior you want: it fails before sending anything anywhere.
Step 2: the command
Verification takes the network you deployed to and the contract's address:
npx hardhat verify --network sepolia 0xYourContractAddress
Run without a subtask, verify submits to Etherscan, Blockscout and Sourcify. You can target one with npx hardhat verify etherscan .... The CLI help I read lists these three subtasks, plus options for --contract (useful when several contracts share a name), --libraries-path and --force.
Step 3: constructor arguments
If your constructor takes arguments, you must pass the same values you used to deploy, in the same order. For anything beyond a couple of simple values, use a module file instead of shell arguments. The ERC-20 from my token tutorial has the constructor TeamToken(address initialOwner, uint256 cap_), so its file looks like this (the address is a placeholder):
constructor-args.ts
// Arguments must match what was used at deployment, in the same order as the constructor.
// TeamToken(address initialOwner, uint256 cap_)
const constructorArgs = [
"0x1111111111111111111111111111111111111111", // initialOwner: placeholder, use your real deployer/owner
1000000n * 10n ** 18n, // cap: 1,000,000 tokens with 18 decimals
];
export default constructorArgs;
npx hardhat verify --network sepolia \
--constructor-args-path ignition/constructor-args.ts \
0xYourContractAddress
The file exports the array as its default export. Note the n suffix on the big number: constructor arguments for uint256 are best written as bigint to avoid silent rounding.
BscScan, Polygonscan and the "which chains are free" catch
Years ago you needed a separate account and key for Etherscan, BscScan and Polygonscan. With Etherscan's API v2, one key plus a chain ID covers the supported chains, and Hardhat 3's plugin is built on it. So the same ETHERSCAN_API_KEY variable serves them all, and Hardhat selects the chain from the network you pass.
The catch is plans. When I read Etherscan's supported-chains page on 17 November 2026, it listed 57 chains, noting that 46 had free-tier access and 11 needed a paid plan. Ethereum mainnet (chain ID 1), Sepolia, Polygon (137) and Arbitrum One (42161) were marked free. BNB Smart Chain (56) and its testnet (97) were marked "Paid tier only", as were Base, OP Mainnet and Avalanche C-Chain. The page also says that source-code and ABI endpoints are available on every chain for every plan, but those are the read endpoints. It doesn't say whether contract verification submissions are covered on the free tier for those chains, so I can't tell you either way. Check before you plan a BNB Chain launch around a free key.
The good news is that you have alternatives. Blockscout and Sourcify need no API key in Hardhat's setup, and the plugin supports them out of the box. Many chains have a Blockscout explorer. And for a chain that Hardhat doesn't know about, you can add a chainDescriptors entry with the explorer's name and API URL.
Build profiles: the quiet cause of failures
By default, verify uses the production build profile, as that is the recommended profile for deployment, and Hardhat Ignition deployments use it automatically. If you deployed with a different profile (say default, with the optimizer off), the bytecode won't match. Pass --build-profile default to match, and you may also need to run npx hardhat build with the same profile to regenerate the right artifacts. In the project behind these posts, I configured both a default profile and a production profile with the optimizer on at 200 runs, so this is a real distinction, not a theoretical one.
Troubleshooting checklist
These are the failure causes the Hardhat docs list, with how I'd work through them:
- "Contract not found" right after deploying. The explorer may not have indexed it yet. The docs say waiting a minute is normally enough.
- Wrong constructor arguments. Compare your file against the deployment script, including order and units. You can also read the creation transaction's input data on the explorer to see the encoded arguments.
- Source code changed since deployment. If you deployed weeks ago, the code in your repository may have moved on. Check out the commit you deployed from.
- Different build profile. See above. Try
--build-profilewith the other profile, starting withdefault. - Missing library addresses. If your contract links external libraries, pass
--libraries-path. - Already verified. Use
--forceonly if you really need to resubmit.
Habits that save time
- Record the deployment. Save the commit hash, compiler version, build profile and constructor arguments when you deploy. Verification is just replaying them.
- Verify on a testnet first. Practise the whole flow on Sepolia before mainnet, where a mistake is less embarrassing. The testnet-to-mainnet checklist covers the rest of the sequence.
- Keep secrets out of config. Use the keystore or environment variables, and never commit a private key or API key.
- Verify proxies and implementations. For an upgradeable setup, the implementation behind the proxy must be verified too, and the explorer's "proxy" features may need a manual step. Read the explorer's docs for that, since I haven't tested it.
Short checklist
hardhat-verifyin the plugin list, key throughconfigVariable.- Same commit, compiler and build profile as the deployment.
- Constructor arguments in a file, as
bigintwhere needed. - A plan check for your target chain on Etherscan, or use Blockscout or Sourcify.
- Verify on a testnet first and record every setting you used.
Shipping your first contract?
I help teams build, test and deploy Solidity projects, including the verification and release steps that are easy to get wrong. If you'd like a hand, get in touch.
See services Get in touchWhat I ran this against
- Hardhat 3.22.0 with the bundled
@nomicfoundation/hardhat-verifyplugin on 17 November 2026. I confirmed that theverifytask and itsetherscan,blockscoutandsourcifysubtasks exist (npx hardhat verify --help), that the configuration below loads, and that Hardhat fails fast with its HHE7 error when a configuration variable is missing. - I did not verify a live contract. That needs a funded testnet deployment, an RPC URL and an Etherscan API key, which I did not use. The commands below follow the Hardhat 3 documentation; I have not seen them succeed against a real explorer.
- Etherscan's plan-by-chain table changes. I read it on 17 November 2026; check the live page before you rely on it.
Sources checked
- Hardhat 3 documentation, "Verifying smart contracts" (the
hardhat-verifyplugin, Etherscan API v2 and a single key, Blockscout and Sourcify,--constructor-args-path, theproductionbuild profile and the troubleshooting list): hardhat.org. - Etherscan API documentation, "Supported Chains" (chain IDs and which chains need a paid plan; it states that source-code and ABI endpoints are available on all chains for every plan): docs.etherscan.io/supported-chains.