# Contract Endpoints
Contract endpoints provide access to smart contract data including ABIs, source code, and verification functionality.
## Table of Contents
- [Get Contract ABI](#get-contract-abi)
- [Get Contract Source Code](#get-contract-source-code)
- [Get Contract Creation](#get-contract-creation)
- [Verify Contract Source Code](#verify-contract-source-code)
- [Check Verification Status](#check-verification-status)
- [Verify Proxy Contract](#verify-proxy-contract)
- [Get Verified Contracts](#get-verified-contracts)
---
## Get Contract ABI
Retrieve the Application Binary Interface (ABI) for a verified contract.
### MCP Tool
`get-contract-abi`
### Endpoint
```
GET https://api.etherscan.io/v2/api
```
### Parameters
| Parameter | Required | Type | Description |
|-----------|----------|------|-------------|
| chainid | Yes | number | Network chain ID |
| module | Yes | string | Set to `contract` |
| action | Yes | string | Set to `getabi` |
| address | Yes | string | Contract address |
| apikey | Yes | string | Your API key |
### Example Request
```bash
curl "https://api.etherscan.io/v2/api?chainid=1&module=contract&action=getabi&address=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48&apikey=YourApiKey"
```
### Example Response
```json
{
"status": "1",
"message": "OK",
"result": "[{\"constant\":true,\"inputs\":[],\"name\":\"name\",\"outputs\":[{\"name\":\"\",\"type\":\"string\"}],\"payable\":false,\"stateMutability\":\"view\",\"type\":\"function\"},{\"constant\":false,\"inputs\":[{\"name\":\"_spender\",\"type\":\"address\"},{\"name\":\"_value\",\"type\":\"uint256\"}],\"name\":\"approve\",\"outputs\":[{\"name\":\"\",\"type\":\"bool\"}],\"payable\":false,\"stateMutability\":\"nonpayable\",\"type\":\"function\"}]"
}
```
### Notes
- ABI is returned as a JSON string
- Parse the result to get the ABI array
- Only available for verified contracts
- Returns error for unverified contracts
- Essential for contract interaction
### Usage Example
```javascript
const response = await fetch('https://api.etherscan.io/v2/api?chainid=1&module=contract&action=getabi&address=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48&apikey=YourApiKey');
const data = await response.json();
const abi = JSON.parse(data.result);
```
---
## Get Contract Source Code
Get the source code and metadata for a verified contract.
### MCP Tool
`get-contract-source`
### Endpoint
```
GET https://api.etherscan.io/v2/api
```
### Parameters
| Parameter | Required | Type | Description |
|-----------|----------|------|-------------|
| chainid | Yes | number | Network chain ID |
| module | Yes | string | Set to `contract` |
| action | Yes | string | Set to `getsourcecode` |
| address | Yes | string | Contract address |
| apikey | Yes | string | Your API key |
### Example Request
```bash
curl "https://api.etherscan.io/v2/api?chainid=1&module=contract&action=getsourcecode&address=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48&apikey=YourApiKey"
```
### Example Response
```json
{
"status": "1",
"message": "OK",
"result": [
{
"SourceCode": "pragma solidity ^0.8.0;\n\ncontract Token {\n...",
"ABI": "[{...}]",
"ContractName": "USDC",
"CompilerVersion": "v0.8.19+commit.7dd6d404",
"OptimizationUsed": "1",
"Runs": "200",
"ConstructorArguments": "",
"EVMVersion": "Default",
"Library": "",
"LicenseType": "MIT",
"Proxy": "0",
"Implementation": "",
"SwarmSource": ""
}
]
}
```
### Response Fields
| Field | Description |
|-------|-------------|
| SourceCode | Contract source code (may be JSON for multi-file) |
| ABI | Contract ABI as JSON string |
| ContractName | Name of the contract |
| CompilerVersion | Solidity compiler version used |
| OptimizationUsed | "1" if optimization enabled, "0" otherwise |
| Runs | Number of optimization runs |
| ConstructorArguments | ABI-encoded constructor arguments |
| EVMVersion | EVM version (e.g., "london", "paris") |
| Library | Library addresses used |
| LicenseType | SPDX license identifier |
| Proxy | "1" if proxy contract, "0" otherwise |
| Implementation | Implementation contract address (if proxy) |
| SwarmSource | Swarm source hash |
### Notes
- Source code format depends on verification method:
- Single file: Plain Solidity code
- Multi-file: JSON with file structure
- Vyper: Vyper source code
- For proxy contracts, check `Implementation` field
- License types: MIT, GPL-3.0, Apache-2.0, None, etc.
---
## Get Contract Creation
Get information about how and when a contract was deployed.
### MCP Tool
`get-contract-creation`
### Endpoint
```
GET https://api.etherscan.io/v2/api
```
### Parameters
| Parameter | Required | Type | Description |
|-----------|----------|------|-------------|
| chainid | Yes | number | Network chain ID |
| module | Yes | string | Set to `contract` |
| action | Yes | string | Set to `getcontractcreation` |
| contractaddresses | Yes | string | Comma-separated contract addresses (max 5) |
| apikey | Yes | string | Your API key |
### Example Request
```bash
curl "https://api.etherscan.io/v2/api?chainid=1&module=contract&action=getcontractcreation&contractaddresses=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48&apikey=YourApiKey"
```
### Example Response
```json
{
"status": "1",
"message": "OK",
"result": [
{
"contractAddress": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
"contractCreator": "0x95ba4cf87d6723ad9c0db21737d862be80e93911",
"txHash": "0x2a...",
"blockNumber": "6082465",
"timestamp": "1533324504",
"contractFactory": "0x...",
"creationBytecode": "0x60806040..."
}
]
}
```
### Notes
- Can query up to **5 contracts** at once
- Returns creator address and deployment transaction
- Useful for:
- Verifying contract authenticity
- Finding deployment details
- Factory pattern analysis
- `contractFactory` is populated if contract was deployed by a factory
---
## Verify Contract Source Code
Submit a contract for source code verification.
### MCP Tool
`verify-contract`
### Endpoint
```
POST https://api.etherscan.io/v2/api
```
### Parameters
| Parameter | Required | Type | Description |
|-----------|----------|------|-------------|
| chainid | Yes | number | Network chain ID |
| module | Yes | string | Set to `contract` |
| action | Yes | string | Set to `verifysourcecode` |
| contractaddress | Yes | string | Contract address to verify |
| sourceCode | Yes | string | Contract source code (or JSON for multi-file) |
| codeformat | Yes | string | `solidity-single-file` or `solidity-standard-json-input` |
| contractname | Yes | string | Contract name |
| compilerversion | Yes | string | Compiler version (e.g., `v0.8.19+commit.7dd6d404`) |
| optimizationUsed | Yes | string | "0" or "1" |
| runs | No | string | Optimization runs (default: 200) |
| constructorArguements | No | string | ABI-encoded constructor arguments |
| evmversion | No | string | EVM version (e.g., "paris", "london") |
| licenseType | No | string | License type (1=No License, 3=MIT, 5=GPL-3.0, etc.) |
| apikey | Yes | string | Your API key |
### Example Request
```bash
curl -X POST "https://api.etherscan.io/v2/api" \
-d "chainid=1" \
-d "module=contract" \
-d "action=verifysourcecode" \
-d "contractaddress=0x..." \
-d "sourceCode=pragma solidity ^0.8.0;..." \
-d "codeformat=solidity-single-file" \
-d "contractname=MyContract" \
-d "compilerversion=v0.8.19+commit.7dd6d404" \
-d "optimizationUsed=1" \
-d "runs=200" \
-d "licenseType=3" \
-d "apikey=YourApiKey"
```
### Example Response
```json
{
"status": "1",
"message": "OK",
"result": "j3qg6rnwvvzqwjgyvwxxbrvpnbgfzvyh6ux3d9y8qwcgkdrxsm"
}
```
### Notes
- Returns a GUID to check verification status
- Process may take a few seconds to complete
- Use [Check Verification Status](#check-verification-status) to monitor progress
- Source code must match deployed bytecode exactly
- Constructor arguments must be ABI-encoded
### License Types
| Code | License |
|------|---------|
| 1 | No License (None) |
| 2 | The Unlicense (Unlicense) |
| 3 | MIT License (MIT) |
| 4 | GNU General Public License v2.0 (GNU GPLv2) |
| 5 | GNU General Public License v3.0 (GNU GPLv3) |
| 6 | GNU Lesser General Public License v2.1 (GNU LGPLv2.1) |
| 7 | GNU Lesser General Public License v3.0 (GNU LGPLv3) |
| 8 | BSD 2-clause "Simplified" license (BSD-2-Clause) |
| 9 | BSD 3-clause "New" Or "Revised" license (BSD-3-Clause) |
| 10 | Mozilla Public License 2.0 (MPL-2.0) |
| 11 | Open Software License 3.0 (OSL-3.0) |
| 12 | Apache 2.0 (Apache-2.0) |
| 13 | GNU Affero General Public License (GNU AGPLv3) |
| 14 | Business Source License (BSL 1.1) |
---
## Check Verification Status
Check the status of a contract verification submission.
### MCP Tool
`check-verification`
### Endpoint
```
GET https://api.etherscan.io/v2/api
```
### Parameters
| Parameter | Required | Type | Description |
|-----------|----------|------|-------------|
| chainid | Yes | number | Network chain ID |
| module | Yes | string | Set to `contract` |
| action | Yes | string | Set to `checkverifystatus` |
| guid | Yes | string | GUID from verification submission |
| apikey | Yes | string | Your API key |
### Example Request
```bash
curl "https://api.etherscan.io/v2/api?chainid=1&module=contract&action=checkverifystatus&guid=j3qg6rnwvvzqwjgyvwxxbrvpnbgfzvyh6ux3d9y8qwcgkdrxsm&apikey=YourApiKey"
```
### Example Response (Success)
```json
{
"status": "1",
"message": "OK",
"result": "Pass - Verified"
}
```
### Example Response (Pending)
```json
{
"status": "0",
"message": "NOTOK",
"result": "Pending in queue"
}
```
### Example Response (Failed)
```json
{
"status": "0",
"message": "NOTOK",
"result": "Fail - Unable to verify. Error: Constructor arguments are incorrect"
}
```
### Possible Results
| Result | Description |
|--------|-------------|
| Pass - Verified | Verification successful |
| Pending in queue | Verification in progress |
| Already Verified | Contract was already verified |
| Fail - Unable to verify | Verification failed (check error message) |
### Notes
- Poll this endpoint after submitting verification
- Recommended: Wait 5 seconds between checks
- Verification typically completes in 10-30 seconds
- Save the GUID to check status later
---
## Verify Proxy Contract
Verify a proxy contract and link it to its implementation.
### MCP Tool
`verify-proxy`
### Endpoint
```
POST https://api.etherscan.io/v2/api
```
### Parameters
| Parameter | Required | Type | Description |
|-----------|----------|------|-------------|
| chainid | Yes | number | Network chain ID |
| module | Yes | string | Set to `contract` |
| action | Yes | string | Set to `verifyproxycontract` |
| address | Yes | string | Proxy contract address |
| expectedimplementation | No | string | Expected implementation address |
| apikey | Yes | string | Your API key |
### Example Request
```bash
curl -X POST "https://api.etherscan.io/v2/api" \
-d "chainid=1" \
-d "module=contract" \
-d "action=verifyproxycontract" \
-d "address=0x..." \
-d "apikey=YourApiKey"
```
### Example Response
```json
{
"status": "1",
"message": "OK",
"result": "k2jcqzxvvvczqwjgyvwxxbrvpnbgfzvyh6ux3d9y8qwcgkdrxsm"
}
```
### Notes
- Proxy contract must already be verified
- Implementation contract must be verified
- Supports common proxy patterns:
- EIP-1967 (Transparent Proxy)
- EIP-1822 (UUPS Proxy)
- OpenZeppelin Proxy patterns
- Returns GUID to check status
- Use `expectedimplementation` to verify against specific implementation
---
## Get Verified Contracts
Get a list of recently verified contracts.
### MCP Tool
`get-verified-contracts`
### Endpoint
```
GET https://api.etherscan.io/v2/api
```
### Parameters
| Parameter | Required | Type | Description |
|-----------|----------|------|-------------|
| chainid | Yes | number | Network chain ID |
| module | Yes | string | Set to `contract` |
| action | Yes | string | Set to `listcontracts` |
| page | No | number | Page number (default: 1) |
| offset | No | number | Records per page (max 100, default: 10) |
| apikey | Yes | string | Your API key |
### Example Request
```bash
curl "https://api.etherscan.io/v2/api?chainid=1&module=contract&action=listcontracts&page=1&offset=10&apikey=YourApiKey"
```
### Example Response
```json
{
"status": "1",
"message": "OK",
"result": [
{
"SourceCode": "...",
"ABI": "[...]",
"ContractName": "MyToken",
"CompilerVersion": "v0.8.19+commit.7dd6d404",
"OptimizationUsed": "1",
"Runs": "200",
"ConstructorArguments": "",
"EVMVersion": "paris",
"Library": "",
"LicenseType": "MIT",
"Proxy": "0",
"Implementation": "",
"SwarmSource": "",
"ContractAddress": "0x..."
}
]
}
```
### Notes
- Returns most recently verified contracts
- Useful for monitoring new deployments
- Includes all verification metadata
- Limited to 100 records per request
---
## Compiler Versions
### Common Solidity Versions
```
v0.8.24+commit.e11b9ed9
v0.8.23+commit.f704f362
v0.8.22+commit.4fc1097e
v0.8.21+commit.d9974bed
v0.8.20+commit.a1b79de6
v0.8.19+commit.7dd6d404
v0.8.18+commit.87f61d96
v0.8.17+commit.8df45f5f
```
Get full list: [Solidity Compiler Releases](https://github.com/ethereum/solidity/releases)
## Best Practices
### Verification Tips
1. **Match Deployment Settings**: Use exact compiler settings from deployment
2. **Flatten Multi-File Contracts**: Use tools like `hardhat-flatten` or `truffle-flattener`
3. **Include Constructor Args**: ABI-encode constructor arguments correctly
4. **Check Optimization**: Verify if optimization was enabled during deployment
5. **Test Locally First**: Compile locally and verify bytecode matches
### Security Considerations
- Verify all contracts in production
- Review verified source code before interacting
- Check for proxy patterns and implementations
- Verify contract creator and deployment transaction
## Error Messages
| Error | Solution |
|-------|----------|
| Constructor arguments are incorrect | ABI-encode constructor args properly |
| Unable to locate matching bytecode | Check compiler version and settings |
| Already verified | Contract is already verified |
| Invalid compiler version | Use exact compiler version format |
| Optimization settings mismatch | Match optimization settings from deployment |
## Rate Limits
- Free tier: **5 calls/second**
- Verification submissions: **5 per day** (free tier)
- Status checks: Unlimited
## See Also
- [Account Endpoints](./account-endpoints.md)
- [Token Endpoints](./tokens-endpoints.md)
- [Etherscan Verification Guide](https://docs.etherscan.io/tutorials/verifying-contracts-programmatically)
