Utility Reference

Reference for creating the Nexus client, its lifecycle, chain/token lookups, and stateless helpers.

The Nexus SDK is created with createNexusClient and exposes a headless client plus a set of stateless helpers. This page covers client configuration, lifecycle, chain/token lookups, and the utility exports.

Creating a client

TypeScript

import { createNexusClient } from '@avail-project/nexus-core';
 
const client = createNexusClient({
  network: 'mainnet',
});
 
await client.initialize();

Configuration

TypeScript

createNexusClient(config?: {
  network?: 'mainnet' | 'testnet' | NetworkConfig;
  debug?: boolean;
  analytics?: AnalyticsConfig;
  devTiming?: DevTimingConfig;
  domain?: string;
  forceMayan?: boolean;
}): NexusClient

Option	Type	Description
`network`	`'mainnet' \| 'testnet' \| NetworkConfig`	Target network. Defaults to `'mainnet'`. Pass a `NetworkConfig` object for a fully custom deployment.
`debug`	`boolean`	Enable verbose debug logging.
`analytics`	`AnalyticsConfig`	Analytics configuration (see Analytics).
`devTiming`	`DevTimingConfig`	Developer timing instrumentation for spans.
`domain`	`string`	Override the auto-detected domain used in the ephemeral-key sign message.
`forceMayan`	`boolean`	Force routing through Mayan where available.

Custom network config

TypeScript

type NetworkConfig = {
  MIDDLEWARE_HTTP_URL: string;
  MIDDLEWARE_WS_URL: string;
  INTENT_EXPLORER_URL: string;
  NETWORK_HINT: 'mainnet' | 'testnet';
};
 
const client = createNexusClient({
  network: {
    MIDDLEWARE_HTTP_URL: 'https://your-deployment.example.com/middleware/',
    MIDDLEWARE_WS_URL: 'wss://your-deployment.example.com/middleware/',
    INTENT_EXPLORER_URL: 'https://your-deployment.example.com/',
    NETWORK_HINT: 'mainnet',
  },
});

Lifecycle

`initialize()`

Initialize the client. Call once before invoking any operation; it can run before or after setEVMProvider().

TypeScript

await client.initialize();

`setEVMProvider(provider)`

Attach or replace the EIP-1193 EVM provider used to sign and send transactions.

TypeScript

await client.setEVMProvider(window.ethereum);

Parameter	Type	Description
`provider`	`EthereumProvider`	EIP-1193 compatible provider (MetaMask, WalletConnect, etc.).

`hasEvmProvider`

Boolean getter — true once an EVM provider has been attached.

TypeScript

if (client.hasEvmProvider) {
  // Safe to run operations that need a wallet
}

`destroy()`

Tear down the client and release resources (analytics, sockets). Call when unmounting your app.

TypeScript

client.destroy();

Chain and token helpers

`getSupportedChains()`

Return the chains and tokens supported by the connected deployment.

TypeScript

const supported = client.getSupportedChains();
// SupportedChainsAndTokensResult: Array<{ id, name, logo, swapSupported, tokens }>

`isSupportedChain(chainId)`

TypeScript

const ok = client.isSupportedChain(137); // boolean

`convertTokenReadableAmountToBigInt(amount, tokenSymbol, chainId)`

Convert a human-readable amount into raw integer units using the token's on-chain decimals.

TypeScript

const amountRaw = client.convertTokenReadableAmountToBigInt('83.5', 'USDC', 137);
// 83_500_000n

`client.chainList`

client.chainList exposes synchronous lookups over the resolved deployment.

TypeScript

client.chainList.getChainByID(chainID: number): Chain;
client.chainList.getTokenInfoBySymbol(chainID: number, symbol: string): TokenInfo;
client.chainList.getNativeToken(chainID: number): TokenInfo;
client.chainList.getVaultContractAddress(chainID: number): `0x${string}`;
client.chainList.getTokenByAddress(chainID: number, address: `0x${string}`): TokenInfo;
client.chainList.getTokenByCurrencyId(chainID: number, currencyId: number): TokenInfo;
client.chainList.getChainAndTokenFromSymbol(
  chainID: number,
  tokenSymbol: string,
): { chain: Chain; token: TokenInfo; isNativeToken: boolean };
client.chainList.getChainAndTokenByAddress(
  chainID: number,
  address: `0x${string}`,
): { chain: Chain; token: TokenInfo; isNativeToken: boolean };

TypeScript

const polygon = client.chainList.getChainByID(137);
const usdc = client.chainList.getTokenInfoBySymbol(137, 'USDC');
const vault = client.chainList.getVaultContractAddress(137);

Max-amount helpers

`calculateMaxForBridge(params)`

Compute the maximum amount that can be bridged for a token to a destination chain. maxAmountRaw can be passed straight into bridge() as toAmountRaw.

TypeScript

const max = await client.calculateMaxForBridge({
  toChainId: 137,
  toTokenSymbol: 'USDC',
});
 
type BridgeMaxResult = {
  toChainId: number;
  toTokenSymbol: string;
  provider: BridgeProvider;
  maxAmount: string;     // human decimal string
  maxAmountRaw: bigint;  // raw integer units
  symbol: string;
  decimals: number;
  sources: Array<{
    chainId: number;
    tokenAddress: Hex;
    symbol: string;
    decimals: number;
    amount: string;      // human decimal drawn from this source
  }>;
};

`calculateMaxForSwap(params)`

Compute the maximum input available for a swap into a destination token. See the Swap Methods pages for the swap surface.

TypeScript

const max = await client.calculateMaxForSwap({
  toChainId: 8453,
  toTokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
});
 
type SwapMaxResult = {
  toChainId: number;
  toTokenAddress: Hex;
  maxAmount: string;     // human decimal string
  maxAmountRaw: bigint;  // raw integer units
  symbol: string;
  decimals: number;
  sources: Array<{
    chainId: number;
    tokenAddress: Hex;
    symbol: string;
    decimals: number;
    amount: string;
  }>;
};

Stateless utilities

Formatting and address helpers are importable directly from the /utils subpath, and are also available on client.utils.

TypeScript

import {
  formatTokenBalance,
  formatTokenBalanceParts,
  formatUnits,
  parseUnits,
  truncateAddress,
  isValidAddress,
  getCoinbaseRates,
  getSupportedChains,
} from '@avail-project/nexus-core/utils';

Formatting

TypeScript

// Format a raw balance for display
const formatted = formatTokenBalance(1234567890n, { decimals: 6, symbol: 'USDC' });
 
// Get the parts separately
const parts = formatTokenBalanceParts(1234567890n, { decimals: 6 });
 
// Convert between raw and human units
const raw = parseUnits('1.5', 18);   // 1500000000000000000n
const human = formatUnits(raw, 18);  // "1.5"

Addresses

TypeScript

const valid = isValidAddress('0x742d35Cc6634C0532925a3b8D4C9db96c4b4Db45'); // boolean
const short = truncateAddress('0x742d35Cc6634C0532925a3b8D4C9db96c4b4Db45'); // "0x742d...Db45"

Token logo fallback

getFallbackTokenLogoDataUri generates a deterministic gradient SVG logo as a data URI — useful as an onError fallback for token images. Note it is exported from the main entry point, not /utils:

TypeScript

import { getFallbackTokenLogoDataUri } from '@avail-project/nexus-core';
 
const logo = getFallbackTokenLogoDataUri('USDC'); // "data:image/svg+xml;charset=utf-8,..."
const large = getFallbackTokenLogoDataUri('USDC', 256); // optional size, defaults to 128

Prices and supported chains

TypeScript

// Current token prices from Coinbase
const rates = await getCoinbaseRates();
 
// Supported chains and tokens for a network (async, standalone helper)
const supported = await getSupportedChains('mainnet');

Via `client.utils`

The same helpers are attached to the client as NexusUtils:

TypeScript

const rates = await client.utils.getCoinbaseRates();
const supported = await client.utils.getSupportedChains('mainnet');
const formatted = client.utils.formatTokenBalance(1234567890n, { decimals: 6, symbol: 'USDC' });

Note

client.getSupportedChains() (the client method) is synchronous and returns the currently connected deployment's chains. The standalone getSupportedChains(network) helper is asynchronous and fetches the deployment for the given network hint.

Analytics

The Nexus SDK includes built-in analytics powered by PostHog. Analytics are enabled by default and send anonymous telemetry to Avail's PostHog instance; they can be customized or disabled through the analytics config.

Disabling analytics

TypeScript

const client = createNexusClient({
  network: 'mainnet',
  analytics: { enabled: false },
});

Privacy controls

TypeScript

const client = createNexusClient({
  network: 'mainnet',
  analytics: {
    enabled: true,
    privacy: {
      anonymizeWallets: true, // Hash wallet addresses
      anonymizeAmounts: true, // Exclude transaction amounts
    },
  },
});

Custom analytics (BYO PostHog)

TypeScript

const client = createNexusClient({
  network: 'mainnet',
  analytics: {
    enabled: true,
    posthogApiKey: 'your-posthog-key',
    posthogApiHost: 'https://your-posthog-instance.com',
    appMetadata: {
      appName: 'My DApp',
      appVersion: '1.0.0',
      appUrl: 'https://mydapp.com',
    },
  },
});

Accessing analytics programmatically

TypeScript

if (client.analytics.isEnabled()) {
  client.analytics.track('custom_event', { foo: 'bar' });
}

Common pitfalls

Operation amounts are raw integer units (bigint), not human-readable decimal strings. Use convertTokenReadableAmountToBigInt() or parseUnits() to convert.
Bridge methods (bridge, bridgeAndTransfer, bridgeAndExecute) identify tokens by symbol; swap methods identify tokens by contract address.
Call initialize() once before running operations. It fetches deployment data and does not require a provider, so it can run before or after setEVMProvider().
Call destroy() on teardown to flush analytics and close sockets.

Skills Integration

skills.sh skills give AI coding agents (Codex, Claude Code, Cursor, etc.) deep context about the Nexus SDK.

# Install the SDK skill
npx skills add availproject/nexus-sdk

nexus-core — Full v2 integration guide: client lifecycle, operations, hooks, events, error handling, utils, and v1 → v2 migration

Browse it at skills.sh/availproject/nexus-sdk. For Widgets skills, see MCP & Agent Skills.

How is this guide?

Hooks and Errors

Cookbook Recipes

createNexusClient(config?: { network?: 'mainnet' | 'testnet' | NetworkConfig; debug?: boolean; analytics?: AnalyticsConfig; devTiming?: DevTimingConfig; domain?: string; forceMayan?: boolean; }): NexusClient

Option

Type

Description

network

'mainnet' | 'testnet' | NetworkConfig

Target network. Defaults to 'mainnet'. Pass a NetworkConfig object for a fully custom deployment.

debug

boolean

Enable verbose debug logging.

analytics

AnalyticsConfig

Analytics configuration (see Analytics).

devTiming

DevTimingConfig

Developer timing instrumentation for spans.

domain

string

Override the auto-detected domain used in the ephemeral-key sign message.

forceMayan

boolean

Force routing through Mayan where available.

type NetworkConfig = { MIDDLEWARE_HTTP_URL: string; MIDDLEWARE_WS_URL: string; INTENT_EXPLORER_URL: string; NETWORK_HINT: 'mainnet' | 'testnet'; }; const client = createNexusClient({ network: { MIDDLEWARE_HTTP_URL: 'https://your-deployment.example.com/middleware/', MIDDLEWARE_WS_URL: 'wss://your-deployment.example.com/middleware/', INTENT_EXPLORER_URL: 'https://your-deployment.example.com/', NETWORK_HINT: 'mainnet', }, });

Parameter

Type

Description

provider

EthereumProvider

EIP-1193 compatible provider (MetaMask, WalletConnect, etc.).

client.chainList.getChainByID(chainID: number): Chain; client.chainList.getTokenInfoBySymbol(chainID: number, symbol: string): TokenInfo; client.chainList.getNativeToken(chainID: number): TokenInfo; client.chainList.getVaultContractAddress(chainID: number): `0x${string}`; client.chainList.getTokenByAddress(chainID: number, address: `0x${string}`): TokenInfo; client.chainList.getTokenByCurrencyId(chainID: number, currencyId: number): TokenInfo; client.chainList.getChainAndTokenFromSymbol( chainID: number, tokenSymbol: string, ): { chain: Chain; token: TokenInfo; isNativeToken: boolean }; client.chainList.getChainAndTokenByAddress( chainID: number, address: `0x${string}`, ): { chain: Chain; token: TokenInfo; isNativeToken: boolean };

const max = await client.calculateMaxForBridge({ toChainId: 137, toTokenSymbol: 'USDC', }); type BridgeMaxResult = { toChainId: number; toTokenSymbol: string; provider: BridgeProvider; maxAmount: string; // human decimal string maxAmountRaw: bigint; // raw integer units symbol: string; decimals: number; sources: Array<{ chainId: number; tokenAddress: Hex; symbol: string; decimals: number; amount: string; // human decimal drawn from this source }>; };

const max = await client.calculateMaxForSwap({ toChainId: 8453, toTokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', }); type SwapMaxResult = { toChainId: number; toTokenAddress: Hex; maxAmount: string; // human decimal string maxAmountRaw: bigint; // raw integer units symbol: string; decimals: number; sources: Array<{ chainId: number; tokenAddress: Hex; symbol: string; decimals: number; amount: string; }>; };

import { formatTokenBalance, formatTokenBalanceParts, formatUnits, parseUnits, truncateAddress, isValidAddress, getCoinbaseRates, getSupportedChains, } from '@avail-project/nexus-core/utils';

// Format a raw balance for display const formatted = formatTokenBalance(1234567890n, { decimals: 6, symbol: 'USDC' }); // Get the parts separately const parts = formatTokenBalanceParts(1234567890n, { decimals: 6 }); // Convert between raw and human units const raw = parseUnits('1.5', 18); // 1500000000000000000n const human = formatUnits(raw, 18); // "1.5"

import { getFallbackTokenLogoDataUri } from '@avail-project/nexus-core'; const logo = getFallbackTokenLogoDataUri('USDC'); // "data:image/svg+xml;charset=utf-8,..." const large = getFallbackTokenLogoDataUri('USDC', 256); // optional size, defaults to 128

// Current token prices from Coinbase const rates = await getCoinbaseRates(); // Supported chains and tokens for a network (async, standalone helper) const supported = await getSupportedChains('mainnet');

const rates = await client.utils.getCoinbaseRates(); const supported = await client.utils.getSupportedChains('mainnet'); const formatted = client.utils.formatTokenBalance(1234567890n, { decimals: 6, symbol: 'USDC' });

const client = createNexusClient({ network: 'mainnet', analytics: { enabled: true, privacy: { anonymizeWallets: true, // Hash wallet addresses anonymizeAmounts: true, // Exclude transaction amounts }, }, });

const client = createNexusClient({ network: 'mainnet', analytics: { enabled: true, posthogApiKey: 'your-posthog-key', posthogApiHost: 'https://your-posthog-instance.com', appMetadata: { appName: 'My DApp', appVersion: '1.0.0', appUrl: 'https://mydapp.com', }, }, });

Search Documentation

Utility Reference

Creating a client

Configuration

Custom network config

Lifecycle

initialize()

setEVMProvider(provider)

hasEvmProvider

destroy()

Chain and token helpers

getSupportedChains()

isSupportedChain(chainId)

convertTokenReadableAmountToBigInt(amount, tokenSymbol, chainId)

client.chainList

Max-amount helpers

calculateMaxForBridge(params)

calculateMaxForSwap(params)

Stateless utilities

Formatting

Addresses

Token logo fallback

Prices and supported chains

Via client.utils

Analytics

Disabling analytics

Privacy controls

Custom analytics (BYO PostHog)

Accessing analytics programmatically

Common pitfalls

Skills Integration

Search Documentation

Utility Reference

Creating a client

Configuration

Custom network config

Lifecycle

initialize()

setEVMProvider(provider)

hasEvmProvider

destroy()

Chain and token helpers

getSupportedChains()

isSupportedChain(chainId)

convertTokenReadableAmountToBigInt(amount, tokenSymbol, chainId)

client.chainList

Max-amount helpers

calculateMaxForBridge(params)

calculateMaxForSwap(params)

Stateless utilities

Formatting

Addresses

Token logo fallback

Prices and supported chains

Via client.utils

Analytics

Disabling analytics

Privacy controls

Custom analytics (BYO PostHog)

Accessing analytics programmatically

Common pitfalls

Skills Integration

`initialize()`

`setEVMProvider(provider)`

`hasEvmProvider`

`destroy()`

`getSupportedChains()`

`isSupportedChain(chainId)`

`convertTokenReadableAmountToBigInt(amount, tokenSymbol, chainId)`

`client.chainList`

`calculateMaxForBridge(params)`

`calculateMaxForSwap(params)`

Via `client.utils`

`initialize()`

`setEVMProvider(provider)`

`hasEvmProvider`

`destroy()`

`getSupportedChains()`

`isSupportedChain(chainId)`

`convertTokenReadableAmountToBigInt(amount, tokenSymbol, chainId)`

`client.chainList`

`calculateMaxForBridge(params)`

`calculateMaxForSwap(params)`

Via `client.utils`