A deployment from an existing Hardhat project to a custom EVM chain needs a named networks entry with a JSON-RPC url, an explicit chainId, and funded signer accounts; Hardhat 3 also needs type: "http", while explorer verification needs a separate chain mapping.
-
Result: a deploy script runs against the intended chain, and the contract can be verified on its block explorer.
-
Have ready: the Chain ID, RPC URL, funded deployer key, and the explorer’s verification API URL.
Start with the chain’s own documentation for its Chain ID and RPC URL. Cross-check both on Chainlist so the endpoint you put in Hardhat matches the network you intend to deploy to. Chainlist also identifies the native currency you need in the deployer account to pay transaction fees.
The RPC URL is the address Hardhat uses to send JSON-RPC requests. The Chain ID identifies the chain that answers those requests. The explorer’s browser URL serves contract pages; its API URL accepts verification submissions. Get the API URL from the explorer’s documentation, since a browser address alone is insufficient.
Configure the network and explorer
Configure one network name consistently across deployment commands and verification settings. I recommend setting chainId even though Hardhat treats it as optional: for a new chain, the early check is more useful than silently accepting whichever node an RPC URL reaches. Hardhat’s network configuration documents the connection fields.
-
Add the network entry. In hardhat.config.ts, give your network a name such as customNet. For Hardhat 3, its entry has the shape customNet: { type: "http", url: configVariable("CUSTOM_RPC_URL"), chainId: YOUR_CHAIN_ID, accounts: [configVariable("DEPLOYER_PRIVATE_KEY")] }. Replace YOUR_CHAIN_ID with the decimal number from the chain’s documentation. The entry now tells Hardhat where to connect, which chain to expect, and which account can sign a deployment. In Hardhat 2, use the same url, chainId, and accounts fields without type.
-
Supply the key outside the config file. Set CUSTOM_RPC_URL and DEPLOYER_PRIVATE_KEY through Hardhat 3 configuration variables, or load environment variables in a Hardhat 2 project. Never paste the private key into hardhat.config.ts. Confirm that the corresponding public address holds enough of the chain’s native currency for deployment gas. You should be able to identify a funded deployer address without exposing its key.
-
Map the custom explorer. With Hardhat 2’s hardhat-verify plugin, add etherscan.customChains containing { network: "customNet", chainId: YOUR_CHAIN_ID, urls: { apiURL: "EXPLORER_API_URL", browserURL: "EXPLORER_BROWSER_URL" } }. If that explorer requires an API key, set etherscan.apiKey for the same network name. Hardhat 2’s verification configuration uses this shape. Hardhat 3 uses chainDescriptors keyed by Chain ID instead: put the explorer’s url and apiUrl under blockExplorers, and configure its verification provider under verify. Hardhat 3’s verification guide shows that structure. In either version, the visible result is a mapping from the deployed chain to the explorer that will receive its source code.
-
Read the connected Chain ID before deploying. Make a small script that requests eth_chainId from the selected network and prints its decimal value. In Hardhat 3, obtain a provider with await hre.network.create(), then call provider.request({ method: "eth_chainId" }); convert the returned hexadecimal value with Number(BigInt(value)). Run it as npx hardhat run scripts/check-chain.ts --network customNet. A Hardhat 2 script can request the same method through hre.network.provider.send("eth_chainId"). The printed number should equal the configured chainId. Hardhat compares the configured value with the node’s reported ID and halts on a mismatch before deployment: Hardhat 2 reports HH101, while Hardhat 3 reports HHE708. That failure catches a wrong or redirected RPC endpoint before it receives a deploy transaction.
-
Deploy, then verify. Run your existing deployment script with --network customNet and keep the resulting contract address. Run npx hardhat verify --network customNet CONTRACT_ADDRESS, supplying the original constructor arguments when the contract has them. The step is complete when the script prints the expected Chain ID, deployment returns an address on that chain, and the explorer accepts the verification.
Related questions
These Hardhat tasks use the same chain details for different purposes.
How do I verify contracts on a custom block explorer?
Configure the explorer’s verification API separately from the deployment RPC. Use customChains with apiURL and browserURL in Hardhat 2, or chainDescriptors with apiUrl and url in Hardhat 3. Submit the deployed address and the constructor arguments used for that deployment.
How do I fork a custom EVM chain in Hardhat?
Point a simulated network’s forking.url at the custom chain’s RPC endpoint. Hardhat 3 uses type: "edr-simulated" for that local network; Hardhat 2 places forking under its hardhat network. A fork is useful for testing against remote state, while deployment uses the customNet HTTP entry above.
When the check script prints the Chain ID you configured and the deploy command returns a contract address, you have confirmed that Hardhat reached the intended chain with a working signer.