Skip to Content
Avail Nexus is now live! Check out our docs to get started.
NexusQuickstartNexus Core

Nexus-core

This page will help you quickly get started with nexus-core.

We also made a demo app for Nexus Core to make it easier for devs to get on-boarded with the Avail Nexus SDK:

Getting started with the headless Nexus SDK is simple.

Make sure to have a wallet provider

The Nexus SDK requires an injected wallet provider (e.g. RainbowKit, ConnectKit, etc.)

To be clear, even a basic injected provider using the window.ethereum object will work, but we recommend using a dedicated wallet provider.

Initialize the SDK

A more complete example of getting started with nexus-core can be found in this page of our docs.

Choose the network type you want to use and initialize the SDK with the wallet provider.

Typescript
import { NexusSDK } from '@avail-project/nexus-core';
import type { NexusNetwork } from '@avail-project/nexus-core';
 
// Mainnet (default)
const sdk = new NexusSDK();
 
// Testnet
const sdk = new NexusSDK({ network: 'testnet' as NexusNetwork });
 
// Initialize with provider (required)
await sdk.initialize(window.ethereum); // Returns: Promise<void>

Set up hooks for the SDK

  • Hooks are mandatory. If these are not set up then once the intent is created the flow will not progress at all.
  • Events are optional (recommended), but hooks must be covered during initialization.

Hooks let your app approve/deny the transaction intent and manage token allowances before the SDK proceeds.

The SDK provides two hooks for this purpose:

  • setOnIntentHook: This hook is used to approve/deny the transaction intent. Use it to allow your users to approve or reject the final intent.
  • setOnAllowanceHook: This hook is used to manage token allowances. Use it to allow your users to approve or reject the required token allowances.
hooks.ts
// Assuming `sdk` is initialized from the previous step
 
// Intent approval: show routes/fees to user, then allow() or deny().
// Tip: call refresh() periodically (e.g., every 5s) to keep fees current.
sdk.setOnIntentHook(({ intent, allow, deny, refresh }) => {
  // Show intent in your UI. Example decision:
  const userConfirms = true; // replace with your UI logic
  if (userConfirms) allow();
  else deny();
 
  // Optionally set up a timer to refresh quotes:
  // setInterval(() => refresh(), 5000);
});
 
// Allowance approval: specify spend permissions per required source.
// Valid values: 'min' | 'max' | string | bigint (array length must match sources.length)
sdk.setOnAllowanceHook(({ allow, deny, sources }) => {
  // Show allowances needed to user, then:
  allow(['min']); // or ['max'] or custom per source
  // Call deny() to cancel.
});

Events help you monitor progress and show hashes/links in the UI.

The SDK emits the following events:

Bridge & Execute Operations:

  • BRIDGE_EXECUTE_EXPECTED_STEPS: Emitted when the intent for the bridge and execute operation is created. Contains an ordered array of ProgressStep objects.
  • BRIDGE_EXECUTE_COMPLETED_STEPS: Emits per completed step of the intent’s fulfillment, contains a ProgressStep object in each emission.

Transfer & Bridge Operations:

  • EXPECTED_STEPS: Emitted when the intent for the transfer or bridge operation is created. Contains an ordered array of ProgressStep objects.
  • STEP_COMPLETE: Emits per completed step of the intent’s fulfillment, contains a ProgressStep object in each emission.

Here is a complete example of how you can subscribe to these events:

events.ts
import { NEXUS_EVENTS, ProgressStep } from '@avail-project/nexus-core';
 
// Bridge & Execute Progress
const unsubscribeBridgeExecuteExpected = sdk.nexusEvents.on(
  NEXUS_EVENTS.BRIDGE_EXECUTE_EXPECTED_STEPS,
  (steps: ProgressStep[]) => {
    console.log(
      'Bridge & Execute steps →',
      steps.map((s) => s.typeID),
    );
  },
);
 
const unsubscribeBridgeExecuteCompleted = sdk.nexusEvents.on(
  NEXUS_EVENTS.BRIDGE_EXECUTE_COMPLETED_STEPS,
  (step: ProgressStep) => {
    console.log('Bridge & Execute completed →', step.typeID, step.data);
 
    if (step.typeID === 'IS' && step.data.explorerURL) {
      console.log('View transaction:', step.data.explorerURL);
    }
  },
);
 
// Transfer & Bridge Progress (optimized operations)
const unsubscribeTransferExpected = sdk.nexusEvents.on(
  NEXUS_EVENTS.EXPECTED_STEPS,
  (steps: ProgressStep[]) => {
    console.log(
      'Transfer/Bridge steps →',
      steps.map((s) => s.typeID),
    );
    // For direct transfers: ['CS', 'TS', 'IS'] (3 steps, ~5-15s)
  },
);
 
const unsubscribeTransferCompleted = sdk.nexusEvents.on(
  NEXUS_EVENTS.STEP_COMPLETE,
  (step: ProgressStep) => {
    console.log('Transfer/Bridge completed →', step.typeID, step.data);
 
    if (step.typeID === 'IS' && step.data.explorerURL) {
      // Transaction submitted with hash - works for both direct and CA
      console.log('Transaction hash:', step.data.transactionHash);
      console.log('Explorer URL:', step.data.explorerURL);
    }
  },
);
 
// Cleanup
return () => {
  unsubscribeBridgeExecuteExpected();
  unsubscribeBridgeExecuteCompleted();
  unsubscribeTransferExpected();
  unsubscribeTransferCompleted();
};
Last updated on
QuickstartNexus Widgets