Asset Registry API Reference

Package: `@tetherto/wdk-asset-registry`

Exports

Export	Description
`default`	Base registry class for assets that include `id` and `chainId`; import it as `WdkBaseAssetRegistry`
`WdkTokenAssetRegistry`	Token registry class with token-specific lookup helpers
`BaseAssetSchema`	Zod schema for base asset records
`BaseAssetJsonSchema`	JSON schema for base asset records
`TokenAssetSchema`	Zod schema for token asset records
`TokenAssetJsonSchema`	JSON schema for token asset records
`fromUniswapToken(token)`	Convert one Uniswap token-list entry into a `TokenAsset`
`fromUniswapTokenList(tokens)`	Convert a list of Uniswap token-list entries into `TokenAsset[]`
`AssetRegistryError`	Error class for registry-level failures such as duplicate asset IDs

Class: `WdkBaseAssetRegistry`

In-memory registry for BaseAsset-compatible records.

Constructor

Create A Base Registry

import WdkBaseAssetRegistry from '@tetherto/wdk-asset-registry'

const registry = new WdkBaseAssetRegistry(initialAssets)

Pass zero or more asset arrays to preload records.

Methods

Method	Description	Returns
`registerAsset(asset, upsert?)`	Validate and register one asset by `asset.id`	`void`
`registerAssets(assets, upsert?)`	Register a list of assets	`void`
`getAssets()`	Return all registered assets	`BaseAsset[]`
`getAssetById(id)`	Return one asset by exact ID	`BaseAsset \| null`
`getAsset(filter, options?)`	Return all assets matching one or more partial filters	`BaseAsset[]`

`registerAsset(asset, upsert?)`

Validates the asset before registration. Duplicate IDs throw AssetRegistryError unless upsert is true.

registry.registerAsset({
  id: 'eip155:1',
  chainId: 'eip155:1'
})

`registerAssets(assets, upsert?)`

Registers each asset by calling registerAsset().

registry.registerAssets([
  { id: 'eip155:1', chainId: 'eip155:1' },
  { id: 'eip155:137', chainId: 'eip155:137' }
])

`getAssetById(id)`

Looks up an asset by exact id.

Get Asset By ID

const asset = registry.getAssetById('eip155:1')

`getAsset(filter, options?)`

Finds assets that match one or more partial filters. Pass an array of filter objects. Keys inside one filter object are AND conditions. Multiple filter objects are OR conditions.

Filter Assets

const byChain = registry.getAsset([
  { chainId: 'eip155:1' }
])

const byOneOfMany = registry.getAsset([
  { chainId: 'eip155:1' },
  { chainId: 'eip155:137' }
])

String comparisons are case-insensitive by default. Pass { caseSensitive: true } to require exact casing.

Class: `WdkTokenAssetRegistry`

Token-specific registry built on WdkBaseAssetRegistry.

Create A Token Registry

import { WdkTokenAssetRegistry } from '@tetherto/wdk-asset-registry'
import commonTokens from '@tetherto/wdk-asset-registry/assets/common-tokens' with { type: 'json' }

const registry = new WdkTokenAssetRegistry(commonTokens)

Methods

Method	Description	Returns
`getTokens()`	Return all registered token assets	`TokenAsset[]`
`getTokenById(id)`	Return one token by exact ID	`TokenAsset \| null`
`getTokenByAddress(address, options?)`	Return all tokens matching an address	`TokenAsset[]`
`getTokenBySymbol(symbol, options?)`	Return all tokens matching a symbol	`TokenAsset[]`
`getTokenByChain(chainId, options?)`	Return all tokens matching a chain ID	`TokenAsset[]`

Token Lookups

const usdtTokens = registry.getTokenBySymbol('USDT')
const tokensByAddress = registry.getTokenByAddress('0xdAC17F958D2ee523a2206206994597C13D831ec7')
const chainTokens = registry.getTokenByChain('eip155:1')

Helper Functions

`fromUniswapToken(token)`

Converts one Uniswap token-list entry into a TokenAsset.

Normalize One Token

import { fromUniswapToken } from '@tetherto/wdk-asset-registry'

const token = fromUniswapToken({
  chainId: 1,
  address: '0xdAC17F958D2ee523a2206206994597C13D831ec7',
  symbol: 'USDT',
  name: 'Tether USD',
  decimals: 6
})

`fromUniswapTokenList(tokens)`

Converts a token-list array into TokenAsset[].

Normalize A Token List

import { fromUniswapTokenList } from '@tetherto/wdk-asset-registry'

const tokens = fromUniswapTokenList(uniswapTokenList.tokens)

Types

`BaseAsset`

type BaseAsset = {
  id: string
  chainId: string | number
}

`TokenAsset`

type TokenAsset = BaseAsset & {
  address: string
  symbol: string
  name: string
  decimals: number
  isNative: boolean
}

`BaseAssetOptions`

type BaseAssetOptions = {
  caseSensitive?: boolean
}

`BaseAssetFilter<TSchema>`

type BaseAssetFilter<TSchema extends object> = Partial<TSchema>

Bundled Assets

@tetherto/wdk-asset-registry/assets/common-tokens exports bundled token metadata. In v1.0.0-beta.1, the published list contains USDT, USDT0, and XAUt token records across supported chains.

Errors

Error	Cause
`AssetRegistryError`	Registry-level failure, such as duplicate asset registration without `upsert`
`ZodError`	Invalid asset shape passed to registration or normalization helpers

Notes

Exact ID lookups return null when no asset matches. Filter and token-helper lookups return an empty array.
registerAssets() validates and registers each asset sequentially. It is not an atomic batch transaction.
The token registry validates records with TokenAssetSchema.
Asset registry metadata is static and local; use live providers for balances, prices, quotes, chain state, or contract validation.

Need Help?

Discord CommunityConnect with developers, ask questions, share your projects

Join Community

GitHub IssuesReport bugs, request features, and get technical help

Open an Issue

Email ContactFor sensitive or private matters, contact our team directly

Send an email

Asset Registry API Reference

On this page