Skip to content

Ethplorer API

alexesnsk edited this page Oct 3, 2024 · 140 revisions

Ethplorer’s API can be used to query information about Ethereum tokens, balances, addresses, history of transactions, contracts, and custom structures.

The same API is available for the list of supported chains.

For tracking many addresses at once, consider using the Bulk API Monitor.

There is no warranty for provided data. By using Ethplorer code, APIs, or widgets, you hereby agree with the Terms of Usage and Privacy Policy.

The API service is offered for free, but you are required to place references to the Ethplorer API on your website. Alternatively, you can use Ethplorer’s direct links to transactions or addresses.

API Key Limits

Freekey limits

The free API key for development purposes is freekey. It is not recommended for production use.

Please do not overload the servers. See fair usage limits below:

Requests are limited to 2 per second, 30/min, 200/hour, 1000/24hours, 3000/week.
Max number of transactions/operations in response: 100
Max allowed timestamp age: 30 days

Personal key limits

Only a single API key should be used per project. Creating several keys to exceed the limits violates our policy. For tracking many addresses, use the Bulk API.

To get a free personal API key, please sign up for an Ethplorer account and visit the API Panel section.

See personal API key usage limits below:

Requests per second: 10
Max number of transactions/operations in response: 1000
Max allowed timestamp age: 1 year

API Index

Supported chains

Ethplorer exposes the same endpoints and API Keys for all explorers Ethereum Mainnet, BNB Chain explorer, Blast explorer, Linea explorer and testnets at different base addresses.

For the blockchains other than Ethereum, consider ETH as it's own gas token in endpoints and responses. (BNB for BNB Chain, etc)

Network Address
Ethereum Mainnet https://api.ethplorer.io/
Ethereum Testnet Sepolia https://sepolia-api.ethplorer.io/
Ethereum Testnet Holesky https://holesky-api.ethplorer.io/
BNB Chain https://api.binplorer.com/
Linea chain Mainnet https://api.lineaplorer.build/
Blast L2 Mainnet https://api.blastplorer.info/
Blast L2 Testnet Sepolia https://sepolia-api.blastplorer.info/
Deprecated networks:
Ethereum Testnet Goerli https://goerli-api.ethplorer.io/

API Methods

An API token must be provided in the apiKey URL parameter for all methods.

Errors


Get last block

Returns the number of the last processed block on the chain.

Request

/getLastBlock

Response

{
    lastBlock:     # last scanned block number,
}

Examples

Request:

/getLastBlock?apiKey=freekey

Response:

{
    lastBlock: 9553012
}

Get token info

Returns information about a token defined by its contract address.

Request

/getTokenInfo/{address}

Response

{
    address:             # token address,
    totalSupply:         # total token supply,
    name:                # token name,
    symbol:              # token symbol,
    decimals:            # number of significant digits,
    price: {             # token price (false, if not available),
        rate:            # current price in currency,
        currency:        # token price currency (USD),
        diff:            # 24 hours rate difference (in percent),
        diff7d:          # 7 days rate difference (in percent),
        diff30d:         # 30 days rate difference (in percent),
        marketCapUsd:    # market cap (USD),
        availableSupply: # available supply,
        volume24h:       # 24 hours volume,
        ts:              # last rate update timestamp,
    },
    publicTags: []       # [optional] one or more tags from https://ethplorer.io/tag/,
    owner:               # token owner address,
    countOps:            # total count of token operations,
    txsCount:            # total number of transactions with token address,
    totalIn:             # total amount of incoming tokens,
    totalOut:            # total amount of outgoing tokens,
    transfersCount:      # total number of token operations,
    ethTransfersCount:   # [optional] total number of ethereum operations,
    holdersCount:        # total numnber of token holders,
    issuancesCount:      # total count of token issuances,
    image:               # [optional] token image url,
    description:         # [optional] token description,
    website:             # [optional] token website url,
    lastUpdated:         # last updated timestamp,
}

Examples

Request:

/getTokenInfo/0xf3db5fa2c66b7af3eb0c0b782510816cbe4813b8?apiKey=freekey

Response:

{
    address:             "0xf3db5fa2c66b7af3eb0c0b782510816cbe4813b8",
    totalSupply:         "250000000000",
    name:                "Everex",
    symbol:              "EVX",
    decimals:            "4",
    price: {
        rate:            0.230116419553,
        currency:        'USD',
        diff:            -4.16,
        diff7d:          -22.43,
        diff30d:         -3.7029295574431,
        marketCapUsd:    5223642.7238531,
        availableSupply: 22700000,
        volume24h:       962488.940022787
        ts:              1582883824
    },
    owner:               "0x73fdd81b897edae0dd8323958982dc4da50f470d",
    countOps:            102917,
    transfersCount:	     102917,
    holdersCount:        6625,
    issuancesCount:      0,
    lastUpdated:         1582883592
}

Get address info

Returns information about an address.

Request

/getAddressInfo/{address}?token={contract address}

Additional parameters:

token: {contract address}   # The response includes balances for all tokens in posession by the address, if any. To provide entries only for some token or tokens, specify them in the request URL.
showETHTotals: [true|false] # To add the total values of incoming and outgoing transactions for each token, set `showETHTotals` to `true`. Values are provided in **ETH**.
showTxsCount: [true|false] # To add the total number of incoming and outgoing transactions for address, set `showTxsCount` to `true`.

Response

{
    address: # address,
    ETH: {   # [optional] ETH specific information,
        balance:    # ETH balance (integer, may be slightly inaccurate on huge numbers),
        rawBalance: # balance in wei, as a string,
        totalIn:    # total incoming ETH value (showETHTotals parameter should be set to get this value),
        totalOut:   # total outgoing ETH value (showETHTotals parameter should be set to get this value)
    },
    contractInfo: {  # exists if the address is a contract
       creatorAddress:  # contract creator address,
       transactionHash: # contract creation transaction hash,
       timestamp:       # contract creation timestamp
    },
    tokenInfo:  # exists if the specified address is a token contract address (same format as token info),
    tokens: [   # exists if the specified address has any token balances
        {
            tokenInfo:  # token data (same format as token info),
            balance:    # token balance (integer, may be slightly inaccurate on huge numbers),
            rawBalance: # exact token balance, as a string,
            totalIn:    # total incoming token value,
            totalOut:   # total outgoing token value
        },
        ...
    ],
    countTxs:    # [optional] total number of incoming and outgoing transactions (including contract creation)
}

Examples

Request:

/getAddressInfo/0xff71cb760666ab06aa73f34995b42dd4b85ea07b?apiKey=freekey

Get transaction info

Returns information about a transaction.

Request

/getTxInfo/{transaction hash}

Response

{
    hash:          # transaction hash,
    timestamp:     # transaction block creation time,
    blockNumber:   # transaction block number,
    confirmations: # number of confirmations,
    success:       # true if there were no errors during transaction execution,
    from:          # source address,
    to:            # destination address,
    value:         # transaction value in ETH,
    input:         # transaction input data (hex),
    gasLimit:      # gas limit set to this transaction,
    gasUsed:       # gas used for this transaction,
    creates:       # address of created contract, if available,
    logs: [        # event logs
        {
            address: # log record address,
            topics:  # log record topics,
            data:    # log record data
        },
        ...
    ],
    operations: [  # list of token operations for this transaction
        {
            # Same format as /getTokenHistory
        },
        ...
    ]
}

Examples

Request:

/getTxInfo/0x6aa670c983425eba23314459c48ae89b3b8d0e1089397c56400ce2da5ece9d26?apiKey=freekey

Get last token operations

Returns a list of the last operations on a token.

Request

/getTokenHistory/{address}

Additional params

type: [**transfer**|mint|burn]         # Show operations only of specified type.
limit: {int}                           # Maximum number of operations to show. Can not be more than 1000, the default is 10.
timestamp: {Unix timestamp}            # Starting offset for listing operations.

Response

{
    operations: [
        {
            timestamp:       # operation timestamp,
            transactionHash: # transaction hash,
            tokenInfo:       # token data (same format as token info),
            type:            # operation type (transfer, mint, or burn),
            address:         # operation target address, if available,
            from:            # source address, if two addresses were involved,
            to:              # destination address, if two addresses were involved,
            value:           # operation value
        },
        ...
    ]
}

Examples

Show last 10 operations across all available tokens:

/getTokenHistory?apiKey=freekey

Show last 5 transfers for token at address 0xff71cb760666ab06aa73f34995b42dd4b85ea07b:

/getTokenHistory/0xff71cb760666ab06aa73f34995b42dd4b85ea07b?apiKey=freekey&type=transfer&limit=5

Get last address operations

Returns a list of the last operations involving an address.

Request

/getAddressHistory/{address}
type: [**transfer**|mint|burn]         # Show operations only of specified type.
limit: {int}                           # Maximum number of operations to show. Can not be more than 1000, the default is 10.
timestamp: {Unix timestamp}            # Starting offset for listing operations.

Additional parameters

token: {contract address}         # Show operations with only the specified token.
type: [**transfer**|mint|burn]        # Show operations only of specified type.
limit: {int}                      # Maximum number of operations to show. Can not be more than 1000, the default is 10.
timestamp: {Unix timestamp}       # Starting offset for listing operations.

Response

{
    operations: [
        {
            timestamp:       # operation timestamp,
            transactionHash: # transaction hash,
            tokenInfo:       # token data (same format as token info),
            type:            # operation type (transfer, mint, burn),
            address:         # operation target address, if available,
            from:            # source address, if two addresses were involved,
            to:              # destination address, if two addresses were involved,
            value:           # operation value
        },
        ...
    ]
}

Examples

Show last transfers for address 0x1f5006dff7e123d550abc8a4c46792518401fcaf:

/getAddressHistory/0x1f5006dff7e123d550abc8a4c46792518401fcaf?apiKey=freekey&type=transfer

Get address transactions

Returns list of transactions for a specified address.

Request

/getAddressTransactions/{address}

Additional params

limit: {int}                     # Maximum number of operations to show. Can not be more than 1000, default is 10.
timestamp: {Unix timestamp}      # Starting offset for listing transactions.
showZeroValues: [true|**false**] # Show transactions with zero ETH value.

Response

[
    {
        timestamp:       # operation timestamp
        from:            # source address, if two addresses were involved,,
        to:              # destination address, if two addresses were involved,
        hash:            # transaction hash,
        value:           # transaction value in ETH,
        input:           # input data,
        success:         # true if the transaction was completed, false otherwise
    },
]

Examples

/getAddressTransactions/0xb297cacf0f91c86dd9d2fb47c6d12783121ab780?apiKey=freekey

Get top

Get the top tokens sorted by one of the available criteria.

Request

/getTop

Additional parameters

criteria: {criterion} # Sort tokens by `trade` - trade volume, `cap` - capitalization, or `count` - total operations. The default is `trade`.
limit: {int}          # Maximum number of entries to show. Can not be more than 50, default is 50.

Response

{
    tokens: [
        {
            # token data (same format as token info),
            # token data by criteria and period,
        },
        ...
    ]
}

Examples

Shows top 50 tokens by capitalization:

/getTop?apiKey=freekey&criteria=cap

Get top tokens

Shows top 50 most active tokens for the last 30 days:

Request

/getTopTokens

Response

{
    tokens: [
        {
            # token data (same format as token info)
        },
        ...
    ]
}

Examples

/getTopTokens?apiKey=freekey

Get top token holders

Returns information about addresses holding the most of a token.

Request

/getTopTokenHolders/{address}

Additional params

limit: {int} # Maximum number of holders to show. Can not be more than 1000 for a private key, or 100 for `freekey`, default is 10.

Response

{
    holders: [
        {
            address:    # address of the holder,
            rawBalance: # exact token balance, as a string,
            balance:    # token balance as float,
            share:      # share of the holder in percent
        },
        ...
    ]
}

Examples

Shows top 100 token holders:

/getTopTokenHolders/0xf3Db5Fa2C66B7aF3Eb0C0b782510816cbe4813b8?apiKey=freekey&limit=100

Get new tradable tokens

Returns an array containing up to 100 new tradable tokens sorted by creation time.

Available for Ethereum Mainnet only

Request

/getTokensNew

Response

[
    {
        address:             # token address,
        totalSupply:         # total token supply,
        name:                # token name,
        symbol:              # token symbol,
        decimals:            # number of significant digits,
        price: {             # token price (false if not available)
            rate:            # current rate,
            currency:        # token price currency (USD),
            diff:            # 24 hours rate difference (in percent),
            diff7d:          # 7 days rate difference (in percent),
            diff30d:         # 30 days rate difference (in percent),
            marketCapUsd:    # market cap (USD),
            availableSupply: # available supply,
            volume24h:       # 24 hours volume,
            ts:              # last rate update timestamp
        },
        owner:               # token owner address,
        countOps:            # total count of token operations,
        txsCount:            # total number of transactions with token address,
        totalIn:             # total amount of incoming tokens,
        totalOut:            # total amount of outgoing tokens,
        transfersCount:      # total number of token operations,
        ethTransfersCount:   # [optional] total number of ethereum operations,
        holdersCount:        # total numnber of token holders,
        issuancesCount:      # total count of token issuances,
        image:               # [optional], token image url,
        description:         # [optional] token description,
        website:             # [optional] token website url,
        lastUpdated:         # last update timestamp,
        added:               # timestamp when the token was added
    },
    . . .
]

Examples

/getTokensNew?apiKey=freekey

Error response

{
    error: {
        code:    # error code (integer),
        message: # error message
    }
}

Error codes

Code Message HTTP Status
Authentication
1 Invalid API Key 401
133 API key temporarily suspended. Contact support. 403
135 Method disabled for this API key 403
136 getAddressHistory with token filter disabled for this API key 403
System errors
3 Database connection failed 503
999 Internal Error 503
Invalid parameters errors
101 Missing transaction hash 400
102 Invalid transaction hash format 400
104 Invalid address format 406
108 Invalid timestamp 406
111 Address is required 400
150 Address is not a token contract 400
404 Transaction not found 404