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 (exceed and you will be blocked).

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.


We would also like to thank the following API Service Sponsors:

____________________
Gold Sponsors
 

____________________
Community Sponsor
 


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
[BETA] Get a list of 'Internal' Transactions by Address
Get "Internal Transactions" by Transaction Hash
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" );
    }            
});
                           

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

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)
* 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




Websockets


[Beta] The WebSocket API allows developers to receive Real-Time notifications about new transactions. The Websocket Demo Page can be useful for seeing how this works. The following policies apply:

* To keep the socket connection alive send a {"event":"ping"} every 20 seconds
* Maximum number of 30 subscriptions per client
* Maximum of 10 concurrent socket connections per/IP
* After connecting to the socket you have to subscribe to an event within the next 60 seconds or get disconnected
* In the event of a disconnection, your client will need to reconnect and re-subscribe to events


Connection URL

  • wss://socket.etherscan.io/wshandler

Send a Ping (every 20 secs to keep the connection alive)
  • {"event": "ping"}
  • You will receive a Pong response:
    {"event": "pong"}

Subscribe to receive new txns for a Single Address
  • {"event": "txlist", "address": "0x2a65aca4d5fc5b5c859090a6c34d164135398226"}
  • Successful subscription response:
    {"event":"subscribe-txlist", "status":"1", "message":"OK, 0x2a65aca4d5fc5b5c859090a6c34d164135398226"}
    Failure subscription response:
    {"event":"subscribe-txlist", "status":"0", "message":"NOTOK, duplicate subscription 0x2a65aca4d5fc5b5c859090a6c34d164135398226"}



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 and 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)