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.
To use our API with web sockets, please see the SDK.
API usage has rate limits. Please see Rate Limits for more details.
Getting Started
Setup API Key
Create a Blocknative account by clicking the Sign up button on Mempool Explorer and following the instructions. Account creation requires email confirmation to complete.
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.
Secret keys additionally are available to be generated for API keys which allow secure usage of configuration modification endpoints.
Setup Webhook
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.
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 Address to Watch
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:
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.
It is safe to add the same address multiple times or to unwatch addresses not being watched.
Authentication
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
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-58356684728b
Screencasts
See how to setup a Slack webhook in this screencast:
API
Add transaction to watch
POST
https://api.blocknative.com/transaction
Use the Blocknative https://api.blocknative.com/transaction endpoint to
POST
individual transaction hashes to watch for state changes (mempool and chain confirmation). For each transaction, specify your API key, the transaction
hash
or
txid
to watch, the transaction's blockchain (currently
ethereum
and
bitcoin
are supported), and the network to watch (see supported networks below).
Request Body
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
Remove transaction to watch
DELETE
https://api.blocknative.com/transaction
Use the Blocknative https://api.blocknative.com/transaction endpoint to DELETE individual transaction hashes that you are currently watching. For each transaction, specify your API key, the transaction hash or txid to watch, the transaction's blockchain (currently ethereum and bitcoin are supported), and the network to watch (see supported networks below).
Request Body
Add address to watch
POST
https://api.blocknative.com/address
Use the Blocknative https://api.blocknative.com/address endpoint to
POST
individual addresses to watch for transactions. For each address, specify your API key, the address to watch, the blockchain (currently Ethereum and Bitcoin are supported), and the networks to watch (see supported networks below).
\
Request Body
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
This endpoint will return success
if the specified address on the specified network(s) are already being watched for the apikey
.
Remove address to watch
DELETE
https://api.blocknative.com/address
Use the Blocknative https://api.blocknative.com/address endpoint to
DELETE
individual addresses from watching for transactions. For each address, specify your API key, the address to remove, the blockchain (currently
ethereum
and
bitcoin
are supported), and the networks to remove from watch (see supported networks below).
Request Body
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
This endpoint will return success
if the specified address on the specified network(s) was not being watched for the apikey
.
List of watched addresses
GET
https://api.blocknative.com/address/<your-api-key>/<blockchain>/<network>/
Use this endpoint to access the watched addresses for your API key. Include your API key and the appropriate blockchain (currently
ethereum
and
bitcoin
are supported) and network. See below for Supported Networks.
Path Parameters
Query Parameters
Required elements of the API request path
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.
Optional query string parameters for large lists
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.
List of watched transactions
GET
https://api.blocknative.com/transaction/<your-api-key>/<blockchain>/<network>/
Use this endpoint to access the watched transactions for your API key. Include your API key and the appropriate blockchain (currently
ethereum
and
bitcoin
are supported) and network. See below for Supported Networks.
Path Parameters
Query Parameters
Required elements of the API request path
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.
Optional query string parameters for large lists
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 all configuration scopes
GET
https://api.blocknative.com/<blockchain>/<network>/configs
Use this endpoint to access all of the configuration scopes given on an API key. Include the appropriate blockchain and network, for which supported networks are listed below. Include your API key and it's associated secret key in a "credentials" header via the formatting "apiKey:secretKey". Your secret key can be set via your Accounts page where your keys are listed.
Path Parameters
Headers
Get configuration in specific scope
GET
https://api.blocknative.com/<blockchain>/<network>/configs/<raw-scope>
Use this endpoint to access the full config deployed at a specific blockchain, network, API key and scope. Include the appropriate blockchain and network, for which supported networks are listed below. Include your API key and it's associated secret key in a "credentials" header via the formatting "apiKey:secretKey". Your secret key can be set via your Accounts page where your keys are listed.
Path Parameters
Headers
Add a configuration
PUT
https://api.blocknative.com/<blockchain>/<network>/configs/<raw-scope>
Use this endpoint to add configurations to certain API keys at certain blockchains and networks. Include your API key and it's associated secret key in a "credentials" header via the formatting "apiKey:secretKey".
\
\
Configurations can be exported from Mempool Explorer as specified here (https://docs.blocknative.com/mempool-explorer#configurations-sidebar).
Path Parameters
Headers
Request Body
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.
Websocket configuration example
Global configuration example
Address configuration example
Delete a configuration
DELETE
https://api.blocknative.com/<blockchain>/<network>/configs/<raw-scope>
Using this endpoint, you can clear a configuration set at a certain API key for a blockchain, network and scope. Include your API key and it's associated secret key in a "credentials" header in the form "apiKey:secretKey".
Path Parameters
Headers
Ethereum Notifications
Transaction state changes are POST
ed to your custom URL (webhook) with a JSON payload containing the transaction details. The contents of the payload depends on the type of transactions.
Base Payload
The following fields are included in every transaction notification and are captured directly from the mempool or block data. Fields are not ordered.
Gas Details
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:
A Definitive Guide to Ethereum EIP-1559 Gas Fee Calculations
Type 2 (EIP-1559) Transactions
Type 0 (Pre-EIP-1559) Transactions
Metadata Payload
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.
Decoded Contract Payload
For some contract calls, Blocknative decodes the input
field of the transaction to interpret details of the contract method call. Fields are not ordered.
Blocknative currently supports decoding of the following contracts and regularly adds more:
Uniswap v3 (Mainnet and Matic)
Uniswap Universal Router (Mainnet and Matic)
Uniswap v2 (Routing and Factory - Mainnet and Matic)
Uniswap v1 (Mainnet and Matic)
Sushiswap Router
0x Protocol v2.1
0x Protocol v3
Curve.Fi (All pools shown here)
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)
ERC 4337 EntryPoints
Along with supported Ethereum token protocols:
ERC-20
ERC-721
ERC-165
ERC-777
ERC-1820
Internal Transactions Payload
Blocknative will send confirmed
notifications 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.
The internalTransactions
array contains details on each internal transaction executed by the contract call of the parent (main) transaction. Fields are not ordered.
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.
Simulated Pending Payload
Blocknative will send pending-simulation
notifications 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 Mainnet and Sepolia Testnet.
The payload structure for pending-simulation
notifications is the same as for confirmed
notifications with the addition of the following object.
Examples
Direct send transaction
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.
As a direct ETH transfer, this transaction has 0x
for its input
.
Contract call transaction
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.
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 support@blocknative.com or on our Discord server with your contract address (for each supported network) and ABI.
Token transfer transaction
If the watched transaction is a ERC-20/ERC-721 transfer, or an ERC-20/ERC-721 token transfer
or transferFrom
transaction involves a watched address, the details of the transfer and token involved are included in the transaction notification.
Supported Networks
Ethereum and EVM Compatible
Transaction Events (State Changes)
Get Started Today
Sign up for a free Blocknative Account at https://explorer.blocknative.com/ with your work email address.
If you have any questions, connect with the team on our discord
Last updated