@nomiclabs/hardhat-etherscan - Etherscan v2 API Compatible Fork

A fork of @nomiclabs/hardhat-etherscan with fixes for Etherscan v2 API compatibility on any chain.

Note: The original @nomiclabs/hardhat-etherscan package is officially deprecated. For Hardhat 3.0+, use @nomicfoundation/hardhat-verify instead. This fork exists for projects still using Hardhat 2.x that need v2 API support with query parameters.

🐛 The Problem

When verifying contracts on any chain that uses Etherscan v2 API with query parameters (e.g., Basescan, or any custom explorer), the original plugin fails with:

Error in plugin @nomiclabs/hardhat-etherscan: The Etherscan API responded with a failure status.
The verification may still succeed but should be checked manually.
Reason: Missing chainid parameter (required for v2 api)

Root cause: Many Etherscan v2 API implementations require query parameters like chainid in all requests. The original plugin was stripping these parameters when building query strings for verification status checks.

Affected chains: Any chain where you configure apiURL with query parameters:

• Base (Basescan)
• Any L2 or sidechain using Etherscan API v2
• Custom block explorers requiring query parameters

✅ The Fix

This fork preserves existing URL query parameters (like chainid) when making API requests.

Changed Files

• src/etherscan/EtherscanService.ts

  • Modified getVerificationStatus() function
  • Modified isAlreadyVerified() function

• dist/src/etherscan/EtherscanService.js

  • Compiled JavaScript with same fixes

Technical Details

Before (broken):

// ❌ Old behavior - overwrites chainid parameter
const parameters = new URLSearchParams({ ...req });
const urlWithQuery = new URL(url);
urlWithQuery.search = parameters.toString(); // chainid LOST!

After (fixed):

// ✅ New behavior - preserves chainid parameter
const urlWithQuery = new URL(url);
const mergedParams = new URLSearchParams(urlWithQuery.search); // Get existing params
for (const [key, value] of Object.entries(req)) {
  mergedParams.set(key, value); // Merge new params
}
urlWithQuery.search = mergedParams.toString(); // chainid PRESERVED!

📦 Installation

Using npm/yarn with GitHub dependency

npm install github:pinto-org/hardhat-etherscan
# or
yarn add github:pinto-org/hardhat-etherscan

In your package.json

{
  "dependencies": {
    "@nomiclabs/hardhat-etherscan": "github:pinto-org/hardhat-etherscan#master"
  }
}

⚙️ Configuration

Configure your hardhat.config.js with any Etherscan v2 API URL that includes query parameters:

Example: Base Network (Basescan)

require("@nomiclabs/hardhat-etherscan");

module.exports = {
  networks: {
    base: {
      url: process.env.BASE_RPC_URL || "https://mainnet.base.org",
      accounts: [process.env.PRIVATE_KEY]
    }
  },
  etherscan: {
    apiKey: {
      base: process.env.BASESCAN_API_KEY
    },
    customChains: [
      {
        network: "base",
        chainId: 8453,
        urls: {
          // ↓ Important: Query parameters (like chainid) are now preserved
          apiURL: "https://api.basescan.org/api?chainid=8453",
          browserURL: "https://basescan.org"
        }
      }
    ]
  },
  solidity: "0.8.20"
};

Generic Pattern for Any Chain

customChains: [
  {
    network: "your-chain",
    chainId: <YOUR_CHAIN_ID>,
    urls: {
      // Add any required query parameters to the API URL
      apiURL: "https://api.your-explorer.com/api?chainid=<YOUR_CHAIN_ID>",
      browserURL: "https://your-explorer.com"
    }
  }
]

🚀 Usage

Same as the original package:

npx hardhat verify --network base <contract-address> <constructor-args>

Example

npx hardhat verify --network base 0x1234...5678 "Constructor arg 1" 42

Complex Arguments

For contracts with complex constructor arguments, create an arguments.js file:

module.exports = [
  "0x1234567890123456789012345678901234567890",
  50,
  {
    x: 10,
    y: 5
  }
];

Then verify with:

npx hardhat verify --network base --constructor-args arguments.js 0x1234...5678

🌐 Compatibility

| Package | Version | |---------|---------| | Hardhat | 2.x | | Node.js | 14+ | | Networks | All Etherscan-compatible explorers (especially v2 API) |

Tested With

• ✅ Base (Basescan mainnet & testnet)
• ✅ Ethereum mainnet (Etherscan)
• ✅ Any chain using Etherscan API v2 with query parameters

Compatible With

This fork works with any block explorer that:

• Uses Etherscan-compatible API
• Requires query parameters in the API URL
• Implements v2 API standards

Examples include L2s, sidechains, and custom explorers requiring chainid or other query parameters.

⚠️ For Hardhat 3.0+ Users

If you're using Hardhat 3.0 or later, use the official replacement package instead:

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

This fork is specifically for Hardhat 2.x projects that cannot easily upgrade.

🔧 Maintenance

• Base version: @nomiclabs/[email protected] (final release)
• Status: Frozen at this version (original package is deprecated)
• Updates: Only critical security fixes will be applied

🤝 Contributing

Found another issue or have improvements?

1. Open an issue describing the problem
2. Fork this repo
3. Submit a PR with your fix
4. Include tests if possible

📚 Related Links

• Original package on npm
• Hardhat GitHub
• Basescan API Documentation
• Pinto Protocol

📄 License

MIT (same as original package)

💬 Credits

• Original package: Nomic Labs LLC
• Fork maintained by: Pinto
• Contributors: See GitHub contributors

🐛 When You Need This Fork

If you see any of these errors, you need this fork:

Missing chainid parameter (required for v2 api)

Missing <parameter> parameter

Or any error indicating that query parameters are being stripped from your API URL.

Solution: Use this fork with query parameters in your apiURL configuration as shown above. This fork preserves all query parameters throughout the verification process.