Onboard (older version)
This page is for Onboard v1, which is an older version. For web3-onboard which is the newest, modernized version, see the web3-onboard page.
Use the latest version of Onboard at https://github.com/blocknative/web3-onboard . This version is no longer maintained.

Example desktop wallet select modal

Example mobile wallet select modal
It should take less than 5 minutes to get going with Blocknative Onboard.
Go to the Account Dashboard at https://explorer.blocknative.com/account and setup an account with an email address. You will receive an email to confirm your account.
On the Account Dashboard at https://explorer.blocknative.com/account, create an API key with your choice of name or use/rename the Default Key. Consider using different API keys for development, staging, and production releases.

npm install bnc-onboard
Use the minimum required config. There are more options available as detailed in the initialization section.
import Onboard from 'bnc-onboard'
import Web3 from 'web3'
let web3;
const onboard = Onboard({
dappId: apiKey, // [String] The API key created by step one above
networkId: networkId, // [Integer] The Ethereum network ID your Dapp uses.
subscriptions: {
wallet: wallet => {
web3 = new Web3(wallet.provider)
}
}
});
The wallet subscription function will be called when the user selects a wallet so you can instantiate web3 with the selected provider.
Ask the user to select a wallet and then check wallet is ready to transact.
await onboard.walletSelect();
await onboard.walletCheck();
See the above Quickstart guide in a screencast:
Onboard.js Quickstart Screencast
For a deeper dive with additional wallets that builds on the Quick Start, see this screencast:
Additional Wallets Screencast
For an example of a basic React demo integration of both Onboard.js and Notify.js, checkout the GitHub repo:
https://github.com/blocknative/onboard-notify-react
and the live demo:
const options = {
dappId: String,
networkId: Number,
networkName: String,
darkMode: Boolean,
blockPollingInterval: Number,
subscriptions: {
address: Function,
network: Function,
balance: Function,
wallet: Function
},
walletSelect: {
heading: String,
description: String,
explanation: String,
wallets: Array,
agreement: {
version: String,
termsUrl: String,
privacyUrl: String
}
},
walletCheck: Array
}
Your unique
apiKey
that identifies your application. You can generate a dappId
by visiting the Blocknative account page and create a free account. The dappid
enables Onboard to use Blocknative notification services to efficiently maintain address balance state. This is not required to use Onboard to connect wallets to Dapps. It is required to efficiently get an up to date wallet balance value via the balance
subscription or getState()
calls.The
Ethereum
network id that your application runs on. The following values are valid:1
main
Ethereum Network mainnet3
ropsten
Ethereum Network testnet4
rinkeby
Ethereum Network testnet5
goerli
Ethereum Network testnet28
boba-rinkeby
Boba Network Rinkeby testnet42
kovan
Ethereum Network testnet56
bsc
Binance Smart Chain Network mainnet100
xdai
xDai POA Network mainnet137
polygon
Polygon-Matic Network mainnet250
fantom-opera
Fantom Network mainnet288
boba
Boba Network mainnet4000
fantom-testnet
Fantom Network testnet
This option allows one to specify a custom network name for all non-supported networks (see
networkId
above for supported networks). For instance, if you set networkId: 56
for Binance smart chain and the user is connected to a different network, the wallet select modal will show local as the network to switch to. But if you specify networkName: "Binance Mainnet"
then this will display instead of local.Opt for the Dark color scheme or not.
Change the rate at which blocks are polled by provider, default is set to 4 seconds.
If no
dappId
is provided, then "Powered by Blocknative" branding will be displayed on all modals. You can choose to hide the branding by setting hideBranding: true
. If you have included a dappId
then the branding will be hidden by default. If you would like the branding to display when including a dappId
then set hideBranding: false
.An object of callback functions that get called whenever the corresponding value changes. Use these callbacks to sync your UI or to store the values for use elsewhere in your code. Valid parameters to register callbacks for are:
address
- called with the user's current address[string]
ens
- called with the user's current ens name (if available)[object]
name
- The user's resolved ens name[string]
avatar
- A link to the user's avatar[string]
getText
- A function to retrieve the user's text records[function]
contentHash
- The user's content hash record[string]
network
- called with the user's current network id[number]
balance
- called with the user's current balance[string]
wallet
- called with the user's current wallet[object]
provider
- The JavaScript provider for interacting with the walletname
- The wallet display nameinstance
- If the wallet type is'sdk'
then this is the initialized wallet instancetype
- The wallet type'hardware' | 'injected' | 'sdk'
connect
- The function that initiates the wallet connection logicdashboard
- Some SDK wallets allow for opening to wallet dashboardicons
-[object]
Image strings for the wallet icon{ svg, src, srcset }
A object that defines how the wallet select screen will render using the following parameters:
heading
- [optional] : A string that will be the wallet select modal headingdescription
- [optional] : A string that will be the wallet select modal descriptionexplanation
- [optional] : A string that will be included in the "What is a Wallet" sectionwallets
- [optional] : An array of wallet modules or wallet initialization objects that the user can select fromagreement
- [optional]: An object containing properties for use with terms of service agreementversion
- The current version of the terms that the user needs to agree to. When this value is updated the user's agreement is invalidated and they must re-agree upon next usage.termsUrl
- [optional]: A string that will be used for the terms of service url that a user can agree to before using onboardprivacyUrl
- [optional]: A string that will be used for the privacy policy url that a user can agree to before using onboard
If not provided, then the default
heading
and description
and wallets
that don't require initialization will be included for you.An array of wallet check modules or wallet check initialization objects that will be used to check if the user is ready to transact.
To initialize Onboard, simply import the library and call it with your
initializationOptions
:import Onboard from 'bnc-onboard'
const initializationOptions = {
// ..... options here
}
const onboard = Onboard(initializationOptions)
The return value will be the initialized
onboard
library which contains the API functions below.If you initialize Onboard with a
networkId
that is not one of the supported networks all modals will refer to that network with the name unknown
. You can name unrecognized networks by also passing in a networkName
in to your initialization object:const onboard = Onboard({
// ... other init options
networkId: 137,
networkName: 'matic'
})
If you are using a local network for testing, you can ensure that the onboarding checks work correctly by setting the
networkId
for that local network to a number that is not taken by other valid networks.
If you are using the ganache-cli
for instance, you can set the networkId
via the -i
flag:ganache-cli -i 35
This will set the Ganache
networkId
to 35
Then in your Onboard config, also set the
networkId
property to the same value:const onboard = Onboard({
networkId: 35,
// ...other config options
})
When you are ready to get a user to select a wallet and connect it to your Dapp, you can call the
walletSelect
function to display the wallet select modal:const walletSelected = await onboard.walletSelect()
// returns a Promise that:
// resolves with true if the user selected a wallet
// resolves with false if the user exited from the wallet select modal
This function will show a modal that displays buttons for all of the wallets that you initialized onboard with. It will guide the user through the process of connecting to the wallet that they select. Once the process is successful the function will resolve with
true
. This means that the provider
subscription will have been called with the provider of the selected wallet and you can go ahead and instantiate your web3 library with the provider and also instantiate your contracts.The
walletSelect
function can also be called with a autoSelectWallet
string. If the string passed in is a valid walletName
, then Onboard will automatically select that wallet for the user. This enables saving the previously selected wallet in localStorage
and automatically selecting it for the user when they next visit your Dapp.Once a wallet is selected, you will want to make sure that the user's wallet is prepared and ready to transact by calling the
walletCheck
function:const readyToTransact = await onboard.walletCheck()
// returns a Promise that:
// resolves with true if user is ready to transact
// resolves with false if user exited before completing all wallet checks
This function will run through the
walletCheck
modules that were passed in via initialization sequentially, making sure the user has passed the condition contained in each module and eventually resolves with true
if the user completed the sequence. This means that the user is ready to transact. This function is useful to call before every transaction to make sure that nothing has changed since the last time it was called.You may want to reset all of Onboard's internal wallet state and also disconnect from any active SDK instances when a user logs out of your app. You can call the
walletReset
function to do this easily.// user wants to log out of session and the wallet state needs to be reset...
onboard.walletReset()
// this method is synchronous and returns undefined
If you want to show the account select modal for hardware wallets at any time you can call the
accountSelect
function. For example you could display a button that allows the user switch accounts:<button onclick="onboard.accountSelect()">Switch Account</button>
This function will give you the current state of the user:
const currentState = onboard.getState()
console.log(currentState)
// {
// address: string
// network: number
// balance: string
// wallet: Wallet
// mobileDevice: boolean
// appNetworkId: number
// }
You can update some configuration parameters by passing a
config
object in to the config
function:onboard.config({ darkMode: true, networkId: 4 })
Available parameters that you can update are:
darkMode
-[boolean]
networkId
-[number]
To initialize the built in wallet modules, an array of wallet initialization objects needs to be passed to the
walletSelect.wallets
parameter of the Onboard initialization object. The order of the array is the order that the wallets will be displayed. Mobile wallets will be displayed when a user is on a mobile device and desktop wallets are displayed when they are on a desktop device.Each wallet initialization object has additional optional customization parameters:
preferred
-Boolean
Will define whether it is shown at the top of the selection screen. If any of the wallets are set topreferred
, then all other wallets that aren't, will be hidden until the user clicks the "Show More" button. If there are no wallets set topreferred
, then the first four wallets will be shown and the remaining wallets will be hidden until the show more button is clicked.label
-String
Will over ride the wallet name that is displayed on the button.svg
-String
Ansvg
string that will over ride the icon that is displayed on the button.iconSrc
-String
An alternative to providing thesvg
string, by providing a url source.display
-Object
Customize which wallets to display based on which device a user is using. Note: For wallets that are mobile or desktop only this option will not override this. For instance, if a wallet is mobile only settingdisplay: { desktop: true }
will not display this wallet on desktop.desktop
-Boolean
default:true
mobile
-Boolean
default:true
An example configuration that includes all of the supported wallets:
import Onboard from 'bnc-onboard'
const FORTMATIC_KEY = "Your Fortmatic key here"
const PORTIS_KEY = "Your Portis key here"
const INFURA_KEY = "Your Infura key here"
const APP_URL = "Your app url here"
const CONTACT_EMAIL = "Your contact email here"
const RPC_URL = "https://<network>.infura.io/v3/<INFURA_KEY>"
const APP_NAME = "Your app name here"
const wallets = [
{ walletName: "coinbase", preferred: true },
{ walletName: "trust", preferred: true, rpcUrl: RPC_URL },
{ walletName: "metamask", preferred: true },
{ walletName: "authereum" },
{
walletName: 'trezor',
appUrl: APP_URL,
email: CONTACT_EMAIL,
rpcUrl: RPC_URL
},
{
walletName: 'ledger',
rpcUrl: RPC_URL
},
{
walletName: 'lattice',
rpcUrl: RPC_URL,
appName: APP_NAME
},
{
walletName: 'keepkey',
rpcUrl: RPC_URL
},
{
walletName: 'mewwallet',
rpcUrl: RPC_URL
},
{
walletName: 'cobovault',
rpcUrl: RPC_URL,
appName: APP_NAME,
},
{
walletName: 'keystone',
rpcUrl: RPC_URL,
appName: APP_NAME,
},
{
walletName: "fortmatic",
apiKey: FORTMATIC_KEY,
preferred: true
},
{
walletName: "portis",
apiKey: PORTIS_KEY,
preferred: true,
label: 'Login with Email'
},
{
walletName: "walletConnect",
infuraKey: INFURA_KEY
},
{ walletName: "opera" },
{ walletName: "operaTouch" },
{ walletName: "torus" },
{ walletName: "status" },
{ walletName: "walletLink" rpcUrl: RPC_URL, appName: APP_NAME }
{ walletName: "imToken", rpcUrl: RPC_URL },
{ walletName: "meetone" },
{ walletName: "mykey", rpcUrl: RPC_URL },
{ walletName: "huobiwallet", rpcUrl: RPC_URL },
{ walletName: "hyperpay" },
{ walletName: "wallet.io", rpcUrl: RPC_URL },
{ walletName: "atoken" },
{ walletName: "frame" },
{ walletName: "ownbit" },
{ walletName: "alphawallet" },
{ walletName: "gnosis" },
{ walletName: "xdefi" },
{ walletName: "bitpie" },
{ walletName: "binance" },
{ walletName: "liquality" },
{ walletName: "tally" },
{ walletName: "blankwallet" },
{ walletName: "mathwallet" },
{ walletName: "1inch" },
{ walletName: "ronin" },
]
const onboard = Onboard({
//... other options
walletSelect: {
wallets: wallets
}
})
The following list of wallet modules are included in Onboard and their
initializationObject
is listed for each wallet:Wallets
detectedwallet
The detected wallet will be displayed as an option when an injected Ethereum provider is detected, but it is not recognized by Onboard. This allows users to connect to your app with any provider that conforms to the EIP-1193 standard.
metamask - (desktop & mobile support)
{ walletName: 'metamask' }
authereum - (desktop & mobile support)
{
walletName: 'authereum',
disableNotifications: false // [OPTIONAL]
rpcUri: '<CUSTOM_RPC_URI>' // [OPTIONAL]
webUri: '<CUSTOM_WEB_URI>' // [OPTIONAL]
xsUri: '<CUSTOM_XS_URI>' // [OPTIONAL]
blockedPopupRedirect: true // [OPTIONAL]
}
walletConnect - (desktop & mobile support)
{
walletName: 'walletConnect',
infuraKey: 'INFURA_KEY', // your infura id [String][Optional if rpc is provided instead]
rpc: {
['networkId']: '<RPC_ENDPOINT_URL_STRING>'
}, // [Optional]
bridge: '<BRIDGE_URL>' // url to a bridge server [String][Optional]
}
portis - (desktop & mobile support)
{
walletName: 'portis',
apiKey: 'PORTIS_KEY' // your Portis apiKey [String]
}
fortmatic - (desktop & mobile support)
{
walletName: 'fortmatic',
apiKey: 'FORTMATIC_KEY' // your Fortmatic apiKey [String]
rpcUrl: '<RPC_ENDPOINT>' // optional - use only for custom networks such as matic
}
trust - (mobile only support)
{ walletName: 'trust' }
coinbase - (mobile only support)
Desktop support for``
Coinbase Wallet
``can be found through``
walletLink module
{ walletName: 'coinbase' }
opera - (desktop & mobile support)
{ walletName: 'opera' }
opera touch - (mobile only support)
{ walletName: 'operaTouch' }
status - (mobile only support)
{ walletName: 'status' }
torus - (desktop & mobile support)
{
walletName: 'torus',
rpcUrl: String, // [optional]
buttonPosition: String, // [optional]
modalZIndex: Number, // [optional]
apiKey: String, // [optional]
buildEnv: String, // 'production' | 'development' | 'staging' | 'testing' | 'lrc' [optional]
enableLogging: Boolean, // [optional]
enabledVerifiers: VerifierStatus, // [optional]
loginConfig: LoginConfig, // [optional]
showTorusButton: Boolean, // [optional]
integrity: IntegrityParams, // [optional]
whiteLabel: WhiteLabelParams, // [optional]
loginMethod: String // 'google' | 'facebook' | 'twitch' | 'reddit' | 'discord' | [optional]
}
trezor - (desktop & mobile support)
{
walletName: 'trezor',
appUrl: APP_URL, // the url of your app (required for manifest)
email: CONTACT_EMAIL, // your contact email, (required for manifest)
rpcUrl: RPC_URL, // url to connect to an RPC endpoint (ie infura)
// See section Hardware Wallet Custom Networks for more info
customNetwork: HardwareWalletCustomNetwork
}
ledger - (desktop & mobile support)
Ledger has an additional optional
LedgerTransport
parameter for when you are building an Electron app and need to pass in the node ledger transport module. You can also use this option to pass in whichever Ledger transport that you would like to use based on feature detection (eg. Windows 10 user might need WebUSB transport instead of the default U2F transport).{
walletName: 'ledger',
rpcUrl: RPC_URL // url to connect to an RPC endpoint (ie infura)
LedgerTransport: TransportNodeHid,
// See section Hardware Wallet Custom Networks for more info
customNetwork: HardwareWalletCustomNetwork
}
lattice - (desktop & mobile support)
{
walletName: 'lattice',
rpcUrl: RPC_URL, // url to connect to an RPC endpoint (ie infura)
appName: APP_NAME // app name that is displayed on device
}
keepkey - (desktop only support)
{
walletName: 'keepkey',
rpcUrl: RPC_URL, // url to connect to an RPC endpoint (ie infura)
}
cobovault - (desktop & mobile support)
{
walletName: 'cobovault',
rpcUrl: RPC_URL, // url to connect to an RPC endpoint (ie infura)
appName: APP_NAME // app name that is displayed on device
}
keystone - (desktop & mobile support)
{
walletName: 'keystone',
rpcUrl: RPC_URL, // url to connect to an RPC endpoint (ie infura)
appName: APP_NAME // app name that is displayed on device
}
walletLink -``
Coinbase Wallet
``for desktop (desktop only support)
{
walletName: 'walletLink',
rpcUrl: RPC_URL, // url to connect to an RPC endpoint (ie infura)
appName: <YOUR_APP_NAME>, // string to label your app
appLogoUrl: <YOUR LOGO URL> // string url of your app logo [OPTIONAL]
}
imToken - (mobile only support)
{
walletName: 'imToken',
rpcUrl: RPC_URL // url to connect to an RPC endpoint (ie infura)[OPTIONAL]
}
meetone - (mobile only support)
{ walletName: 'meetone' }
mykey - (mobile only support)
{
walletName: 'mykey',
rpcUrl: RPC_URL // url to connect to an RPC endpoint (ie infura)[OPTIONAL]
}
huobiwallet - (mobile only support)
{
walletName: 'huobiwallet',
rpcUrl: RPC_URL // url to connect to an RPC endpoint (ie infura)[OPTIONAL]
}
hyperpay - (mobile only support)
{ walletName: 'hyperpay' }
wallet.io - (mobile only support)
{ walletName: "wallet.io", rpcUrl: RPC_URL } // url to connect to an RPC endpoint (ie infura)[OPTIONAL]
atoken - (mobile only support)
{ walletName: "atoken" }
frame - (mobile only support)
{ walletName: "frame" }
ownbit - (mobile only support)
{ walletName: "ownbit" }
alphawallet - (mobile only support)
{ walletName: "alphawallet" }
gnosis - (desktop only support)
Gnosis wallet is unique as it designed to be used within the Gnosis Safe Apps interface. If the user opens your dApp within the Safe Apps interface, Gnosis wallet will be automatically selected and the select wallet modal will not be shown. This is to ensure that the user doesn't mistakenly use their wallet instead of their Safe Multisig wallet for the transaction.
{ walletName: "gnosis" }
xdefi - (desktop & mobile support)
{ walletName: "xdefi" }
bitpie - (mobile only support)
{ walletName: "bitpie" }
liquality - (desktop only support)
{ walletName: "liquality" }
binance - (desktop only support)
{ walletName: 'binance' }
mewwallet - (mobile only support)
{
walletName: 'mewwallet',
rpcUrl: RPC_URL, // url to connect to an RPC endpoint (ie infura)
}
tally - (desktop only support)
{ walletName: 'tally' }
blankwallet - (desktop only support)
{ walletName: 'blankwallet' }
mathwallet - (desktop & mobile support)
{ walletName: 'mathwallet' }
1inch - (mobile only support)
{ walletName: '1inch' }
Did - (mobile only support)
{ walletName: 'did' }
ronin - (desktop only support)
Ronin now only works on Axie's domains and will open to be used by other domains when the Ronin chain is ready - Updates From Ronin Dev
Due to the Ronin extension restriction, please add
127.0.0.1 dev.skymavis.one
in your hosts file /etc/hosts
and access dev.skymavis.one:<port>
instead of localhost:<port>
.{ walletName: 'ronin' }
Onboard now supports passing in custom network info for hardware wallets allowing users to use their hardware wallets with non-Ethereum networks such as Energy Web Chain. The
customNetwork
object is passed to the Common
constructor of the @ethereumjs/common
library. This is then used to build the transaction that will be signed. Please refer to these instructions for more information.
Note: Currently only Trezor and Ledger support this functionality/Example
const onboard = Onboard({
networkId: 1234
//... other options
walletSelect: {
wallets:[
{
walletName: 'ledger',
rpcUrl: RPC_URL,
customNetwork: {
networkId: number
genesis: GenesisBlock
hardforks: Hardfork[]
bootstrapNodes: BootstrapNode[]
}
},
]
}
})
To initialize the built in wallet check modules, an array of wallet check initialization objects needs to be passed to the
walletCheck
parameter of the Onboard initialization object. The order of the array is the order that the checks will be performed.Each wallet check initialization object has additional optional customization parameters:
heading
-String
Will over ride the heading displayed in the wallet check modal.description
-String
Will over ride the description displayed in the wallet check modal.icon
-String
Ansvg
string that will over ride the icon displayed in the wallet check modal.button
-{ text: String, onclick: () => void}
An object that defines an extra button's text and onclick function.html
-String
A html string that will be rendered in the modal as html markup underneath the description.
import Onboard from 'bnc-onboard'
const walletChecks = [
{ checkName: 'derivationPath' },
{ checkName: 'accounts' },
{ checkName: 'connect' },
{ checkName: 'network' },
{ checkName: 'balance', minimumBalance: '1000000' }
]
const onboard = Onboard({
//... other options
walletCheck: walletChecks
})
The following wallet check modules are included in Onboard:
connect
: Checks that the Dapp has access to the users' accounts and fires the connect function if the selected wallet has one to prompt the user to allow access.
{ checkName: 'connect' }
derivationPath
: Provides a UI to allow a user to select or input the derivation path they would like to use with their hardware wallet. Note: will only display if the connected wallet is of type "hardware". Note:html
andbutton
customization parameters won't work for this module as it needs them itself for correct operation.
{ checkName: 'derivationPath' }
accounts
: Provides a UI to allow a user to select and load accounts on their hardware wallet. Note: will only display if the connected wallet is of type "hardware". Note:html
andbutton
customization parameters won't work for this module as it needs them itself for correct operation.
{ checkName: 'accounts' }