Bridge Kit SDK Reference

constructor(config?: BridgeKitConfig)

// Standard setup
const kit = new BridgeKit();

// Setup with an additional provider
const provider = new MyCustomBridgingProvider();
const kit = new BridgeKit({ providers: [provider] });

interface BridgeKitConfig {
  /**
   * Add an array of bridging providers available for routing transfers.
   *
   * Each provider must implement the BridgingProvider interface and declare
   * which chains and tokens it supports. The kit will automatically select
   * the appropriate provider based on order and the transfer parameters.
   */
  providers?: BridgingProvider[];
}

export interface CustomFeePolicy {
  /**
   * A function that returns the fee to charge for the bridge transfer.
   * Return the fee in human-readable format (for example, '1' or '1.0' for 1 USDC).
   * The fee is added on top of the transfer amount.
   */
  computeFee: (params: BridgeParams) => Promise<string> | string;
  /**
   * A function that returns the fee recipient address on the source chain.
   * Must return a valid address for the source chain.
   */
  resolveFeeRecipientAddress: (
    feePayoutChain: ChainDefinition,
    params: BridgeParams,
  ) => Promise<string> | string;
}

const kit = new BridgeKit();

// Set a global custom fee policy
kit.setCustomFeePolicy({
  computeFee: (params) => {
    const amount = parseFloat(params.amount);
    // 1% fee, capped between 5-50 USDC
    const fee = Math.min(Math.max(amount * 0.01, 5), 50);
    return fee.toFixed(6);
  },
  resolveFeeRecipientAddress: (feePayoutChain) => {
    // Return appropriate address format based on chain type
    return feePayoutChain.type === "solana"
      ? "YOUR_SOLANA_ADDRESS" // Base58 format
      : "YOUR_EVM_ADDRESS"; // 0x format
  },
});

async bridge(params: BridgeParams): Promise

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

console.log("Transfer completed:", result.state);

async estimate(params: BridgeParams): Promise

// Estimate costs
const estimate = await kit.estimate({
  from: { adapter, chain: "Arc_Testnet" },
  to: { adapter, chain: "Base_Sepolia" },
  amount: "10.00",
});
console.log("Estimated fees:", estimate);

const cctpFee = estimate.fees.find((fee) => fee.type === "provider")?.amount;

// Only proceed if the CCTP protocol fee is less than 0.10 USDC
// Also proceed if the `cctpFee` variable is null/undefined since there is no protocol fee to charge
if (cctpFee == null || parseFloat(cctpFee) < 0.1) {
  // Execute the crosschain transfer
  const result = await kit.bridge({
    from: { adapter, chain: "Arc_Testnet" },
    to: { adapter, chain: "Base_Sepolia" },
    amount: "10.00",
  });
  console.log("Bridge completed:", result);
  // Error if the cost is over 5 USDC
} else {
  console.log("CCTP fee is above threshold:", cctpFee, "USDC");
}

getSupportedChains(): ChainDefinition[]

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

const kit = new BridgeKit();
const chains = kit.getSupportedChains();

// Use 'name' property to display in your UI
function showChainSelector(chains: ChainDefinition[]) {
  return chains.map((chain) => (
    <option value={chain.chain}>{chain.name}</option>
  ));
}

on(
  action: string,
  handler: (payload: AllActions) => void
): void

// Listen to specific events
kit.on("approve", (payload) => {
  console.log("Approval completed:", payload.values.txHash);
});
kit.on("mint", (payload) => {
  console.log("Mint completed:", payload.values.txHash);
});

// Listen to all events
kit.on("*", (event) => {
  console.log(`[${event.method}] Progress:`, event.values);
});

off(
  action: string,
  handler: (payload: AllActions) => void
): void

const mintHandler = (event) => console.log("Mint:", event.values.txHash);

// Register handler
kit.on("mint", mintHandler);

// Remove handler
kit.off("mint", mintHandler);

async retry(result: BridgeResult, context: RetryContext): Promise<BridgeResult>

// Assume we have a failed bridge result from a previous operation
const failedResult = await kit.bridge({
  from: { adapter, chain: "Arbitrum_Sepolia" },
  to: { adapter, chain: "Arc_Testnet" },
  amount: "100.00",
});

// If the bridge failed, retry it
if (failedResult.state === "error") {
  try {
    const retryResult = await kit.retry(failedResult, {
      from: adapter,
      to: adapter,
    });

    console.log("Retry completed:", retryResult.state);
  } catch (error) {
    console.error("Retry failed:", error);
  }
}

setCustomFeePolicy(customFeePolicy: CustomFeePolicy): void

removeCustomFeePolicy(): void

// Set a custom fee policy
kit.setCustomFeePolicy({
  computeFee: (params) => "1.0",
  resolveFeeRecipientAddress: () => "YOUR_WALLET_ADDRESS",
});

// Later, remove it
kit.removeCustomFeePolicy();

interface BridgeParams {
  from: AdapterContext;
  to: BridgeDestination;
  amount: string;
  config?: BridgeConfig;
  token?: "USDC";
}

interface BridgeConfig {
  transferSpeed?: "FAST" | "SLOW";
  maxFee?: string;
  customFee?: CustomFee | undefined;
}

interface CustomFee {
  value?: string;
  recipientAddress?: string;
}

// Transfer with a per-transfer custom fee
const result = await kit.bridge({
  from: { adapter, chain: "Arc_Testnet" },
  to: { adapter, chain: "Base_Sepolia" },
  amount: "100.00",
  config: {
    transferSpeed: "FAST",
    customFee: {
      value: "2.0",
      recipientAddress: "YOUR_FEE_RECIPIENT_ADDRESS", // Must match source chain format
    },
  },
});

type AdapterContext = {
  adapter: Adapter;
  chain: ChainIdentifier;
};

await kit.bridge({
  from: { adapter, chain: "Ethereum_Sepolia" }, // AdapterContext for Ethereum Sepolia
  to: { adapter, chain: "Arc_Testnet" }, // AdapterContext for Arc Testnet
  amount: "25.00",
});

type BridgeDestination = AdapterContext | BridgeDestinationWithAddress;

type BridgeDestinationWithAddress = AdapterContext & {
  recipientAddress: string;
};

await kit.bridge({
  from: { adapter: myAdapter, chain: "Base_Sepolia" },
  to: {
    adapter: myAdapter,
    chain: "Arc_Testnet",
    recipientAddress: "RECIPIENT_WALLET_ADDRESS", // Custom address on Arc Testnet
  },
  amount: "50.0",
});

interface RetryContext {
  from: Adapter;
  to: Adapter;
}

// Retry a failed bridge operation with fresh adapters
const retryResult = await kit.retry(failedResult, {
  from: sourceAdapter,
  to: destAdapter,
});

interface BridgeResult {
  amount: string;
  token: "USDC";
  state: "pending" | "success" | "error";
  config?: BridgeConfig;
  provider: string;
  source: {
    address: string;
    chain: ChainDefinition;
  };
  destination: {
    address: string;
    chain: ChainDefinition;
    recipientAddress?: string;
  };
  steps: BridgeStep[];
}

{
  "amount": "25.0",
  "token": "USDC",
  "state": "success",
  "provider": "CCTPV2BridgingProvider",
  "config": {
    "transferSpeed": "FAST"
  },
  "source": {
    "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "chain": {
      "type": "evm",
      "chain": "Arc_Testnet",
      "chainId": 421614,
      "name": "Arc Testnet"
      // ... nativeCurrency, explorerUrl, rpcEndpoints, usdcAddress, eurcAddress, cctp, etc.
    }
  },
  "destination": {
    "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "chain": {
      "type": "evm",
      "chain": "Base_Sepolia",
      "chainId": 84532,
      "name": "Base Sepolia"
      // ... additional ChainDefinition properties
    }
  },
  "steps": [
    {
      "name": "approve",
      "state": "success",
      "txHash": "0x1234567890abcdef1234567890abcdef12345678",
      "explorerUrl": "https://testnet.arcscan.io/tx/0x1234567890abcdef1234567890abcdef12345678"
    },
    {
      "name": "burn",
      "state": "success",
      "txHash": "0xabcdef1234567890abcdef1234567890abcdef12",
      "explorerUrl": "https://testnet.arcscan.io/tx/0xabcdef1234567890abcdef1234567890abcdef12"
    },
    {
      "name": "fetchAttestation",
      "state": "success",
      "data": {
        "attestation": "0x9876543210fedcba9876543210fedcba98765432"
      }
    },
    {
      "name": "mint",
      "state": "success",
      "txHash": "0xfedcba9876543210fedcba9876543210fedcba98",
      "explorerUrl": "https://sepolia.basescan.org/tx/0xfedcba9876543210fedcba9876543210fedcba98"
    }
  ]
}

interface BridgeStep {
  name: string;
  state: "pending" | "success" | "error" | "noop";
  txHash?: string;
  explorerUrl?: string;
  data?: unknown;
  errorMessage?: string;
  error?: unknown;
}

interface EstimateResult {
  token: "USDC";
  amount: string;
  source: {
    address: string;
    chain: Blockchain;
  };
  destination: {
    address: string;
    chain: Blockchain;
    recipientAddress?: string;
  };
  gasFees: {
    name: string;
    token: string;
    blockchain: Blockchain;
    fees: EstimatedGas | null;
    error?: unknown;
  }[];
  fees: {
    type: "kit" | "provider";
    token: "USDC";
    amount: string | null;
    error?: unknown;
  }[];
}

{
  "token": "USDC",
  "amount": "100.0",
  "source": {
    "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "chain": "Arc_Testnet"
  },
  "destination": {
    "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "chain": "Base_Sepolia"
  },
  "gasFees": [
    {
      "name": "Approve",
      "token": "Arc",
      "blockchain": "Arc_Testnet",
      "fees": {
        /* EstimatedGas object */
      }
    },
    {
      "name": "Burn",
      "token": "Arc",
      "blockchain": "Arc_Testnet",
      "fees": {
        /* EstimatedGas object */
      }
    },
    {
      "name": "Mint",
      "token": "ETH",
      "blockchain": "Base_Sepolia",
      "fees": {
        /* EstimatedGas object */
      }
    }
  ],
  "fees": [
    {
      "type": "provider",
      "token": "USDC",
      "amount": "0.01" // CCTP protocol fee (varies by route, 0-0.14 USDC for FAST)
    },
    {
      "type": "kit",
      "token": "USDC",
      "amount": "1.0" // Custom developer fee (optional)
    }
  ]
}

interface EstimatedGas {
  gas: bigint;
  gasPrice: bigint;
  fee: string;
}

class KitError extends Error {
  readonly code: number;
  readonly name: string;
  readonly type: ErrorType;
  readonly recoverability: Recoverability;
  readonly cause?: {
    trace?: unknown;
  };
}

import { KitError, isKitError } from "@circle-fin/bridge-kit";

try {
  await kit.bridge(params);
} catch (error) {
  if (isKitError(error)) {
    console.log(`Error ${error.code}: ${error.name}`);
    console.log(`Type: ${error.type}, Recoverability: ${error.recoverability}`);
    console.log(`Message: ${error.message}`);
  }
}

const InputError: {
  NETWORK_MISMATCH: {
    code: 1001;
    name: "INPUT_NETWORK_MISMATCH";
    type: "INPUT";
  };
  INVALID_AMOUNT: { code: 1002; name: "INPUT_INVALID_AMOUNT"; type: "INPUT" };
  UNSUPPORTED_ROUTE: {
    code: 1003;
    name: "INPUT_UNSUPPORTED_ROUTE";
    type: "INPUT";
  };
  INVALID_ADDRESS: { code: 1004; name: "INPUT_INVALID_ADDRESS"; type: "INPUT" };
  INVALID_CHAIN: { code: 1005; name: "INPUT_INVALID_CHAIN"; type: "INPUT" };
  VALIDATION_FAILED: {
    code: 1098;
    name: "INPUT_VALIDATION_FAILED";
    type: "INPUT";
  };
};

import { InputError, getErrorCode } from "@circle-fin/bridge-kit";

try {
  await kit.bridge(params);
} catch (error) {
  if (getErrorCode(error) === InputError.NETWORK_MISMATCH.code) {
    console.log("Cannot bridge between mainnet and testnet");
  }
}

const BalanceError: {
  INSUFFICIENT_TOKEN: {
    code: 9001;
    name: "BALANCE_INSUFFICIENT_TOKEN";
    type: "BALANCE";
  };
  INSUFFICIENT_GAS: {
    code: 9002;
    name: "BALANCE_INSUFFICIENT_GAS";
    type: "BALANCE";
  };
  INSUFFICIENT_ALLOWANCE: {
    code: 9003;
    name: "BALANCE_INSUFFICIENT_ALLOWANCE";
    type: "BALANCE";
  };
};

import { BalanceError, isBalanceError } from "@circle-fin/bridge-kit";

try {
  await kit.bridge(params);
} catch (error) {
  if (isBalanceError(error)) {
    console.log("Insufficient funds. Please add more tokens to your wallet.");
    showAddFundsUI();
  }
}

const OnchainError: {
  TRANSACTION_REVERTED: {
    code: 5001;
    name: "ONCHAIN_TRANSACTION_REVERTED";
    type: "ONCHAIN";
  };
  SIMULATION_FAILED: {
    code: 5002;
    name: "ONCHAIN_SIMULATION_FAILED";
    type: "ONCHAIN";
  };
  OUT_OF_GAS: { code: 5003; name: "ONCHAIN_OUT_OF_GAS"; type: "ONCHAIN" };
  GAS_LIMIT_EXCEEDED: {
    code: 5004;
    name: "ONCHAIN_GAS_LIMIT_EXCEEDED";
    type: "ONCHAIN";
  };
};

import { OnchainError, isOnchainError } from "@circle-fin/bridge-kit";

try {
  await kit.bridge(params);
} catch (error) {
  if (isOnchainError(error)) {
    console.log("Transaction failed on-chain:", error.message);
  }
}

const RpcError: {
  ENDPOINT_ERROR: { code: 4001; name: "RPC_ENDPOINT_ERROR"; type: "RPC" };
  INVALID_RESPONSE: { code: 4002; name: "RPC_INVALID_RESPONSE"; type: "RPC" };
  NONCE_ERROR: { code: 4003; name: "RPC_NONCE_ERROR"; type: "RPC" };
};

import { RpcError, isRpcError } from "@circle-fin/bridge-kit";

try {
  await kit.bridge(params);
} catch (error) {
  if (isRpcError(error)) {
    console.log("RPC provider issue. Retrying...");
    setTimeout(() => retryOperation(), 5000);
  }
}

const NetworkError: {
  CONNECTION_FAILED: {
    code: 3001;
    name: "NETWORK_CONNECTION_FAILED";
    type: "NETWORK";
  };
  TIMEOUT: { code: 3002; name: "NETWORK_TIMEOUT"; type: "NETWORK" };
};

import { NetworkError, isNetworkError } from "@circle-fin/bridge-kit";

try {
  await kit.bridge(params);
} catch (error) {
  if (isNetworkError(error)) {
    console.log("Network connection issue. Please check your internet.");
  }
}

function isKitError(error: unknown): error is KitError;

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

try {
  await kit.bridge(params);
} catch (error) {
  if (isKitError(error)) {
    console.log(`Structured error: ${error.name} (${error.code})`);
  } else {
    console.log("Regular error:", error);
  }
}

function isFatalError(error: unknown): boolean;

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

try {
  await kit.bridge(params);
} catch (error) {
  if (isFatalError(error)) {
    // Don't retry - show user-friendly error message
    showUserError(error.message);
  }
}

function isRetryableError(error: unknown): boolean;

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

try {
  await kit.bridge(params);
} catch (error) {
  if (isRetryableError(error)) {
    // Implement retry logic with exponential backoff
    setTimeout(() => retryOperation(), 5000);
  }
}

function isInputError(error: unknown): error is KitError;

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

try {
  await kit.bridge(params);
} catch (error) {
  if (isInputError(error)) {
    console.log("Validation error:", error.message);
    showValidationUI();
  }
}

function isBalanceError(error: unknown): error is KitError;

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

try {
  await kit.bridge(params);
} catch (error) {
  if (isBalanceError(error)) {
    console.log("Insufficient funds:", error.message);
    showAddFundsUI();
  }
}

function isOnchainError(error: unknown): error is KitError;

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

try {
  await kit.bridge(params);
} catch (error) {
  if (isOnchainError(error)) {
    console.log("Transaction failed:", error.message);
    showTransactionErrorUI();
  }
}

function isRpcError(error: unknown): error is KitError;

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

try {
  await kit.bridge(params);
} catch (error) {
  if (isRpcError(error)) {
    console.log("RPC error:", error.message);
    retryWithBackoff();
  }
}

function isNetworkError(error: unknown): error is KitError;

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

try {
  await kit.bridge(params);
} catch (error) {
  if (isNetworkError(error)) {
    console.log("Network issue:", error.message);
    retryWithBackoff();
  }
}

function getErrorMessage(error: unknown): string;

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

try {
  await riskyOperation();
} catch (error) {
  const message = getErrorMessage(error);
  console.log("Error occurred:", message);
  // Works with Error, KitError, string, or any other type
}

function getErrorCode(error: unknown): number | null;

import { getErrorCode, InputError } from "@circle-fin/bridge-kit";

try {
  await kit.bridge(params);
} catch (error) {
  const code = getErrorCode(error);
  if (code === InputError.NETWORK_MISMATCH.code) {
    showNetworkMismatchHelp();
  }
}