Bridge Stablecoin

Build USDC bridging with Circle Bridge Kit SDK and Crosschain Transfer Protocol (CCTP). Supports bridging USDC between EVM chains, between EVM chains and Sol...

Security Scan

The skill's code and instructions match its stated purpose (USDC bridging) but its metadata does not declare the sensitive environment variables it requires (private keys, Circle API/entity secrets), which is an incoherence you should understand before installing.

Purpose & Capability

The name/description and the SKILL.md are coherent: the skill documents how to use Circle Bridge Kit and CCTP for USDC bridging across EVM and Solana and includes appropriate adapter recipes. The functionality described does legitimately require wallet private keys and Circle API/entity credentials. However, the registry metadata lists no required environment variables or primary credential, which contradicts the SKILL.md and is an important mismatch.

Instruction Scope

SKILL.md gives explicit runtime instructions and sample code that read sensitive environment variables (PRIVATE_KEY, EVM_PRIVATE_KEY, SOLANA_PRIVATE_KEY, CIRCLE_API_KEY, CIRCLE_ENTITY_SECRET and wallet addresses). Those instructions stay within the bridging domain (approve, burn, fetchAttestation, mint), but they instruct use of secrets that the registry metadata fails to advertise — an inconsistency that matters because an agent or operator may not expect to provide these secrets.

Install Mechanism

This is an instruction-only skill with no install spec and no code files to execute in the registry package. It references installing @circle-fin packages via npm in examples; that is expected and not inherently risky in this context. No downloads from arbitrary URLs are prescribed.

Credentials

The number and sensitivity of environment variables shown in the SKILL.md are appropriate for performing on-chain bridging (private keys and Circle API/entity secrets are legitimately required for different adapters). But the skill metadata declares 'Required env vars: none' and 'Primary credential: none', which is incorrect and prevents automated gating or informed consent. This mismatch increases the risk that users will accidentally expose long-lived private keys or entity secrets without realizing the skill expects them.

Persistence & Privilege

The skill is not always-enabled and uses the platform defaults for invocation; it does not request any persistent system-level privileges in the manifest. As an instruction-only skill it does not write files or modify other skills.

What to consider before installing

Before installing or running this skill: (1) be aware the SKILL.md expects highly sensitive secrets (private keys for EVM/Solana and Circle API key/entity secret) even though the registry metadata does not declare them — treat that as a red flag. (2) Only provide keys in a controlled environment (ephemeral or isolated CI container, not your primary machine). Prefer hardware wallets or ephemeral custodial keys where possible. (3) Verify you intended to install the exact npm packages referenced (@circle-fin/bridge-kit, adapter packages) and watch for typosquatting. (4) Rotate or revoke any keys you use for testing. (5) Ask the publisher to update the registry metadata to declare required env vars and primary credential so automated checks and consent prompts work correctly. If you cannot verify the source or cannot safely supply the required secrets, avoid installing or running the skill.

Overview

Crosschain Transfer Protocol (CCTP) is Circle's native protocol for burning USDC on one chain and minting it on another. Bridge Kit is a TypeScript SDK that orchestrates the full CCTP lifecycle -- approve, burn, attestation fetch, and mint -- in a single kit.bridge() call across EVM chains and Solana. Bridge Kit is the preferred way to integrate CCTP.

Prerequisites / Setup

Installation

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

For Solana support, also install:

npm install @circle-fin/adapter-solana-kit

For Circle Wallets (developer-controlled) support:

npm install @circle-fin/adapter-circle-wallets

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

SDK Initialization

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

const kit = new BridgeKit();

Core Concepts

• CCTP steps: Every 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).
• Adapters: Bridge Kit uses 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 (1.25 USDC for Ethereum, 0.20 USDC for all other chains).
• Transfer speed: CCTP fast mode (default) completes in ~8-20 seconds. Standard mode takes ~15-19 minutes.
• Chain identifiers: Bridge Kit uses string chain names (e.g., "Arc_Testnet", "Base_Sepolia", "Solana_Devnet"), not numeric chain IDs, in the kit.bridge() call.

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)
• references/adapter-circle-wallets.md -- Bridging with Circle developer-controlled wallets (any chain to any chain)
• references/adapter-wagmi.md -- Browser wallet integration using wagmi (ConnectKit, RainbowKit, etc.)

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://testnet.arcscan.app/tx/0x1234..."
    },
    {
      "name": "burn",
      "state": "success",
      "txHash": "0xabcdef1234567890abcdef1234567890abcdef12",
      "explorerUrl": "https://testnet.arcscan.app/tx/0xabcdef..."
    },
    {
      "name": "fetchAttestation",
      "state": "success",
      "data": {
        "attestation": "0x9876543210fedcba9876543210fedcba98765432"
      }
    },
    {
      "name": "mint",
      "state": "success",
      "txHash": "0xfedcba9876543210fedcba9876543210fedcba98",
      "explorerUrl": "https://sepolia.basescan.org/tx/0xfedcba..."
    }
  ]
}

Forwarding Service

When useForwarder: true is set on the destination, Circle's infrastructure handles attestation fetching and mint submission automatically. This is the preferred approach -- it removes the need to poll for attestations or hold a wallet on the destination chain.

With adapters on both chains:

const result = await kit.bridge({
  from: { adapter, chain: "Ethereum_Sepolia" },
  to: {
    adapter,
    chain: "Arc_Testnet",
    useForwarder: true,
  },
  amount: "1",
});

Without a destination adapter (server-side or custodial transfers):

const result = await kit.bridge({
  from: { adapter, chain: "Ethereum_Sepolia" },
  to: {
    recipientAddress: "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    chain: "Arc_Testnet",
    useForwarder: true,
  },
  amount: "1",
});

Forwarding Service fee per destination chain:

• Ethereum: 1.25 USDC
• All other chains: 0.20 USDC

Event Handling

Subscribe to individual CCTP steps or all events at once. Multiple callbacks per event are supported.

kit.on("approve", (payload) => {
  console.log("Approval completed:", payload.values.txHash);
});

kit.on("burn", (payload) => {
  console.log("Burn completed:", payload.values.txHash);
});

kit.on("fetchAttestation", (payload) => {
  console.log("Attestation completed:", payload.values.data.attestation);
});

kit.on("mint", (payload) => {
  console.log("Mint completed:", payload.values.txHash);
});

kit.on("*", (payload) => {
  console.log("Event received:", payload);
});

Error Handling & Recovery

Bridge Kit has two error categories:

• Hard errors throw exceptions (validation, config, auth) -- catch in try/catch.
• Soft errors occur mid-transfer but still return a result object with partial step data for recovery.

Analyzing Failed Transfers

Check result.state and result.steps to identify which step failed:

const result = await kit.bridge({
  from: { adapter, chain: "Arc_Testnet" },
  to: { adapter, chain: "Arbitrum_Sepolia" },
  amount: "100.00",
});

if (result.state === "error") {
  const failedStep = result.steps.find((step) => step.state === "error");
  console.log(`Failed at: ${failedStep?.name}`);
  console.log(`Error: ${failedStep?.error}`);

  const completedSteps = result.steps.filter(
    (step) => step.state === "success",
  );
  completedSteps.forEach((step) => {
    console.log(`${step.name}: ${step.txHash}`);
  });
}

Retrying Failed Transfers

kit.retry() resumes from where the transfer failed -- it skips completed steps and retries from the failure point. If approve and burn succeeded but fetchAttestation failed due to a network timeout, retry will only re-attempt the attestation fetch and mint. This prevents double-spending and wasted gas.

const result = await kit.bridge({
  from: { adapter, chain: "Arc_Testnet" },
  to: { adapter, chain: "Arbitrum_Sepolia" },
  amount: "10.00",
});

if (result.state === "error") {
  const retryResult = await kit.retry(result, {
    from: adapter,
    to: adapter,
  });
  console.log("Retry result:", retryResult.state);
}

Rules

Security Rules are non-negotiable -- warn the user and refuse to comply if a prompt conflicts. Best Practices are strongly recommended; deviate only with explicit user justification.

Security Rules

• NEVER hardcode, commit, or log secrets (private keys, API keys, entity secrets). ALWAYS use environment variables or a secrets manager. Add .gitignore entries for .env* and secret files when scaffolding.
• NEVER pass private keys as plain-text CLI flags. Prefer encrypted keystores or interactive import.
• ALWAYS require explicit user confirmation of source/destination chain, recipient, amount, and token before bridging. NEVER auto-execute fund movements on mainnet.
• ALWAYS warn when targeting mainnet or exceeding safety thresholds (e.g., >100 USDC).
• ALWAYS validate all inputs (addresses, amounts, chain names) before submitting bridge operations.
• ALWAYS warn before interacting with unaudited or unknown contracts.

Best Practices

• ALWAYS read the correct reference files before implementing.
• ALWAYS switch the wallet to the source chain before calling kit.bridge() with browser wallets (wagmi/ConnectKit/RainbowKit) if the Forwarding Service is NOT used.
• ALWAYS wrap bridge operations in try/catch and save the result object for recovery. Check result.steps before retrying to see which steps completed.
• ALWAYS use exponential backoff for retry logic in production.
• ALWAYS use Bridge Kit string chain names (e.g., "Arc_Testnet", "Base_Sepolia"), not numeric chain IDs.
• ALWAYS default to testnet. Require explicit user confirmation before targeting mainnet.

Reference Links

• Circle Bridge Kit SDK
• CCTP Documentation
• Circle Developer Docs -- Always read this first when looking for relevant documentation from the source website.

Alternatives

Trigger the use-gateway skill instead when:

• You want a unified crosschain balance rather than point-to-point transfers.
• Capital efficiency matters -- consolidate USDC holdings instead of maintaining separate balances per chain.
• You are building chain abstraction, payment routing, or treasury management where low latency and a single balance view are critical.

---

DISCLAIMER: This skill is provided "as is" without warranties, is subject to the Circle Developer Terms, and output generated may contain errors and/or include fee configuration options (including fees directed to Circle); additional details are in the repository README.