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 and Bitcoin 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 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 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:
Address Type | Example |
Pubkey hash (P2PKH address) |
|
Script hash (P2SH address) |
|
SegWit Pay 2 Witness Public Key Hash (P2SH-P2WPKH) |
|
SegWit mainnet (P2WPKH address) |
|
SegWit Testnet (P2WPKH address) |
|
SegWit mainnet (P2WSH address) |
|
SegWit Testnet (P2WSH address) |
|
Testnet pubkey hash |
|
Testnet script hash |
|
To stop notifications for an address, use the Unwatch Address button.
It is safe to add the same address multiple times or to unwatch 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 or txid to watch, the transaction's blockchain (currently ethereum and bitcoin are supported), and the network to watch (see supported networks below).{
"apiKey": "<api-key>",
"hash": "<transaction-hash (ethereum)>",
"txid": "<txid (bitcoin)>"
"blockchain": "<ethereum or bitcoin>",
"network": "main"
}{"msg": "success"}
Response body will describe nature of request failure.​Examples:XYZ is not a valid apiKey(string `hash` or `txid`) XYZ is an invalid transaction hash / txid(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. (ethereum only)
txid is the transaction id to watch (bitcoin only)
blockchain is the blockchain system to monitor. Ethereum and Bitcoin are 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
Bitcoin
curl -X POST -H "Content-Type: application/json" -d '{"apiKey":"<api-key>","txid":"<txid>","blockchain":"bitcoin","network": "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 Ethereum and Bitcoin are 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. ethereum and bitcoin are 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
Bitcoin
curl -X POST -H "Content-Type: application/json" -d '{"apiKey":"<api-key>","address":"<account-address>","blockchain":"bitcoin","networks":["main", "testnet"]}' 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 ethereum and bitcoin are 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 remove from watching.
blockchain is the blockchain for the address. ethereum and bitcoin are 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
Bitcoin
curl -X DELETE -H "Content-Type: application/json" -d '{"apiKey":"<api-key>","address":"<account-address>","blockchain":"bitcoin","networks":["main", "testnet"]}' 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 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,"gasUsed": String, present only when the tx is on-chain,"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'
Field | Description |
| The address initiating, signing, the transaction |
| Address receiving the transaction |
| The |
| Maximum amount of gas available to the transaction |
| Amount, in wei, per unit of |
| Gas used during transaction execution. Only present when the tx is on-chain. |
| Amount of ETH transferred directly from |
| Transaction id hash unique for every transaction |
| Data sent to transaction. For direct value transfers from one external account to another, this field contains |
| Transaction signature components (ECDSA signature components and recovery id) |
| Block id hash for transactions that are on-chain. Field is |
| Block number for transactions that are on-chain. Field is |
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,"timePending": String, (optional, present if status confirmed or failed)"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)
Field | Description |
| Blockchain of this transaction |
| Network name of this transaction (see table to supported networks below) |
| New status of this transaction (see table of supported status values below) |
| Optional. Time difference in milliseconds between first pending detection and first on-chain detection. Value is empty string if first detection is on-chain (i.e. there was no |
| Blocknative API key associated with the notification |
| Version number of the Blocknative monitor that detected the transaction state change |
| Identifier of the Blocknative monitor that first detected the transaction state change |
| Version number of the Blocknative server that delivered the notification |
| Timestamp when notification is sent |
| 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 |
| Optional. Indicates if funds are incoming or outgoing relative to the |
| Optional. Address of recipient of funds if |
| Optional. Watched address which triggered the notification. This field is present only if notification triggered by |
| Optional. The transaction hash of the replaced transaction from a speedup or cancel |
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}}
Blocknative currently supports decoding of the following contracts and regularly adds more:
0x Protocol v2.1
0x Protocol v3
Pillar Badge
rToken
Synthetix ExchangeRates
Synthetix Proxy
Rebalancing Set Exchange Issuance v2
Field | Description |
| Name of the called contract |
| Address of the called contract |
| Name of the called method |
| Optional. A series of keys and values specific to the contract method. This field is present only if the contract method call includes parameters. |
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 |
| Array of objects containing details of each internal transaction (see below) |
| 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 of internal transaction (one of |
| Address initiating the internal transaction call (typically the parent (main) transaction's contract address |
| Address the internal transaction is calling or sending value to |
| Data sent to internal transaction. For value transfers from external account initiating parent (main) transaction to another external account, this field contains |
| Maximum amount of gas available to the internal transaction |
| Amount of gas actually used executing the internal transaction |
| Amount of ETH transferred directly to |
| 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 |
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 involved in internal transaction. Each address contains an array of balances changes, one for each |
| Amount of value transfer (balance change) in wei to the |
| Details of the asset being transferred. Contains |
| The address of the token contract if the value is not |
| The type of asset transferred (e.g. "ether" or "erc20") |
| The symbol of the asset transferred. "ETH" or appropriate ERC20 symbol |
| Array of individual transfers to |
| Address of the other side of the transfer relative to the |
| The amount of asset transferred with this |
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","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.
{"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.
{"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"}
The following fields are included in every transaction notification and are captured directly from the mempool or block data.
"rawTransaction": {"txid": String,"hash": String,"version": Number,"size": Number,"vsize": Number,"weight": Number,"locktime": Number,"vin": Vin[],"vout": Vout[],"hex": String,}
Field | Descriptions |
| The transaction id unique for each transaction |
| The transaction hash unique for each transaction, can be the same as the txid |
| ​Transaction version number currently version 1 or 2. Programs creating transactions using newer consensus rules may use higher version numbers. Version 2 means that BIP 68 applies. |
| Total size of this transaction |
| The virtual size of this transaction |
| The weight of this transaction |
| The block number or timestamp at which this transaction is unlocked |
| An array of transaction inputs (see below for details) |
| An array of transaction outputs (see below for details) |
| The hex format of the transaction |
"txid": String,"vout": Number,"scriptSig": {"asm": String,"hex": String},"txinwitness": String[],"sequence": Number
Field | Description |
| The unique transaction id for this input transaction |
| The index of which output this transaction is in it's vout array |
| The unlocking script that satisfies the conditions placed on the output by the |
| Contains data required to check transaction validity |
| A number intended to allow unconfirmed time-locked transactions to be updated before being finalized |
"value": Number,"n": Number,"scriptPubKey": {"asm": String,"hex": String,"reqSigs": Number,"type": String,"addresses": String[]}
Field | Description |
| The value of this output in btc |
| The index of this input in the |
| The script which sets the conditions that must be fulfilled for the value to be spent |
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.
"txid": String,"system": String,"network": String,"status": Status,"apiKey": String,"monitorVersion": String,"monitorId": String,"serverVersion": String,"timeStamp": String,"timePending": String,"watchedAddress": String,"inputs": Transfer[],"outputs": Transfer[],"fee": String,"netBalanceChanges": BalanceChange[],
Field | Description |
| The transaction id unique for each transaction |
| Blockchain of this transaction |
| Network name of this transaction (see table to supported networks below) |
| New status of this transaction (see table of supported status values below) |
| Blocknative API key associated with the notification |
| Version number of the Blocknative monitor that detected the transaction state change |
| Identifier of the Blocknative monitor that first detected the transaction state change |
| Version number of the Blocknative server that delivered the notification |
| Timestamp when notification is sent |
| Optional. Time difference in milliseconds between first pending detection and first on-chain detection. Value is empty string if first detection is on-chain (i.e. there was no |
| Optional. Watched address which triggered the notification for this apikey. This field is present only if notification was triggered by activity on a |
| An array of input Transfer objects (see below) |
| An array of output Transfer objects (see below) |
| The fee paid in btc for this transaction |
| An array of Balance Change Objects (see below) that represent the net balance change for each address involved in the transaction |
"address": String,"value": String
Field | Description |
address | The address of the input/output transaction |
value | The value in btc of the input/output transaction |
"address": String,"delta": String
Field | Description |
| The address that had the balance change |
| number indicating net change in funds at this address as result of all inputs/outputs |
Name | Id |
| 1 |
| 3 |
| 4 |
| 5 |
| 42 |
Name | Id |
| 1 |
| 2 |
Currently pending and confirmed transactions are supported for Bitcoin
Key | Description |
| the transaction was detected in the mempool |
| a replacement transaction (same |
| a replacement transaction (same |
| the transaction was mined with no errors |
| the transaction was mined, but failed to execute due to EVM error |
| the transaction was dropped from the mempool before being mined into 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​
