forked from amilabs/Ethplorer
-
Notifications
You must be signed in to change notification settings - Fork 358
Ethplorer API
alexesnsk edited this page Oct 3, 2023
·
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 Binplorer (BNB Chain explorer).
For the Binplorer API, consider ETH as BNB (in endpoints and responses)
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.
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
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
Ethplorer exposes the same endpoints and API Keys for Ethereum Mainnet and the BNB Chain explorer at different base addresses:
| Network | Address |
|---|---|
| Ethereum Mainnet | https://api.ethplorer.io/ |
| Ethereum Testnet Goerli | https://goerli-api.ethplorer.io |
| Ethereum Testnet Sepolia | https://sepolia-api.ethplorer.io/ |
| BNB Chain | https://api.binplorer.com/ |
An API token must be provided in the apiKey URL parameter for all methods.
- getLastBlock
- getTokenInfo
- getAddressInfo
- getTxInfo
- getTokenHistory
- getAddressHistory
- getAddressTransactions
- getTop
- getTopTokens
- getTopTokenHolders
- getTokensNew
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
}
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
}
Returns information about an address.
Request
/getAddressInfo/{address}?token={contract address}&showETHTotals=false&showTxsCount=false
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
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
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
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
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 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
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
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,
balance: # token balance,
share: # share of the holder in percent
},
...
]
}
Examples
Shows top 100 token holders:
/getTopTokenHolders/0xf3Db5Fa2C66B7aF3Eb0C0b782510816cbe4813b8?apiKey=freekey&limit=100
Returns an array containing up to 100 new tradable tokens sorted by creation time.
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: {
code: # error code (integer),
message: # error message
}
}
| 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 |