Skip to content
On this page

Wallet Client โ€‹

A Wallet Client is an interface to interact with Ethereum Account(s) and provides the ability to retrieve accounts, execute transactions, sign messages, etc through Wallet Actions.

The createWalletClient function sets up a Wallet Client with a given Transport.

The Wallet Client supports signing over:

Import โ€‹

ts
import { createWalletClient } from 'viem'

JSON-RPC Accounts โ€‹

A JSON-RPC Account defers signing of transactions & messages to the target Wallet over JSON-RPC. An example could be sending a transaction via a Browser Extension Wallet (e.g. MetaMask) with the window.ethereum Provider.

Below is an example of how you can set up a JSON-RPC Account.

1: Initialize a Wallet Client โ€‹

Before we set up our Account and start consuming Wallet Actions, we will need to set up our Wallet Client with the custom Transport, where we will pass in the window.ethereum Provider:

ts
import { createWalletClient, custom } from 'viem'
import { mainnet } from 'viem/chains'

const client = createWalletClient({
  chain: mainnet,
  transport: custom(window.ethereum)
})

2: Set up your JSON-RPC Account โ€‹

We will want to retrieve an address that we can access in our Wallet (e.g. MetaMask).

ts
import { createWalletClient, custom } from 'viem' 
import { mainnet } from 'viem/chains'

const client = createWalletClient({
  chain: mainnet,
  transport: custom(window.ethereum)
})

const [address] = await client.getAddresses() 
// or: const [address] = await client.requestAddresses() 

Note: Some Wallets (like MetaMask) may require you to request access to Account addresses via client.requestAddresses first.

3: Consume Wallet Actions โ€‹

Now you can use that address within Wallet Actions that require a signature from the user:

ts
import { createWalletClient, custom } from 'viem'
import { mainnet } from 'viem/chains'

const client = createWalletClient({
  chain: mainnet,
  transport: custom(window.ethereum)
})

const [address] = await client.getAddresses()

const hash = await client.sendTransaction({ 
  account: address,
  to: '0xa5cc3c03994DB5b0d9A5eEdD10CabaB0813678AC',
  value: parseEther('0.001')
})

Optional: Hoist the Account โ€‹

If you do not wish to pass an account around to every Action that requires an account, you can also hoist the account into the Wallet Client.

ts
import { createWalletClient, http } from 'viem'
import { mainnnet } from 'viem/chains'

const [account] = await window.ethereum.request({ method: 'eth_requestAccounts' })

const client = createWalletClient({ 
  account, 
  chain: mainnet,
  transport: http()
})

const hash = await client.sendTransaction({
  account, 
  to: '0xa5cc3c03994DB5b0d9A5eEdD10CabaB0813678AC',
  value: parseEther('0.001')
})

Local Accounts (Private Key, Mnemonic, etc) โ€‹

A Local Account performs signing of transactions & messages with a private key before executing a method over JSON-RPC.

There are three types of Local Accounts in viem:

Below are the steps to integrate a Private Key Account, but the same steps can be applied to Mnemonic & HD Accounts.

1: Initialize a Wallet Client โ€‹

Before we set up our Account and start consuming Wallet Actions, we will need to set up our Wallet Client with the http Transport:

ts
import { createWalletClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createWalletClient({
  chain: mainnet,
  transport: http()
})

2: Set up your Local Account โ€‹

Next, we will instantiate a Private Key Account using privateKeyToAccount:

ts
import { createWalletClient, http } from 'viem'
import { privateKeyToAccount } from 'viem/accounts' 
import { mainnet } from 'viem/chains'

const client = createWalletClient({
  chain: mainnet,
  transport: http()
})

const account = privateKeyToAccount('0x...') 

3: Consume Wallet Actions โ€‹

Now you can use that Account within Wallet Actions that need a signature from the user:

ts
import { createWalletClient, http } from 'viem'
import { privateKeyToAccount } from 'viem/accounts'
import { mainnet } from 'viem/chains'

const client = createWalletClient({
  chain: mainnet,
  transport: http()
})

const account = privateKeyToAccount('0x...')

const hash = await client.sendTransaction({ 
  account,
  to: '0xa5cc3c03994DB5b0d9A5eEdD10CabaB0813678AC',
  value: parseEther('0.001')
})

Optional: Hoist the Account โ€‹

If you do not wish to pass an account around to every Action that requires an account, you can also hoist the account into the Wallet Client.

ts
import { createWalletClient, http } from 'viem'
import { privateKeyToAccount } from 'viem/accounts'
import { mainnet } from 'viem/chains'

const account = privateKeyToAccount('0x...')

const client = createWalletClient({ 
  account, 
  chain: mainnet,
  transport: http()
})

const hash = await client.sendTransaction({
  account, 
  to: '0xa5cc3c03994DB5b0d9A5eEdD10CabaB0813678AC',
  value: parseEther('0.001')
})

Parameters โ€‹

account (optional) โ€‹

  • Type: Account | Address

The Account to use for the Wallet Client. This will be used for Actions that require an account as an argument.

Accepts a JSON-RPC Account or Local Account (Private Key, etc).

ts
import { createWalletClient, custom } from 'viem'
import { privateKeyToAccount } from 'viem/accounts'

const client = createWalletClient({
  account: privateKeyToAccount('0x...') 
  key: 'foo', 
  transport: custom(window.ethereum)
})

const hash = await client.sendTransaction({
  to: '0xa5cc3c03994DB5b0d9A5eEdD10CabaB0813678AC',
  value: parseEther('0.001')
})

chain (optional) โ€‹

The Chain of the Wallet Client.

Used in the sendTransaction & writeContract Actions to assert that the chain matches the wallet's active chain.

ts
const client = createWalletClient({
  chain: mainnet, 
  transport: custom(window.ethereum)
})

key (optional) โ€‹

  • Type: string
  • Default: "wallet"

A key for the Client.

ts
import { createWalletClient, custom } from 'viem'

const client = createWalletClient({
  key: 'foo', 
  transport: custom(window.ethereum)
})

name (optional) โ€‹

  • Type: string
  • Default: "Wallet Client"

A name for the Client.

ts
import { createWalletClient, custom } from 'viem'

const client = createWalletClient({
  name: 'Foo Wallet Client', 
  transport: custom(window.ethereum)
})

pollingInterval (optional) โ€‹

  • Type: number
  • Default: 4_000

Frequency (in ms) for polling enabled Actions.

ts
import { createWalletClient, custom } from 'viem'

const client = createWalletClient({
  pollingInterval: 10_000, 
  transport: custom(window.ethereum)
})

Released under the MIT License.