Wallet Client

A function to create a 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:

JSON-RPC Accounts (e.g. Browser Extension Wallets, WalletConnect, etc.).
Local Accounts (e.g. private key/mnemonic wallets).

Import

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:

import { ,  } from 'viem'
import {  } from 'viem/chains'
 
const  = ({
  : ,
  : (.!)
})

2: Set up your JSON-RPC Account

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

import { ,  } from 'viem'
import {  } from 'viem/chains'
 
const  = ({
  : ,
  : (.!)
})
 
const [] = await .() 
// 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:

import { , ,  } from 'viem'
import {  } from 'viem/chains'
 
const  = ({
  : ,
  : (.!)
})
 
const [] = await .()
 
const  = await .({ 
  : ,
  : '0xa5cc3c03994DB5b0d9A5eEdD10CabaB0813678AC',
  : ('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.

import { , ,  } from 'viem'
import {  } from 'viem/chains'
 
const [] = await .!.({ : 'eth_requestAccounts' })
 
const  = ({ 
  , 
  : ,
  : ()
})
 
const  = await .({
  , 
  : '0xa5cc3c03994DB5b0d9A5eEdD10CabaB0813678AC',
  : ('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:

import { ,  } from 'viem'
import {  } from 'viem/chains'
 
const  = ({
  : ,
  : ()
})

2: Set up your Local Account

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

import { ,  } from 'viem'
import {  } from 'viem/accounts'
import {  } from 'viem/chains'
 
const  = ({
  : ,
  : ()
})
 
const  = ('0x...')

3: Consume Wallet Actions

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

import { , ,  } from 'viem'
import {  } from 'viem/accounts'
import {  } from 'viem/chains'
 
const  = ({
  : ,
  : ()
})
 
const  = ('0x...')
 
const  = await .({ 
  ,
  : '0xa5cc3c03994DB5b0d9A5eEdD10CabaB0813678AC',
  : ('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.

import { , ,  } from 'viem'
import {  } from 'viem/accounts'
import {  } from 'viem/chains'
 
const  = ('0x...')
 
const  = ({ 
  , 
  : ,
  : ()
})
 
const  = await .({
  , 
  : '0xa5cc3c03994DB5b0d9A5eEdD10CabaB0813678AC',
  : ('0.001')
})

Optional: Extend with Public Actions

When using a Local Account, you may be finding yourself using a Public Client instantiated with the same parameters (transport, chain, etc) as your Wallet Client.

In this case, you can extend your Wallet Client with Public Actions to avoid having to handle multiple Clients.

import { , ,  } from 'viem'
import {  } from 'viem/accounts'
import {  } from 'viem/chains'
 
const  = ('0x...')
 
const  = ({ 
  ,
  : ,
  : ()
}).() // [!code ++]
 
const {  } = await .({ ... }) // Public Action
const  = await .() // Wallet Action

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).

import { , ,  } from 'viem'
import {  } from 'viem/chains'
 
const  = ({
  : '0x...', 
  : ,
  : (.!)
})
 
const  = await .({
  : '0xa5cc3c03994DB5b0d9A5eEdD10CabaB0813678AC',
  : ('0.001')
})

chain (optional)

Type: Chain

The Chain of the Wallet Client.

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

const  = ({
  : , 
  : (.!)
})

cacheTime (optional)

Type: number
Default: client.pollingInterval

Time (in ms) that cached data will remain in memory.

const  = ({
  : 10_000, 
  : ,
  : (.!)
})

ccipRead (optional)

Type: (parameters: CcipRequestParameters) => Promise<CcipRequestReturnType> | false
Default: true

CCIP Read configuration.

CCIP Read is enabled by default, but if set to false, the client will not support offchain CCIP lookups.

const  = ({
  : false, 
  : (.!)
})

ccipRead.request (optional)

Type: (parameters: CcipRequestParameters) => Promise<CcipRequestReturnType>

A function that will be called to make the offchain CCIP lookup request.

const  = ({
  : { 
    async ({ , ,  }) { 
      // ...
    } 
  }, 
  : (.!)
})

key (optional)

Type: string
Default: "wallet"

A key for the Client.

const  = ({
  : 'foo', 
  : (.!)
})

name (optional)

Type: string
Default: "Wallet Client"

A name for the Client.

const  = ({
  : 'Foo Wallet Client', 
  : (.!)
})

pollingInterval (optional)

Type: number
Default: 4_000

Frequency (in ms) for polling enabled Actions.

const  = ({
  : 10_000, 
  : (.!)
})

rpcSchema (optional)

Type: RpcSchema
Default: WalletRpcSchema

Typed JSON-RPC schema for the client.

import {  } from 'viem'
 
type  = [{ 
  : 'eth_wagmi', 
  : [string] 
  : string
}] 
 
const  = ({
  : <>(), 
  : (.!)
})
 
const  = await .({ 
  : 'eth_wa // [!code focus] 
  : ['hello'], 
})

dataSuffix (optional)

Type: Hex | { value: Hex; required?: boolean }

Data to append to the end of transaction calldata. Useful for adding transaction attribution.

When a simple hex string is provided, the suffix is appended on a best-effort basis. When using the object form with required: true, transactions will fail if the suffix cannot be appended.

Applies to sendTransaction, sendTransactionSync, sendCalls, simulateContract, and estimateContractGas actions.

const  = ({
  : '0xdeadbeef', 
  : (.!)
})

Suggest changes to this page