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 SDK.
API usage has rate limits. Please see Rate Limits for more details.
Getting Started
Setup API Key
Create a Blocknative account by clicking the Sign up button on Mempool Explorer and following the instructions. Account creation requires email confirmation to complete.
Blocknative will create a Default API key for your account that you can use. You can create additional API keys from your account page on explorer.blocknative.com/account by clicking the Add new API key button to the upper right.
Secret keys additionally are available to be generated for API keys which allow secure usage of configuration modification endpoints.
Add new API key button
API Key creation form
Setup Webhook
Create a new webhook for an 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 webhooks must begin with https://hooks.slack.com/services.
Discord webhooks must begin with https://discordapp.com/api/webhooks.
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
Watch Address form
To stop notifications for an address, use the View Address button next to Add webhook, and click the Delete icon next to the address you'd like to stop watching.
View Addresses button lets you view a list of all addresses you're watching on that API Key
It is safe to add the same address multiple times or to unwatch addresses not being watched.
Authentication
No authentication is currently required to facilitate testing, apart from configuration modification endpoints. Basic auth (username/password) is supported and recommended for production use, and we are adding additional authentication methods based on customer requirements. We recommend HTTPS requests but also offer support for HTTP.
Secret keys
Secret keys are available to be generated per API key, which can be used to access these endpoints:
​Get all configuration scopes​
​Get configuration in specific scope​
​Add a configuration​
​Delete a configuration​
These end points require a 'credentials' header which takes the API key and associated secret key in one variable in the form "apiKey:secretKey".
Example: 9ed49579-a78b-4c82-b796-6db3aded6ed2:67ed12d1-f0ab-4f18-812c-58356684728b
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",
  "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"
}
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. 
get
Get all configuration scopes
https://api.blocknative.com/<blockchain>/<network>/configs
Use this endpoint to access all of the configuration scopes given on an API key. Include the appropriate blockchain and network, for which supported networks are listed below. Include your API key and it's associated secret key in a "credentials" header via the formatting "apiKey:secretKey". Your secret key can be set via your Accounts page where your keys are listed.
Request
Response
Request
Path Parameters
network
required
string
Network with watched addresses
blockchain
required
string
Blockchain with watched addresses
Headers
credentials
required
string
Here we define an API key and secret key together in the form "apiKey:secretKey"
Response
200: OK
[
    "global",
    "0x7a250d5630b4cf539739df2c5dacb4c659f2488d"
]
400: Bad Request
Response body will describe nature of request failure.
​
Examples:
incorrect or no header apiKey:secretKey given
XYZ is not a valid apiKey
invalid secret key
get
Get configuration in specific scope
https://api.blocknative.com/<blockchain>/<network>/configs/<raw-scope>
Use this endpoint to access the full config deployed at a specific blockchain, network, API key and scope. Include the appropriate blockchain and network, for which supported networks are listed below. Include your API key and it's associated secret key in a "credentials" header via the formatting "apiKey:secretKey". Your secret key can be set via your Accounts page where your keys are listed. 
Request
Response
Request
Path Parameters
raw-scope
required
string
The desired scope, options for this path can be retrieved by the 'Get all configuration scope' endpoint detailed above
network
required
string
Network with watched addresses
blockchain
required
string
Blockchain with watched addresses
Headers
credentials
required
string
Here we define an API key and secret key together in the form "apiKey:secretKey"
Response
200: OK
{
    "configName": "example config name",
    "fields": [
        "example field"
    ],
    "filters": [
        {
            "status": "example"
        }
    ],
    "abi": []
}
400: Bad Request
Response body will describe nature of request failure.
​
Examples:
incorrect or no header apiKey:secretKey given
XYZ is not a valid apiKey
invalid secret key
put
Add a configuration
https://api.blocknative.com/<blockchain>/<network>/configs/<raw-scope>
Use this endpoint to add configurations to certain API keys at certain blockchains and networks. Include your API key and it's associated secret key in a "credentials" header via the formatting "apiKey:secretKey".

Configurations can be exported from Mempool Explorer as specified here (https://docs.blocknative.com/mempool-explorer#configurations-sidebar).
Request
Response
Request
Path Parameters
raw-scope
required
string
The desired scope, options for this path can be retrieved by the 'Get all configuration scope endpoint' detailed above
network
required
string
Network with watched addresses
blockchain
required
string
Blockchain with watched addresses
Headers
credentials
required
string
Here we define an API key and secret key together in the form "apiKey:secretKey"
Body Parameters
required
string
Example JSON payload for an address:
{ 
    "configName": "example",
    "fields": ["example field"],
    "filters": [{"status": "pending"}],
    "abi" : []
}
Response
200: OK
{
    "msg": "ok"
}
400: Bad Request
Response body will describe nature of request failure.
​
Examples:
incorrect or no header apiKey:secretKey given
XYZ is not a valid apiKey
invalid secret key
Cannot set config item <key> in <scope>
Reached max config limit for <apiKey>:<blockchain>:<network>
Websocket configuration example
{
    "configName": "Limiting my public BN API key",
    "allowedOrigins": ["http://example.com", "http://example2.com"],
    "ipNotificationRatelimit": 250,
    "ipNotificationRatelimitWindow": 1,
    "ipPendingSimulationRatelimit": 50,
    "ipPendingSimulationRatelimitWindow": 1
}
Global configuration example
{
    "configName": "Global config example",
    "fields": ["example field"],
    "filters": [{"status": "pending"}]
}
Address configuration example
{ 
    "configName": "Example address config",
    "fields": ["example field"],
    "filters": [{"status": "pending"}],
    "abi" : []
}
delete
Delete a configuration
https://api.blocknative.com/<blockchain>/<network>/configs/<raw-scope>
Using this endpoint, you can clear a configuration set at a certain API key for a blockchain, network and scope. Include your API key and it's associated secret key in a "credentials" header in the form "apiKey:secretKey".
Request
Response
Request
Path Parameters
raw-scope
required
string
The desired scope, options for this path can be retrieved by the 'Get all configuration scope endpoint' detailed above
network
required
string
Network with watched addresses
blockchain
required
string
Blockchain with watched addresses
Headers
credentials
required
string
Here we define an API key and secret key together in the form "apiKey:secretKey"
Response
200: OK
{
    "msg": "ok"
}
400: Bad Request
Response body will describe nature of request failure.
​
Examples:
incorrect or no header apiKey:secretKey given
XYZ is not a valid apiKey
invalid secret key
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,
  "gasPriceGwei": Number,
  "gasUsed": String, present only when the tx is on-chain,
  "baseFeePerGas": String,
  "maxPriorityFeePerGas": String,
  "maxFeePerGas" String,
  "type": number,
  "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',
  "estimatedBlocksUntilConfirmed": Number, or null for estimates of 1-5
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
gasPriceGwei
Amount, in gwei, per unit of gas, rounded to an integer
gasUsed
Gas used during transaction execution. Only present when the tx is on-chain.
baseFeePerGas
(post-London fork) base fee per gas of this block
maxPriorityFeePerGas
(type 2 transactions) max priority fee per gas in wei
maxFeePerGas
(type 2 transactions) max fee per gas in wei
type
(post-London fork) transaction type
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
Transaction signature component (hex encoded)
r
Transaction signature component (hex encoded)
s
Transaction signature component (hex encoded)
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
estimatedBlocksUntilConfirmed
Predicted number of blocks from pendingBlockNumberuntil confirmation based ongasPriceand Gas Platform data. Field is 1 - 5 or nullfor estimates outside of 1 - 5.
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, // the UTC time of first detection of current status
  "pendingTimeStamp": String // ISO UTC time of initial pending status detection
  "pendingBlockNumber": Number // the chain head block number at time of pending detection
  "transactionIndex": Number, // optional, present if status confirmed, failed
  "blockTimeStamp": String, // optional, present if status confirmed, failed - UTC time of miner block creation
  "timePending": String, // optional, present if status confirmed, failed, speedup, cancel. "-1" if first detectiong is on-chain.
  "blocksPending": Number, // optional, present if status confirmed, failed, speedup, cancel
  "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)
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
UTC ISO timestamp when Blocknative first detected this transaction update
pendingTimeStamp
UTC ISO timestamp when Blocknative first detected the pending state for this transaction
pendingBlockNumber
The chain head block number when the pending state was first detected
transactionIndex
Optional. For confirmed or failed transactions, the index (order) of the transaction in the block.
blockTimeStamp
Optional. UTC ISO block timestamp the miner reported when collating the block this transaction was eventually mined in. The block timestamp is usually a few seconds before timeStamp, the difference being the time between the miner collating the block, and the block being mined and propagated throughout the network
timePending
Optional. The number of milliseconds from initial pending detection to confirmed or failed detection. "-1" if first detection is on-chain.
blocksPending
Optional. The number of blocks since the initial pending detection to confirmed or failed detection.
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 hash of the transaction that replaced this transaction in the txpool
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 v3 (Factory, Routing, NFT Descriptor, NFT Positional Manager and Migrator)
Uniswap v2 (Routing and Factory)
Uniswap v1
Sushiswap Router
0x Protocol v2.1
0x Protocol v3
Curve.Fi (All pools shown here)
Synthetix ExchangeRates
Synthetix Proxy
MakerDAO
Rebalancing Set Exchange Issuance v2
Set Protocol
Abridged
Pillar Badge
rToken
1inch Exchange V1
1inch Exchange V2
1inch Exchange V3
Aave: Lending Pool V2
Aave Flashloans
Balancer (BFactory, BPool, Distribution and Exchange Proxy 2)
Pancakeswap Router (Binance Smart Chain)
Pancakeswap Router V2 (Binance Smart Chain)
Honeyswap Router (xDai)
Sushiswap V2 Factory
DIGG Orchestrator
Quickswap Router & Factory (Matic)
Aave Lending Pool (Matic)
Aavegotchi: Opensea (Matic)
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
Simulated Pending Payload
Blocknative will send pending-simulationnotifications when a watchedAddress is detected in the from or to field of the main transaction or internal transactions of a contract call. The notification will include details of the internal transactions and balance changes resulting from those internal transactions. The internal transaction details and balance changes are probabilistic based on simulating the transaction against the latest confirmed block. Fields are not ordered.
pending-simulation notifications are only available for Ethereum Main Network.
The payload structure for pending-simulation notifications is the same as for confirmed notifications with the addition of the following object.
"simDetails": {
    "blockNumber": Number,
    "performanceProfile": {
      "breakdown": [
        {
          "label": "detected",
          "timeStamp": String // UTC time of first detection of transaction
        },
        {
          "label": "traceStart",
          "timeStamp": String // UTC time of when transaction simulation started
        },
        {
          "label": "traceEnd",
          "timeStamp": String // UTC time of when transaction simulation completed
        },
        {
          "label": "dispatch",
          "timeStamp": String // UTC time of when notification sent
        }
      ],
      "e2eMs": Number // end to end processing time in milliseconds
    }
  }
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",
  "gasPriceGwei": 10,
  "hash": "0x7fb386cc248fc46f9a56c53794f1580b6c48f6e16e4c2c5ed5e7a533af2ac2cf",
  "input": "0x",
  "to": "0x87c382487b6f20926acf7076de1210845d62e7cc",
  "transactionIndex": 0,
  "value": "100000000000000000",
  "asset": "ETH",
  "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",
  "gasPriceGwei": 1,
  "hash": "0x1ae540c5f8e4f50e951a3192d05cfd2da1028d4c7275455087de6dddd1139188",
  "input": "0x6c5c7a700000000000000000000000006921144ad2a2923ae11c5652feb3b0d9053d9152",
  "to": "0x9E7aE8c4D07670Df36FdB88c1b3Ae06dc4625fa0",
  "transactionIndex": 6,
  "value": "0",
  "asset": "ETH",
  "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 [email protected] 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",
    "gasPriceGwei": 10,
    "hash": "0xb85704efacd25d28cc9ab7e0eb726a30ed4dd4607a5008d57eb69bc262db503f",
    "input": "0xa9059cbb0000000000000000000000006f782dbf141c50e0b79b044b471fb8d76bcb7aed0000000000000000000000000000000000000000000000004563918244f40000",
    "to": "0xaff4481d10270f50f203e0763e2597776068cbc5",
    "transactionIndex": 0,
    "value": "5000000000000000000",
    "asset": "WEENUS",
    "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,
  "blockHash": String,
  "blockHeight": Number
}
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
blockHash
Hash of the block the transaction was mined in (or null for pending transactions)
blockHeight
Height of the block the transaction was mined in (or null for pending transactions)
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[], 
"blockHeight": String,
"blockHash": String,
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 "-1" 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
blockHeight
Height of the block the transaction was mined in (or null for pending transactions)
blockHash
Hash of the block the transaction was mined in (or null for pending transactions)
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 and EVM Compatible
Name
Id
Description
main
1
Ethereum Mainnet
ropsten
3
Ethereum Testnet
rinkeby
4
Ethereum Testnet
goerli
5
Ethereum Testnet
kovan
42
Ethereum Testnet
bsc-main
56
Binance Smart Chain
xdai
100
Ethereum L2
matic-main
137
Polygon
Bitcoin
Name
Id
Description
main
1
Bitcon Main
testnet
2
Bitcon Testnet
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
pending-simulation
the transaction was detected in the "pending" area of the mempool and is eligible for inclusion in a block and has been simulated against the latest 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​

Mempool Explorer

Rate Limits

Last updated 2 weeks ago

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`
`gasPriceGwei`	Amount, in gwei, per unit of gas, rounded to an integer
`gasUsed`	Gas used during transaction execution. Only present when the tx is on-chain.
`baseFeePerGas`	(post-London fork) base fee per gas of this block
`maxPriorityFeePerGas`	(type 2 transactions) max priority fee per gas in wei
`maxFeePerGas`	(type 2 transactions) max fee per gas in wei
`type`	(post-London fork) transaction type
`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`	Transaction signature component (hex encoded)
`r`	Transaction signature component (hex encoded)
`s`	Transaction signature component (hex encoded)
`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`
`estimatedBlocksUntilConfirmed`	Predicted number of blocks from `pendingBlockNumber`until confirmation based on`gasPrice`and Gas Platform data. Field is `1 - 5` or `null`for estimates outside of 1 - 5.

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)
`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`	UTC ISO timestamp when Blocknative first detected this transaction update
`pendingTimeStamp`	UTC ISO timestamp when Blocknative first detected the `pending` state for this transaction
`pendingBlockNumber`	The chain head block number when the `pending` state was first detected
`transactionIndex`	Optional. For confirmed or failed transactions, the index (order) of the transaction in the block.
`blockTimeStamp`	Optional. UTC ISO block timestamp the miner reported when collating the block this transaction was eventually mined in. The block timestamp is usually a few seconds before `timeStamp`, the difference being the time between the miner collating the block, and the block being mined and propagated throughout the network
`timePending`	Optional. The number of milliseconds from initial `pending` detection to `confirmed` or `failed` detection. "-1" if first detection is on-chain.
`blocksPending`	Optional. The number of blocks since the initial `pending` detection to `confirmed` or `failed` detection.
`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 hash of the transaction that replaced this transaction in the txpool
`failureReason`	Optional. For `failed` transactions, the reason why the transaction failed. Some failures may not have a discernible reason.

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`

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.

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 the`address`. 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`

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`

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)

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
`blockHash`	Hash of the block the transaction was mined in (or `null` for `pending` transactions)
`blockHeight`	Height of the block the transaction was mined in (or `null` for `pending` transactions)

Field	Description
address	The address of the input/output transaction
value	The value in btc of the input/output transaction

Name	Id	Description
`main`	1	Ethereum Mainnet
`ropsten`	3	Ethereum Testnet
`rinkeby`	4	Ethereum Testnet
`goerli`	5	Ethereum Testnet
`kovan`	42	Ethereum Testnet
`bsc-main`	56	Binance Smart Chain
`xdai`	100	Ethereum L2
`matic-main`	137	Polygon

Key	Description
`pending`	the transaction was detected in the "pending" area of the mempool and is eligible for inclusion in a block
`pending-simulation`	the transaction was detected in the "pending" area of the mempool and is eligible for inclusion in a block and has been simulated against the latest 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

API

Getting Started

Setup API Key

Setup Webhook

Add Address to Watch

Authentication

Secret keys

Screencasts

API

postAdd transaction to watch

postAdd address to watch

deleteRemove address to watch

getList of watched addresses

Required elements of the API request path

Optional query string parameters for large lists

getList of watched transactions

Required elements of the API request path

Optional query string parameters for large lists

getGet all configuration scopes

getGet configuration in specific scope

putAdd a configuration

Websocket configuration example

Global configuration example

Address configuration example

deleteDelete a configuration

Ethereum Notifications

Base Payload

Metadata Payload

Decoded Contract Payload

Internal Transactions Payload

Simulated Pending Payload

Examples

Direct send transaction

Contract call transaction

Token transfer transaction

Bitcoin Notifications

Base Payload

Vin

Vout

Metadata Payload

Transfer

BalanceChange

Supported Networks

Ethereum and EVM Compatible

Bitcoin

Transaction Events (State Changes)

Get Started Today

post
Add transaction to watch

post
Add address to watch

delete
Remove address to watch

get
List of watched addresses

get
List of watched transactions

get
Get all configuration scopes

get
Get configuration in specific scope

put
Add a configuration

delete
Delete a configuration

`Vin`

`Vout`

`Transfer`

`BalanceChange`