viem Integration Integrate EVM blockchains using viem for TypeScript/JavaScript applications. Quick Decision Guide Building... Use This Node.js script/backend viem with http transport React/Next.js frontend wagmi hooks (built on viem) Real-time event monitoring viem with webSocket transport Browser wallet integration wagmi or viem custom transport Installation
Core library
npm install viem
For React apps, also install wagmi
npm
install
wagmi viem @tanstack/react-query
Core Concepts
Clients
viem uses two client types:
Client
Purpose
Example Use
PublicClient
Read-only operations
Get balances, read contracts, fetch logs
WalletClient
Write operations
Send transactions, sign messages
Transports
Transport
Use Case
http()
Standard RPC calls (most common)
webSocket()
Real-time event subscriptions
custom()
Browser wallets (window.ethereum)
Chains
viem includes 50+ chain definitions. Import from
viem/chains
:
import
{
mainnet
,
arbitrum
,
optimism
,
base
,
polygon
}
from
'viem/chains'
;
Quick Start Examples
Read Balance
import
{
createPublicClient
,
http
,
formatEther
}
from
'viem'
;
import
{
mainnet
}
from
'viem/chains'
;
const
client
=
createPublicClient
(
{
chain
:
mainnet
,
transport
:
http
(
)
,
}
)
;
const
balance
=
await
client
.
getBalance
(
{
address
:
'0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'
,
}
)
;
console
.
log
(
Balance:
${
formatEther
(
balance
)
}
ETH
)
;
Read Contract
import
{
createPublicClient
,
http
,
parseAbi
}
from
'viem'
;
import
{
mainnet
}
from
'viem/chains'
;
const
client
=
createPublicClient
(
{
chain
:
mainnet
,
transport
:
http
(
)
,
}
)
;
const
abi
=
parseAbi
(
[
'function balanceOf(address) view returns (uint256)'
,
'function decimals() view returns (uint8)'
,
]
)
;
const
balance
=
await
client
.
readContract
(
{
address
:
'0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'
,
// USDC
abi
,
functionName
:
'balanceOf'
,
args
:
[
'0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'
]
,
}
)
;
Send Transaction
import
{
createWalletClient
,
http
,
parseEther
}
from
'viem'
;
import
{
privateKeyToAccount
}
from
'viem/accounts'
;
import
{
mainnet
}
from
'viem/chains'
;
const
account
=
privateKeyToAccount
(
process
.
env
.
PRIVATE_KEY
as
0x
${
string
}
)
;
const
client
=
createWalletClient
(
{
account
,
chain
:
mainnet
,
transport
:
http
(
)
,
}
)
;
const
hash
=
await
client
.
sendTransaction
(
{
to
:
'0x...'
,
value
:
parseEther
(
'0.1'
)
,
}
)
;
console
.
log
(
Transaction hash:
${
hash
}
)
;
Write to Contract
import
{
createWalletClient
,
createPublicClient
,
http
,
parseAbi
,
parseUnits
}
from
'viem'
;
import
{
privateKeyToAccount
}
from
'viem/accounts'
;
import
{
mainnet
}
from
'viem/chains'
;
const
account
=
privateKeyToAccount
(
process
.
env
.
PRIVATE_KEY
as
0x
${
string
}
)
;
const
walletClient
=
createWalletClient
(
{
account
,
chain
:
mainnet
,
transport
:
http
(
)
,
}
)
;
const
publicClient
=
createPublicClient
(
{
chain
:
mainnet
,
transport
:
http
(
)
,
}
)
;
const
abi
=
parseAbi
(
[
'function transfer(address to, uint256 amount) returns (bool)'
]
)
;
// Simulate first to catch errors
const
{
request
}
=
await
publicClient
.
simulateContract
(
{
address
:
'0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'
,
abi
,
functionName
:
'transfer'
,
args
:
[
'0x...'
,
parseUnits
(
'100'
,
6
)
]
,
account
,
}
)
;
// Execute the transaction
const
hash
=
await
walletClient
.
writeContract
(
request
)
;
// Wait for confirmation
const
receipt
=
await
publicClient
.
waitForTransactionReceipt
(
{
hash
}
)
;
console
.
log
(
Confirmed in block
${
receipt
.
blockNumber
}
)
;
Reference Documentation
For deeper coverage of specific topics:
Topic
Reference File
Client setup, transports, chains
Clients & Transports
Reading blockchain data
Reading Data
Sending transactions
Writing Transactions
Private keys, HD wallets
Accounts & Keys
ABI handling, multicall
Contract Patterns
React/wagmi hooks
Wagmi React
Related Plugins
Once you're comfortable with viem basics, the
uniswap-trading
plugin provides comprehensive Uniswap swap integration:
Uniswap Trading API integration
Universal Router SDK usage
Token swap implementations
Install it with:
claude plugin add @uniswap/uniswap-trading
Common Utilities
Unit Conversion
import
{
parseEther
,
formatEther
,
parseUnits
,
formatUnits
}
from
'viem'
;
// ETH
parseEther
(
'1.5'
)
;
// 1500000000000000000n (wei)
formatEther
(
1500000000000000000n
)
;
// "1.5"
// Tokens (e.g., USDC with 6 decimals)
parseUnits
(
'100'
,
6
)
;
// 100000000n
formatUnits
(
100000000n
,
6
)
;
// "100"
Address Utilities
import
{
getAddress
,
isAddress
}
from
'viem'
;
isAddress
(
'0x...'
)
;
// true/false
getAddress
(
'0x...'
)
;
// checksummed address
Hashing
import
{
keccak256
,
toHex
}
from
'viem'
;
keccak256
(
toHex
(
'hello'
)
)
;
// 0x1c8aff950685c2ed4bc3174f3472287b56d9517b9c948127319a09a7a36deac8
Error Handling
viem throws typed errors that can be caught and handled:
import
{
ContractFunctionExecutionError
,
InsufficientFundsError
}
from
'viem'
try
{
await
client
.
writeContract
(
...
)
}
catch
(
error
)
{
if
(
error
instanceof
ContractFunctionExecutionError
)
{
console
.
error
(
'Contract call failed:'
,
error
.
shortMessage
)
}
if
(
error
instanceof
InsufficientFundsError
)
{
console
.
error
(
'Not enough ETH for gas'
)
}
}
Resources
viem Documentation
wagmi Documentation
viem GitHub
wagmi GitHub