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.

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.

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.

{
    "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. Supported Ethereum networks are listed below.

{
    "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. Supported Ethereum networks are listed below.

{
    "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. Supported Ethereum networks are listed below.

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:

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.

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

Transaction Events (State Changes)