Understanding Balance Types

Why bridge and swap operations use different token balances, and when to use each.

You are viewing the Nexus SDK v2 docs. For the current SDK, see the v3 docs and the v2 → v3 migration guide.

Nexus allows you to query 2 types of balances for different use cases. These balances determine the sourcing of liquidity when doing certain operations.

Bridge Balance
Swap Balance

Both queries return the same TokenBalance[] shape — a unified per-token total with a per-chain breakdown:

type TokenBalance = {
  balance: string;
  value: string; // USD value
  chainBalances: ChainBalance[]; // per-chain breakdown
  decimals: number;
  logo: string;
  name: string;
  symbol: string;
};

Bridge Balance

Use Fetch Bridge Balance to get all token balances available for bridge operations across supported chains in a single call. Any Bridge Method you call will source liquidity from these balances.

client.getBalancesForBridge(): Promise<TokenBalance[]>

Swap Balance

Use Fetch Swap Balance to get all token balances available for swap operations across supported chains in a single call. Any Swap Method you call will source liquidity from these balances.

client.getBalancesForSwap(): Promise<TokenBalance[]>

Why two different balances?

Nexus solvers only manage liquidity for canonical bridge tokens — currently ETH, USDC, and USDT (see Supported Chains & Tokens). Bridge balances reflect what solvers can move across chains directly. A bridge route may be served natively by Nexus or via Mayan — the SDK selects the provider automatically per route. For crosschain swaps, Nexus orchestrates the intent but the actual swaps are executed by partner DEX aggregators (such as LiFi, Bebop, and 0x). This means swap operations can access a much wider range of tokens, since they aren't limited by solver liquidity. Because the available tokens differ between bridging and swapping, each operation needs its own balance query — your "swappable" balances are not the same as your "bridgeable" assets.

Note

Learn more about Bridge methods.

How is this guide?

Liquidity Routing

Control where your tokens are sourced from.

Bridge Balance Swap Balance Why two different balances?

Edit in GitHub

type TokenBalance = { balance: string; value: string; // USD value chainBalances: ChainBalance[]; // per-chain breakdown decimals: number; logo: string; name: string; symbol: string; };

Search Documentation

Understanding Balance Types

Bridge Balance

Swap Balance

Why two different balances?

Search Documentation

Understanding Balance Types

Bridge Balance

Swap Balance

Why two different balances?