Adapter Setups

Standard setup

The standard setup is the fastest way to start. Create one adapter from your wallet private key that works across multiple blockchains.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.

TypeScript

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

const adapter = createViemAdapterFromPrivateKey({
  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.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/app-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,
      }),
    });
  },
});

Browser wallet

You can create an adapter from browser wallet apps like MetaMask or Phantom:

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,
});

Standard setup

The standard setup is the fastest way to start. Create one adapter from your wallet private key that works across multiple blockchains.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.

TypeScript

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

const adapter = createEthersAdapterFromPrivateKey({
  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.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 { createEthersAdapterFromPrivateKey } from "@circle-fin/adapter-ethers-v6";
import { EthereumSepolia, ArcTestnet } from "@circle-fin/app-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);
  },
});

Browser wallet

You can create an adapter from browser wallet apps like MetaMask or Phantom:

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,
});

Standard setup

The standard setup is the fastest way to start. Create one adapter from your wallet private key that works across multiple blockchains.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.

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

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,
  });
}

server-side onlyYou can use the Circle Wallets adapter if you already manage wallets through Circle. Suited for enterprise and backend applications, it uses developer-controlled wallets and Circle Contracts so you can use App Kit on supported blockchains without managing private keys yourself.The Circle Wallets adapter requires these credentials from the Circle 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.

Get Started

Core Capabilities

Use Cases

Standard setup

Custom RPC

Browser wallet

Standard setup

Custom RPC

Browser wallet

Standard setup

Custom RPC

Browser wallet

Get Started

Core Capabilities

Use Cases

​Standard setup

​Custom RPC

​Browser wallet

​Standard setup

​Custom RPC

​Browser wallet

​Standard setup

​Custom RPC

​Browser wallet

Standard setup

Custom RPC

Browser wallet

Standard setup

Custom RPC

Browser wallet

Standard setup

Custom RPC

Browser wallet