circlefin/skills/bridge-tokens

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

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
• Using a Solana browser wallet (Wallet Standard provider such as Phantom, Solflare, or Backpack) -> Use the Solana provider adapter. READ references/adapter-browser-wallet.md

Question 3 -- Which chains are you bridging between?

• EVM-to-EVM or EVM-to-Solana -> Use Viem and/or Solana Kit adapters. READ references/adapter-private-key.md

Token Choice

Question 4 -- Which token are you bridging?

• USDC -> any CCTP route (EVM or Solana).
• wETH, cirBTC, EURC, or a CCTPx token ID -> EVM-to-EVM only. READ references/non-usdc-cctpx.md. If the destination is Solana or the registry does not list the route, stop and offer swap-tokens; do not substitute a different chain pair.

Workflow

1. Walk the Decision Guide -- settle the SDK (App Kit vs Bridge Kit) and the wallet/adapter with the user before writing any code.
2. Install and initialize -- install the chosen kit plus adapter, then construct the kit and adapter (see Prerequisites / Setup).
3. Confirm the transfer -- token, amount, source and destination chains, and recipient. Validate chain names and addresses. Default to testnet; require explicit confirmation before mainnet.
4. For CCTPx tokens, quote first -- confirm that the registry supports the selected EVM route, settle FAST vs SLOW with the user, call kit.estimateBridge() (App Kit) or kit.estimate() (Bridge Kit), and surface the quoted fee before executing. Quote reuse is best-effort: surface a QUOTE_NOT_REUSED warning on the result.
5. Execute the bridge -- call kit.bridge({ token, from, to, amount, ... }), only from an explicit user action (never auto-invoke). READ the adapter reference for the exact code.
6. Track and recover -- inspect result.state / result.steps, subscribe with kit.on(), and on a soft failure resume with kit.retryBridge(result, ...) (App Kit) or kit.retry(result, ...) (Bridge Kit) -- never re-run kit.bridge() from scratch.

Core Concepts

• CCTP steps (USDC): Every USDC bridge transfer executes four sequential steps -- approve (ERC-20 allowance), burn (destroy USDC on source chain), fetchAttestation (wait for Circle to sign the burn proof), and mint (create USDC on destination chain).
• CCTPx transfers: the same kit.bridge({ token, from, to, amount }) call; pass a registry alias or token ID directly as token. The steps are approve -> transfer -> fetchAttestation -> forward, with an approveFee step before transfer only when the fee is an ERC-20 (Circle's relayer mints on the destination automatically -- no destination gas or useForwarder toggle needed). Every CCTPx transfer pays a relayer fee in the source chain's native token; FAST (default) adds a pre-finality fee, while SLOW waits for source-chain finality and skips it. Call kit.estimateBridge() (App Kit) or kit.estimate() (Bridge Kit) first and surface the quoted fee to the user before bridging; the bridge call stays behind the user's explicit confirm action. Check result.state === "success" for completion. CCTPx routes reject custom fees, feePayment: "destination", and useForwarder: false.
• Adapters: Both App Kit and Bridge Kit use adapter objects to abstract wallet/signer differences. Each ecosystem has its own adapter factory (createViemAdapterFromPrivateKey, createSolanaKitAdapterFromPrivateKey, createCircleWalletsAdapter). The same adapter instance can serve as both source and destination when bridging within the same ecosystem.
• Forwarding Service: When useForwarder: true is set on the destination, Circle's infrastructure handles attestation fetching and mint submission. This removes the need for a destination wallet or polling loop. There is a per-transfer fee that varies by route (see below).
• Transfer speed: CCTP fast mode (default) completes in ~8-20 seconds. Standard mode takes ~15-19 minutes.
• Chain identifiers: Both SDKs use string chain names (e.g., "Arc", "Arc_Testnet", "Base_Sepolia", "Solana_Devnet"), not numeric chain IDs, in the kit.bridge() call.
• Browser-safe packages: Current App Kit, Bridge Kit, and Solana adapters ship the required browser compatibility internally. Browser requests omit Node-only headers, and Solana operations need no consumer Buffer shim. Upgrade stale packages instead of adding polyfills.

Implementation Patterns

READ the corresponding reference based on the user's request:

• references/adapter-private-key.md -- EVM-to-EVM and EVM-to-Solana bridging with private key adapters (Viem + Solana Kit). Includes App Kit and Bridge Kit examples.
• references/adapter-circle-wallets.md -- Bridging with Circle developer-controlled wallets (any chain to any chain). Includes App Kit and Bridge Kit examples.
• references/adapter-wagmi.md -- Browser wallet integration using wagmi (ConnectKit, RainbowKit, etc.). Includes App Kit and Bridge Kit examples.
• references/adapter-browser-wallet.md -- Solana browser wallet integration using a Wallet Standard provider, with no manual polyfills
• references/non-usdc-cctpx.md -- bridging CCTPx registry aliases and token IDs on supported EVM routes: route validation, quote-then-confirm flow, and FAST/SLOW transfer speed

Sample Response from kit.bridge()

{
  "amount": "25.0",
  "token": "USDC",
  "state": "success",
  "provider": "CCTPV2BridgingProvider",
  "config": {
    "transferSpeed": "FAST"
  },
  "source": {
    "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "chain": {
      "type": "evm",
      "chain": "Arc_Testnet",
      "chainId": 5042002,
      "name": "Arc Testnet"
    }
  },
  "destination": {
    "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "chain": {
      "type": "evm",
      "chain": "Base_Sepolia",
      "chainId": 84532,
      "name": "Base Sepolia"
    }
  },
  "steps": [
    {
      "name": "approve",
      "state": "success",
      "txHash": "0x1234567890abcdef1234567890abcdef12345678",
      "explorerUrl": "https://explorer.testnet.arc.io/tx/0x1234..."
    },
    {
      "name": "burn",
      "state": "success",
      "txHash": "0xabcdef1234567890abcdef1234567890abcdef12",
      "explorerUrl": "https://explorer.testnet.arc.io/tx/0xabcdef..."
    },
    {
      "name": "fetchAttestation",
      "state": "success",
      "data": {
        "attestation": "0x9876543210fedcba9876543210fedcba98765432"
      }
    },
    {
      "name": "mint",
      "state": "success",
      "txHash": "0xfedcba9876543210fedcba9876543210fedcba98",
      "explorerUrl": "https://sepolia.basescan.org/tx/0xfedcba..."
    }
  ]
}

Forwarding Service, events, and recovery