Hooks and Events

Set up hooks once after SDK init

• Call sdk.setOnIntentHook(callback) .

• Call sdk.setOnAllowanceHook(callback) .

• Call sdk.setOnSwapIntentHook(callback) .

• If a hook is not set, the SDK auto-approves and continues.

• If a hook is set, always call allow(...) or deny() or the flow will stall.

• Optionally auto-deny after a timeout to avoid hanging UX.

Handle intent hook (bridge / bridgeAndTransfer / bridgeAndExecute)

Signature

sdk.setOnIntentHook((data) => { // data: OnIntentHookData });

OnIntentHookData

• allow(): void — continue the flow

• deny(): void — reject the flow

• intent: ReadableIntent — readable intent info for UI

• refresh(selectedSources?: number[]): Promise<ReadableIntent> — refresh the intent

How to use

• Store data in a ref so UI can call allow() /deny() later.

• Call refresh() on an interval (e.g., every 15s) if you show intent details.

• If the user closes the modal or cancels, call deny() and clear the ref.

Handle allowance hook (approval control)

Signature

sdk.setOnAllowanceHook((data) => { // data: OnAllowanceHookData });

OnAllowanceHookData

• allow(decisions): void

• decisions must match the number of sources

• each entry can be 'min' , 'max' , bigint , or numeric string

• deny(): void

• sources: AllowanceHookSources

• includes chain/token info and current vs required allowance

How to use

• Present each source to the user (chain + token + required allowance).

• Build the decisions array in the same order as sources .

• Call allow(decisions) to continue, or deny() to cancel.

• Ensure decisions.length === sources.length or the SDK will reject with INVALID_VALUES_ALLOWANCE_HOOK .

Handle swap intent hook (swap flows)

Signature

sdk.setOnSwapIntentHook((data) => { // data: OnSwapIntentHookData });

OnSwapIntentHookData

• allow(): void

• deny(): void

• intent: SwapIntent

• refresh(): Promise<SwapIntent>

How to use

• Store data and show a UI summary.

• Call allow() to proceed or deny() to cancel.

Stream events for progress UI

Attach listeners

• All main operations accept { onEvent } in options.

Event names and payloads

• NEXUS_EVENTS.STEPS_LIST → BridgeStepType[]

• NEXUS_EVENTS.STEP_COMPLETE → BridgeStepType

• NEXUS_EVENTS.SWAP_STEP_COMPLETE → SwapStepType

Typical usage

• Use STEPS_LIST to seed step trackers.

• Use STEP_COMPLETE and SWAP_STEP_COMPLETE to update progress and explorer links.

Handle errors and cancellation

• If an operation throws, clear intent/allowance refs to avoid stale state.

• On user cancel, call deny() for the active hook and reset UI state.

• If a hook is set but no allow() /deny() is called, the intent remains pending.

Expand error-handling patterns

Normalize errors

• The SDK throws NexusError for known failures.

• Import from SDK:

• import { NexusError, ERROR_CODES } from '@avail-project/nexus-core'

Map common error codes to UX responses

• USER_DENIED_INTENT / USER_DENIED_ALLOWANCE / USER_DENIED_INTENT_SIGNATURE :

• Treat as user cancel; show a neutral message and reset UI.

• INVALID_VALUES_ALLOWANCE_HOOK :

• Fix decisions length/type and resubmit.

• SDK_NOT_INITIALIZED / WALLET_NOT_CONNECTED / CONNECT_ACCOUNT_FAILED :

• Prompt user to reconnect; re-run sdk.initialize(...) .

• INVALID_INPUT / INVALID_ADDRESS_LENGTH :

• Validate inputs; block submission until fixed.

• INSUFFICIENT_BALANCE / NO_BALANCE_FOR_ADDRESS :

• Prompt user to reduce amount or fund source chain.

• TOKEN_NOT_SUPPORTED / CHAIN_NOT_FOUND :

• Block submission and update selectors.

• QUOTE_FAILED / SWAP_FAILED / RATES_CHANGED_BEYOND_TOLERANCE / SLIPPAGE_EXCEEDED_ALLOWANCE :

• Re-run quote or suggest a smaller amount.

• RFF_FEE_EXPIRED :

• Re-simulate and re-submit the transaction.

• TRANSACTION_TIMEOUT / LIQUIDITY_TIMEOUT :

• Show “pending” state and allow retry or check intent history.

• TRANSACTION_REVERTED :

• Display failure with explorer link if available.

• COSMOS_ERROR / INTERNAL_ERROR :

• Show a generic error and log err.data?.details for support.

Use a helper pattern

import { NexusError, ERROR_CODES } from '@avail-project/nexus-core';

export function getReadableNexusError(err: unknown): string { if (err instanceof NexusError) { switch (err.code) { case ERROR_CODES.USER_DENIED_INTENT: case ERROR_CODES.USER_DENIED_ALLOWANCE: case ERROR_CODES.USER_DENIED_INTENT_SIGNATURE: return 'Transaction cancelled by user'; case ERROR_CODES.INSUFFICIENT_BALANCE: return 'Insufficient balance'; case ERROR_CODES.SLIPPAGE_EXCEEDED_ALLOWANCE: case ERROR_CODES.RATES_CHANGED_BEYOND_TOLERANCE: return 'Price changed too much. Please try again.'; case ERROR_CODES.TRANSACTION_TIMEOUT: return 'Transaction timed out. Please retry.'; default: return err.message; } } if (err instanceof Error) return err.message; return 'Unknown error'; }

Clean up on error

• Clear intent/allowance refs and reset progress state:

• intentRef.current = null; allowanceRef.current = null; swapIntentRef.current = null;

• reset step UI and pending flags