Notify API
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 Notify SDK.
Create a Blocknative account on https://account.blocknative.com. Account creation requires email confirmation to complete.
From the API Keys section of https://account.blocknative.com, create an API key for your Blocknative account.
Create a new webhook for the 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 only Ethereum is supported), and network. See below for Supported Ethereum 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 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.
You can add and remove addresses to watch directly from the Dashboard with the "Watch Address" and "Remove Address" buttons under a webhook. It is safe to add the same address multiple times or to remove addresses not being watched.
NOTE: A list of watched addresses will be available in the future.
No authentication is currently required to facilitate testing. Basic auth (username/password) is supported and recommended for production use, and we are adding additional authentication methods based on customer requirements. All requests must be over HTTPS.
See how to setup a Slack webhook in this screencast:
postAdd transaction to watch
POST individual transaction hashes to watch for state changes (mempool and chain confirmation). For each transaction, specify your API key, the transaction hash to watch, the transaction's blockchain (currently only ethereum is supported), and the network to watch (see supported networks below).{
"apiKey": "<api-key>",
"hash": "<transaction-hash>",
"blockchain": "ethereum",
"network": "main"
}{"msg": "success"}
Response body will describe nature of request failure.​Examples:XYZ is not a valid apiKey(string `hash`) XYZ is an invalid ethereum transaction hash(string `blockchain`) XYZ is not supported(string `network`) XYZ is an invalid network
apiKey is the API Key created from Setup API Key step above.
hash is the transaction hash to watch.
blockchain is the blockchain system to monitor. Only Ethereum is supported at this time.
network is the Ethereum network to monitor for the specified transaction hash. See below for Supported Ethereum Networks.
Example curl call:
curl -X POST -H "Content-Type: application/json" -d '{"apiKey":"<api-key>","hash":"<transaction-hash>","blockchain":"ethereum","networks":["main"]}' https://api.blocknative.com/transaction
postAdd address to watch
POST individual addresses to watch for transactions. For each address, specify your API key, the address to watch, the blockchain (currently only ethereum is supported), and the networks to watch (see supported networks below).
{
"apiKey": "<api-key>",
"address": "<account-address>",
"blockchain": "ethereum",
"networks": ["main", "rinkeby"]
}{"msg": "success"}
Response body will describe nature of request failure.​Examples:XYZ is not a valid apiKey(string `address`) XYZ is an invalid ethereum address(string `blockchain`) XYZ is not supported(array `networks`) ["XYZ"] contains an invalid network
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. Only 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 Ethereum Networks.
Example curl call:
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.
deleteRemove address to watch
DELETE individual addresses from watching for transactions. For each address, specify your API key, the address to remove, the blockchain (currently only ethereum is supported), and the networks to remove from watch (see supported networks below).{
"apiKey": "<api-key>",
"address": "<account-address>",
"blockchain": "ethereum",
"networks": ["main", "rinkeby"]
}{"msg": "success"}
Response body will describe nature of request failure.​Examples:XYZ is not a valid apiKey(string `address`) XYZ is an invalid ethereum address(string `blockchain`) XYZ is not supported(array `networks`) ["XYZ"] contains an invalid network
apiKey is the API Key created from Setup API Key step above.
address is the external account address to remoce from watching.
blockchain is the blockchain for the address. Only 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 Ethereum Networks.
Example curl call:
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.
Transaction state changes are POSTed to your custom URL (webhook) with a JSON payload containing the transaction (and possibly contract) details. The contents of the payload depends on the type of transactions.
In addition to the transaction details provided from the mempool or block, the JSON payload is augmented with the following field:
Field | Description |
| blockchain of this transaction (currently only |
| network id of this transaction (see table to supported networks below) |
| new state of this transaction (see table of supportd status values below) |
| the symbol of the asset being trasnferred, e.g. ETH |
| indicates if funds are incoming or outgoing relative to the |
| the recipient of funds if |
| the watched account address which triggered the notification |
| the API key associated with the watched address |
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.
Example
{"system": "ethereum","nonce": 1061,"id": "6f782dbf-248f-c46f-9a56-c53794f1","network": "rinkeby","from": "0x6f782dbf141c50e0b79b044b471fb8d76bcb7aed","status": "pending","blockHash": "0x0000000000000000000000000000000000000000000000000000000000000000","blockNumber": null,"gas": 21000,"gasPrice": "10000000000","hash": "0x7fb386cc248fc46f9a56c53794f1580b6c48f6e16e4c2c5ed5e7a533af2ac2cf","input": "0x","to": "0x87c382487b6f20926acf7076de1210845d62e7cc","transactionIndex": 0,"value": "100000000000000000","asset": "ETH","v": "0x2b","r": "0x8b98b6f6e9634803049e23784aac881da6d9c2a66250eca2ea3b4202608acc6f","s": "0x4119c446c1a4475d4afad635231ef7033ff7aa7a65229a99f01a782769668418","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.
Example
{"system": "ethereum","nonce": 1066,"id": "e08fc37a-db98-4954-be23-757719c7317c","from": "0x6F782dBf141C50E0B79b044B471FB8D76Bcb7aeD","network": "rinkeby","status": "confirmed","blockHash": "0xcef0fe0ce003662287777425181006e141ae517793e148e856076c6ae50c1023","blockNumber": 4862011,"gas": 36402,"gasPrice": "1000000000","hash": "0x1ae540c5f8e4f50e951a3192d05cfd2da1028d4c7275455087de6dddd1139188","input": "0x6c5c7a700000000000000000000000006921144ad2a2923ae11c5652feb3b0d9053d9152","to": "0x9E7aE8c4D07670Df36FdB88c1b3Ae06dc4625fa0","transactionIndex": 6,"value": "0","asset": "ETH","v": "0x2b","r": "0x718b7f2005730ecbc5641a273ac6852b28eb914a9997f54a6855d16bfc1b8fd","s": "0x6bfe62a0936ba52159ba30da3173263fa747543da827a74b94cdcca82b08dc3f","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 support@blocknative.com 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.
Example
{"system": "ethereum","nonce": 67,"from": "0x87c382487b6f20926acf7076de1210845d62e7cc","network": "rinkeby","id": "87c38248-acd2-5d28-cc9a-b7e0eb72","status": "pending","blockHash": "0x0000000000000000000000000000000000000000000000000000000000000000","blockNumber": null,"gas": 54643,"gasPrice": "10000000000","hash": "0xb85704efacd25d28cc9ab7e0eb726a30ed4dd4607a5008d57eb69bc262db503f","input": "0xa9059cbb0000000000000000000000006f782dbf141c50e0b79b044b471fb8d76bcb7aed0000000000000000000000000000000000000000000000004563918244f40000","to": "0xaff4481d10270f50f203e0763e2597776068cbc5","transactionIndex": 0,"value": "5000000000000000000","asset": "WEENUS","v": "0x2b","r": "0xd430080bb02c855f3af4c88e5a4877625d820f310e25cc09e77da28f2953fb0a","s": "0x33d755b7e3c07f89eb9305f526f1671ef56c364dc458232e1452e12e7cb54439","contractCall": {"contractType": "erc20","contractAddress": "0xaff4481d10270f50f203e0763e2597776068cbc5","methodName": "transfer","params": {"_to": "0x6f782dbf141c50e0b79b044b471fb8d76bcb7aed","_value": "5000000000000000000"}},"direction": "outgoing","counterparty": "0x6f782dbf141c50e0b79b044b471fb8d76bcb7aed","watchedAddress": "0x87c382487b6f20926acf7076de1210845d62e7cc","apiKey": "15273e72873dba2cd065"}
Name | Id |
| 1 |
| 3 |
| 4 |
| 5 |
| 42 |
Key | Description |
| server detected transaction in mempool indicating transaction is |
| server detected replacement transaction in mempool with more gas |
| server detected replacement transaction in mempool sent to another wallet account (not contract) with more gas and no value |
| server detected transaction on blockchain as |
| server detected transaction on blockchain as |
| server detected transaction removed from mempool and not confirmed in a block |
Sign up for a free Blocknative Account at https://account.blocknative.com/ with your work email address.
If you have any questions, connect with the team on our discord​
