viem-erc20

Viem extensions for ERC20 tokens.

Installation

Install viem and viem-erc20 as dependencies:

npm install viem viem-erc20

Methods

This package provides ESM-friendly helpers for interacting with ERC20 contracts using viem.

getErc20TokenAllowance

Reads the allowance of a spender for a given owner.

getErc20TokenAllowance(client, { address, owner, spender });

• client: Client (from viem) — required
• address: Address — ERC20 contract address (required)
• owner: Address — Token holder address (required)
• spender: Address — Spender address (required)

Example:

import { getErc20TokenAllowance } from "viem-erc20/actions";
const allowance = await getErc20TokenAllowance(client, {
  address: "0x6B175474E89094C44Da98b954EedeAC495271d0F", // DAI
  owner: "0xYourWalletAddress",
  spender: "0xSpenderAddress",
});

getErc20TokenBalance

Reads the balance of an account.

getErc20TokenBalance(client, { account, address });

• client: Client (from viem) — required
• account: Address — Account to check balance for (required)
• address: Address — ERC20 contract address (required)

Example:

import { getErc20TokenBalance } from "viem-erc20/actions";
const balance = await getErc20TokenBalance(client, {
  account: "0xYourWalletAddress",
  address: "0x6B175474E89094C44Da98b954EedeAC495271d0F", // DAI
});

getErc20TokenDecimals

Reads the decimals value of an ERC20 token contract.

getErc20TokenDecimals(client, { address });

• client: Client (from viem) — required
• address: Address — ERC20 contract address (required)

Example:

import { getErc20TokenDecimals } from "viem-erc20/actions";
const decimals = await getErc20TokenDecimals(client, {
  address: "0x6B175474E89094C44Da98b954EedeAC495271d0F", // DAI
});

getErc20TokenName

Reads the name value of an ERC20 token contract.

getErc20TokenName(client, { address });

• client: Client (from viem) — required
• address: Address — ERC20 contract address (required)

Example:

import { getErc20TokenName } from "viem-erc20/actions";
const name = await getErc20TokenName(client, {
  address: "0x6B175474E89094C44Da98b954EedeAC495271d0F", // DAI
});

getErc20TokenSymbol

Reads the symbol value of an ERC20 token contract.

getErc20TokenSymbol(client, { address });

• client: Client (from viem) — required
• address: Address — ERC20 contract address (required)

Example:

import { getErc20TokenSymbol } from "viem-erc20/actions";
const symbol = await getErc20TokenSymbol(client, {
  address: "0x6B175474E89094C44Da98b954EedeAC495271d0F", // DAI
});

getErc20TokenTotalSupply

Gets the total supply of the ERC20 token.

getErc20TokenTotalSupply(client, { address });

• client: Client (from viem) — required
• address: Address — ERC20 contract address (required)

Example:

import { getErc20TokenTotalSupply } from "viem-erc20/actions";
const totalSupply = await getErc20TokenTotalSupply(client, {
  address: "0x6B175474E89094C44Da98b954EedeAC495271d0F", // DAI
});

approveErc20Token

Sends an approval transaction to allow a spender to spend tokens on behalf of the owner.

approveErc20Token(walletClient, { address, spender, amount });

• walletClient: WalletClient (from viem) — required
• address: Address — ERC20 contract address (required)
• spender: Address — Spender address (required)
• amount: bigint — Amount to approve (required, must be > 0)

Example:

import { approveErc20Token } from "viem-erc20/actions";
const tx = await approveErc20Token(walletClient, {
  address: "0x6B175474E89094C44Da98b954EedeAC495271d0F", // DAI
  spender: "0xSpenderAddress",
  amount: 1000000000000000000n, // 1 DAI (in wei)
});

Usage with .extend()

You can extend your viem client with ERC20 actions using .extend() and the provided helpers:

import { createPublicClient, createWalletClient, http } from "viem";
import { erc20PublicActions, erc20WalletActions } from "viem-erc20";

// Example: extending a public client
const publicClient = createPublicClient({
  chain, // your chain config
  transport: http(),
}).extend(erc20PublicActions());

// Now you can call:
const allowance = await publicClient.getErc20TokenAllowance({
  address: "0x6B175474E89094C44Da98b954EedeAC495271d0F",
  owner: "0xYourWalletAddress",
  spender: "0xSpenderAddress",
});

// Example: extending a wallet client
const walletClient = createWalletClient({
  account, // your account config
  chain, // your chain config
  transport: http(),
}).extend(erc20WalletActions());

// Now you can call:
const tx = await walletClient.approveErc20Token({
  address: "0x6B175474E89094C44Da98b954EedeAC495271d0F",
  spender: "0xSpenderAddress",
  amount: 1000000000000000000n,
});

Local Setup

To install the dependencies, run:

npm install

To run the tests, run:

npm test