Mempool API
Connect to Blocknative transaction monitoring services directly with webhooks
Overview
This documentation describes how to connect to and use Blocknative's transaction monitoring service using webhooks. The service delivers near real time notifications of Ethereum transaction state changes via POSTs to your URL (webhook). Each state change is a JSON payload with all the transaction details.
- 1.Create a Blocknative account by clicking the Sign up button on Mempool Explorer and following the instructions. Account creation requires email confirmation to complete.
- 2.Blocknative will create a Default API key for your account that you can use. You can create additional API keys from your account page on explorer.blocknative.com/account by clicking the Add new API key button to the upper right.
- 3.Secret keys additionally are available to be generated for API keys which allow secure usage of configuration modification endpoints.
Add new API key button
API Key creation form
Create a new webhook for an API key by clicking the "Add a Webhook" button to the right of the API key. This will reveal a form to enter the webhook specifics: URL, blockchain (currently Ethereum and Bitcoin are supported), and network. See below for Supported Networks. You can optionally include a username and password if your webhook used basic authentication.
Webhook creation form
We support Slack webhooks. If you want to create a Discord webhook, append
/slack to the end of the Discord URL to use its Slack compatibility mode.Slack webhooks must begin with https://hooks.slack.com/services.
Discord webhooks must begin with https://discordapp.com/api/webhooks.
Slack and Discord limit the size of messages so notifications involving large contract inputs may be abbreviated. Normal, i.e. not Slack/Discord, webhooks are not abbreviated.
Add an address to watch by clicking the Watch Address button and entering the address.
Ethereum addresses begin with a
0x followed by 40 characters (hexadecimal). Any valid Ethereum address can be used, including external accounts and smart contracts.
The following Bitcoin addresses are valid:
Watch Address form
To stop notifications for an address, use the View Address button next to Add webhook, and click the Delete icon next to the address you'd like to stop watching.
View Addresses button lets you view a list of all addresses you're watching on that API Key
It is safe to add the same address multiple times or to unwatch addresses not being watched.
No authentication is currently required to facilitate testing, apart from configuration modification endpoints. Basic auth (username/password) is supported and recommended for production use, and we are adding additional authentication methods based on customer requirements. We recommend HTTPS requests but also offer support for HTTP.
Secret keys are available to be generated per API key, which can be used to access these endpoints:
These end points require a 'credentials' header which takes the API key and associated secret key in one variable in the form "apiKey:secretKey".
Example:
9ed49579-a78b-4c82-b796-6db3aded6ed2:67ed12d1-f0ab-4f18-812c-58356684728bSee how to setup a Slack webhook in this screencast:
How to Setup a Webhook Screencast
post
https://api.blocknative.com
/transaction
Add transaction to watch
apiKey is the API Key created from Setup API Key step above.
hash is the transaction hash to watch. (ethereum only)
blockchain is the blockchain system to monitor. ethereum is supported at this time.
network is the Blockchain network to monitor for the specified transaction hash. See below for Supported Networks.Example
curl call:Ethereum
curl -X POST -H "Content-Type: application/json" -d '{"apiKey":"<api-key>","hash":"<transaction-hash>","blockchain":"ethereum","network": "main"}' https://api.blocknative.com/transaction
delete
https://api.blocknative.com
/transaction
Remove transaction to watch
post
https://api.blocknative.com
/address
Add address to watch
apiKey is the API Key created from Setup API Key step above.
address is the external account address to watch.
blockchain is the blockchain system to monitor. ethereum is supported at this time.
networks is an array containing 1 or more networks to monitor for the specific address. See below for Supported Networks.Example
curl call:Ethereum
curl -X POST -H "Content-Type: application/json" -d '{"apiKey":"<api-key>","address":"<account-address>","blockchain":"ethereum","networks":["main"]}' https://api.blocknative.com/address
This endpoint will return
success if the specified address on the specified network(s) are already being watched for the apikey.delete
https://api.blocknative.com
/address
Remove address to watch
apiKey is the API Key created from Setup API Key step above.
address is the external account address to remove from watching.
blockchain is the blockchain for the address. ethereum is supported at this time.
networks is an array containing 1 or more networks to remove monitoring for the specific address. See below for Supported Networks.Example
curl call:Ethereum
curl -X DELETE -H "Content-Type: application/json" -d '{"apiKey":"<api-key>","address":"<account-address>","blockchain":"ethereum","networks":["main"]}' https://api.blocknative.com/address
This endpoint will return
success if the specified address on the specified network(s) was not being watched for the apikey.get
https://api.blocknative.com
/address/<your-api-key>/<blockchain>/<network>/
List of watched addresses
your-api-key is the API Key created from Setup API Key step above.
blockchain is the blockchain for the watched addresses you want to retrieve. ethereum is supported.
network is the network for the watched addresses you want to retrieve. See below for Supported Networks.page is the page number, of multiple pages, you want to retrieve. Use the total value in the API response along with the size parameter to iterate over all the pages of watched addresses.
size is the length of a page of results. The default size is 100 items per page. The maximum size is 1000 items per page.
order is the sort of the retrieved items according to when they were added to the list (via POST described earlier). The sort order must be either asc (oldest - newest) or desc (newest to oldest). Default is asc.API requests are rate limited. Use larger page sizes for larger lists in order to get all items.
get
https://api.blocknative.com
/transaction/<your-api-key>/<blockchain>/<network>/
List of watched transactions
your-api-key is the API Key created from Setup API Key step above.
blockchain is the blockchain for the watched transactions you want to retrieve. ethereum is supported.
network is the network for the watched transactions you want to retrieve. See below for Supported Networks.page is the page number, of multiple pages, you want to retrieve. Use the total value in the API response along with the size parameter to iterate over all the pages of watched transactions.
size is the length of a page of results. The default size is 100 items per page. The maximum size is 1000 items per page.
order is the sort of the retrieved items according to when they were added to the list (via POST described earlier). The sort order must be either asc (oldest - newest) or desc (newest to oldest). Default is asc.API requests are rate limited. Use larger page sizes for larger lists in order to get all items.
get
https://api.blocknative.com
/<blockchain>/<network>/configs
Get all configuration scopes
get
https://api.blocknative.com
/<blockchain>/<network>/configs/<raw-scope>
Get configuration in specific scope
put
https://api.blocknative.com
/<blockchain>/<network>/configs/<raw-scope>
Add a configuration
There is a limit of 50 configurations per API key. If you need to watch more than 50 addresses and also filter them, it is recommended that you subscribe to all of the addresses and then use a
'global' scoped filter that will apply to all of those addresses.{
"configName": "Limiting my public BN API key",
"allowedOrigins": ["http://example.com", "http://example2.com"],
"ipNotificationRatelimit": 250,
"ipNotificationRatelimitWindow": 1,
"ipPendingSimulationRatelimit": 50,
"ipPendingSimulationRatelimitWindow": 1
}
{
"configName": "Global config example",
"fields": ["example field"],
"filters": [{"status": "pending"}]
}
{
"configName": "Example address config",
"fields": ["example field"],
"filters": [{"status": "pending"}],
"abi" : []
}
delete
https://api.blocknative.com
/<blockchain>/<network>/configs/<raw-scope>
Delete a configuration
Transaction state changes are
POSTed to your custom URL (webhook) with a JSON payload containing the transaction details. The contents of the payload depends on the type of transactions.The following fields are included in every transaction notification and are captured directly from the mempool or block data. Fields are not ordered.
"from": String,
"to": String,
"nonce": Number,
"gas": Number,
"gasPrice": String,
"gasPriceGwei": Number,
"gasUsed": Number, present only when the tx is on-chain,
"baseFeePerGas": String,
"baseFeePerGasGwei": Number,
"maxPriorityFeePerGas": String,
"maxPriorityFeePerGasGwei": Number,
"maxFeePerGas" String,
"maxFeePerGasGwei" Number,
"type": Number,
"value": String,
"hash": String,
"input": String,
"v": String,
"r": String,
"s": String,
"blockHash": String, or null when status is 'pending',
"blockNumber": String, or null when status is 'pending',
"estimatedBlocksUntilConfirmed": Number, or null for estimates of 1-5
Field | Description |
from | The address initiating, signing, the transaction |
to | Address receiving the transaction |
nonce | The from address nonce (transaction count from that address) |
gas | Maximum amount of gas available to the transaction |
gasUsed | Gas used during transaction execution. Only present when the tx is on-chain. |
value | Amount of ETH transferred directly from from address |
hash | Transaction id hash unique for every transaction |
input | Data sent to transaction. For direct value transfers from one external account to another, this field contains 0x. For contract calls, this value contains the contract method signature and params as a hex string. |
v | Transaction signature component (hex encoded) |
r | Transaction signature component (hex encoded) |
s | Transaction signature component (hex encoded) |
blockHash | Block id hash for transactions that are on-chain. Field is null unless notification status is confirmed or failed |
blockNumber | Block number for transactions that are on-chain. Field is null unless notification status is confirmed or failed |
estimatedBlocksUntilConfirmed | Predicted number of blocks from pendingBlockNumberuntil confirmation based ongasPriceand Gas Platform data. Field is 1 - 5 or nullfor estimates outside of 1 - 5. |
type | Denotes the gas pricing used for this transaction. |
Notifications include gas price information depending on the
type of the transaction.For an in-depth look at how EIP-1559 transactions are priced, see:
Field | Description |
|---|---|
baseFeePerGas | Base fee per gas of this block |
maxPriorityFeePerGas | Max priority fee per gas in wei |
maxFeePerGas | Max fee per gas in wei |
baseFeePerGasGwei | baseFeePerGas in gwei, rounded to the 3rd most significant digit |
maxPriorityFeePerGasGwei | maxPriorityFeePerGas in gwei, rounded to an integer |
maxFeePerGasGwei | maxFeePerGas in gwei, rounded to an integer |
Field | Description |
|---|---|
gasPrice | Amount, in wei, per unit of gas |
gasPriceGwei | Amount, in gwei, per unit of gas, rounded to an integer |
In addition to the transaction details provided from the mempool or block, the JSON payload is augmented with the following field. Fields are not ordered.
"system": String,
"network": String,
"status": Status,
"apiKey": String,
"monitorVersion": String,
"monitorId": String,
"serverVersion": String,
"timeStamp": String, // the UTC time of first detection of current status
"pendingTimeStamp": String // ISO UTC time of initial pending status detection
"pendingBlockNumber": Number // the chain head block number at time of pending detection
"transactionIndex": Number, // optional, present if status confirmed, failed
"blockTimeStamp": String, // optional, present if status confirmed, failed - UTC time of miner block creation
"timePending": String, // optional, present if status confirmed, failed, speedup, cancel. "-1" if first detectiong is on-chain.
"blocksPending": Number, // optional, present if status confirmed, failed, speedup, cancel
"asset": String, // optional, present if direct transfer of ETH or ERC20
"direction": String, // optional, present in payloads with a `watchedAddress` param
"counterparty": String, // optional, present in payloads with a `watchedAddress` param
"watchedAddress": String, // optional, present when payload triggered by activity related to a watched address
"replaceHash": String, // optional, present if status is speedup or cancel
"failureReason": String, // optional, present if status is failed
Field | Description |
system | Blockchain of this transaction |
network | |
status | |
apiKey | Blocknative API key associated with the notification |
monitorVersion | Version number of the Blocknative monitor that detected the transaction state change |
monitorId | Identifier of the Blocknative monitor that first detected the transaction state change |
serverVersion | Version number of the Blocknative server that delivered the notification |
timeStamp | UTC ISO timestamp when Blocknative first detected this transaction update |
pendingTimeStamp | UTC ISO timestamp when Blocknative first detected the pending state for this transaction |
pendingBlockNumber | The chain head block number when the pending state was first detected |
transactionIndex | Optional. For confirmed or failed transactions, the index (order) of the transaction in the block. |
blockTimeStamp | Optional. UTC ISO block timestamp the miner reported when collating the block this transaction was eventually confirmed in. The block timestamp is usually a few seconds before timeStamp, the difference being the time between the validator collating the block, and the block being confirmed and propagated throughout the network |
timePending | Optional. The number of milliseconds from initial pending detection to confirmed or failed detection. "-1" if first detection is on-chain. |
blocksPending | Optional. The number of blocks since the initial pending detection to confirmed or failed detection. |
asset | Optional. Symbol of the asset being transferred, e.g. ETH. This field is present only if transaction directly transfers Ether or is an ERC20 token transfer |
direction | Optional. Indicates if funds are incoming or outgoing relative to the watchedAddress. This field is present only if notification triggered by watchedAddress |
counterparty | Optional. Address of recipient of funds if watchedAddress is the sender in the transaction, address of sender of funds if watchedAddress is the recipient in the transaction. This field is present only if notification triggered by watchedAddress |
watchedAddress | Optional. Watched address which triggered the notification. This field is present only if notification triggered by watchedAddress |
replaceHash | Optional. The hash of the transaction that replaced this transaction in the txpool |
failureReason | Optional. For failed transactions, the reason why the transaction failed. Some failures may not have a discernible reason. |
For some contract calls, Blocknative decodes the
input field of the transaction to interpret details of the contract method call. Fields are not ordered. "contractCall": {
"contractType": String,
"contractAddress": String,
"methodName": String,
"params": {
// key value pairs specific to the contract method
},
"contractName": String,
"contractDecimals": Number (optional),
"decimalValue": String (optional),
}
Blocknative currently supports decoding of the following contracts and regularly adds more:
- Uniswap v3 (Factory, Routing, NFT Descriptor, NFT Positional Manager and Migrator)
- Uniswap v2 (Routing and Factory)
- Uniswap v1
- Sushiswap Router
- 0x Protocol v2.1
- 0x Protocol v3
- Synthetix ExchangeRates
- Synthetix Proxy
- MakerDAO
- Rebalancing Set Exchange Issuance v2
- Set Protocol
- Abridged
- Pillar Badge
- rToken
- 1inch Exchange V1
- 1inch Exchange V2
- 1inch Exchange V3
- Aave: Lending Pool V2
- Aave Flashloans
- OpenSea
- Balancer (BFactory, BPool, Distribution and Exchange Proxy 2)
- Honeyswap Router (Gnosis Chain)
- Sushiswap V2 Factory
- DIGG Orchestrator
- Quickswap Router & Factory (Matic)
- Aave Lending Pool (Matic)
- Aavegotchi: Opensea (Matic)
Along with supported Ethereum token protocols:
- ERC-20
- ERC-721
- ERC-165
- ERC-777
- ERC-1820
Field | Description |
contractType | Type of the called contract |
contractAddress | Address of the called contract |
methodName | Name of the called method |
params | Optional. A series of keys and values specific to the contract method. This field is present only if the contract method call includes parameters. |
contractName | Optional. Name of the called contract |
contractDecimals | Optional. The result of calling the decimal() method on the smart contract, if it exists |
decimalValue | Optional. If there is a value field in the params object, and contractDecimals is present, decimalValue will equal value / 10^contractDecimals |
Blocknative will send
confirmednotifications when a watchedAddress is detected in the internal transactions of a contract call. In this case, the confirmed notification will include details of the internal transactions and balance changes resulting from those internal transactions. Fields are not ordered. "internalTransactions": [],
"netBalanceChanges": Object
Field | Description |
internalTransactions | Array of objects containing details of each internal transaction (see below) |
netBalanceChanges | Object containing details of balance changes for all addresses involved in internal transactions (see below) |
The
internalTransactions array contains details on each internal transaction executed by the contract call of the parent (main) transaction. Fields are not ordered. "internalTransactions": [
{
"type": String,
"from": String,
"to": String,
"input": String,
"gas": Number,
"gasUsed": Number,
"value": String,
"contractCall": Object (optional, contains an additional param 'contractAlias' which will be the symbol of the token if this is an erc20 transfer or transferFrom)
},
...
]
Field | Description |
type | Type of internal transaction (one of CALL, DELEGATECALL, STATICCALL, CALLCODE) |
from | Address initiating the internal transaction call (typically the parent (main) transaction's contract address |
to | Address the internal transaction is calling or sending value to |
input | Data sent to internal transaction. For value transfers from external account initiating parent (main) transaction to another external account, this field contains 0x. For contract calls, this value contains the contract method signature and params as a hex string. |
gas | Maximum amount of gas available to the internal transaction |
gasUsed | Amount of gas actually used executing the internal transaction |
value | Amount of ETH transferred directly to to address from parent (main) transaction from address. |
contractCall | Optional. A series of keys and values specific to the contract method . This object is present only if the contract method call includes parameters and Blocknative decodes the internal transaction contract call (e.g. an ERC20 transfer). For details see decoded contract payload above.
NOTE: If the Internal transaction is an ERC20 transfer or transferFrom call, the contractCall object will include an additional field, contractAlias with the symbol of the token transferred. |
The
netBalanceChanges object contains details of all the balance changes resulting from the internal transactions details in the internalTransactions array. The object is an array with an entry for each address involved in the internal transactions."netBalanceChanges": [
{
"address": String,
"balanceChanges": [
{
"delta": String,
"asset": {
"contractAddress": String
"symbol": String,
"type": String
},
"breakdown": [
{
"amount": String,
"counterparty": String
},
...
]
}
]
},
...
]
Field | Description |
address | Address involved in internal transaction. Each address contains an array of balances changes, one for each counterparty |
delta | Amount of value transfer (balance change) in wei to the address. Outgoing value is represented as a negative balance change and incoming value is represented as a positive balance change |
asset | Details of the asset being transferred. Contains contractAddress, type and symbol |
contractAddress | The address of the token contract if the value is not ETH (ether), not present if the value os ETH |
type | The type of asset transferred (e.g. "ether" or "erc20") |
symbol | The symbol of the asset transferred. "ETH" or appropriate ERC20 symbol |
breakdown | Array of individual transfers to address for the current asset |
counterparty | Address of the other side of the transfer relative to the address |
amount | The amount of asset transferred with this counterparty |
Blocknative will send
pending-simulationnotifications when a watchedAddress is detected in the from or to field of the main transaction or internal transactions of a contract call. The notification will include details of the internal transactions and balance changes resulting from those internal transactions. The internal transaction details and balance changes are probabilistic based on simulating the transaction against the latest confirmed block. Fields are not ordered.pending-simulation notifications are only available for Ethereum Main Network.The payload structure for
pending-simulation notifications is the same as for confirmed notifications with the addition of the following object."simDetails": {
"blockNumber": Number,
"performanceProfile": {
"breakdown": [
{
"label": "detected",
"timeStamp": String // UTC time of first detection of transaction
},
{
"label": "traceStart",
"timeStamp": String // UTC time of when transaction simulation started
},
{
"label": "traceEnd",
"timeStamp": String // UTC time of when transaction simulation completed
},
{
"label": "dispatch",
"timeStamp": String // UTC time of when notification sent
}
],
"e2eMs": Number // end to end processing time in milliseconds
}
}
A direct send transaction is sending funds (ether) from one account to another. The
hash is setup as a watched transaction and/or to address or the from addresses or both are setup as watched addresses.{
"system": "ethereum",
"nonce": 1061,
"id": "6f782dbf-248f-c46f-9a56-c53794f1",
"network": "rinkeby",
"from": "0x6f782dbf141c50e0b79b044b471fb8d76bcb7aed",
"status": "pending",
"blockHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
"blockNumber": null,
"gas": 21000,
"gasPrice": "10000000000",
"gasPriceGwei": 10,
"hash": "0x7fb386cc248fc46f9a56c53794f1580b6c48f6e16e4c2c5ed5e7a533af2ac2cf",
"input": "0x",
"to": "0x87c382487b6f20926acf7076de1210845d62e7cc",
"transactionIndex": 0,
"value": "100000000000000000",
"asset": "ETH",
"direction": "outgoing",
"counterparty": "0x87c382487b6f20926acf7076de1210845d62e7cc",
"watchedAddress": "0x6f782dbf141c50e0b79b044b471fb8d76bcb7aed",
"apiKey": "3462c0f0-471f-4b7d-84c3-50e0244a9403"
}
As a direct ETH transfer, this transaction has
0x for its input.When watched transaction is a contract call, or a watched address makes a contract call, a similar transaction notification is generated where the
to address is the contract.{
"system": "ethereum",
"nonce": 1066,
"id": "e08fc37a-db98-4954-be23-757719c7317c",
"from": "0x6F782dBf141C50E0B79b044B471FB8D76Bcb7aeD",
"network": "rinkeby",
"status": "confirmed",
"blockHash": "0xcef0fe0ce003662287777425181006e141ae517793e148e856076c6ae50c1023",
"blockNumber": 4862011,
"gas": 36402,
"gasPrice": "1000000000",
"gasPriceGwei": 1,
"hash": "0x1ae540c5f8e4f50e951a3192d05cfd2da1028d4c7275455087de6dddd1139188",
"input": "0x6c5c7a700000000000000000000000006921144ad2a2923ae11c5652feb3b0d9053d9152",
"to": "0x9E7aE8c4D07670Df36FdB88c1b3Ae06dc4625fa0",
"transactionIndex": 6,
"value": "0",
"asset": "ETH",
"direction": "outgoing",
"counterparty": "0x9E7aE8c4D07670Df36FdB88c1b3Ae06dc4625fa0",
"watchedAddress": "0x6f782dbf141c50e0b79b044b471fb8d76bcb7aed",
"apiKey": "15273e72873dba2cd065"
}
As a contract call, this transaction has a value for input. The value contains the contract method signature and and parameters to the method call.
If you would like to have your contract decoded (method and parameter names delivered in JSON message) please contact Blocknative at [email protected] or on our Discord server with your contract address (for each supported network) and ABI.
If the watched transaction is a ERC-20/ERC-721 transfer, or an ERC-20/ERC-721 token
transfer or transferFromtransaction involves a watched address, the details of the transfer and token involved are included in the transaction notification.{
"system": "ethereum",
"nonce": 67,
"from": "0x87c382487b6f20926acf7076de1210845d62e7cc",
"network": "rinkeby",
"id": "87c38248-acd2-5d28-cc9a-b7e0eb72",
"status": "pending",
"blockHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
"blockNumber": null,
"gas": 54643,
"gasPrice": "10000000000",
"gasPriceGwei": 10,
"hash": "0xb85704efacd25d28cc9ab7e0eb726a30ed4dd4607a5008d57eb69bc262db503f",
"input": "0xa9059cbb0000000000000000000000006f782dbf141c50e0b79b044b471fb8d76bcb7aed0000000000000000000000000000000000000000000000004563918244f40000",
"to": "0xaff4481d10270f50f203e0763e2597776068cbc5",
"transactionIndex": 0,
"value": "5000000000000000000",
"asset": "WEENUS",
"contractCall": {
"contractType": "erc20",
"contractAddress": "0xaff4481d10270f50f203e0763e2597776068cbc5",
"methodName": "transfer",
"params": {
"_to": "0x6f782dbf141c50e0b79b044b471fb8d76bcb7aed",
"_value": "5000000000000000000"
}
},
"direction": "outgoing",
"counterparty": "0x6f782dbf141c50e0b79b044b471fb8d76bcb7aed",
"watchedAddress": "0x87c382487b6f20926acf7076de1210845d62e7cc",
"apiKey": "15273e72873dba2cd065"
}
Name | Id | Description |
main | 1 | Ethereum Mainnet |
goerli | 5 | Ethereum Testnet |
xdai | 100 | Ethereum L2 |
matic-main | 137 | Polygon |
Key | Description |
pending | the transaction was detected in the "pending" area of the mempool and is eligible for inclusion in a block |
pending-simulation | the transaction was detected in the "pending" area of the mempool and is eligible for inclusion in a block and has been simulated against the latest block |
stuck | the transaction was detected in the "queued" area of the mempool and is not eligible for inclusion in a block |
speedup | a replacement transaction (same nonce and from, higher gas) was detected in the mempool with the same to, value and input parameters as the transaction being replaced |
cancel | a replacement transaction (same nonce and from, higher gas) was detected in the mempool with different to, value or input parameters compared to the transaction being replaced |
confirmed | the transaction was mined or validated with no errors |
failed | the transaction was mined or validated, but failed to execute due to EVM error |
dropped | the transaction was dropped from the mempool before being mined or validated into a block |
Sign up for a free Blocknative Account at https://account.blocknative.com/ with your work email address.
Last modified 16d ago