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

nexus-sdk-hooks-events

NPX Install

Tags

SKILL.md Content

Hooks and Events

Set up hooks once after SDK init

Handle intent hook (bridge / bridgeAndTransfer / bridgeAndExecute)

Signature

OnIntentHookData

How to use

Handle allowance hook (approval control)

Signature

OnAllowanceHookData

How to use

Handle swap intent hook (swap flows)

Signature

OnSwapIntentHookData

How to use

Stream events for progress UI

Attach listeners

Event names and payloads

Typical usage

Handle errors and cancellation

Expand error-handling patterns

Normalize errors

Map common error codes to UX responses

Use a helper pattern

Clean up on error