@thetanuts-test/erc20

ERC20 token operations with proper decimal handling for the Thetanuts SDK.

Installation

# pnpm
pnpm add @thetanuts-test/core @thetanuts-test/erc20

# npm
npm install @thetanuts-test/core @thetanuts-test/erc20

# yarn
yarn add @thetanuts-test/core @thetanuts-test/erc20

Quick Start

import { createThetanutsClient } from '@thetanuts-test/core'
import { erc20 } from '@thetanuts-test/erc20'

// Create client
const client = createThetanutsClient({ chainId: 8453 })

// Get token balance
const balance = await erc20.getBalance(client, {
  token: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', // USDC
  address: '0xYourAddress...',
})

// Get token info
const info = await erc20.getTokenInfo(client, '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913')
console.log(info) // { name: 'USD Coin', symbol: 'USDC', decimals: 6, address: '0x...' }

API Reference

Read Functions

getBalance(client, params)

Get token balance for an address.

const balance = await erc20.getBalance(client, {
  token: '0xTokenAddress...',
  address: '0xWalletAddress...',
})
// Returns: bigint (in smallest unit)

getAllowance(client, params)

Get current allowance for a spender.

const allowance = await erc20.getAllowance(client, {
  token: '0xTokenAddress...',
  owner: '0xOwnerAddress...',
  spender: '0xSpenderAddress...',
})
// Returns: bigint

getDecimals(client, token)

Get token decimals.

const decimals = await erc20.getDecimals(client, '0xTokenAddress...')
// Returns: number (e.g., 18, 6)

getTokenInfo(client, token)

Get complete token information.

const info = await erc20.getTokenInfo(client, '0xTokenAddress...')
// Returns: { address, name, symbol, decimals }

getTotalSupply(client, token)

Get total token supply.

const supply = await erc20.getTotalSupply(client, '0xTokenAddress...')
// Returns: bigint

Write Functions

Note: Write functions require a wallet client. See @thetanuts-test/core for setup.

approve(client, params)

Approve tokens for a spender.

import { parseUnits } from 'viem'

const result = await erc20.approve(client, {
  token: '0xTokenAddress...',
  spender: '0xSpenderAddress...',
  amount: parseUnits('100', 6), // 100 USDC
})
// Returns: { hash: '0x...', success: boolean }

ensureAllowance(client, params)

Approve only if current allowance is insufficient. Returns null if no approval needed.

import { parseUnits } from 'viem'

// Approve exact amount
const result = await erc20.ensureAllowance(client, {
  token: '0xTokenAddress...',
  spender: '0xSpenderAddress...',
  amount: parseUnits('100', 6),
})

// Approve unlimited (MAX_UINT256)
const resultMax = await erc20.ensureAllowance(client, {
  token: '0xTokenAddress...',
  spender: '0xSpenderAddress...',
  amount: parseUnits('100', 6),
  approveMax: true,
})

if (result === null) {
  console.log('Already approved!')
} else {
  console.log('Approved:', result.hash)
}

transfer(client, params)

Transfer tokens to another address.

import { parseUnits } from 'viem'

const result = await erc20.transfer(client, {
  token: '0xTokenAddress...',
  to: '0xRecipientAddress...',
  amount: parseUnits('50', 6),
})
// Returns: { hash: '0x...', success: boolean }

transferFrom(client, params)

Transfer tokens from one address to another (requires prior approval).

const result = await erc20.transferFrom(client, {
  token: '0xTokenAddress...',
  from: '0xFromAddress...',
  to: '0xToAddress...',
  amount: parseUnits('50', 6),
})

Usage Patterns

Check Balance Before Transfer

import { formatUnits, parseUnits } from 'viem'

const amount = parseUnits('100', 6) // 100 USDC

// Check balance
const balance = await erc20.getBalance(client, { token, address: client.address })

if (balance < amount) {
  const formatted = formatUnits(balance, 6)
  throw new Error(`Insufficient balance: ${formatted} USDC`)
}

// Transfer
await erc20.transfer(client, { token, to: recipient, amount })

Approve Before Contract Interaction

// Ensure sufficient allowance before calling a contract
await erc20.ensureAllowance(client, {
  token: usdcAddress,
  spender: contractAddress,
  amount: depositAmount,
  approveMax: true, // Approve once, use many times
})

// Now interact with the contract...

Batch Read Token Info

const tokens = ['0xUSDC...', '0xWETH...', '0xDAI...']

const tokenInfos = await Promise.all(
  tokens.map(token => erc20.getTokenInfo(client, token))
)

TypeScript

Import types as needed:

import type {
  GetBalanceParams,
  GetAllowanceParams,
  ApproveParams,
  EnsureAllowanceParams,
  TransferParams,
  ApproveResult,
  TransferResult,
  TokenInfo,
} from '@thetanuts-test/erc20'

Notes

• All amounts are in the token's smallest unit (wei for 18-decimal tokens)
• Use parseUnits(amount, decimals) to convert human-readable amounts
• Use formatUnits(amount, decimals) to display amounts
• Write operations require a wallet client
• ensureAllowance is recommended over approve to avoid unnecessary transactions

License

MIT