@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.

$3

- src/etherscan/EtherscanService.ts
- Modified getVerificationStatus() function
- Modified isAlreadyVerified() function

- dist/src/etherscan/EtherscanService.js
- Compiled JavaScript with same fixes

$3

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

After (fixed):
`javascript
// ✅ 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

$3

`bash
npm install github:pinto-org/hardhat-etherscan


or


yarn add github:pinto-org/hardhat-etherscan
`

$3

`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:

$3

`javascript
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"
};
`

$3

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

---

🚀 Usage

Same as the original package:

`bash
npx hardhat verify --network base
`

$3

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

$3

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

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

Then verify with:

`bash
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) |

$3

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

$3

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:

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

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

---

🔧 Maintenance

- Base version: @nomiclabs/hardhat-etherscan@3.1.8 (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
`

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.