Configuration
Introduction#
Wormhole Connect is a flexible React widget that streamlines cross-chain asset transfers and enables seamless interoperability by leveraging Wormhole's powerful infrastructure. Designed for easy integration into decentralized applications (dApps), Wormhole Connect abstracts the complexities of cross-chain communication, providing a user-friendly experience for both developers and end users.
This guide provides detailed instructions on configuring Wormhole Connect and highlights the many ways it can be customized to fit your specific needs, from integrating supported blockchains and tokens to tailoring the user interface.
Note
To upgrade from Wormhole Connect v0 to v1, please refer to the migration guide for instructions.
If you're using an older version of Wormhole Connect (v0.x), please refer to the v0.x configuration documentation.
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. It is recommended that you 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 routeAutomaticTokenBridgeRoute
- automatically redeemed (relayed) Token Bridge routeCCTPRoute
- manually redeemed CCTP routeAutomaticCCTPRoute
- automatically redeemed (relayed) CCTP routeDEFAULT_ROUTES
- array containing the four preceding routes (TokenBridgeRoute
,AutomaticTokenBridgeRoute
,CCTPRoute
,AutomaticCCTPRoute
)nttAutomaticRoute(nttConfig)
- function that returns the automatically-redeemed (relayed) Native Token Transfer (NTT) routenttManualRoute(nttConfig)
- function that returns the manually-redeemed NTT routenttRoutes(nttConfig)
- function that returns both NTT routes as an arrayMayanRoute
- route that offers multiple Mayan protocolsMayanRouteSWIFT
- route for Mayan’s Swift protocol onlyMayanRouteMCTP
- route for Mayan’s MCTP protocol onlyMayanRouteWH
- 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 src/config/types.ts 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:
Using the tokens
property, you can customize the tokens shown in the UI. In the following example, we add a custom token and restrict Connect from displaying 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',
nativeChain: 'Ethereum',
icon: Icon.ETH,
tokenId: {
chain: 'Ethereum',
address: '0x1151CB3d861920e07a38e03eEAd12C32178567F6',
},
coinGeckoId: 'bonk',
decimals: 18,
},
},
wrappedTokens: {
BONK: {
Solana: 'DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263',
},
},
};
function App() {
return <WormholeConnect config={config} />;
}
Changing the Color Scheme#
You can customize Connect's color scheme by providing a theme
prop.
import WormholeConnect, {
WormholeConnectConfig,
WormholeConnectTheme,
} from '@wormhole-foundation/wormhole-connect';
const config: WormholeConnectConfig = {
/* Your config... */
};
const theme: WormholeConnectTheme = {
mode: 'dark',
primary: '#78c4b6',
font: 'Comic Sans; sans-serif',
};
function App() {
return <WormholeConnect config={config} theme={theme} />;
}
import WormholeConnect, {
WormholeConnectConfig,
WormholeConnectTheme,
wormholeConnectHosted,
} from '@wormhole-foundation/wormhole-connect';
const config: WormholeConnectConfig = {
/* Your config... */
};
const theme: WormholeConnectTheme = {
mode: 'dark',
primary: '#78c4b6',
font: 'Comic Sans; sans-serif',
};
const container = document.getElementById('bridge-container');
wormholeConnectHosted(container, {
config,
theme,
});
The WormholeConnectTheme
type supports the following properties:
Property |
Description | Example |
---|---|---|
mode |
Dark mode or light mode. Required | "dark" or "light" |
input |
Color used for input fields, dropdowns | "#AABBCC" |
primary |
Primary color used for buttons | "#AABBCC" |
secondary |
Secondary color used for some UI elements | "#AABBCC" |
text |
Primary color used for text | "#AABBCC" |
textSecondary |
Secondary color used for dimmer text | "#AABBCC" |
error |
Color to display errors in, usually some shade of red | "#AABBCC" |
success |
Color to display success messages in | "#AABBCC" |
badge |
Background color used for chain logos | "#AABBCC" |
font |
Font used in the UI, can be custom font available in your application | "Arial; sans-serif" |
More Configuration Options#
Wallet Set Up#
Your selected blockchain network determines the available wallet options when using Wormhole Connect.
- For EVM chains, wallets like MetaMask and 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 WalletConnect as a supported wallet option, you'll need to obtain a project ID on the WalletConnect cloud dashboard.
Toggle Hamburger Menu#
By setting the showHamburgerMenu
option to false, you can deactivate the hamburger menu, which will position the links at the bottom.
Add Extra Menu Entry#
By setting the showHamburgerMenu
option to false,
you can add extra links. The following properties are accessed through the menu[]
property (e.g., menu[].label
):
Property | Description |
---|---|
label |
Link name to show up |
href |
Target URL or URN |
target |
Anchor standard target, by default _blank |
order |
Order where the new item should be injected |
import WormholeConnect, {
WormholeConnectConfig,
} from '@wormhole-foundation/wormhole-connect';
const config: WormholeConnectConfig = {
ui: {
showHamburgerMenu: false,
menu: [
{
label: 'Advance Tools',
href: 'https://portalbridge.com',
target: '_self',
order: 1,
},
],
},
};
function App() {
return <WormholeConnect config={config} />;
}
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} />;
}