Notify

Blocknative Documentation
Search…
Blocknative Documentation
Overview
Notify
Client library for a full notification UI experience. Powered by our Mempool API.
Live Demo
Checkout our live demo using React at https://reactdemo.blocknative.com/​
The demo is open source so you can see a sample implementation of Notify (and Onboard): https://github.com/blocknative/onboard-notify-react​
Sample Notifications
To see the notify.js library in action, checkout the code sandboxes at the end of this documentation or the open source demo site at https://reactdemo.blocknative.com/.
Notify.js uses Notify API, which has rate limits. Please see Rate Limits for more details.
Quickstart
It should take less than 5 minutes to get going with Blocknative Notify.
Create a Blocknative Account
Setup your Blocknative account at https://explorer.blocknative.com/account?signup=true using an email address. You will receive an email to confirm your account. You can then go to your account page at https://explorer.blocknative.com/account.
Create an API Key
On your Account page, create a new API key with your choice of name using the Add new API Key button on the top right. Blocknative will create a default API key for you but it is recommended you create your own as API keys segment analytics data. Consider using different API keys for development, staging, and production releases.
Add new API key button on the Account page
Install the widget using npm
1
npm install bnc-notify
Copied!
Initialize the Library
Use the minimum required config. There are more options available in our documentation.
1
import Notify from "bnc-notify"
2
​
3
var notify = Notify({
4
  dappId: apiKey,       // [String] The API key created by step one above
5
  networkId: networkId  // [Integer] The Ethereum network ID your Dapp uses.
6
});
Copied!
Track transactions
Send a transaction using web3.js and get the transaction hash while its processing. Let notify know the hash and it will track its progress through the mempool and into a block.
1
// get current account
2
const accounts = await web3.eth.getAccounts();
3
const address = accounts[0];
4
​
5
// send the transaction using web3.js and get the hash
6
web3.eth.sendTransaction({
7
    from: address,
8
    to: "0x792ec62e6840bFcCEa00c669521F678CE1236705",
9
    value: "1000000"})
10
.on('transactionHash', function(hash){
11
	// pass the hash to notify to track it
12
	notify.hash(hash)
13
};
Copied!
And you are live!
Sample Notifications
Example Code
For an example of a basic React demo integration of both Notify.js and Onboard.js, checkout the GitHub repo:

https://github.com/blocknative/onboard-notify-react​
and the live demo:
​https://reactdemo.blocknative.com/ ​
Screencasts
See the above Quickstart guide in a screencast:
Notify.js Quickstart Screencast
See how to add and customize advanced notifications to your Dapp:
Add and Customize Advanced Notifications
Initialization
1
import Notify from "bnc-notify"
2
​
3
const options = {
4
  dappId: String,
5
  system: String
6
  networkId: Number,
7
  onerror: Function
8
  darkMode: Boolean, // (default: false)
9
  mobilePosition: String, // 'top', 'bottom' (default: 'top')
10
  desktopPosition: String, // 'bottomLeft', 'bottomRight', 'topLeft', 'topRight' (default: 'bottomRight')
11
  txApproveReminderTimeout: Number, // (default: 20000)
12
  txStallPendingTimeout: Number, // (default: 20000)
13
  txStallConfirmedTimeout: Number // (default: 90000)
14
  transactionHandler: Function,
15
  clientLocale: String, // (default: 'en')
16
  notifyMessages: Object
17
}
18
​
19
const notify = Notify(options)
Copied!
dappId [required] (optional if in UI only mode)
Your unique api key that identifies your application. You can generate a dappId by visiting the Blocknative account page and create a free account.
system [default = 'ethereum']
The blockchain system that you would like to track transactions on. Currently supported systems are 'bitcoin' and 'ethereum'. 
networkId [required] (optional if in UI only mode)
The network id that your application runs on. The following values are valid:
Ethereum
1 Main Network
3 Ropsten Test Network
4 Rinkeby Test Network
5 Goerli Test Network
42 Kovan Test Network
56 Binance Smart Chain
100 xDai POA Network
137 Polygon Matic Main Network
Bitcoin
1 Main Network
2 Testnet Network
onerror
A function to catch any errors that Notify does not handle internally such as event rate limit errors.
darkMode
Boolean value sets notification rendering to use light text on dark background. Default is false.
mobilePosition
String value sets where notifications appear on mobile devices. Value must be either top or bottom. Default is top.
desktopPosition
String value sets where notifications appear on desktop devices. Value must be bottomLeft, bottomRight, topLeft, or topRight. Default is bottomRight.
txApproveReminderTimeout
Number value sets time to wait until approval reminder notification is presented. This notifications reminds user to confirm/approve a transaction for processing by the wallet. Default is 20000 milliseconds (20 seconds).
tsStallPendingTimeout
Number value sets time to wait until stall notification is presented if transaction is not detected in the txPool. Default is 20000 milliseconds (20 seconds).
tsStallConfirmedTimeout
Number value sets time to wait until stall notification is presented if transaction is not confirmed in a block. Default is 90000 milliseconds (90 seconds).
transactionHandler
The function defined for the transactionHandler parameter will be called once for every status update for every transaction that is associated with a watched address or a watched transaction. This is useful as a global handler for all transactions and status updates. The callback is called with the following object:
1
{
2
  emitterResult: Any, // The value that was returned from the emitter for this transaction
3
  transaction: TransactionObject // See below for details
4
}
Copied!
See the Transaction Object section for more info on what is included in the transaction parameter.
clientLocale
Sets the locale for internationalization within notify. Defaults to English ('en'). See the i18n section for more details.
notifyMessages
An object that defines all of the transaction messages. Can be used to customize the default messages, and can also be used to add multiple language support for transaction notifications. See the i18n section for more details.
Notifications
hash
To get notifications for every status that occurs after sending a transaction ("post-flight"), use the hash function:
1
// Ethereum
2
// send the transaction using web3.js and get the hash
3
web3.eth.sendTransaction(txOptions).on("transactionHash", hash => {
4
  // pash the hash in to notify.hash
5
  const { emitter } = notify.hash(hash)  
6
})
7
​
8
// Bitcoin
9
const { emitter } = notify.hash(txid) 
Copied!
Check out the Emitter Section for details on the emitter object
account
You can register an address with Notify to display notifications for all incoming and outgoing transactions that occur on that account by using the account function:
1
// Etherum
2
const accounts = await provider.enable()
3
// register address for all transactions that occur on the user's account
4
const { emitter } = notify.account(accounts[0])
5
​
6
// Bitcoin
7
const { emitter } = notify.account(address)
Copied!
Check out the Emitter Section for details on the emitter object
transaction
To get notifications for every status that occurs for the full transaction lifecycle ("pre-flight" and "post-flight"), use the transaction function:
The transaction function only applies to Ethereum transactions
1
const { emitter, result } = notify.transaction({
2
  estimateGas: Function,
3
  gasPrice: Function,
4
  balance: String,
5
  txDetails: {
6
    to: String,
7
    value: Number || String
8
  },
9
  sendTransaction: Function,
10
  contractCall: {
11
    methodName: String,
12
    params: Array
13
  }
14
})
Copied!
result is a promise that resolves with the id of the transaction or rejects with an error if there was an error initiating the transaction. The id is useful for when you would like to initiate the transaction yourself and didn't pass a sendTransaction function in to transaction. You can then send the transaction yourself, receive the hash, and then call notify.hash(hash, id). By passing in the id to hash you enable notify to link the preflight notifications to the post send transaction notifications, ensuring a consistent UX.
The transaction function takes an object as the argument which allows you to progressively opt in to which checks and corresponding notifications that you would like during the "pre-flight" phase of the transaction lifecycle. Below is a list of the parameters, what is expected for each of those parameters, and the corresponding notifications you will get by including those parameters:
estimateGas - [balance check notification]
The estimateGas function must return a Promise that resolves with a String that is the gas estimate in wei. This function can vary depending on whether it is a contract transaction or just a regular send transaction call.
gasPrice - [balance check notification]
The gasPrice function must return a Promise that resolves with a String that is the gas price in wei.
balance - [balance check notification]
The users' balance in wei
txDetails - [repeat transaction check notification]
The txDetails object includes a to parameter which is the address the transaction is being sent to and the value parameter, which is the value of the transaction.
contractCall - [repeat transaction check notification]
The contractCall object includes a methodName parameter which is the name of the method on the contract being called and the params parameter is the parameters that the contract method was called with.
sendTransaction - [send transaction error, approval reminder, and stall notifications]
The sendTransaction function must return a Promise that resolves with a String that is the transaction hash.
notification
You may want to trigger a notification for a custom event that may not be related to a transaction. You can use the notification function to do that:
1
const notificationObject = {
2
  eventCode: "dbUpdate"
3
  type: "pending",
4
  message: "Updating the database with your information"
5
}
6
​
7
const { update, dismiss } = notify.notification(notificationObject)
8
​
9
//.... somewhere else in your code
10
​
11
if (dbUpdated) {
12
  update({
13
    eventCode: "dbUpdateComplete"
14
    type: "success",
15
    message: "Your info is up to date!"
16
  })
17
} else {
18
  update({
19
    eventCode: "dbUpdateSlow"
20
    type: "pending",
21
    message: "Database update is taking longer than usual, hang in there!"
22
  })
23
}
Copied!
The notification function is called with a notification object with the following parameters:
eventCode: a string which is used to keep track of that event for your analytics dashboard
type: a string that defines the style - ['hint' (gray), 'pending' (yellow), 'success' (green), 'error' (red)]
message: a message string that is displayed on the notification
autoDismiss: a number in milliseconds before the notification auto dismisses or 0 for no auto dismissal. success and hint types default to 4000
onclick: a function to call when the notification is clicked by the user
Returned from the notification function is an object that has two functions defined on it:
update: a function that can be called with a new notification object to replace the original notification with
dismiss: a function that can be called to dismiss the notification manually
unsubscribe
You may want to unsubscribe from an account address or transaction hash that you are watching and stop receiving notifications:
1
// unsubscribe from watched address
2
notify.unsubscribe(address)
3
​
4
// unsubscribe from watched transaction
5
notify.unsubscribe(hash | txid)
Copied!
config
Some configuration options can be set or updated after the library is initialized:
1
notify.config({
2
  networkId: String,
3
  system: String,
4
  darkMode: Boolean, // (default: false)
5
  mobilePosition: String, // 'top', 'bottom' (default: 'top')
6
  desktopPosition: String, // 'bottomLeft', 'bottomRight', 'topLeft', 'topRight' (default: 'bottomRight')
7
  txApproveReminderTimeout: Number, // (default: 20000)
8
  txStallPendingTimeout: Number, // (default: 20000)
9
  txStallConfirmedTimeout: Number, // (default: 90000)
10
  clientLocale: String, // (default: 'en')
11
  notifyMessages: Object
12
})
Copied!
If a new networkId or system is passed to the config function, then the current WebSocket connection will automatically be closed and a new connection will be established.
Emitter
The emitter object returned is used to listen for transaction events:
1
emitter.on("txRepeat", transaction => {
2
  // return false for no notification
3
  // no return (or return undefined) to show default notification
4
  // return custom notification object to show custom notifications, can return all or one of the following parameters:
5
  return {
6
    type: String, // ['hint' (gray), 'pending' (yellow), 'success' (green), 'error' (red)]
7
    message: String, // The message you would like to display
8
    autoDismiss: Number // The number of milliseconds before the notification automatically hides or 0 for no autodismiss
9
    onclick: Function // A function to call when the notification is clicked
10
    link: String // a url string that will make the notification a link when clicked on
11
  }
12
})
13
​
14
// You can also use the `all` event to register a listener for all events for that transaction. The `all` listener will only be called if there isn't a listener defined for the particular event:
15
​
16
emitter.on("all", transaction => {
17
  // called on every event that doesn't have a listener defined on this transaction
18
})
Copied!
Linking to a Block Explorer
You may want to link to a block explorer (such as Etherscan, Alethio, Bloxy etc) on every transaction notification. To do this, a link parameter can be added to the notification object returned from the emitter callback specifying the url:
1
function addEtherscan(transaction) {
2
  return {
3
    link: `https://etherscan.io/tx/${transaction.hash}`
4
  }
5
}
6
​
7
// then on each transaction...
8
const { emitter } = notify.hash(hash)
9
emitter.on('all', addEtherscan)
Copied!
Event Codes
The following event codes are valid events to listen to on the transaction emitter:
Client Side Generated Events (when using transaction function):
txRequest: Transaction has been initiated and is waiting approval from the user
txRepeat: Transaction has the same value and to address, so may be a repeat transaction
txAwaitingApproval: A previous transaction is awaiting approval
txConfirmReminder: Transaction has not been confirmed after timeout
txStallPending: Transaction has not been received in the mempool after timeout
txStallConfirmed: Transaction has been in the mempool for longer than the timeout
txError: An error has occurred initiating the transaction
txSendFail: The user rejected the transaction
txUnderpriced: The gas was set too low for the transaction to complete
txSent: Transaction has been sent to the network
Server Side (Notify SDK) Generated Events
txPool: Transaction was detected in the "pending" area of the mempool and is eligible for inclusion in a block
txStuck: Transaction was detected in the "queued" area of the mempool and is not eligible for inclusion in a block
txConfirmed: Transaction has been mined
txFailed: Transaction has failed
txSpeedUp: A new transaction has been submitted with the same nonce and a higher gas price, replacing the original transaction
txCancel: A new transaction has been submitted with the same nonce, a higher gas price, a value of zero and sent to an external address (not a contract)
txDropped: Transaction was dropped from the mempool without being added to a block. NOTE: Transaction could reappear in mempool.
Local Networks
When using a local network (such as Ganache), Notify has no way of seeing pending and confirmed statuses for transactions on that network and will not display any notifications. The emitter will also not emit events for those statuses. Notify will set the network to local if a networkId is passed in during initialization that is not one of the supported networks​
Transaction Object
The callback that is registered for events on the emitter will be called with the following transaction object:
1
{
2
  status: String, // current status of the transaction
3
  hash: String, // transaction hash (ethereum)
4
  txid: String, // transaction id (bitcoin)
5
  to: String, // the address the transaction is being sent to
6
  from: String, // the address the transaction is being sent from
7
  gas: Number, // the gas in wei
8
  gasPrice: String, // the gasPrice in wei
9
  gasPriceGwei: Number, // the gasPrice in gwei
10
  nonce: Number, // the nonce of the transaction
11
  value: String, // the value being sent
12
  eventCode: String, // the event code for this status
13
  blockHash: String, // the hash of the block that this transaction was included in
14
  blockNumber: Number, // the block number of the block that this transaction was included in
15
  input: String, // hex string of the input data
16
  transactionIndex: Number, // same as the nonce
17
  counterParty: String, // address of the counterparty of the transaction when watching an account
18
  direction: String, // the direction of the transaction in relation to the account that is being watched ("incoming" or "outgoing")
19
  watchedAddress: String, // the address of the account being watched
20
  originalHash: String, // if a speedup or cancel status, this will be the hash of the original transaction
21
  asset: String, // the asset that was transferred
22
  contractCall: { // if transaction was a contract call otherwise undefined
23
    contractAddress: String, // the address of the contract that has been called
24
    contractType: String, // the contract type eg: ERC20, ERC721
25
    methodName: String, // the name of the method that was called
26
    params: {
27
      // params that the contract method was called with
28
    }
29
  },
30
  system: String // 'bitcoin' or 'ethereum'
31
}
Copied!
Customizing CSS
To gain the required specificity to override the default styles, use the class name .bn-notify-custom plus the class name that you would like to override in your CSS file. For example, if you would like to customize the font-family of the notifications, then you would target the top level ul element that has the class bn-notify-notifications in your CSS file:
1
.bn-notify-custom .bn-notify-notifications {
2
    font-family: Roboto;
3
}
Copied!
Below is a list of the main classes that you would target to customize the CSS: 
class name
description
.bn-notify-notifications
container holding all of the notifications
.bn-notify.notification
top level element of each notification
.bn-notify-notification-info
notification content container
.bn-notify-notification-info-message
notification message
.bn-notify-notification-close
close notification icon container
i18n
Notify has internationalization built in, allowing you to enable transaction notifications that match your user's locale and to give the user an option to switch locale.
clientLocale
Notify will automatically detect the browser's locale and set an internal clientLocale. If that locale is defined within the notifyMessages object, then it will use that locale for all transaction messages. If it isn't defined, then it will fallback to the default 'en' locale. You can explicitly set the clientLocale for the user by calling the config function or passing it in via initializationObject.
notifyMessages
This object contains the messages for all the transaction states supported by Notify. The library has default transaction messages for the 'en' clientLocale and can be extended to include transaction messages for additional clientLocale settings. To extend the default notifyMessages object, you can pass in a notifyMessages object to either the config function or to the initializationObject.
Below is an example object that implements a 'es' (Spanish) notifyMessages object:
1
const notifyMessages = {
2
  es: {
3
    transaction: {
4
      txRequest: 'Su transacción está esperando que confirme',
5
      nsfFail: 'No tiene fondos suficientes para completar esta transacción.',
6
      txUnderpriced:
7
        'El precio del gas para su transacción es demasiado bajo, intente nuevamente con un precio del gas más alto',
8
      txRepeat: 'Esto podría ser una transacción repetida',
9
      txAwaitingApproval:
10
        'Tienes una transacción anterior esperando que confirmes',
11
      txConfirmReminder:
12
        'Confirme su transacción para continuar, la ventana de transacción puede estar detrás de su navegador',
13
      txSendFail: 'Rechazaste la transacción',
14
      txSent: 'Su transacción ha sido enviada a la red.',
15
      txStallPending:
16
        'Su transacción se ha estancado y no ha ingresado al grupo de transacciones',
17
      txPool: 'Su transacción ha comenzado',
18
      txStallConfirmed:
19
        'Su transacción se ha estancado y no ha sido confirmada.',
20
      txSpeedUp: 'Su transacción ha sido acelerada',
21
      txCancel: 'Tu transacción está siendo cancelada',
22
      txFailed: 'Su transacción ha fallado',
23
      txConfirmed: 'Su transacción ha tenido éxito.',
24
      txError: 'Vaya, algo salió mal, por favor intente nuevamente'
25
    },
26
    watched: {
27
      txPool:
28
        'su cuenta está {verb, select, receiving {recibiendo} sending {enviando}} {formattedValue} {asset} {preposition, select, from {desde} to {a}} {counterpartyShortened}',
29
      txSpeedUp:
30
        'su cuenta está {verb, select, receiving {recibiendo} sending {enviando}} {formattedValue} {asset} {preposition, select, from {desde} to {a}} {counterpartyShortened}',
31
      txCancel:
32
        'su cuenta está {verb, select, receiving {recibiendo} sending {enviando}} {formattedValue} {asset} {preposition, select, from {desde} to {a}} {counterpartyShortened}',
33
      txConfirmed:
34
        'su cuenta {verb, select, received {recibió} sent {ha enviado}} con éxito {formattedValue} {asset} {preposition, select, from {de} to {a}} {counterpartyShortened}',
35
      txFailed:
36
        'su cuenta fallado {verb, select, received {recibió} sent {ha enviado}} con éxito {formattedValue} {asset} {preposition, select, from {de} to {a}} {counterpartyShortened}'
37
    },
38
    time: {
39
      minutes: 'min',
40
      seconds: 'sec'
41
    }
42
  }
43
}
44
​
45
notify.config({ notifyMessages })
Copied!
The notifyMessages object above would get merged with Notify's internal notifyMessages object, extending Notify to support both English and Spanish transaction notification messages.
You can include as many of the above parameters as you would like in each language object. If Notify gets an undefined value back from the language object, then it will fallback to the English default included in Notify.
Notify uses format.js under the hood, which uses the ICU message syntax to format messages. Check out their guide to the ICU message syntax here.
For each language, you can include a transaction object, a watched object and a time object. 
The transaction object will be referenced for notifications that have been triggered via the hash or transaction function. 

The watched object will be referenced for notifications that have been triggered by watching an address via the account function.

The time object will be referenced for expressing the amount of time that has passed during pending states on the notification.
Each message will be called with the following inputs that will be formatted in to a message string:
The formatted value of the transaction:
formattedValue - (transaction, watched)
The asset that is being sent or received:
asset - (transaction, watched)
The correct verb based on whether the transaction is being incoming or outgoing and whether it is confirmed or pending:
verb - (watched)
Possible values are: 'received', 'sent', 'receiving', 'sending'
The correct preposition based on the direction of the transaction:
preposition - (watched)
Possible values are: 'from', 'to'
A shortened address of the counter party of the transaction:
counterpartyShortened - (watched)
UI Only Mode
You can optionally run Notify.js as a simple notification UI library by not including a dappId in your initialization options. In this scenario, Notify.js will not initiate a WebSocket connection to the Blocknative servers and all functionality other than the notification function will be disabled.
Rollup Builds
You may run in to an error: Uncaught TypeError: dist is not a constructor when building with Rollup.js. To fix this issue make sure that you are using @rollup/plugin-commonjs version 16.0.0 and above
Get Started Today
Sign up for a free Blocknative Account at https://explorer.blocknative.com/account?signup=true with your work email address. 
 If you have any questions, connect with the team on our discord​
React Demo
To see a Notify integration in a simple React app you can check out our react-demo repo on GitHub: https://github.com/blocknative/react-demo

We have the reactdemo codebase deployed so that you try Notify from an end user perspective: https://reactdemo.blocknative.com/​
​
​
​
​
Mempool SDK
Onboard
Last modified 3mo ago
Live Demo

Quickstart

Create a Blocknative Account

Create an API Key

Install the widget using npm

Initialize the Library

Track transactions

And you are live!

Example Code

Screencasts

Initialization

dappId [required] (optional if in UI only mode)

system [default = 'ethereum']

networkId [required] (optional if in UI only mode)

onerror

darkMode

mobilePosition

desktopPosition

txApproveReminderTimeout

tsStallPendingTimeout

tsStallConfirmedTimeout

transactionHandler

clientLocale

notifyMessages

Notifications

hash

account

transaction

notification

unsubscribe

config

Emitter

Linking to a Block Explorer

Event Codes

Client Side Generated Events (when using transaction function):

Server Side (Notify SDK) Generated Events

Local Networks

Transaction Object

Customizing CSS

i18n

clientLocale

notifyMessages

UI Only Mode

Rollup Builds

Get Started Today

React Demo

​

`dappId` [required] (optional if in UI only mode)

`system` [default = 'ethereum']

`networkId` [required] (optional if in UI only mode)

`onerror`

`darkMode`

`mobilePosition`

`desktopPosition`

`txApproveReminderTimeout`

`tsStallPendingTimeout`

`tsStallConfirmedTimeout`

`transactionHandler`

`clientLocale`

`notifyMessages`

`hash`

`account`

`transaction`

`notification`

`unsubscribe`

`config`

Client Side Generated Events (when using `transaction` function):

`clientLocale`

`notifyMessages`
