/bridge-tokens

name: bridge-tokens
description: "Build browser or server token bridging across chains with Circle App Kit or standalone Bridge Kit. Bridges USDC across CCTP chains (EVM and Solana) and CCTPx tokens on supported EVM routes, including registry aliases such as wETH, cirBTC, and EURC plus registry-listed token IDs, through the same `kit.bridge()` call. Supports browser wallets, private-key and Circle Wallets adapters, bridge events, transfer speed (FAST/SLOW), Forwarding Service, and recovery. Bridge operations require no kit key. Use when: bridge a token across chains, bridge USDC, bridge a CCTPx token alias or token ID, move tokens between chains, build wallet-connected bridge UIs, configure Viem/Ethers/Solana adapters, or use @circle-fin/bridge-kit, @circle-fin/app-kit, CCTP, CCTPx, forwarding, or bridge routes."
requirements:
  runtimes: []
  connectors: []

Overview

This skill bridges tokens across chains with Circle's App Kit or Bridge Kit. **USDC** moves over Crosschain Transfer Protocol (CCTP) -- burn on the source chain, mint on the destination. **CCTPx tokens** use a registry alias (such as wETH, cirBTC, or EURC) or a registry-listed token ID. Both run through the **same `kit.bridge()` call** -- pass the alias or token ID directly as `token` and the SDK routes it automatically; there is no protocol to choose. App Kit (`@circle-fin/app-kit`) is Circle's all-inclusive SDK covering bridge, swap, and send in one package; standalone Bridge Kit (`@circle-fin/bridge-kit`) ships the same bridge API in a lighter package. **Recommend App Kit** unless the user wants bridge-only functionality. **Bridge operations need no kit key.**

Both SDKs run in browser and server applications. Use browser wallet provider adapters in client code and keep private keys plus Circle Wallets credentials on the server. App Kit `>=1.11.0` and Bridge Kit `>=1.12.2` bundle for browsers without consumer-provided Node or `Buffer` polyfills. CCTPx tokens require App Kit or Bridge Kit `>=1.15.0`; browser apps bridging CCTPx tokens need App Kit `>=1.15.2` or Bridge Kit `>=1.15.1`.

Supported tokens & routes

Pass a registry alias or token ID directly as `token` in `kit.bridge()` and `kit.estimateBridge()` (App Kit) / `kit.estimate()` (Bridge Kit); do not wrap it in a provider-selector object. The SDK routes it to the correct protocol automatically. Only USDC supports Solana; every CCTPx route is EVM-to-EVM. Aliases are case-sensitive (`"wETH"`, not `"WETH"`), and a token ID is a bytes32 hex string (`0x` followed by 64 hex characters).

| Token selector | Supported chains | |---|---| | `USDC` | All CCTP-supported chains (EVM + Solana) -- see [supported chains](https://developers.circle.com/cctp) | | `EURC` | Ethereum, Base, and Arc on mainnet, plus eligible testnet routes | | `wETH` | Ethereum <-> Arc on mainnet, plus eligible testnet routes | | `cirBTC` | Ethereum <-> Arc on mainnet, plus eligible testnet routes | | Registry-listed token ID | Any EVM route where the CCTPx registry lists that token on both endpoint domains |

CCTPx-enabled EVM chains are Ethereum, Arc, Base, Arbitrum, Optimism, Polygon, and Avalanche. A chain being CCTPx-enabled does not make every token routable to every other chain. The SDK fetches the CCTPx token registry from Circle at runtime and throws `INPUT_UNSUPPORTED_ROUTE` when the selected token is not listed on both endpoints -- do not hardcode route lists.

Prerequisites / Setup

Installation

Pick **one** base kit — App Kit (recommended) or the standalone Bridge Kit — then add adapters as needed.

App Kit with Viem adapter (recommended):

npm install @circle-fin/app-kit @circle-fin/adapter-viem-v2
# Optional: Solana support
npm install @circle-fin/adapter-solana-kit
# Optional: Circle Wallets (developer-controlled) support
npm install @circle-fin/adapter-circle-wallets

Or, for bridge-only apps, the standalone Bridge Kit (lighter package) instead of App Kit:

npm install @circle-fin/bridge-kit @circle-fin/adapter-viem-v2

Environment Variables

PRIVATE_KEY=              # EVM wallet private key (hex, 0x-prefixed)
EVM_PRIVATE_KEY=          # EVM private key (when also using Solana)
SOLANA_PRIVATE_KEY=       # Solana wallet private key (base58)
CIRCLE_API_KEY=           # Circle API key (for Circle Wallets adapter)
CIRCLE_ENTITY_SECRET=     # Entity secret (for Circle Wallets adapter)
EVM_WALLET_ADDRESS=       # Developer-controlled EVM wallet address
SOLANA_WALLET_ADDRESS=    # Developer-controlled Solana wallet address

No `KIT_KEY` is needed for bridge operations. Browser-wallet integrations need none of the variables above. Never expose a private key, Circle API key, entity secret, or optional App Kit credential to client code.

SDK Initialization

**App Kit** (recommended):

import { AppKit } from "@circle-fin/app-kit";

const kit = new AppKit();

**Bridge Kit** (standalone):

import { BridgeKit } from "@circle-fin/bridge-kit";

const kit = new BridgeKit();

Decision Guide

ALWAYS walk through these questions with the user before writing any code. Do not skip steps or assume answers.

SDK Choice

**Question 1 -- Will you need swap or send functionality in the future?**

• Yes, or unsure -> **App Kit** (recommended) -- single SDK covers bridge + swap + send, easier to extend later
• No, bridge-only and will never need swap or send -> **Bridge Kit** -- standalone, lighter package for bridge-only use cases

Wallet / Adapter Choice

**Question 2 -- How do you manage your wallet/keys?**

• Managing your own private key (self-custodied, stored in env var or secrets manager) -> Question 3
• Using Circle developer-controlled wallets (Circle manages key storage and signing) -> Use Circle Wallets adapter. READ `references/adapter-circle-wallets.md`
• Using an EVM browser wallet (wagmi, ConnectKit, RainbowKit, or any EIP-1193 provider) -> Use the Viem provider adapter. READ `references/adapter-wagmi.md`
• U