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

Notify API usage has rate limits. Please see Rate Limits for more 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.

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

Setup Webhook

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.

Webhook creation form

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 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:

Address Type

Example

Pubkey hash (P2PKH address)

17VZNX1SN5NtKa8UQFxwQbFeFc3iqRYhem

Script hash (P2SH address)

3EktnHQD7RiAE6uzMj2ZifT9YgRrkSgzQX

SegWit Pay 2 Witness Public Key Hash (P2SH-P2WPKH)

3EktnHQD7RiAE6uzMj2ZifT9YgRrkSgzQX

SegWit mainnet (P2WPKH address)

bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4

SegWit Testnet (P2WPKH address)

tb1qw508d6qejxtdg4y5r3zarvary0c5xw7kxpjzsx

SegWit mainnet (P2WSH address)

bc1qrp33g0q5c5txsp9arysrx4k6zdkfs4nce4xj0gdcccefvpysxf3qccfmv3

SegWit Testnet (P2WSH address)

tb1qrp33g0q5c5txsp9arysrx4k6zdkfs4nce4xj0gdcccefvpysxf3q0sl5k7

Testnet pubkey hash

mipcBbFg9gMiCh81Kj8tqqdgoZub1ZJRfn

Testnet script hash

2MzQwSSnBHWHqSAqtTVQ6v47XtaisrJa1Vc

Add Address to Watch

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.

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.

Screencasts

See how to setup a Slack webhook in this screencast:

How to Setup a Webhook Screencast

API

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

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

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 ethereum and bitcoin are supported), and the networks to remove from watch (see supported networks below).
Request
Response
Request
Body Parameters
required
string
JSON payload: { "apiKey": "<api-key>", "address": "<account-address>", "blockchain": "ethereum", "networks": ["main", "rinkeby"] }
Response
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 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.

get
List of watched addresses

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.
Request
Response
Request
Path Parameters
your-api-key
required
string
Your API key
blockchain
required
string
Blockchain with watched addresses
network
required
string
Network with watched addresses
Query Parameters
page
optional
number
The page of watched addresses to receive
size
optional
number
The size of a page
order
optional
string
The creation time order of watched addresses
Response
200: OK
{
"total": 0, // total number of watched addresses
"page": 1, // current page number of watched addresses
"pageSize": 1000, // maximum size of current page
"items": [] // array of watched address strings
}
400: Bad Request
Response body will describe nature of request failure.
Examples:
XYZ is not a valid apiKey

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 and bitcoin are 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.

get
List of watched transactions

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.
Request
Response
Request
Path Parameters
your-api-key
required
string
Your API key
blockchain
required
string
Blockchain with watched transactions
network
required
string
Network with watched transactions
Query Parameters
page
optional
number
The page of watched transactions to receive
size
optional
number
The size of a page
order
optional
string
The creation time order of watched transactions
Response
200: OK
{
"total": 0, // total number of watched transactions
"page": 1, // current page number of watched transactions
"pageSize": 1000, // maximum size of current page
"items": [] // array of watched transaction hash/id strings
}
400: Bad Request
Response body will describe nature of request failure.
Examples:
XYZ is not a valid apiKey

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 and bitcoin are 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.

Ethereum Notifications

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.

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.

"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

from

The address initiating, signing, the transaction

to

Address receiving the transaction

nonce

The from address nonce (transaction count from that address)

gas

Maximum amount of gas available to the transaction

gasPrice

Amount, in wei, per unit of gas

gasUsed

Gas used during transaction execution. Only present when the tx is on-chain.

value

Amount of ETH transferred directly from from address

hash

Transaction id hash unique for every transaction

input

Data sent to transaction. For direct value transfers from one external account to another, this field contains 0x. For contract calls, this value contains the contract method signature and params as a hex string.

v, r, s

Transaction signature components (ECDSA signature components and recovery id)

blockHash

Block id hash for transactions that are on-chain. Field is null unless notification status is confirmed or failed

blockNumber

Block number for transactions that are on-chain. Field is null unless notification status is confirmed or failed

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.

"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),
"failureReason": String (optional, present if status is failed)

Field

Description

system

Blockchain of this transaction

network

Network name of this transaction (see table to supported networks below)

status

New status of this transaction (see table of supported status values below)

timePending

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 pending detection. This field is present only if transaction status indicates an on-chain state (confirmed or failed)

apiKey

Blocknative API key associated with the notification

monitorVersion

Version number of the Blocknative monitor that detected the transaction state change

monitorId

Identifier of the Blocknative monitor that first detected the transaction state change

serverVersion

Version number of the Blocknative server that delivered the notification

timestamp

Timestamp when notification is sent

asset

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

direction

Optional. Indicates if funds are incoming or outgoing relative to the watchedAddress. This field is present only if notification triggered by watchedAddress

counterparty

Optional. Address of recipient of funds if watchedAddress is the sender in the transaction, address of sender of funds if watchedAddress is the recipient in the transaction. This field is present only if notification triggered by watchedAddress

watchedAddress

Optional. Watched address which triggered the notification. This field is present only if notification triggered by watchedAddress

replaceHash

Optional. The transaction hash of the replaced transaction from a speedup or cancel

failureReason

Optional. For failed transactions, the reason why the transaction failed. Some failures may not have a discernible reason.

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.

"contractCall": {
"contractType": String,
"contractAddress": String,
"methodName": String,
"params": {
// key value pairs specific to the contract method
},
"contractName": String,
"contractDecimals": Number (optional),
"decimalValue": String (optional),
}

Blocknative currently supports decoding of the following contracts and regularly adds more:

  • Uniswap v2 (Routing and Factory)

  • Uniswap v1

  • 0x Protocol v2.1

  • 0x Protocol v3

  • Curve.Fi

  • Synthetix ExchangeRates

  • Synthetix Proxy

  • MakerDAO

  • Rebalancing Set Exchange Issuance v2

  • Set Protocol

  • Abridged

  • Pillar Badge

  • rToken

Along with supported Ethereum token protocols:

  • ERC-20

  • ERC-721

  • ERC-165

  • ERC-777

  • ERC-1820

Field

Description

contractType

Type of the called contract

contractAddress

Address of the called contract

methodName

Name of the called method

params

Optional. A series of keys and values specific to the contract method. This field is present only if the contract method call includes parameters.

contractName

Optional. Name of the called contract

contractDecimals

Optional. The result of calling the decimal() method on the smart contract, if it exists

decimalValue

Optional. If there is a value field in the params object, and contractDecimals is present, decimalValue will equal value / 10^contractDecimals

Internal Transactions Payload

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

internalTransactions

Array of objects containing details of each internal transaction (see below)

netBalanceChanges

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

Type of internal transaction (one of CALL, DELEGATECALL, STATICCALL, CALLCODE)

from

Address initiating the internal transaction call (typically the parent (main) transaction's contract address

to

Address the internal transaction is calling or sending value to

input

Data sent to internal transaction. For value transfers from external account initiating parent (main) transaction to another external account, this field contains 0x. For contract calls, this value contains the contract method signature and params as a hex string.

gas

Maximum amount of gas available to the internal transaction

gasUsed

Amount of gas actually used executing the internal transaction

value

Amount of ETH transferred directly to to address from parent (main) transaction from address.

contractCall

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 transfer or transferFrom call, the contractCall object will include an additional field, contractAlias with the symbol of the token transferred.

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

Address involved in internal transaction. Each address contains an array of balances changes, one for each counterparty

delta

Amount of value transfer (balance change) in wei to theaddress. Outgoing value is represented as a negative balance change and incoming value is represented as a positive balance change

asset

Details of the asset being transferred. Contains contractAddress, type and symbol

contractAddress

The address of the token contract if the value is not ETH (ether), not present if the value os ETH

type

The type of asset transferred (e.g. "ether" or "erc20")

symbol

The symbol of the asset transferred. "ETH" or appropriate ERC20 symbol

breakdown

Array of individual transfers to address for the current asset

counterparty

Address of the other side of the transfer relative to the address

amount

The amount of asset transferred with this counterparty

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.

{
"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.

{
"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.

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

Bitcoin Notifications

Base Payload

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

txid

The transaction id unique for each transaction

hash

The transaction hash unique for each transaction, can be the same as the txid

version

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.

size

Total size of this transaction

vsize

The virtual size of this transaction

weight

The weight of this transaction

locktime

The block number or timestamp at which this transaction is unlocked

vin

An array of transaction inputs (see below for details)

vout

An array of transaction outputs (see below for details)

hex

The hex format of the transaction

Vin

"txid": String,
"vout": Number,
"scriptSig": {
"asm": String,
"hex": String
},
"txinwitness": String[],
"sequence": Number

Field

Description

txid

The unique transaction id for this input transaction

vout

The index of which output this transaction is in it's vout array

scriptSig

The unlocking script that satisfies the conditions placed on the output by the scriptPubKey

txinwitness

Contains data required to check transaction validity

sequence

A number intended to allow unconfirmed time-locked transactions to be updated before being finalized

Vout

"value": Number,
"n": Number,
"scriptPubKey": {
"asm": String,
"hex": String,
"reqSigs": Number,
"type": String,
"addresses": String[]
}

Field

Description

value

The value of this output in btc

n

The index of this input in the vout array

scriptPubKey

The script which sets the conditions that must be fulfilled for the value to be spent

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.

"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

txid

The transaction id unique for each transaction

system

Blockchain of this transaction

network

Network name of this transaction (see table to supported networks below)

status

New status of this transaction (see table of supported status values below)

apikey

Blocknative API key associated with the notification

monitorVersion

Version number of the Blocknative monitor that detected the transaction state change

monitorId

Identifier of the Blocknative monitor that first detected the transaction state change

serverVersion

Version number of the Blocknative server that delivered the notification

timeStamp

Timestamp when notification is sent

timePending

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 pending detection. This field is present only if transaction status indicates an on-chain state (confirmed or failed)

watchedAddress

Optional. Watched address which triggered the notification for this apikey. This field is present only if notification was triggered by activity on a watchedAddress

inputs

An array of input Transfer objects (see below)

outputs

An array of output Transfer objects (see below)

fee

The fee paid in btc for this transaction

netBalanceChanges

An array of Balance Change Objects (see below) that represent the net balance change for each address involved in the transaction

Transfer

"address": String,
"value": String

Field

Description

address

The address of the input/output transaction

value

The value in btc of the input/output transaction

BalanceChange

"address": String,
"delta": String

Field

Description

address

The address that had the balance change

delta

number indicating net change in funds at this address as result of all inputs/outputs

Supported Networks

Ethereum

Name

Id

main

1

ropsten

3

rinkeby

4

goerli

5

kovan

42

xdai

100

Bitcoin

Name

Id

main

1

testnet

2

Transaction Events (State Changes)

Currently pending and confirmed transactions are supported for Bitcoin

Key

Description

pending

the transaction was detected in the "pending" area of the mempool and is eligible for inclusion in a block

stuck

the transaction was detected in the "queued" area of the mempool and is not eligible for inclusion in a block

speedup

a replacement transaction (same nonce and from, higher gas) was detected in the mempool with the same to, value and input parameters as the transaction being replaced

cancel

a replacement transaction (same nonce and from, higher gas) was detected in the mempool with different to, value or input parameters compared to the transaction being replaced

confirmed

the transaction was mined with no errors

failed

the transaction was mined, but failed to execute due to EVM error

dropped

the transaction was dropped from the mempool before being mined into a block

Get Started Today

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