Adapter Setups

Bridge Kit supports these adapter types:

Chain client adapters abstract away the complexity of different blockchain architectures. Each adapter manages blockchain-specific bridging operations.
The Circle Wallet adapter is available if you already use Circle’s developer-controlled wallets. It uses your Circle Wallets account to let you transfer between supported blockchains.

Chain client adapter setups

Bridge Kit works with these client adapter libraries:

viem v2 for EVM-compatible blockchains
ethers v6 for EVM-compatible blockchains
solana for the Solana blockchain

You only need to set up with one EVM adapter, either Viem or Ethers. Add the Solana adapter to your setup only if you plan to transfer to or from Solana. The following table shows ways to set up chain client adapters and when to use each setup.

Setup method	Description	Use case
Standard	Standard setup that creates an adapter from a private wallet key. Uses default built-in public RPC endpoints and factory functions.	Testing environments that need a quick start without custom RPC configuration.
Custom RPC	Private key setup that lets you configure an RPC endpoint.	Production deployments that require reliable RPC providers.
Browser wallet	Uses an injected wallet provider, such as MetaMask or Phantom, to create an adapter in the browser.	Browser-based apps that rely on user wallet providers.

Standard setup

This setup is the fastest way to start. Create one adapter from your wallet private key to transfer tokens between EVM-compatible blockchains. Add the Solana adapter to transfer tokens to or from Solana. This setup uses public RPC endpoints and factory functions. For production, you should configure a custom RPC. Public connections have rate limits and might be slow. Select the tab to see code examples for your adapter choice.

Viem
Ethers
Solana

This code block initializes the Viem adapter to transfer tokens between EVM-compatible chains:

TypeScript

import { createViemAdapterFromPrivateKey } from "@circle-fin/adapter-viem-v2";

const adapter = createViemAdapterFromPrivateKey({
  privateKey: process.env.PRIVATE_KEY as string,
});

This code block initializes the Ethers adapter to transfer tokens between EVM-compatible chains:

TypeScript

import { createEthersAdapterFromPrivateKey } from "@circle-fin/adapter-ethers-v6";

const adapter = createEthersAdapterFromPrivateKey({
  privateKey: process.env.PRIVATE_KEY as string,
});

This code block initializes the Solana adapter to bridge on Solana:

TypeScript

import { createSolanaKitAdapterFromPrivateKey } from "@circle-fin/adapter-solana-kit";

// Solana accepts Base58, Base64, or JSON array format private keys
const adapter = createSolanaKitAdapterFromPrivateKey({
  privateKey: process.env.PRIVATE_KEY as string,
});

Custom RPC

You can replace the public RPC from the standard setup with your own connection. For production, you should use a paid service like Alchemy or QuickNode. These services are more reliable than free connections. The following code shows how to set up your own RPC. Pick your adapter to see the code.

Viem
Ethers
Solana

To use your own connection, replace the default one and add your custom RPC endpoints. Map each chain to its RPC endpoint so one adapter can work across multiple chains. This example uses Alchemy connections:

TypeScript

import { createViemAdapterFromPrivateKey } from "@circle-fin/adapter-viem-v2";
import { EthereumSepolia, ArcTestnet } from "@circle-fin/bridge-kit/chains";
import { createPublicClient, http } from "viem";

// Map RPC endpoints by chain name
const RPC_BY_CHAIN_NAME: Record<string, string> = {
  [EthereumSepolia.name]: `https://eth-sepolia.g.alchemy.com/v2/${process.env.ALCHEMY_KEY}`,
  [ArcTestnet.name]: `https://arc-testnet.g.alchemy.com/v2/${process.env.ALCHEMY_KEY}`,
};

// Create an adapter
const adapter = createViemAdapterFromPrivateKey({
  privateKey: process.env.PRIVATE_KEY as string,
  // Replace the default connection
  getPublicClient: ({ chain }) => {
    const rpcUrl = RPC_BY_CHAIN_NAME[chain.name];
    if (!rpcUrl) {
      throw new Error(`No RPC configured for chain: ${chain.name}`);
    }
    return createPublicClient({
      chain,
      transport: http(rpcUrl, {
        retryCount: 3,
        timeout: 10000,
      }),
    });
  },
});

TypeScript

import { createEthersAdapterFromPrivateKey } from "@circle-fin/adapter-ethers-v6";
import { EthereumSepolia, ArcTestnet } from "@circle-fin/bridge-kit/chains";
import { JsonRpcProvider } from "ethers";

// Map RPC endpoints by chain name
const RPC_BY_CHAIN_NAME: Record<string, string> = {
  [EthereumSepolia.name]: `https://eth-sepolia.g.alchemy.com/v2/${process.env.ALCHEMY_KEY}`,
  [ArcTestnet.name]: `https://arc-testnet.g.alchemy.com/v2/${process.env.ALCHEMY_KEY}`,
};

// Create an adapter
const adapter = createEthersAdapterFromPrivateKey({
  privateKey: process.env.PRIVATE_KEY as string,
  // Replace the default connection
  getProvider: ({ chain }) => {
    const rpcUrl = RPC_BY_CHAIN_NAME[chain.name];
    if (!rpcUrl) {
      throw new Error(`No RPC configured for chain: ${chain.name}`);
    }
    return new JsonRpcProvider(rpcUrl);
  },
});

To use your own connection, create a custom connection to your RPC endpoint. Point to that connection when making a Solana adapter. This example creates a custom connection using Alchemy:

TypeScript

import { createSolanaKitAdapterFromPrivateKey } from "@circle-fin/adapter-solana-kit";
import { createSolanaRpc } from "@solana/kit";

// Create an adapter
const adapter = createSolanaKitAdapterFromPrivateKey({
  privateKey: process.env.SOLANA_PRIVATE_KEY as string,
  // Replace the default connection
  getRpc: () =>
    // Use an Alchemy connection
    createSolanaRpc(
      `https://solana-devnet.g.alchemy.com/v2/${process.env.ALCHEMY_KEY}`,
    ),
});

Browser wallet

You can create an adapter from browser wallet apps like MetaMask or Phantom. The following code creates an adapter from a browser wallet. Pick your adapter to see the code.

Viem
Ethers
Solana

TypeScript

import { createViemAdapterFromProvider } from "@circle-fin/adapter-viem-v2";
import type { EIP1193Provider } from "viem";

declare global {
  interface Window {
    ethereum?: EIP1193Provider;
  }
}

// Check if wallet provider is available
if (!window.ethereum) {
  throw new Error("No wallet provider found");
}

const adapter = await createViemAdapterFromProvider({
  provider: window.ethereum,
});

TypeScript

import { createEthersAdapterFromProvider } from "@circle-fin/adapter-ethers-v6";
import type { Eip1193Provider } from "ethers";

declare global {
  interface Window {
    ethereum?: Eip1193Provider;
  }
}

// Check if wallet is installed
if (!window.ethereum) {
  throw new Error("No wallet provider found");
}

const adapter = await createEthersAdapterFromProvider({
  provider: window.ethereum,
});

TypeScript

import {
  createSolanaKitAdapterFromProvider,
  SolanaKitWalletProvider,
} from "@circle-fin/adapter-solana-kit";

declare global {
  interface Window {
    solana?: SolanaKitWalletProvider;
  }
}

if (window.solana) {
  const adapter = await createSolanaKitAdapterFromProvider({
    provider: window.solana,
  });
}

Circle Wallets adapter setup

server-side only You can use the Circle Wallets adapter if you already manage wallets through Circle. Suited for enterprise and backend applications, it uses Circle’s developer-controlled wallets and Circle Contracts so you can transfer between supported blockchains without managing private keys yourself. The Circle Wallets adapter requires these credentials from the Circle Developer Console:

API Key: Environment-prefixed (examples: TEST_API_KEY:abc123:def456, LIVE_API_KEY:xyz:uvw) or Base64-encoded.
Entity Secret: 64 lowercase alphanumeric characters.

This code block initializes the Circle Wallets adapter:

Typescript

import { createCircleWalletsAdapter } from "@circle-fin/adapter-circle-wallets";

// Initialize adapter with Circle credentials (server-side only)
const adapter = createCircleWalletsAdapter({
  apiKey: process.env.CIRCLE_API_KEY!, // Format: TEST_API_KEY:abc:def or Base64
  entitySecret: process.env.CIRCLE_ENTITY_SECRET!, // Format: 64 lowercase alphanumeric chars
});

The Circle Wallets adapter does not support gas sponsorship for crosschain transfers that originate on Solana. For those transactions, the user’s Solana wallet must hold sufficient SOL to pay network fees.

Bridge Kit

CCTP

Gateway

Chain client adapter setups

Standard setup

Custom RPC

Browser wallet

Circle Wallets adapter setup

Bridge Kit

CCTP

Gateway

​Chain client adapter setups

​Standard setup

​Custom RPC

​Browser wallet

​Circle Wallets adapter setup

Chain client adapter setups

Standard setup

Custom RPC

Browser wallet

Circle Wallets adapter setup