Get started

The Intents Swap Widget is highly configurable, allowing developers to tailor its appearance and behavior to fit their application.

Configuration is handled via the <WidgetConfigProvider> component, which wraps your widget(s) and provides global settings.

Installation

Install the widget package using your preferred package manager:

npm install @aurora-is-near/intents-swap-widget

# or

yarn add @aurora-is-near/intents-swap-widget

Alternatively, if you want to use the widget in standalone mode with embedded wallet connection mechanisms:

npm install @aurora-is-near/intents-swap-widget-standalone

# or

yarn add @aurora-is-near/intents-swap-widget-standalone

Setup

To configure the widget, pass a config object to the WidgetConfigProvider. This object defines core parameters such as the app identifier, default tokens, theme, and optional partner fee settings.

Example

import {
  type WidgetConfig,
  WidgetConfigProvider,
  Widget,
} from '@aurora-is-near/intents-swap-widget';

const config: WidgetConfig = {
  connectedWallets: {
    default: '0x...',
    ton: 'ABC123',
  },
  appFees: [
    {
      recipient: 'your.account.near',
      fee: 25,
    },
  ],
};

export default function App() {
  return (
    <WidgetConfigProvider config={config}>
      <Widget />
    </WidgetConfigProvider>
  );
}

Core options

The following options are available if you are not using standalone mode (i.e. you installed @aurora-is-near/intents-swap-widget).

connectedWallets

A map of connected wallet addresses keyed by chain. Used to determine which accounts can send or receive tokens on each network.

providers

The provider(s) for interacting with the connectedWallets. Used for signing messages.

plugins

At the time of writing, this property is used to provide network plugins, one per chain you want to support for native transfers.

Example

import { evm } from '@aurora-is-near/intents-swap-widget-evm';
import { sol } from '@aurora-is-near/intents-swap-widget-solana';
import { stellar } from '@aurora-is-near/intents-swap-widget-stellar';

const config = {
  plugins: { evm, sol, stellar },
};

Install only the sibling packages for chains you actually use.

Note that NEAR support is built in and does not require a plugin.

See Wallet Connection for full examples.

onWalletSignin

Used to trigger wallet connection for main action button. If this function is not provided the button will have the label "Connect wallet" and not be clickable.

onWalletSignout

Used to sign out user's wallet. Currently used for compatibility check modal if a wallet is incompatible. NB: some wallets don't support programmatic logout make sure you guide user accordingly if required on your side.

showProfileButton

Show a profile button at the top of the widget via which you can connect (by calling onWalletSignin) or disconnect (by calling onWalletSignout).

Common Options

The following options are available for all widget packages (i.e. you installed @aurora-is-near/intents-swap-widget or @aurora-is-near/intents-swap-widget-standalone):

apiKey

Your widget integration API Key. Visit Intents Widget Studio to obtain.

referral

Your application name that is used as an alias for quotes. Optional.

enableAccountAbstraction

Used to allow uses to deposit to and withdraw from your app's internal Intents account.

walletSupportedChains

A list of blockchain networks supported by the connected wallet(s).

If this is not provided we will attempt to establish the supported chains based on the format of the wallet address.

sendAddress

Optional fixed destination wallet. If not specified the widget will use the source wallet address as the receiver, by default.

slippageTolerance

The slippage tolerance for a transfer.

This value is defined in basis points (1/100th of a percent). For example, 100 for 1% slippage, or 50 for 0.5% slippage.

enableAutoTokensSwitching

When enabled, the widget automatically rotates the source and target tokens if the user selects the same token on both sides.

refetchQuoteInterval

The interval in milliseconds at which new quotes are fetched automatically. Useful for keeping market prices updated in volatile conditions.

allowedTokensList

Specifies the available tokens by their NEAR intents asset IDs or token symbols. It will only be possible to select tokens from this list in both the source and the target inputs.

allowedSourceTokensList

Specifies the available source tokens by their NEAR intents asset IDs or token symbols. It will only be possible to select tokens from this list in the source input.

allowedTargetTokensList

Specifies the available target tokens by their NEAR intents asset IDs or token symbols. It will only be possible to select tokens from this list in the target input.

filterTokens

A filter function applied to tokens in both the source and target lists. Return true to include the token, or false to exclude it.

This can be useful when we want to exclude, rather than include particular tokens. If you want to include particular tokens the allowedTokensList option might be more suitable.

defaultSourceToken

Predefine the default source token. Can be set to null to keep it not selected.

defaultTargetToken

Predefine the default target token. Can be set to null to keep it not selected.

chainsOrder

Defines the order in which supported chains are displayed.

Can be used to bring particular chains to the top of the list. Any chains not specified here will be sorted according to a default order.

Example

const config = {
  chainsOrder: ['eth', 'btc', 'near'],
}

topChainShortcuts

Defines top chain shortcuts that are visible to a user for quick access in tokens modal.

You can specify different lists of chains based on user's account type (wallet connected). Four chains must be specified to keep layout clean. If the following configuration attributes are set: allowedChainsList, allowedSourceChainsList or allowedTargetChainsList and a chain is not in those lists it's shortcut won't be displayed, be careful specifying multiple chain filters.

Example

const config = {
  // this is the default behaviour
  topChainShortcuts: (intentsAccountType) => {
    switch (intentsAccountType) {
      case 'evm':
        return ['eth', 'arb', 'avax', 'base'] as const;
      case 'sol':
        return ['sol', 'eth', 'btc', 'near'] as const;
      case 'near':
        return ['near', 'sol', 'eth', 'btc'] as const;
      default:
        return ['eth', 'btc', 'sol', 'near'] as const;
    }
  },
}

allowedChainsList

Restricts which chains that can be used when selecting source or target tokens.

Example

const config = {
  allowedChainsList: ['base', 'eth', 'ton'],
}

allowedSourceChainsList

Restricts which chains can be used when selecting source tokens.

Example

const config = {
  allowedSourceChainsList: ['base', 'eth'],
}

allowedTargetChainsList

Restricts which chains can be used when selecting target tokens.

Example

const config = {
  allowedTargetChainsList: ['ton'],
}

chainsFilter

Specify high-level categories of chains that should be displayed when selecting the source or target token.

You will probably find the internal defaults sufficient in most cases, which are driven by the enableAccountAbstraction option and whether or not there are any connectedWallets. However, this option exists for the case where you want more fine-grained control, for example, when building your own custom widget using our components.

Example

const config = {
  chainsFilter: {
    source: { external: 'wallet-supported', intents: 'none' },
    target: { external: 'all', intents: 'none' },
  },
};

priorityAssets

Defines the order in which tokens with no balance are displayed on top of the list.

If you want to promote certain tokens or just show most used on top of the list you can add them here and they will be displayed in a given order. Tokens that have balance always stay on top regardless. Tokens with no balance and not included in priorityAssets are sorted alphabetically at the bottom of the list.

The option accepts an array of arrays, where each child array defines either the chain ID and token symbol, or the asset ID.

Example

const config = {
  priorityAssets: [
    ['eth', 'ETH'],
    ['eth', 'USDT'],
  ],
};

or use asset IDs:

const config = {
  priorityAssets: [
    'nep141:eth.omft.near',
    'nep141:eth-0xdac17f958d2ee523a2206206994597c13d831ec7.omft.near',
  ],
};

or mix:

const config = {
  priorityAssets: [
    'nep141:eth.omft.near',
    ['eth', 'USDT'],
  ],
};

fetchQuote

A function used to implement custom quote fetching behaviour, overriding the default of calling the 1Click API quote endpoint.

For example, you might want to use this proxy quotes via your own API endpoint and insert some additional data based on your backend logic.

Example

const config = {
  fetchQuote: async (data, { signal }) => {
    const res = await axios.post(
    'https://my.proxy.com/quote',
      data,
      { signal },
    );

    return res.data;
  },
}

fetchSourceTokens

A function used to fetch a list of custom source tokens.

For example, you might want to make a call to some API endpoint.

Example

const config = {
  fetchSourceTokens: async () => {
    const res = await fetch('https://example.com/tokens');

    return res.json();
  },
}

fetchTargetTokens

A function used to fetch a list of custom target tokens.

For example, you might want to make a call to some API endpoint.

Example

const config = {
  fetchTargetTokens: async () => {
    const res = await fetch('https://example.com/tokens');

    return res.json();
  },
}

appFees

A list of recipients and their associated fees that will be applied to each swap or transfer.

Properties

• recipient [string] Account ID within Intents to which this fee will be transferred.

• fee [number] Fee for this recipient as part of amountIn in basis points (1/100th of a percent), for example, 100 for a 1% fee.

Example

const config = {
  appFees: [
    {
      recipient: 'recipient.near',
      fee: 100,
    }
  ]
}

alchemyApiKey

An API key for integrating with Alchemy.

This is useful for enabling more reliable balance fetching for EVM chains.

tonCenterApiKey

An API key for integrating with TON Center.

This is useful for fetching balances for the TON chain.

hideSendAddress

Used to hide the send address when swapping or withdrawing.

hideTokenInputHeadings

Used to hide the headings on the token input boxes.

themeParentElementSelector

HTML element that defines CSS theming variables. If not set, the body element is used.

lockSwapDirection

By default, when using the swap widget, we can click the arrow in the middle to switch the swap direction. This option disables that feature.

showTransactionHistory

Enables swaps transaction history for a user's wallet. Disabled by default.

disabledInternalBalanceTokens

Filters out some tokens from internal balance list.

showConversionPreview

Enables live swap conversion preview in the tokens list on hover.

extraQuoteParameters

Allows you to pass extra attributes for each of the 1Click quote request. Includes: virtualChainRecipient, virtualChainRefundRecipient, sessionId. More information: 1Click API Documentation