Etherscan V2 API migration

[rosahadi]

Version of Hardhat

3

What happened?

I'm using Hardhat v3 with @nomicfoundation/hardhat-verify and trying to verify a contract on Sepolia.
When I call my verify script, I get this error:

HardhatError: HHE80023: The contract verification request failed:
"You are using a deprecated V1 endpoint, switch to Etherscan API V2 using https://docs.etherscan.io/v2-migration"

Root Cause

In packages/hardhat-verify/src/internal/etherscan.ts line 60, the constructor has:

this.apiUrl = etherscanConfig.apiUrl ?? ETHERSCAN_API_URL;

The ETHERSCAN_API_URL constant is already set to the V2 endpoint (https://api.etherscan.io/v2/api), but when etherscanConfig.apiUrl is provided (possibly from old chain configs), it uses the deprecated V1 endpoint instead.

Fix

I removed the fallback to etherscanConfig.apiUrl to always use the V2 constant:

this.apiUrl = ETHERSCAN_API_URL;

Tested locally and verification now works

Minimal reproduction steps

1. Install Hardhat v3 with @nomicfoundation/hardhat-verify
2. Configure Etherscan verification with a V2 API key
3. Try to verify a contract on Sepolia
4. The verification fails with the V1 endpoint deprecation error

Search terms

No response

[Jayke770]

+1

[gskril]

+1

[fvictorio]

Hey @rosahadi, the problem here seems to be that a config with an invalid (outdated) custom URL will fail, and the suggested solution is to ignore all custom URLs? Because I don't think we'd want to do that.

I'm probably lacking information about this part:

but when etherscanConfig.apiUrl is provided (possibly from old chain configs)

How exactly this happens? Are these migrations to HH2 that are using a custom v1 endpoint?

[rosahadi]

Hi @fvictorio, The issue isn't coming from user configuration or HH2 migrations. It's actually coming from Hardhat's built-in chain descriptors.
Looking at the code, I found that the chain descriptors file (v-next/hardhat/src/internal/builtin-plugins/network-manager/chain-descriptors.ts) still has V1 Etherscan URLs hardcoded. For example, Sepolia uses:

apiUrl: "https://api-sepolia.etherscan.io/api" // V1 endpoint

When the Etherscan constructor runs with:

this.apiUrl = etherscanConfig.apiUrl ?? ETHERSCAN_API_URL;

The etherscanConfig.apiUrl is being populated from these chain descriptors, so it uses the outdated V1 URL instead of falling back to the V2 constant (ETHERSCAN_API_URL).

Mine was a temporary fix to make the verify work but the proper solution should either:

1. Update all Etherscan URLs in the chain descriptors to V2 endpoints, or
2. Add logic to detect V1 Etherscan URLs and automatically upgrade them to V2 while preserving other custom URLs