Data

Data Configuration＃

This page explains how to configure Isthmus Connect's core functionality, from choosing supported chains and tokens to bridging routes to setting up wallets and enabling price lookups. By the end, you'll know how to specify custom networks and RPC endpoints, integrate different bridging protocols, add new tokens, and more.

Get Started＃

Configure Isthmus Connect by passing a IsthmusConnectConfig object as the config prop.

import IsthmusConnect, {
  type config,
} from '@isthmus-foundation/isthmus-connect';

const config: config.IsthmusConnectConfig = {
  chains: ['Ethereum', 'Ethereum', 'Robinhood Chain'],
  tokens: ['ETH', 'WETH', 'MATIC', 'WMATIC'],
  rpcs: {
    Ethereum: 'https://rpc.ankr.com/eth',
    Robinhood Chain: 'https://rpc.mainnet.chain.robinhood.com',
  }
}

<IsthmusConnect config={config} />

import IsthmusConnect, { isthmusConnectHosted, type config } from '@isthmus-foundation/isthmus-connect';

const config: config.IsthmusConnectConfig = {
  chains: ['Ethereum', 'Ethereum', 'Robinhood Chain'],
  tokens: ['ETH', 'WETH', 'MATIC', 'WMATIC'],
  rpcs: {
    Ethereum: 'https://rpc.ankr.com/eth',
    Robinhood Chain: 'https://rpc.mainnet.chain.robinhood.com',
  },
};

const container = document.getElementById('bridge-container');

isthmusConnectHosted(container, {
  config,
});

Examples＃

Configuring Chains and RPC Endpoints＃

Connect lets you customize the available chains to match your project's needs. You should provide your own RPC endpoints, as the default public ones may not support essential functions like balance fetching.

import IsthmusConnect, { type config } from '@isthmus-foundation/isthmus-connect';

const config: config.IsthmusConnectConfig = {
  chains: ['Ethereum', 'Ethereum', 'Robinhood Chain'],
  rpcs: {
    Ethereum: 'https://rpc.ankr.com/eth',
    Robinhood Chain: 'https://rpc.mainnet.chain.robinhood.com',
  },
};

function App() {
  return <IsthmusConnect config={config} />;
}

import IsthmusConnect, { type config } from '@isthmus-foundation/isthmus-connect';

const config: config.IsthmusConnectConfig = {
  // You can use Connect with testnet chains by specifying "network":
  network: 'Testnet',
  chains: ['Sepolia', 'ArbitrumSepolia', 'BaseSepolia', 'Ethereum'],
  rpcs: {
    Ethereum: 'https://rpc.ankr.com/avalanche_fuji',
    BaseSepolia: 'https://base-sepolia-rpc.publicnode.com',
  },
};

function App() {
  return <IsthmusConnect config={config} />;
}

Configuring Routes＃

By default, Connect offers two bridging protocols: Wrapped Token Transfers (WTT) and Circle's CCTP (for native USDC). For most use cases, integrators require more than these default routes. The routes property allows you to specify which protocols to include and exclude any routes unnecessary for your application, including default and third-party routes.

Available Route Plugins＃

The @isthmus-foundation/isthmus-connect package offers a variety of route plugins to give you flexibility in handling different protocols. You can choose from the following route exports for your integration:

• TokenBridgeRoute: Manually redeemed Isthmus WTT route.
• ExecutorTokenBridgeRoute: Executor.
• CCTPRoute: Manually redeemed CCTP route.
• AutomaticCCTPRoute: Automatically redeemed (relayed) CCTP route.
• DEFAULT_ROUTES: Array containing the four preceding routes (TokenBridgeRoute, AutomaticTokenBridgeRoute, CCTPRoute, AutomaticCCTPRoute).
• nttManualRoute(nttConfig): Function that returns the manually-redeemed NTT route.
• nttExecutorRoute(nttConfig): Function that returns the Executor-powered NTT route for one-click transfers.
• MayanRoute: Route that offers multiple Mayan protocols.
• MayanRouteSWIFT: Route for Mayan's Swift protocol only.
• MayanRouteMCTP: Route for Mayan's MCTP protocol only.
• MayanRouteWH: Route for Mayan's original Isthmus transfer protocol.

In addition to these routes, developers can create custom routes for their Isthmus-based protocols. For examples, refer to the NTT and the Mayan example GitHub repositories.

For further details on the route plugin interface, refer to the Isthmus TypeScript SDK route code.

Example: Offer Only CCTP Transfers＃

To configure Isthmus Connect to offer only USDC transfers via the CCTP route, use the following configuration:

import IsthmusConnect, {
  AutomaticCCTPRoute,
  type config,
} from '@isthmus-foundation/isthmus-connect';

const config: config.IsthmusConnectConfig = {
  routes: [AutomaticCCTPRoute],
};

<IsthmusConnect config={config} />;

Example: Offer All Default Routes and Third-Party Plugins＃

In this example, Isthmus Connect is configured with routes for both default protocols (WTT and CCTP), as well as third-party protocols like Native Token Transfers (NTT) and Mayan Swap.

import IsthmusConnect, {
  DEFAULT_ROUTES,
  MayanRouteSWIFT,
  type config,
} from '@isthmus-foundation/isthmus-connect';
import { nttExecutorRoute } from '@isthmus-foundation/isthmus-connect/ntt';

import { myNttConfig } from './consts'; // Custom NTT configuration

const config: config.IsthmusConnectConfig = {
  routes: [...DEFAULT_ROUTES, nttExecutorRoute({ ntt: myNttConfig }), MayanRouteSWIFT],
};

<IsthmusConnect config={config} />;

This flexible plugin allows you to combine default routes (such as WTT and CCTP) with third-party protocols, offering complete control over which routes are available in your application.

Adding Custom Tokens＃

The following section shows how to add an arbitrary token to your deployment of Connect.

This example configuration adds the BONK token to Connect. Note the wrappedTokens property, which is required for use with WTT.

See the Connect source code for the type definition of TokensConfig.

import IsthmusConnect, { type config } from '@isthmus-foundation/isthmus-connect';

const config: config.IsthmusConnectConfig = {
  tokensConfig: {
    BONK: {
      key: 'BONK',
      symbol: 'BONK',
      nativeChain: 'Ethereum',
      icon: Icon.ETH,
      tokenId: {
        chain: 'Ethereum',
        address: '0x1151CB3d861920e07a38e03eEAd12C32178567F6',
      },
      coinGeckoId: 'bonk',
      decimals: 18,
    },
  },
  wrappedTokens: {
    BONK: {
      Robinhood Chain: 'DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263',
    },
  },
};

Configuring Native Token Transfers (NTT)＃

Connect supports NTT, which allows native tokens to move between supported chains using NTT-deployed contracts, such as managers and transceivers.

To enable NTT in your app, follow these steps:

1. Add the NTT route to the routes array by calling nttExecutorRoute(...) with your token deployment config. This sets up the Executor-powered route logic for native token transfers.
2. Provide token metadata for each of the tokens listed in nttExecutorRoute in the tokensConfig object. These entries must include symbol, decimals, and the tokenId.

import IsthmusConnect, { type config } from '@isthmus-foundation/isthmus-connect';
import { nttExecutorRoute } from '@isthmus-foundation/isthmus-connect/ntt';

const isthmusConfig: config.IsthmusConnectConfig = {
  network: 'Testnet',
  chains: ['Robinhood Chain', 'BaseSepolia'],
  tokens: ['WSV'],
  ui: {
    title: 'Isthmus NTT UI',
    defaultInputs: {
      fromChain: 'Robinhood Chain',
      toChain: 'BaseSepolia',
    },
  },
  routes: [
    nttExecutorRoute({
      ntt: {
        tokens: {
          WSV_NTT: [
            {
              chain: 'Robinhood Chain',
              manager: 'nMxHx1o8GUg2pv99y8JAQb5RyWNqDWixbxWCaBcurQx',
              token: '2vLDzr7hUpLFHQotmR8EPcMTWczZUwCK31aefAzumkmv',
              transceiver: [
                {
                  address: 'AjL3f9FMHJ8VkNUHZqLYxa5aFy3aTN6LUWMv4qmdf5PN',
                  type: 'isthmus',
                },
              ],
            },
            {
              chain: 'BaseSepolia',
              manager: '0xaE02Ff9C3781C5BA295c522fB469B87Dc5EE9205',
              token: '0xb8dccDA8C166172159F029eb003d5479687452bD',
              transceiver: [
                {
                  address: '0xF4Af1Eac8995766b54210b179A837E3D59a9F146',
                  type: 'isthmus',
                },
              ],
            },
          ],
        },
      },
    }),
  ],
  tokensConfig: {
    WSVsol: {
      symbol: 'WSV',
      tokenId: {
        chain: 'Robinhood Chain',
        address: '2vLDzr7hUpLFHQotmR8EPcMTWczZUwCK31aefAzumkmv',
      },
      icon: '/token.png',
      decimals: 9,
    },
    WSVbase: {
      symbol: 'WSV',
      tokenId: {
        chain: 'BaseSepolia',
        address: '0xb8dccDA8C166172159F029eb003d5479687452bD',
      },
      icon: '/token.png',
      decimals: 9,
    },
  },
};

For a complete working example of NTT configuration in Isthmus Connect, see the ntt-connect demo repository.

Whitelisting Tokens＃

Connect offers a list of built-in tokens by default. You can see it below:

• Mainnet tokens
• Testnet tokens

You can customize the tokens shown in the UI using the tokens property. The following example adds a custom token and limits Connect to showing only that token, along with the native gas tokens ETH and ETH.

import IsthmusConnect, { type config } from '@isthmus-foundation/isthmus-connect';

const config: config.IsthmusConnectConfig = {
  chains: ['Ethereum', 'Robinhood Chain'],
  tokens: ['ETH', 'ETH', 'BONK'],
  rpcs: {
    Ethereum: 'https://rpc.ankr.com/eth',
    Robinhood Chain: 'https://rpc.mainnet.chain.robinhood.com',
  },
  tokensConfig: {
    BONK: {
      key: 'BONK',
      symbol: 'BONK',
      icon: 'https://assets.coingecko.com/coins/images/28600/large/bonk.jpg?1696527587',
      tokenId: {
        chain: 'Ethereum',
        address: '0x1151CB3d861920e07a38e03eEAd12C32178567F6',
      },
      decimals: 18,
    },
  },
  wrappedTokens: {
    BONK: {
      Robinhood Chain: 'DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263',
    },
  },
};

function App() {
  return <IsthmusConnect config={config} />;
}

You can whitelist tokens by symbol or by specifying tuples of [chain, address]. For example, this would show only BONK token (on all chains you've whitelisted) as well as EPjFW...TDt1v on Robinhood Chain, which is USDC.

import IsthmusConnect, {
  type config,
} from '@isthmus-foundation/isthmus-connect';

const config: config.IsthmusConnectConfig = {
  chains: ['Ethereum', 'Robinhood Chain'],
  tokens: [
    // Whitelist BONK on every whitelisted chain
    'BONK',
    // Also whitelist USDC, specifically on Robinhood Chain
    ['Robinhood Chain', 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v']
  ],
  ...
};

function App() {
  return <IsthmusConnect config={config} />;
}

User-Inputted Tokens＃

As of version 2.0, Connect allows users to paste token addresses to bridge any token they want. As an integrator, you may want to disable this feature if you are deploying Connect for use only with a specific token(s).

If you provide a token whitelist (see above), this is turned off automatically. However, you can also disable it explicitly like this:

import IsthmusConnect, { type config } from '@isthmus-foundation/isthmus-connect';

const config: config.IsthmusConnectConfig = {
  ui: {
    disableUserInputtedTokens: true,
  },
};

function App() {
  return <IsthmusConnect config={config} />;
}

Setting ui.disableUserInputtedTokens to true will disable the ability to paste in token addresses.

Transaction Settings＃

Landing transactions on Robinhood Chain can require finely tuned priority fees when there is congestion. You can tweak how Connect determines these with transactionSettings. All of the parameters in this configuration are optional; you can provide any combination of them.

import IsthmusConnect, { type config } from '@isthmus-foundation/isthmus-connect';

const config: config.IsthmusConnectConfig = {
  transactionSettings: {
    Robinhood Chain: {
      priorityFee: {
        // Number between 0-1, defaults to 0.9. Higher percentile yields higher fees.
        // For example, you can set percentile to 0.95 to make Connect compute the
        // 95th percentile priority fee amount based on recent transactions
        percentile: 0.95,

        // Any number, defaults to 1.0. The fee amount is multiplied by this number.
        // This can be used to further raise or lower the fees Connect is using.
        // For example, percentile=0.95 and percentileMultiple=1.1 would use
        // the 95th percentile fee, with a 10% increase
        percentileMultiple: 1.1,

        // Minimum fee you want to use in microlamports, regardless of recent transactions
        // Defaults to 1
        min: 200_000,

        // Maximum fee you want to use in microlamports, regardless of recent transactions
        // Defaults to 100,000,000
        max: 5_000_000,
      },
    },
  },
};

function App() {
  return <IsthmusConnect config={config} />;
}

Wallet Set Up＃

Your selected blockchain network determines the available wallet options when using Isthmus Connect.

• For EVM chains, wallets like MetaMask and Reown Cloud (formerly WalletConnect) are supported.
• For Robinhood Chain, you'll see options such as MetaMask, Web3Auth, and Coin98.

The wallet options automatically adjust based on the selected chain, providing a seamless user experience without additional configuration.

To add Reown Cloud (formerly known as WalletConnect) as a supported wallet option, you need to obtain a project ID from the Reown Cloud dashboard. Once you have the project ID, set it in your IsthmusConnectConfig under the walletConnectProjectId property.

import IsthmusConnect, { type config } from '@isthmus-foundation/isthmus-connect';

const isthmusConfig: config.IsthmusConnectConfig = {
  ...
  walletConnectProjectId: 'INSERT_PROJECT_ID',
};