Why bridge and swap operations use different token balances, and when to use each.
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:
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.
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.
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.