Appchains are for mature projects who are seeking scale through dedicated blockspace, full control over their infrastructure, or may be looking to utilize custom gas tokens.

After you’ve deployed an Appchain, offering your users a hassle-free way to move funds is key to a great user experience. If you are looking to launch an Appchain or learn more about Appchains broadly, refer to the Appchains FAQs page.

In this guide, you’ll walk you through integrating the [Bridge component] from OnchainKit into your app to facilitate easy fund transfers.

Make sure you’re running OnchainKit version >= 0.37.0 and have a basic understanding of Viem, JavaScript/TypeScript, and Tanstack before you begin.

​
Objectives

By the end of this tutorial you will be able to:

  1. Install and configure the required dependencies.
  2. Set up environment variables for OnchainKit.
  3. Configure a custom appchain using Viem’s defineChain function.
  4. Integrate a custom Wagmi configuration to support your new chain.
  5. Create a dedicated Bridge page for users to move funds seamlessly.

​
Prerequisites

Ensure you have the following:

  • OnchainKit (version >= 0.37.0)
  • Viem for chain definitions and interactions
  • JavaScript/TypeScript development environment
  • Tanstack for state management

​
Setup

​
Install Dependencies

Start by creating an OnchainKit sample app by running the following commands in your terminal:

# Create an OnchainKit app
mkdir bridge-component
cd bridge-component
npm create onchain

# Install necessary dependencies
npm i @tanstack/react-query dotenv viem

​
Configure Environment Variables

For your application to work, there are a few required environment variables that need to be set. To find them, navigate to the [Coinbase Developer Platform] site, select the API Keys tab, then click the Client API Key button.

With your client API key copied to your clipboard, create a .env file in your project root with the following content. Replace the placeholder for your API key as needed:

NEXT_PUBLIC_ONCHAINKIT_PROJECT_NAME=bridge-tutorial
NEXT_PUBLIC_ONCHAINKIT_API_KEY=
NEXT_PUBLIC_ONCHAINKIT_WALLET_CONFIG=smartWalletOnly

​
Configure Appchain details

Create a new file named Chain.ts in the app/ directory. In this new file, define your appchain using Viem’s defineChain function. In this example, you will configure the Blocklords Appchain:

import 'dotenv/config';
import { defineChain } from 'viem';

export const LordsChain = defineChain({
  id: 845320008,
  name: 'Blocklords',
  nativeCurrency: {
    name: 'Blocklords',
    symbol: 'LRDS',
    decimals: 18,
  },
  rpcUrls: {
    default: {
      http: ['https://blocklords-sepolia-rpc.l3.base.org'],
    },
  },
});

​
Extend Your Wagmi Configuration

To enable the OnchainKit Provider to communicate with both your Base chain and your Appchain, update your Wagmi configuration. Create a wagmi.ts file or modify your configuration file as shown below:

import { createConfig, createStorage, cookieStorage } from 'wagmi';
import { base } from 'viem/chains';
import { LordsChain } from './chain';
import { http } from 'viem';
import { coinbaseWallet } from 'wagmi/connectors';
export function getConfig() {
  return createConfig({
    chains: [base, LordsChain],
    connectors: [
      coinbaseWallet({
        appName: 'Appchain Bridge Tutorial',
        preference: 'smartWalletOnly',
      }),
    ],
    storage: createStorage({
      storage: cookieStorage,
    }),
    ssr: true,
    transports: {
      [base.id]: http(),
      [LordsChain.id]: http(),
    },
  });
}

declare module 'wagmi' {
  interface Register {
    config: ReturnType<typeof getConfig>;
  }
}

After creating your custom Wagmi configuration, be sure to import it into your OnchainKitProvider component (typically within your main provider file e.g. Providers.tsx).

This is a crucial step in enabling our OnchainKit Provider to communicate with both our Base chain and our Appchain.

​
Create the Bridge Component Page

Now, create a dedicated page to display the bridge component. For example, create a new folder named Bridge in your app/ directory and add a page.tsx file with the following content:

'use client';
import { LordsChain } from '../chain';
import {
  ConnectWallet,
  Wallet,
  WalletDropdown,
  WalletDropdownLink,
  WalletDropdownDisconnect,
} from '@coinbase/onchainkit/wallet';
import {
  Address,
  Avatar,
  Name,
  Identity,
  EthBalance,
} from '@coinbase/onchainkit/identity';
import {
  Appchain,
  BridgeableToken,
  AppchainBridge,
} from '@coinbase/onchainkit/appchain';
import { base } from 'viem/chains';

export default function Bridge() {
  const appchain: Appchain = {
    chain: LordsChain,
    icon: (
      <img
        src='https://img.cryptorank.io/coins/blocklords1670492311588.png'
        alt='LRDS'
      />
    ),
  };

  // Define bridgeable tokens (overrides default which is ETH)
  const bridgeableTokens: BridgeableToken[] = [
    {
      address: '0xB676f87A6E701f0DE8De5Ab91B56b66109766DB1',
      remoteToken: '0x4200000000000000000000000000000000000006',
      name: 'Blocklords',
      symbol: 'LRDS',
      decimals: 18,
      chainId: LordsChain.id,
      image: 'https://img.cryptorank.io/coins/blocklords1670492311588.png',
      isCustomGasToken: true, // This field is required for chains with custom gas tokens
    },
  ];

  return (
    <div className='flex flex-col min-h-screen font-sans dark:bg-background dark:text-white bg-white text-black'>
      <header className='pt-4 pr-4'>
        <div className='flex justify-end'>
          <div className='wallet-container'>
            <Wallet>
              <ConnectWallet>
                <Avatar className='h-6 w-6' />
                <Name />
              </ConnectWallet>
              <WalletDropdown>
                <Identity className='px-4 pt-3 pb-2' hasCopyAddressOnClick>
                  <Avatar />
                  <Name />
                  <Address />
                  <EthBalance />
                </Identity>
                <WalletDropdownLink
                  icon='wallet'
                  href='https://keys.coinbase.com'
                  target='_blank'
                  rel='noopener noreferrer'
                >
                  Wallet
                </WalletDropdownLink>
                <WalletDropdownDisconnect />
              </WalletDropdown>
            </Wallet>
          </div>
        </div>
      </header>

      <main className='flex-grow flex items-center justify-center'>
        <div className='max-w-xl w-full p-4'>
          <AppchainBridge
            chain={base}
            appchain={appchain}
            bridgeableTokens={bridgeableTokens}
          />
        </div>
      </main>
    </div>
  );
}

​
Running Locally

npm run dev

For reference, the final demo application is available on GitHub at https://github.com/hughescoin/ock-bridge-tutorial.git.

​
Conclusion

In this tutorial, you learned how to:

  • Set up the required dependencies and environment variables.
  • Configure your custom appchain using Viem.
  • Extend your Wagmi configuration to integrate both your Base chain and your Appchain.
  • Build a dedicated Bridge page to allow users to move funds seamlessly into your appchain.

For additional details or troubleshooting tips, refer to the [OnchainKit documentation] and explore further components.

Happy Building!

Bridge component Appchains FAQs Coinbase Developer Platform