Skip to content

Data

Data Configuration＃

This page explains how to configure Wormhole 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 Wormhole Connect by passing a WormholeConnectConfig object as the config prop.

import WormholeConnect, {
  WormholeConnectConfig,
} from '@wormhole-foundation/wormhole-connect';

const config: WormholeConnectConfig = {
  chains: ['Ethereum', 'Polygon', 'Solana'],
  tokens: ['ETH', 'WETH', 'MATIC', 'WMATIC'],
  rpcs: {
    Ethereum: 'https://rpc.ankr.com/eth',
    Solana: 'https://rpc.ankr.com/solana',
  }
}

<WormholeConnect config={config} />

import WormholeConnect, {
  wormholeConnectHosted,
  WormholeConnectConfig,
} from '@wormhole-foundation/wormhole-connect';

const config: WormholeConnectConfig = {
  chains: ['Ethereum', 'Polygon', 'Solana'],
  tokens: ['ETH', 'WETH', 'MATIC', 'WMATIC'],
  rpcs: {
    Ethereum: 'https://rpc.ankr.com/eth',
    Solana: 'https://rpc.ankr.com/solana',
  },
};

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

wormholeConnectHosted(container, {
  config,
});

Note

The complete type definition of WormholeConnectConfig is available in the Wormhole Connect repository.

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 WormholeConnect, {
  WormholeConnectConfig,
} from '@wormhole-foundation/wormhole-connect';

const config: WormholeConnectConfig = {
  chains: ['Ethereum', 'Polygon', 'Solana'],
  rpcs: {
    Ethereum: 'https://rpc.ankr.com/eth',
    Solana: 'https://rpc.ankr.com/solana',
  },
};

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

import WormholeConnect, {
  WormholeConnectConfig,
} from '@wormhole-foundation/wormhole-connect';

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

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

Note

For a complete list of available chain names, see the Wormhole TypeScript SDK.

Configuring Routes＃

By default, Connect offers two bridging protocols: Token Bridge (for Wormhole-wrapped tokens) 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 @wormhole-foundation/wormhole-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 Wormhole Token Bridge route
  • AutomaticTokenBridgeRoute - automatically redeemed (relayed) Token Bridge route
  • CCTPRoute - manually redeemed CCTP route
  • AutomaticCCTPRoute - automatically redeemed (relayed) CCTP route
  • DEFAULT_ROUTES - array containing the four preceding routes (TokenBridgeRoute, AutomaticTokenBridgeRoute, CCTPRoute, AutomaticCCTPRoute)
  • nttAutomaticRoute(nttConfig) - function that returns the automatically-redeemed (relayed) Native Token Transfer (NTT) route
  • nttManualRoute(nttConfig)- function that returns the manually-redeemed NTT route
  • nttRoutes(nttConfig) - function that returns both NTT routes as an array
  • 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 Wormhole transfer protocol

In addition to these routes, developers can create custom routes for their Wormhole-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 Wormhole TypeScript SDK route code.

Example: Offer Only CCTP Transfers＃

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

import WormholeConnect, {
  AutomaticCCTPRoute,
  WormholeConnectConfig,
} from '@wormhole-foundation/wormhole-connect';

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

<WormholeConnect config={config} />;

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

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

import WormholeConnect, {
  DEFAULT_ROUTES,
  nttRoutes,
  MayanRouteSWIFT,
  WormholeConnectConfig,
} from '@wormhole-foundation/wormhole-connect';

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

const config: WormholeConnectConfig = {
  routes: [...DEFAULT_ROUTES, ...nttRoutes(myNttConfig), MayanRouteSWIFT],
};

<WormholeConnect config={config} />;

This flexible plugin allows you to combine default routes (such as Token Bridge 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.

Note

You will need to register your token with the Token Bridge to get the contract addresses necessary for it to work with that protocol.

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

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

import WormholeConnect, {
  WormholeConnectConfig,
} from '@wormhole-foundation/wormhole-connect';

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

Whitelisting Tokens＃

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

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 SOL.

import WormholeConnect, {
  WormholeConnectConfig,
} from '@wormhole-foundation/wormhole-connect';

const config: WormholeConnectConfig = {
  chains: ['Ethereum', 'Solana'],
  tokens: ['ETH', 'SOL', 'BONK'],
  rpcs: {
    Ethereum: 'https://rpc.ankr.com/eth',
    Solana: 'https://rpc.ankr.com/solana',
  },
  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: {
      Solana: 'DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263',
    },
  },
};

function App() {
  return <WormholeConnect 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 Solana, which is USDC.

import WormholeConnect, {
  WormholeConnectConfig,
} from '@wormhole-foundation/wormhole-connect';

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

function App() {
  return <WormholeConnect 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 WormholeConnect, {
  WormholeConnectConfig,
} from '@wormhole-foundation/wormhole-connect';

const config: WormholeConnectConfig = {
  ui: {
    disableUserInputtedTokens: true
  }
};

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

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

Transaction Settings＃

Landing transactions on Solana 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 WormholeConnect, {
  WormholeConnectConfig,
} from '@wormhole-foundation/wormhole-connect';

const config: WormholeConnectConfig = {
  transactionSettings: {
    Solana: {
      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 <WormholeConnect config={config} />;
}

Note

Connect can calculate fees more accurately if you are using a Triton RPC endpoint.

Wallet Set Up＃

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

  • For EVM chains, wallets like MetaMask and Reown Cloud (formerly WalletConnect) are supported
  • For Solana, you'll see options such as Phantom, Torus, and Coin98

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

If you would like to offer Reown Cloud (formerly WalletConnect) as a supported wallet option, you'll need to obtain a project ID on the Reown Cloud dashboard.

CoinGecko API Key＃

The CoinGecko API can be used to fetch token price data. If you have a CoinGecko API Plan, you can include the API key in the configuration.

import WormholeConnect, {
  WormholeConnectConfig,
} from '@wormhole-foundation/wormhole-connect';

const config: WormholeConnectConfig = {
  coinGeckoApiKey: 'INSERT_API_KEY',
};

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