forked from amilabs/Ethplorer
-
Notifications
You must be signed in to change notification settings - Fork 358
Ethplorer API
Egor Vasilyev edited this page Jun 22, 2023
·
140 revisions
Ethplorer’s API can be used to query information about Ethereum tokens, balances, addresses, history of transactions, contracts, and custom structures. There is no warranty for provided data.
For tracking many addresses at once, consider using the Bulk API Monitor.
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 for Ethereum Mainnet and the Kovan Testnet at different base addresses:
| Network | Address |
|---|---|
| Ethereum Mainnet | https://api.ethplorer.io/ |
| Kovan Testnet | https://kovan-api.ethplorer.io/ |
An API token must be provided in the apiKey URL parameter for all methods.
- getLastBlock
- getTokenInfo
- getAddressInfo
- getTxInfo
- getTokenHistory
- getAddressHistory
- getAddressTransactions
- getTop
- getTopTokens
- getTopTokenHolders
- getTokenHistoryGrouped
- getTokenPriceHistoryGrouped
- 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,
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 a histogram for operations with a token grouped by date.
Request
/getTokenHistoryGrouped/{address}
Additional params
period: {int} # How many days to show. Can not be more than 90, default is 30.
Response
{
countTxs: [
{
_id: {
year: # transaction year,
month: # transaction month,
day: # transaction day
},
ts: # timestamp of the first transaction in group,
cnt: # number of transactions in group
},
...
]
}
Examples
Show operations for token at address 0xf3db5fa2c66b7af3eb0c0b782510816cbe4813b8:
/getTokenHistoryGrouped/0xf3db5fa2c66b7af3eb0c0b782510816cbe4813b8?apiKey=freekey
Returns a histogram for token price grouped by date.
Request
/getTokenPriceHistoryGrouped/{address}
Additional params
period: {int} # How many days to show. Default is 365.
Response
{ history
{
countTxs: [ # grouped token history
{
_id: {
year: # transaction year,
month: # transaction month,
day: # transaction day
},
ts: # timestamp of the first transaction in group,
cnt: # number of transactions in group
},
...
],
prices: [ # grouped token price history
{
ts: # timestamp of the token price,
date: # date of the token price in YYYY-MM-DD format,
open: # open token price,
close: # close token price,
high: # hignest token price,
low: # lowest token price,
volume: # volume,
volumeConverted: # volume in USD,
average: # average token price
},
...
]
}
}
Examples
Get price history for the token at address 0x48c80f1f4d53d5951e5d5438b54cba84f29f32a5:
/getTokenPriceHistoryGrouped/0x48c80f1f4d53d5951e5d5438b54cba84f29f32a5?apiKey=freekey
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,
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 |