Getting started overview

Etherscan provides a block explorer for the Ethereum blockchain and a suite of developer APIs to programmatically access blockchain data. This guide focuses on the steps required to obtain API credentials and execute a foundational API request. The Etherscan API enables developers to retrieve information such as transaction histories, account balances, and smart contract details directly from the Ethereum network through various modules and endpoints, as described in the official Etherscan API documentation.

To begin utilizing the Etherscan API, you will:

  1. Register for an Etherscan account.
  2. Generate a unique API key from your account dashboard.
  3. Formulate an API request using a specific endpoint and your API key.
  4. Execute the request and process the JSON response.

Quick Reference: Etherscan Getting Started Steps

Step What to Do Where
1. Sign Up Create a new Etherscan user account. Etherscan Registration Page
2. Verify Email Confirm your email address to activate your account. Email inbox
3. Generate API Key Navigate to your API Keys section and create a new key. Etherscan API Key Dashboard
4. Review Documentation Understand API modules, actions, and parameters. Etherscan API Documentation
5. Make First Request Construct a URL with an API endpoint and your key. Local development environment (e.g., cURL, browser)

Create an account and get keys

Accessing the Etherscan API requires an API key, which is associated with a registered user account. Follow these steps to set up your account and retrieve your credentials:

  1. Register an Etherscan Account:

    Navigate to the Etherscan registration page. Provide a username, email address, and password. Complete the CAPTCHA to prove you are not a bot.

  2. Verify Your Email:

    After registration, Etherscan will send a verification email to the address you provided. Open this email and click the verification link to activate your account. Until your email is verified, you may have limited access to features, including API key generation.

  3. Log In:

    Once your email is verified, log in to your Etherscan account using your new credentials.

  4. Generate an API Key:

    From your Etherscan dashboard, locate and click on the 'API-KEYs' link, typically found in the top navigation or user menu. On the My API Keys page, click the '+ Add' button to create a new API key. You can optionally provide a name for your key to help manage multiple keys if you plan to use them for different applications.

    Your newly generated API key will be displayed. This key is a unique alphanumeric string that authenticates your requests to the Etherscan API. Treat your API key as sensitive information to prevent unauthorized usage.

Your first request

After obtaining your API key, you can make your first API call. A common starting point is to retrieve the Ether balance for a specific address. The Etherscan API categorizes its functionalities into modules, each with specific actions. For account balances, you will use the account module and the balancemulti action.

API Endpoint Structure

Etherscan API requests follow a standard URL structure:

https://api.etherscan.io/api?
   module=account
   &action=balancemulti
   &address=[COMMA_SEPARATED_ADDRESSES]
   &tag=latest
   &apikey=[YOUR_API_KEY]
  • module: Specifies the API module (e.g., account, transaction, contract).
  • action: Specifies the action within the module (e.g., balancemulti, gettxlist).
  • address: The Ethereum address(es) you are querying, separated by commas.
  • tag: The block parameter, typically latest for the most recent data.
  • apikey: Your unique Etherscan API key.

Example: Get Ether Balance for an Address

Let's retrieve the Ether balance for the Ethereum Foundation's DAO address (0xbb9bc244d798123fde783fcc1c72d3bb8c189413).

1. Construct the URL:

Replace [YOUR_API_KEY] with the API key you generated.

https://api.etherscan.io/api?
   module=account
   &action=balancemulti
   &address=0xbb9bc244d798123fde783fcc1c72d3bb8c189413
   &tag=latest
   &apikey=YOUR_API_KEY

2. Execute the Request:

You can execute this request using various tools. For a quick test, you can paste the URL directly into your web browser, or use a command-line tool like cURL:

curl "https://api.etherscan.io/api?module=account&action=balancemulti&address=0xbb9bc244d798123fde783fcc1c72d3bb8c189413&tag=latest&apikey=YOUR_API_KEY"

3. Interpret the Response:

The API will return a JSON object similar to this (actual balance will vary):

{
  "status": "1",
  "message": "OK",
  "result": [
    {
      "account": "0xbb9bc244d798123fde783fcc1c72d3bb8c189413",
      "balance": "161066035032900000000000"
    }
  ]
}

The "balance" field is expressed in Wei, the smallest denomination of Ether. To convert Wei to Ether, divide by 1018. For example, 161066035032900000000000 Wei is equivalent to 161066.0350329 Ether. For more details on Wei conversion, refer to external resources such as the Mozilla Developer Network's definition of Wei.

Common next steps

After successfully making your first request, consider these common next steps to deepen your integration with Etherscan:

  • Explore More API Modules: Etherscan offers a variety of modules beyond account balances. Investigate the transaction module for retrieving transaction details, the contract module for interacting with smart contract ABIs, or the token module for ERC-20 token information. Detailed documentation is available on the Etherscan API documentation portal.
  • Implement Error Handling: Production applications should always include robust error handling. The Etherscan API typically returns a status: "0" and a descriptive message field for errors. Your application should be prepared to parse these messages and react appropriately.
  • Manage API Key Security: Never embed your API key directly in client-side code or commit it to public repositories. Use environment variables or secure configuration management for server-side applications. For client-side applications, consider using a backend proxy to make API calls securely.
  • Monitor Usage Limits: The free API tier has rate limits, typically 5 calls/second/IP and 100,000 calls/day. Monitor your usage to avoid hitting these limits. For higher throughput, explore Etherscan's paid API plans.
  • Integrate with Programming Languages: While Etherscan does not officially provide SDKs, community-contributed libraries exist for various programming languages (e.g., Python, Node.js). These libraries often abstract away the URL construction and JSON parsing, simplifying development. Alternatively, you can implement HTTP requests directly using standard libraries like Python's requests or JavaScript's fetch.
  • Understand Blockchain Data Structures: A deeper understanding of Ethereum's underlying data structures, such as transactions, blocks, and smart contracts, will enable more effective use of the Etherscan API. Resources like Google's guide to understanding the Ethereum blockchain can provide foundational knowledge.

Troubleshooting the first call

If your initial API call encounters issues, check the following common problems:

  • Incorrect API Key:

    Ensure your API key is correctly copied and pasted into the apikey parameter of your request URL. Missing characters or extra spaces can invalidate the key. Verify it against the key displayed on your Etherscan API key dashboard.

  • Unverified Email:

    If your Etherscan account email is not verified, API key access might be restricted. Log in to Etherscan and check for any outstanding email verification prompts.

  • Invalid Module or Action:

    Double-check the module and action parameters against the Etherscan API documentation. Typos or incorrect combinations will result in an error.

  • Missing Required Parameters:

    Some API actions require specific parameters (e.g., address for balance queries, txhash for transaction details). Ensure all necessary parameters are included and correctly formatted in your URL.

  • Rate Limit Exceeded:

    If you make too many requests in a short period, Etherscan may temporarily block your IP address or return a rate limit error. Wait a few moments before retrying, or consider upgrading your API plan if consistently hitting limits.

  • Incorrect URL Encoding:

    While less common for simple GET requests, ensuring your URL parameters are correctly URL-encoded can prevent issues, especially with special characters in parameters.

  • Network Issues:

    Verify your internet connection and ensure no firewall or proxy settings are blocking outgoing requests to api.etherscan.io.

  • API Server Status:

    Occasionally, an API service might experience downtime. Check Etherscan's official website or channels for any service status updates if you suspect a broader issue.