Bridge and Execute Flows

Call bridge(params, options?)

• Use to move tokens cross-chain (intent-based bridge).

• Signature:

• sdk.bridge(params, { onEvent? })

• Params (BridgeParams ):

• token: string — token symbol (e.g., "ETH", "USDC")

• amount: bigint — smallest units

• toChainId: number — destination chain id

• recipient?: Hex — defaults to connected user address

• gas?: bigint — optional native gas to deliver on destination

• sourceChains?: number[] — restrict source chains

• Result (BridgeResult ):

• explorerUrl: string

• sourceTxs: { chain, hash, explorerUrl }[]

• intent: ReadableIntent

Call bridgeAndTransfer(params, options?)

• Use to bridge and transfer to a recipient address.

• Signature:

• sdk.bridgeAndTransfer(params, { onEvent? })

• Params (TransferParams ):

• token: string

• amount: bigint

• toChainId: number

• recipient: Hex

• sourceChains?: number[]

• Result (TransferResult ):

• transactionHash: string

• explorerUrl: string

Call bridgeAndExecute(params, options?)

• Use to bridge (if needed) and then execute a contract call.

• Signature:

• sdk.bridgeAndExecute(params, { onEvent?, beforeExecute? })

• Params (BridgeAndExecuteParams ):

• token: string , amount: bigint , toChainId: number

• execute: Omit<ExecuteParams, "toChainId">

• Optional: waitForReceipt , requiredConfirmations , timeouts

• beforeExecute hook (optional):

• beforeExecute?: () => Promise<{ value?: bigint; data?: Hex; gas?: bigint }>

• Use to dynamically override execute payload before sending.

• Result (BridgeAndExecuteResult ):

• executeTransactionHash: string

• executeExplorerUrl: string

• bridgeExplorerUrl?: string (undefined if bridge skipped)

• bridgeSkipped: boolean

• intent?: ReadableIntent

Call execute(params, options?)

• Use for a standalone contract call on a chain.

• Signature:

• sdk.execute(params, { onEvent? })

• Params (ExecuteParams ):

• toChainId: number

• to: Hex (contract address)

• data?: Hex

• value?: bigint

• gas?: bigint (optional but recommended for deterministic behavior)

• gasPrice?: 'low' | 'medium' | 'high'

• Optional receipt config: waitForReceipt , receiptTimeout , requiredConfirmations

• Optional tokenApproval?: { token: string; amount: bigint; spender: Hex }

• Result (ExecuteResult ):

• transactionHash , explorerUrl , chainId

• optional receipt fields

Use simulation helpers

• Call sdk.simulateBridge(params) → SimulationResult .

• Call sdk.simulateBridgeAndTransfer(params) → BridgeAndExecuteSimulationResult .

• Call sdk.simulateBridgeAndExecute(params) → BridgeAndExecuteSimulationResult .

• Use simulation to show fees and gas before execution.

• Expect BridgeAndExecuteSimulationResult.bridgeSimulation to be null if bridge is skipped.

Compute max bridgeable amount

• Call sdk.calculateMaxForBridge({ token, toChainId, recipient?, sourceChains? }) .

• Use BridgeMaxResult to set “max” or validate input.

Convert amounts to bigint

• Use sdk.convertTokenReadableAmountToBigInt(amountString, tokenSymbol, chainId) .

• Or use sdk.utils.parseUnits(value, decimals) if decimals are known.

Attach hooks and events

• Attach intent and allowance hooks before calling bridge flows.

• Use NEXUS_EVENTS.STEPS_LIST and NEXUS_EVENTS.STEP_COMPLETE for progress UI.

Handle common failures

• On throw, clear intent/allowance refs and reset UI state.

• On user cancel, call deny() on the active hook and abort.