Introduction


The Etherscan Ethereum Developer APIs are provided as a community service and without warranty, so please just use what you need and no more. They support both GET/POST requests and a rate limit of 5 requests/sec.

To use the API service please create a FREE Api-Key Token from within the ClientPortal->MyApiKey area which you can then use with all your api requests. Either a link back or mention that your app is "Powered by Etherscan.io APIs" would be appreciated.


Account APIs


Get Ether Balance for a single Address


Get Ether Balance for multiple Addresses in a single call
Get a list of 'Normal' Transactions By Address
Get a list of 'Internal' Transactions by Address
Get "Internal Transactions" by Transaction Hash
Get a list of "ERC20 - Token Transfer Events" by Address
Get list of Blocks Mined by Address

Contract APIs


Newly verified Contracts are synced to the API servers within 5 minutes or less

Get Contract ABI for Verified Contract Source Codes


A simple sample for retrieving the contractABI using Web3.js and Jquery to interact with a contract

var Web3 = require('web3');
var web3 = new Web3(new Web3.providers.HttpProvider());
var version = web3.version.api;
            
$.getJSON('http://api.etherscan.io/api?module=contract&action=getabi&address=0xfb6916095ca1df60bb79ce92ce3ea74c37c5d359', function (data) {
    var contractABI = "";
    contractABI = JSON.parse(data.result);
    if (contractABI != ''){
        var MyContract = web3.eth.contract(contractABI);
        var myContractInstance = MyContract.at("0xfb6916095ca1df60bb79ce92ce3ea74c37c5d359");
        var result = myContractInstance.memberId("0xfe8ad7dd2f564a877cc23feea6c0a9cc2e783715");
        console.log("result1 : " + result);            
        var result = myContractInstance.members(1);
        console.log("result2 : " + result);
    } else {
        console.log("Error" );
    }            
});
                           

Get Contract Source Code for Verified Contract Source Codes


[BETA] Verify Source Code

    1. Requires a valid Etherscan APIkey, will reject if otherwise
    2. Current daily limit of 100 submissions per day per user (subject to change)
    3. Only supports HTTP post due to max transfer size limitations for http get
    4. Supports up to 10 different library pairs
    5. Contracts that use "imports" will need to have the code concatenated into one file as we do not support "imports" in separate files. You can try using the Blockcat solidity-flattener or SolidityFlattery
    6. List of supported solc versions, only solc version v0.4.11 and above is supported. Ex. v0.4.25+commit.59dbf8f1
    7. Upon successful submission you will receive a GUID (50 characters) as a receipt.
    8. You may use this GUID to track the status of your submission
    9. Verified Source Codes will be displayed at contractsVerified

    See Demo Source Verification Submission Code at Source Code Verification Sample

    Source Code Submission Gist (returns a guid as part of the result upon success):
  • //Submit Source Code for Verification
    $.ajax({
        type: "POST",                       //Only POST supported  
        url: "//api.etherscan.io/api", //Set to the  correct API url for Other Networks
        data: {
            apikey: $('#apikey').val(),                     //A valid API-Key is required        
            module: 'contract',                             //Do not change
            action: 'verifysourcecode',                     //Do not change
            contractaddress: $('#contractaddress').val(),   //Contract Address starts with 0x...     
            sourceCode: $('#sourceCode').val(),             //Contract Source Code (Flattened if necessary)
            contractname: $('#contractname').val(),         //ContractName
            compilerversion: $('#compilerversion').val(),   // see http://etherscan.io/solcversions for list of support versions
            optimizationUsed: $('#optimizationUsed').val(), //0 = Optimization used, 1 = No Optimization
            runs: 200,                                      //set to 200 as default unless otherwise         
            constructorArguements: $('#constructorArguements').val(),   //if applicable
            libraryname1: $('#libraryname1').val(),         //if applicable, a matching pair with libraryaddress1 required
            libraryaddress1: $('#libraryaddress1').val(),   //if applicable, a matching pair with libraryname1 required
            libraryname2: $('#libraryname2').val(),         //if applicable, matching pair required
            libraryaddress2: $('#libraryaddress2').val(),   //if applicable, matching pair required
            libraryname3: $('#libraryname3').val(),         //if applicable, matching pair required
            libraryaddress3: $('#libraryaddress3').val(),   //if applicable, matching pair required
            libraryname4: $('#libraryname4').val(),         //if applicable, matching pair required
            libraryaddress4: $('#libraryaddress4').val(),   //if applicable, matching pair required
            libraryname5: $('#libraryname5').val(),         //if applicable, matching pair required
            libraryaddress5: $('#libraryaddress5').val(),   //if applicable, matching pair required
            libraryname6: $('#libraryname6').val(),         //if applicable, matching pair required
            libraryaddress6: $('#libraryaddress6').val(),   //if applicable, matching pair required
            libraryname7: $('#libraryname7').val(),         //if applicable, matching pair required
            libraryaddress7: $('#libraryaddress7').val(),   //if applicable, matching pair required
            libraryname8: $('#libraryname8').val(),         //if applicable, matching pair required
            libraryaddress8: $('#libraryaddress8').val(),   //if applicable, matching pair required
            libraryname9: $('#libraryname9').val(),         //if applicable, matching pair required
            libraryaddress9: $('#libraryaddress9').val(),   //if applicable, matching pair required
            libraryname10: $('#libraryname10').val(),       //if applicable, matching pair required
            libraryaddress10: $('#libraryaddress10').val()  //if applicable, matching pair required
        },
        success: function (result) {
            console.log(result);
            if (result.status == "1") {
                //1 = submission success, use the guid returned (result.result) to check the status of your submission.
                // Average time of processing is 30-60 seconds
                document.getElementById("postresult").innerHTML = result.status + ";" + result.message + ";" + result.result;
                // result.result is the GUID receipt for the submission, you can use this guid for checking the verification status
            } else {
                //0 = error
                document.getElementById("postresult").innerHTML = result.status + ";" + result.message + ";" + result.result;
            }
            console.log("status : " + result.status);
            console.log("result : " + result.result);
        },
        error: function (result) {
            console.log("error!");
            document.getElementById("postresult").innerHTML = "Unexpected Error"
        }
    });
                                        

    Check Source code verification submission status:
  • //Check Source Code Verification Status
    $.ajax({
        type: "GET",
        url: "//api.etherscan.io/api",
        data: {
            guid: 'ezq878u486pzijkvvmerl6a9mzwhv6sefgvqi5tkwceejc7tvn', //Replace with your Source Code GUID receipt above
            module: "contract",
            action: "checkverifystatus"
        },
        success: function (result) {
            console.log("status : " + result.status);   //0=Error, 1=Pass 
            console.log("message : " + result.message); //OK, NOTOK
            console.log("result : " + result.result);   //result explanation
            $('#guidstatus').html(">> " + result.result);
        },
        error: function (result) {
            alert('error');
        }
    });
                                        

Transaction APIs


[BETA] Check Contract Execution Status (if there was an error during contract execution)
Note: isError":"0" = Pass , isError":"1" = Error during Contract Execution


[BETA] Check Transaction Receipt Status (Only applicable for Post Byzantium fork transactions)
Note: status: 0 = Fail, 1 = Pass. Will return null/empty value for pre-byzantium fork

Event Logs


[Beta] The Event Log API was designed to provide an alternative to the native eth_getLogs. Below are the list of supported filter parameters:

  • fromBlock, toBlock, address
  • topic0, topic1, topic2, topic3 (32 Bytes per topic)
  • topic0_1_opr (and|or between topic0 & topic1), topic1_2_opr (and|or between topic1 & topic2), topic2_3_opr (and|or between topic2 & topic3), topic0_2_opr (and|or between topic0 & topic2), topic0_3_opr (and|or between topic0 & topic3), topic1_3_opr (and|or between topic1 & topic3)
* fromBlock and toBlock accepts the blocknumber (integer, NOT hex) or 'latest' (earliest & pending is NOT supported yet)
* Topic Operator (opr) choices are either 'and' or 'or' and are restricted to the above choices only
* fromBlock and toBlock parameters are required
* Either the address and/or topic(X) parameters are required, when multiple topic(X) parameters are used the topicX_X_opr (and|or operator) is also required
* For performance & security considerations, only the first 1000 results are return. So please narrow down the filter parameters

Here are some examples of how this filter maybe used:

Get Event Logs from block number 379224 to 'latest' Block, where log address = 0x33990122638b9132ca29c723bdf037f1a891a70c and topic[0] = 0xf63780e752c6a54a94fc52715dbc5518a3b4c3c2833d301a204226548a2a8545


Get Event Logs from block number 379224 to block 400000 , where log address = 0x33990122638b9132ca29c723bdf037f1a891a70c, topic[0] = 0xf63780e752c6a54a94fc52715dbc5518a3b4c3c2833d301a204226548a2a8545 'AND' topic[1] = 0x72657075746174696f6e00000000000000000000000000000000000000000000

Geth/Parity Proxy APIs


The following are the limited list of supported Proxied APIs for Geth available through Etherscan. For the list of the parameters and descriptions please see https://github.com/ethereum/wiki/wiki/JSON-RPC. Parameters provided should be named like in the examples below. For compatibility with Parity, please prefix all hex strings with "0x"


eth_blockNumber
Returns the number of most recent block



eth_getBlockByNumber
Returns information about a block by block number.



eth_getUncleByBlockNumberAndIndex
Returns information about a uncle by block number.



eth_getBlockTransactionCountByNumber
Returns the number of transactions in a block from a block matching the given block number



eth_getTransactionByHash
Returns the information about a transaction requested by transaction hash



eth_getTransactionByBlockNumberAndIndex
Returns information about a transaction by block number and transaction index position



eth_getTransactionCount
Returns the number of transactions sent from an address



eth_sendRawTransaction
Creates new message call transaction or a contract creation for signed transactions



eth_getTransactionReceipt
Returns the receipt of a transaction by transaction hash



eth_call
Executes a new message call immediately without creating a transaction on the block chain



eth_getCode
Returns code at a given address



eth_getStorageAt (**experimental)
Returns the value from a storage position at a given address.



eth_gasPrice
Returns the current price per gas in wei.



eth_estimateGas
Makes a call or transaction, which won't be added to the blockchain and returns the used gas, which can be used for estimating the used gas




Token Info


Get ERC20-Token TotalSupply by ContractAddress


[Deprecated] Get Token TotalSupply by TokenName (Supported TokenNames: DGD, MKR, FirstBlood, HackerGold, ICONOMI, Pluton, REP, SNGLS). This has feature been deprecated, instead use the Api above to look up any ERC20 token supply by its contract address


Get ERC20-Token Account Balance for TokenContractAddress

[Deprecated] Get Token Account Balance by known TokenName (Supported TokenNames: DGD, MKR, FirstBlood, ICONOMI, Pluton, REP, SNGLS). This feature has been deprecated, instead use the Api above to look up any ERC20 token balance by its contract address



General Stats


Get Total Supply of Ether


Get ETHER LastPrice Price



Misc Tools & Utilities



These are 3rd party tools and utilities created by the community and we do not provide any support or warranties for the solutions listed below


py-etherscan-api module (corpetty)



node API (Sebastian Schürmann)