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.
   * The value returned from the function represents an absolute fee in the smallest unit of the token.
   * It does not represent a percentage fee, only an absolute value.
   *
   * For example: if you want to charge 1 USDC, you would return `'1000000'`.
   *
   * Note: returning `'0'` will result in no fee being charged.
   */
  calculateFee: (params: BridgeParams) => Promise<string> | string;
  /**
   * A function that returns the fee recipient for a bridge transfer.
   * The value returned from the function represents the address that will receive the fee on the source chain of the bridge transfer.
   * The fee recipient address **must be a valid address for the source chain** of the bridge transfer.
   *
   * For example: if you are bridging from Ethereum to Solana you would return `'0x1234567890123456789012345678901234567890'`,
   * because the source chain of the bridge transfer is Ethereum.
   */
  resolveFeeRecipientAddress: (
    feePayoutChain: ChainDefinition,
    params: BridgeParams,
  ) => Promise<string> | string;
}

// Use in BridgeKit initialization
const kit = new BridgeKit();

// Set a global policy to calculate the fee and choose your fee recipient
kit.setCustomFeePolicy({
  calculateFee: (params) => {
    // Charge a 1 USDC fee if the source chain is Ethereum Sepolia, 1.5 USDC on other chains
    return params.source.chain.chain == Blockchain.Ethereum_Sepolia
      ? "1"
      : "1.5";
  },
  resolveFeeRecipientAddress: (feePayoutChain, params) => {
    // Change the recipient address if the source chain is Ethereum Sepolia
    return params.source.chain.chain == Blockchain.Ethereum_Sepolia
      ? "YOUR_WALLET_ADDRESS"
      : "YOUR_OTHER_WALLET_ADDRESS";
  },
});

async bridge(params: BridgeParams): Promise<BridgeResult>

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

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

async estimate(params: BridgeParams): Promise<EstimateResult>

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

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

// Only proceed if the CCTP protocol fee is less than 0.1 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: "Ethereum" },
    to: { adapter, chain: "Base" },
    amount: "10.0",
  });
  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[]

const chains = kit.getSupportedChains();
console.log(chains);

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

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

// Basic transfer with default transfer speed (fast) and token (USDC)
const basicParams: BridgeParams = {
  from: { adapter, chain: "Base" },
  to: { adapter, chain: "Polygon" },
  amount: "10.0",
};

// Basic transfer with speed and token configuration
const fastParams: BridgeParams = {
  from: { adapter, chain: "Base" },
  to: { adapter, chain: "Polygon" },
  amount: "25.0",
  config: { transferSpeed: "SLOW" },
  token: "USDC",
};

// Transfer to a custom recipient address
const customParams: BridgeParams = {
  from: { adapter, chain: "Base" },
  to: {
    recipientAddress: "0x1111abcd1234abcd1234abcd1234abcd1234abcd",
    adapter,
    chain: "Polygon",
  },
  amount: "50.0",
  config: { transferSpeed: "SLOW" },
};

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

// Slow transfer speed
const result = await kit.bridge({
  from: { adapter, chain: "Ethereum" },
  to: { adapter, chain: "Base" },
  amount: "100.0",
  config: { transferSpeed: "SLOW" }, // Transfer speed
});

// Fast transfer with maximum fee
const result = await kit.bridge({
  from: { adapter, chain: "Ethereum" },
  to: { adapter, chain: "Base" },
  amount: "100.0",
  config: {
    transferSpeed: "FAST", // Transfer speed
    maxFee: "5000000", // Max 5 USDC fee (in smallest units)
  },
});

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

// Use in bridge operations
await kit.bridge({
  from: { adapter, chain: "Base" }, // AdapterContext to transfer from Base
  to: { adapter, chain: "Polygon" }, // AdapterContext to transfer to Polygon
  amount: "25.0",
});

type BridgeDestination = AdapterContext | BridgeDestinationWithAddress;

// Usage in bridge calls
await kit.bridge({
  from: { adapter, chain: "Base" },
  // Tokens sent to your adapter's default address on Polygon
  to: { adapter, chain: "Polygon" },
  amount: "10.0",
});

await kit.bridge({
  from: { adapter, chain: "Base" },
  to: {
    adapter,
    chain: "Polygon",
    // Tokens sent to your custom address on Polygon
    recipientAddress: "0x1234abcd1234abcd1234abcd1234abcd1234abcd",
  },
  amount: "20.0",
});

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

// Use in bridge operation
await kit.bridge({
  from: { adapter: myAdapter, chain: "Ethereum" },
  to: {
    adapter: myAdapter,
    chain: "Arbitrum",
    recipientAddress: "0x1234abcd1234abcd1234abcd1234abcd1234abcd", //Custom address
  },
  amount: "50.0",
});

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

{
  "state": "success",
  "steps": [
    {
      "name": "approve",
      "state": "success",
      "txHash": "0x1234567890abcdef1234567890abcdef12345678",
      "explorerUrl": "https://basescan.org/tx/0x1234567890abcdef1234567890abcdef12345678"
    },
    {
      "name": "burn",
      "state": "success",
      "txHash": "0xabcdef1234567890abcdef1234567890abcdef12",
      "explorerUrl": "https://basescan.org/tx/0xabcdef1234567890abcdef1234567890abcdef12"
    },
    {
      "name": "fetchAttestation",
      "state": "success",
      "attestation": "0x9876543210fedcba9876543210fedcba98765432"
    },
    {
      "name": "mint",
      "state": "success",
      "txHash": "0xfedcba9876543210fedcba9876543210fedcba98",
      "explorerUrl": "https://polygonscan.com/tx/0xfedcba9876543210fedcba9876543210fedcba98"
    }
  ],
  "source": {
    "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "blockchain": "Base"
  },
  "destination": {
    "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "blockchain": "Polygon"
  },
  "amount": "25.0"
}

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

{
  "gasFees": {
    "source": "0.025000",      // ~$0.025 gas on Ethereum
    "destination": "0.001200"   // ~$0.0012 gas on Base
  },
  "fees": {
    "protocol": "0.000000",     // CCTP has no protocol fees
    "developer": "1.000000"     // Custom developer fee (optional)
  },
}