Guides
DocumentationLog In

Getting Started

This page will help you get started with WalletLink. You'll be up and running in a jiffy!

Introduction

The following guide helps you get started with Coinbase’s WalletLink SDK. WalletLink is an SDK you can integrate into your dapp to allow your users to link their Coinbase Wallet mobile app or extension. WalletLink works well for your apps on both desktop and mobile web.

Coinbase Wallet users access apps from their iOS app, Android app, or Chrome Extension. On mobile, you can link users into Wallet’s dapp browser section via a dynamically generated deeplink, to seamlessly continue using your app in Coinbase Wallet.

You can also visit the following repository:

Setup instructions

Installing

# With Yarn
yarn add walletlink

# With NPM
npm install walletlink

The following instructions are in TypeScript but the usage is the same in JavaScript, except for the occasional type annotations, for example: string[] or as any.

Upgrading from WalletLink 1.0 to 2.0

For most users, update the NPM package and you should be good to go.

If you were using ethereum.on("accountsChanged"), remove it and obtain addresses via EIP-1102 callbacks instead. It's removed to improve compatibility with the latest web3.js.

Dark mode theme (darkMode) is now available as an option to WalletLink constructor.

Initializing WalletLink and a WalletLink-powered Web3 object

// TypeScript
import WalletLink from 'walletlink'
import Web3 from 'web3'

const APP_NAME = 'My Awesome App'
const APP_LOGO_URL = 'https://example.com/logo.png'
const ETH_JSONRPC_URL = 'https://mainnet.infura.io/v3/<YOUR_INFURA_API_KEY>'
const CHAIN_ID = 1

// Initialize WalletLink
export const walletLink = new WalletLink({
  appName: APP_NAME,
  appLogoUrl: APP_LOGO_URL,
  darkMode: false
})

// Initialize a Web3 Provider object
export const ethereum = walletLink.makeWeb3Provider(ETH_JSONRPC_URL, CHAIN_ID)

// Initialize a Web3 object
export const web3 = new Web3(ethereum as any)

Using EIP-1102 to obtain authorization and get Ethereum accounts

Invoking EIP-1102 shows a QR code dialog if the user's mobile wallet is not already connected to your app. The following code should run in response to a user-initiated action such as clicking a button to ensure the pop up is not blocked by the browser.

// Use eth_RequestAccounts
ethereum.request('eth_requestAccounts').then((accounts: string[]) => {
  console.log(`User's address is ${accounts[0]}`)

  // Optionally, have the default account set for web3.js
  web3.eth.defaultAccount = accounts[0]
})

// Alternatively, you can use ethereum.enable()
ethereum.enable().then((accounts: string[]) => {
  console.log(`User's address is ${accounts[0]}`)
  web3.eth.defaultAccount = accounts[0]
})

Once the authorization is obtained from the user, the Web3 object (web3) and the Web3 Provider (ethereum) are ready to be used as per usual.

Disconnecting / De-establishing a link

To disconnect, call the instance method disconnect() on the WalletLink object, or the instance method close() on the WalletLink Web3 Provider object. This de-establishes the link, and requires the user to reconnect by scanning QR code again.

walletLink.disconnect()
// is the same as the following:
ethereum.close()

Integrate with Coinbase Wallet

Web3-React

Image 1: Example wallet select modal on Uniswap

To modify connector.ts:

...
import { WalletLinkConnector } from '@web3-react/walletlink-connector'
…

…
export const walletlink = new WalletLinkConnector({
  url: RPC_URLS[1],
  appName: 'web3-react example',
  supportedChainIds: [1, 3, 4, 5, 42, 10, 137, 69, 420, 80001]
})
…

For webpack5, add the following code snippet to webpack.config.js:

…
resolve: {
 fallback: {
   fs: false,
   // eslint-disable-next-line node/no-extraneous-require
   'stream': require.resolve('stream-browserify'),
   // eslint-disable-next-line node/no-extraneous-require
   'buffer': require.resolve('buffer/'),
   // eslint-disable-next-line node/no-extraneous-require
   'util': require.resolve('util/'),
   'assert': require.resolve('assert/'),
 },
},
…

Then, add the following dependencies to package.json:

…
"assert": "^2.0.0",
"buffer": "^6.0.3",
"stream-browserify": "^3.0.0",
"util": "^0.12.4"
...

BlockNative

Image 2: Example wallet select modal

To modify the 'filename', use Coinbase Wallet:

const wallets = [
...
{ walletName: "coinbase", preferred: true },

const defaultWallets = [
...
    { walletName: 'coinbase' }
]]

Best practices

UX Tips

The following are a few helpful tips based on user feedback:.

  • Label the connection as “Coinbase Wallet” for clarity to users. Avoid using “WalletLink”, which is a developer-oriented term.

  • Use Coinbase Wallet icon set: to download.

  • Have Coinbase Wallet appear above the fold for users to discover without clicking on “Show More”.