Notify 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 Notify SDK.

Getting Started

Setup API Key

  1. Create a Blocknative account on https://account.blocknative.com. Account creation requires email confirmation to complete.

  2. From the API Keys section of https://account.blocknative.com, create an API key for your Blocknative account.

  3. Contact Blocknative support to setup your custom URL (webhook) that will receive transaction state change POSTs from Blocknative. This will be supported by API key creation from step 2 in the Blocknative account dashboard soon.

API Key creation form on https://account.blocknative.com

Authentication

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.

post
Add transaction to watch

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 to watch, the transaction's blockchain (currently only ethereum is supported), and the network to watch (see supported networks below).
Request
Response
Body Parameters
required
string
JSON payload: { "apiKey": "<api-key>", "hash": "<transaction-hash>", "blockchain": "ethereum", "network": "main" }
200: OK
{
"msg": "success"
}
400: Bad Request
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. Supported Ethereum networks are listed below.

post
Add address to watch

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 only ethereum is supported), and the networks to watch (see supported networks below).
Request
Response
Body Parameters
required
string
JSON payload: { "apiKey": "<api-key>", "address": "<account-address", "blockchain": "ethereum", "networks": ["main", "rinkeby"] }
200: OK
{
"msg": "success"
}
400: Bad Request
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. Supported Ethereum networks are listed below.

This endpoint will return success if the specified address on the specified network(s) are already being watched for the apikey.

delete
Remove address to watch

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 only ethereum is supported), and the networks to remove from watch (see supported networks below).
Request
Response
Body Parameters
required
string
JSON payload: { "apiKey": "<api-key>", "address": "<account-address", "blockchain": "ethereum", "networks": ["main", "rinkeby"] }
200: OK
{
"msg": "success"
}
400: Bad Request
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. Supported Ethereum networks are listed below.

This endpoint will return success if the specified address on the specified network(s) was not being watched for the apikey.

Receive transaction notifications

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

system

blockchain of this transaction (currently only ethereum supported)

network

network id of this transaction (see table to supported networks below)

status

new state of this transaction (see table of supportd status values below)

asset

the symbol of the asset being trasnferred, e.g. ETH

direction

indicates if funds are incoming or outgoing relative to the watchedAddress

counterparty

the recipient of funds if watchedAddress is the sender in the transaction, the sender of funds if watchedAddress is the recipient in the transaction

watchedAddress

the watched account address which triggered the notification

apiKey

the API key associated with the watched address

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.

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.

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.

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.

Token transfer transaction

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"
}

Supported Ethereum Networks

Name

Id

main

1

ropsten

3

rinkeby

4

goerli

5

kovan

42

Transaction Events (State Changes)

Key

Description

pending

server detected transaction in mempool indicating transaction is pending

speedup

server detected replacement transaction in mempool with more gas

cancel

server detected replacement transaction in mempool sent to another wallet account (not contract) with more gas and no value

confirmed

server detected transaction on blockchain as confirmed

failed

server detected transaction on blockchain as failed

dropped

server detected transaction removed from mempool and not confirmed in a block