API ReferenceTokens and balancesInterface
TokenModule
ERC-20 token operations: look up a token’s name, symbol, and decimals, resolve its logo, and read an account’s wallet balance.
Reach it as sdk.tokens on an AnvilSDK instance, which creates the module
for you.
Methods
getAccountBalance()
getAccountBalance(params): Promise<bigint>;Returns an account’s wallet balance of one token, in that token’s smallest units.
This is the wallet balance only. Collateral already deposited into the vault is not counted — see VaultModule.getCollateralBalance for that side.
Parameters
| Parameter | Type | Description |
|---|---|---|
params | GetAccountTokenBalanceParams | The token, and the account whose balance to read. |
params.accountAddress? | `0x${string}` | Wallet to read. Defaults to the configured signer’s address. |
params.tokenAddress | `0x${string}` | ERC-20 whose wallet balance (balanceOf) to read. This is wallet holdings, not vault collateral; for the latter use VaultModule.getCollateralBalance. |
Returns
Promise<bigint>
The balance in the token’s smallest units.
getMetadata()
getMetadata(params): Promise<TokenMetadata | undefined>;Returns the presentation metadata (currently the logo URL) for a token.
The profile’s token aliases are applied automatically, which is what lets a testnet token resolve to
its mainnet counterpart’s logo. Passing tokenAliases explicitly overrides the profile’s map.
Parameters
| Parameter | Type | Description |
|---|---|---|
params | GetTokenMetadataParams | The token to look up, and optional alias overrides. |
params.address | `0x${string}` | Token address to resolve a logo for. An address listed in tokenAliases is mapped to its mainnet counterpart before lookup. |
params.tokenAliases? | Readonly<Record<`0x${string}`, `0x${string}`>> | Map from this environment’s token addresses to their mainnet counterparts. sdk.tokens.getMetadata uses the profile’s tokenAliases when you omit it; pass one to override that map. |
Returns
Promise<TokenMetadata | undefined>
The metadata, or undefined when no logo resolves.
getToken()
getToken(params): Promise<Token | undefined>;Returns the Token at an address: name, symbol, and decimals read from the ERC-20
contract, with logo metadata attached when Anvil’s token logo set has one.
Each call reads the token contract and metadata source. A contract that answers symbol() with an
empty string yields undefined rather than throwing.
It is not a general “is this an ERC-20?” probe: an address with no ERC-20 interface at all — an EOA, or an unrelated contract — makes the underlying reads revert, and this throws. Catch if you are checking an address the user supplied.
Parameters
| Parameter | Type | Description |
|---|---|---|
params | GetTokenParams | The token address to look up. |
params.address | `0x${string}` | ERC-20 contract address. Resolved by reading name/symbol/decimals from the token contract itself (any ERC-20, not only Anvil-registered ones). |
Returns
Promise<Token | undefined>
The token, or undefined if the contract reports an empty symbol.
Throws
InvalidArgumentError If params.address is missing. Thrown
before any read.
validateApprove()
validateApprove(params): Promise<ValidationIssue[]>;Validates the parameters of an ERC-20 approve call: address format, and an amount of zero or more.
Zero is valid — it is how an approval is revoked.
Unlike the other validate* methods this one has no matching build*Workflow call. Workflows add
an ERC-20 approve step on their own when one is needed (the deposit workflow does, when the vault’s
approval is short); this method lets you check an approval’s inputs on their own.
Parameters
| Parameter | Type | Description |
|---|---|---|
params | Partial<ERC20ApproveParams> | The partial approve parameters to check. |
params.amount? | bigint | Allowance to set, in the token’s smallest unit. This replaces the current allowance rather than adding to it; some tokens (e.g. USDT) reject non-zero to non-zero changes — see buildERC20RevokeTransaction. |
params.erc20Address? | Address | The ERC-20 token contract whose approve is being called. |
params.from? | Address | If not provided, this will be populated by the configured signer. |
params.spender? | Address | The address being granted the allowance. For protocol flows this is the CollateralVault (sdk.getContractAddress(AnvilContract.CollateralVault)), which pulls tokens on deposit. |
Returns
Promise<ValidationIssue[]>
The issues found. An empty array means every rule ran and passed; a rule whose required field is
missing reports FieldRequired instead of being skipped. An infrastructure failure rejects rather
than returning a partial list.