Utility Reference

Client configuration, lifecycle methods, chain lookups, and stateless helpers.

This page covers createNexusClient, the client lifecycle, and the helpers exported from @avail-project/nexus-core/utils.

createNexusClient

TypeScript

import { createNexusClient } from '@avail-project/nexus-core';
 
const client = createNexusClient({ clientId: 'my-app', network: 'mainnet' });
await client.initialize();
await client.setEVMProvider(provider); // EIP-1193 provider from your wallet connector

Option	Type	Description
`clientId`	`string`	Required. Stable, non-empty identifier for your app. An empty value throws `INVALID_INPUT`.
`network`	`'mainnet' \| 'canary' \| 'testnet' \| NetworkConfig`	Default `'mainnet'`. `mainnet` and `canary` use mainnet chains. `testnet` supports standalone `execute` only; intent and async catalog methods reject with `ENVIRONMENT_NOT_SUPPORTED`.
`debug`	`boolean`	Verbose SDK logging. Default `false`.
`analytics`	`AnalyticsConfig`	Product analytics settings. See Analytics.
`devTiming`	`DevTimingConfig`	Timing spans for development. Default disabled.

A custom NetworkConfig is { MIDDLEWARE_HTTP_URL, INTENT_EXPLORER_URL, NETWORK_HINT }, where NETWORK_HINT is 'mainnet', 'canary', or 'testnet'.

Lifecycle

Member	Description
`initialize(): Promise<void>`	Loads the chain and token catalog. Call once per client before any other method. Methods that need it throw `SDK_NOT_INITIALIZED`.
`setEVMProvider(provider): Promise<void>`	Connects an EIP-1193 provider and captures its first account. Throws `ExecutionError` if the wallet returns no account.
`hasEvmProvider: boolean`	`true` after `setEVMProvider()` succeeds.
`destroy(): void`	Ends the analytics session and closes middleware connections. Call on unmount.
`isSupportedChain(chainId): boolean`	Whether `chainId` is in `getSupportedChains()`.
`chainList: ChainListType`	Synchronous chain lookups for execution metadata.

initialize() does not need a wallet. Catalog methods and exact-input quote previews work before setEVMProvider(); balances, swaps, and execution need a wallet.

The client keeps the account it captured. When the user switches account or wallet, call destroy() and create a new client. Chain switches the SDK makes during execution do not require a new client.

chainList

client.chainList exposes chains and these lookups. Its token lists are not the full catalog; use the token catalog to find tokens.

Method	Returns
`getChainByID(id)`	`Chain`
`getNativeToken(chainID)`	`TokenInfo`
`getTokenByAddress(chainID, address)`	`TokenInfo`
`getChainAndTokenByAddress(chainID, address)`	`{ chain, token, isNativeToken }`
`getVaultContractAddress(chainID)`	`Hex`

Utilities

Import stateless helpers from the /utils subpath. client.utils exposes the same functions.

Function	Description
`parseUnits(value, decimals)`	Decimal string to raw `bigint`.
`formatUnits(value, decimals)`	Raw `bigint` to decimal string.
`formatTokenBalance(value, options?)`	Display string, such as `"1.2346 USDC"` or `"~0.0₄8509"`. `options.decimals` is required for `bigint` input.
`formatTokenBalanceParts(value, options?)`	Same, split into `text`, `integer`, `fraction`, `symbol`, and `approx`.
`isValidAddress(address)`	Whether the string is a valid EVM address.
`truncateAddress(address)`	Shortened address for display.
`getCoinbaseRates()`	`Promise<Record<string, string>>` of Coinbase exchange rates.
`getSupportedChains(network, { clientId })`	Fetches `{ id, name, logo, swapSupported, asSource, asDestination }[]` for a network without a client. `clientId` is required.

TypeScript

import { formatTokenBalance, parseUnits } from '@avail-project/nexus-core/utils';
 
const token = await client.getToken({ chainId: 8453, tokenAddress: usdcOnBase });
const amountRaw = parseUnits('25.5', token.decimals);
const label = formatTokenBalance(amountRaw, { decimals: token.decimals, symbol: token.symbol });
 
const chains = await client.utils.getSupportedChains('mainnet'); // uses the client's clientId

Use token.decimals from the catalog. The same symbol can have different decimals on different chains. getFallbackTokenLogoDataUri(symbol, size = 128) is exported from @avail-project/nexus-core, not /utils. It returns an SVG data URI to use when a token logo fails to load.

Analytics

The SDK sends product analytics to Avail's PostHog instance. In the default mode: 'auto', it stays off outside browsers, on localhost, and when NODE_ENV is test, ci, or development.

Option	Description
`enabled`	`false` disables analytics. Overrides `mode`.
`mode`	`'auto'` (default), `'on'` to always send, or `'off'`.
`privacy`	`{ anonymizeWallets?, anonymizeAmounts? }`: hash addresses and drop amounts.
`posthogApiKey`, `posthogApiHost`	Send events to your own PostHog project.
`appMetadata`	`{ appName?, appVersion?, appUrl? }` attached to events.

TypeScript

const client = createNexusClient({ clientId: 'my-app', analytics: { enabled: false } });

analytics: { enabled: false } stops product analytics only. Diagnostic error logging is separate.

Skills integration

The nexus-core agent skill gives AI coding agents, such as Claude Code, Codex, and Cursor, the current SDK integration guide.


pnpm dlx skills add availproject/nexus-sdk

Browse it at skills.sh/availproject/nexus-sdk. For Widgets skills, see MCP and agent skills.

How is this guide?

Hooks and Errors

Cookbook

createNexusClient Lifecycle chainList Utilities Analytics Skills integration

Edit in GitHub

import { createNexusClient } from '@avail-project/nexus-core'; const client = createNexusClient({ clientId: 'my-app', network: 'mainnet' }); await client.initialize(); await client.setEVMProvider(provider); // EIP-1193 provider from your wallet connector

Option

Type

Description

clientId

string

Required. Stable, non-empty identifier for your app. An empty value throws INVALID_INPUT.

network

'mainnet' | 'canary' | 'testnet' | NetworkConfig

Default 'mainnet'. mainnet and canary use mainnet chains. testnet supports standalone execute only; intent and async catalog methods reject with ENVIRONMENT_NOT_SUPPORTED.

debug

boolean

Verbose SDK logging. Default false.

analytics

AnalyticsConfig

Product analytics settings. See Analytics.

devTiming

DevTimingConfig

Timing spans for development. Default disabled.

Member

Description

initialize(): Promise<void>

Loads the chain and token catalog. Call once per client before any other method. Methods that need it throw SDK_NOT_INITIALIZED.

setEVMProvider(provider): Promise<void>

Connects an EIP-1193 provider and captures its first account. Throws ExecutionError if the wallet returns no account.

hasEvmProvider: boolean

true after setEVMProvider() succeeds.

destroy(): void

Ends the analytics session and closes middleware connections. Call on unmount.

isSupportedChain(chainId): boolean

Whether chainId is in getSupportedChains().

chainList: ChainListType

Synchronous chain lookups for execution metadata.

Method

Returns

getChainByID(id)

Chain

getNativeToken(chainID)

TokenInfo

getTokenByAddress(chainID, address)

TokenInfo

getChainAndTokenByAddress(chainID, address)

{ chain, token, isNativeToken }

getVaultContractAddress(chainID)

Hex

Function

Description

parseUnits(value, decimals)

Decimal string to raw bigint.

formatUnits(value, decimals)

Raw bigint to decimal string.

formatTokenBalance(value, options?)

Display string, such as "1.2346 USDC" or "~0.0₄8509". options.decimals is required for bigint input.

formatTokenBalanceParts(value, options?)

Same, split into text, integer, fraction, symbol, and approx.

isValidAddress(address)

Whether the string is a valid EVM address.

truncateAddress(address)

Shortened address for display.

getCoinbaseRates()

Promise<Record<string, string>> of Coinbase exchange rates.

getSupportedChains(network, { clientId })

Fetches { id, name, logo, swapSupported, asSource, asDestination }[] for a network without a client. clientId is required.

import { formatTokenBalance, parseUnits } from '@avail-project/nexus-core/utils'; const token = await client.getToken({ chainId: 8453, tokenAddress: usdcOnBase }); const amountRaw = parseUnits('25.5', token.decimals); const label = formatTokenBalance(amountRaw, { decimals: token.decimals, symbol: token.symbol }); const chains = await client.utils.getSupportedChains('mainnet'); // uses the client's clientId

Option

Description

enabled

false disables analytics. Overrides mode.

mode

'auto' (default), 'on' to always send, or 'off'.

privacy

{ anonymizeWallets?, anonymizeAmounts? }: hash addresses and drop amounts.

posthogApiKey, posthogApiHost

Send events to your own PostHog project.

appMetadata

{ appName?, appVersion?, appUrl? } attached to events.

Search Documentation

Utility Reference

createNexusClient

Lifecycle

chainList

Utilities

Analytics

Skills integration

Search Documentation

Utility Reference

createNexusClient

Lifecycle

chainList

Utilities

Analytics

Skills integration