App Kit SDK Reference

This reference guide describes the public interfaces, methods, and types available in the App Kit SDK.

AppKit Class

The AppKit is how you’ll perform all stablecoin operations including crosschain bridging, same-chain swaps, token transfers, and fee estimation. It also enables you to add event listeners for bridge transfers.

constructor(config?)

Creates a new AppKit instance.

constructor(config?: AppKitConfig)

Parameters

Name	Type	Description
config	`AppKitConfig`	Optional configuration for fee estimation, developer fees, and the underlying UnifiedBalanceKit.

Usage

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

// Minimal — all defaults
const kit = new AppKit();

// With unified balance config
const kitWithUb = new AppKit({
  unifiedBalance: { providers: [myCustomProvider] },
});

AppKitConfig

type AppKitConfig = CreateContextParams & {
  developerFee?: Partial<DeveloperFeeHooks>;
  disableErrorReporting?: boolean;
  unifiedBalance?: UnifiedBalanceKitConfig;
};

Properties

Name	Type	Description
developerFee	`Partial<DeveloperFeeHooks>`	Optional developer fee hooks passed through to BridgeKit when both are provided
disableErrorReporting	boolean	Disable error telemetry for all underlying kits. When `true`, BridgeKit, SwapKit, and UnifiedBalanceKit will not POST error details to the telemetry endpoint. Defaults to `false`.
unifiedBalance	UnifiedBalanceKitConfig	Optional config forwarded to the underlying UnifiedBalanceKit.

Methods

bridge(params)

Execute a crosschain USDC bridge transfer. Transfers USDC between different blockchain networks using Circle’s Cross-Chain Transfer Protocol (CCTP). Supports both fast and standard transfer speeds with automatic attestation handling.

bridge(params: BridgeParams): Promise<BridgeResult>

Parameters

Name	Type	Description
params	`BridgeParams`	Bridge parameters containing source, destination, amount, and token

BridgeParams

Parameters for initiating a crosschain USDC bridge transfer. This type is used as the primary input to BridgeKit.bridge, allowing users to specify the source and destination adapters, transfer amount, and optional configuration.

The from field specifies the source adapter context (wallet and chain).
The to field specifies the destination, supporting both explicit and derived recipient addresses.
The config field allows customization of bridge behavior (e.g., transfer speed).
The token field is optional and defaults to USDC; other tokens are not currently supported.

interface BridgeParams {
  amount: string;
  config?: BridgeConfig;
  from: AdapterContext<TFromAdapterCapabilities, BridgeChainIdentifier>;
  invocationMeta?: InvocationMeta;
  to: BridgeDestination<TToAdapterCapabilities, BridgeChainIdentifier>;
  token?: "USDC";
}

Properties

Name	Type	Description
amount	string	The amount to transfer
config	BridgeConfig	Optional bridge configuration (e.g., transfer speed). If omitted, defaults will be used
from	`AdapterContext`	The source adapter context (wallet and chain) for the transfer.
invocationMeta	InvocationMeta	Optional invocation metadata for tracing and correlation. When provided, the `traceId` is used to correlate all events emitted during the bridge operation. If not provided, an OpenTelemetry-compatible `traceId` will be auto-generated.
to	`BridgeDestination`	The destination for the transfer, supporting explicit or derived recipient addresses
token	`'USDC'`	The token to transfer. Defaults to `USDC`. If omitted, the provider will use `USDC` by default.

Returns Promise<BridgeResult>

BridgeResult

Result object returned after a successful crosschain bridge operation. This interface contains all the details about a completed bridge, including the bridge parameters, source and destination information, and the sequence of steps that were executed.

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

Properties

Name	Type	Description
amount	string	The amount that was transferred (as a string to avoid precision issues)
config	BridgeConfig	The bridge configuration that was used for this operation
destination	`{ address: string; chain: ChainDefinition; recipientAddress?: string; useForwarder?: boolean }`	Information about the destination chain and address
provider	string	The provider that was used for this operation
source	`{ address: string; chain: ChainDefinition }`	Information about the source chain and address
state	`'pending' \| 'success' \| 'error'`	The state of the transfer
steps	BridgeStep[]	Array of steps that were executed during the bridge process
token	`'USDC'`	The token that was transferred (currently only USDC is supported)

Usage Example

const result = await kit.bridge({
  from: { adapter: sourceAdapter, chain: "Ethereum" },
  to: { adapter: destAdapter, chain: "Polygon" },
  amount: "100.50",
  token: "USDC",
});

console.log("Bridge completed:", result.hash);

estimateBridge(params)

Estimate the bridge operation. Calculates gas costs, protocol fees, and optional custom fees for a crosschain bridge transfer without executing the transaction. Useful for displaying cost estimates to users before they confirm a transfer.

estimateBridge(params: BridgeParams): Promise<EstimateResult>

Parameters

Name	Type	Description
params	`BridgeParams`	Bridge parameters containing source, destination, amount, and token

BridgeParams

The from field specifies the source adapter context (wallet and chain).
The to field specifies the destination, supporting both explicit and derived recipient addresses.
The config field allows customization of bridge behavior (e.g., transfer speed).
The token field is optional and defaults to USDC; other tokens are not currently supported.

interface BridgeParams {
  amount: string;
  config?: BridgeConfig;
  from: AdapterContext<TFromAdapterCapabilities, BridgeChainIdentifier>;
  invocationMeta?: InvocationMeta;
  to: BridgeDestination<TToAdapterCapabilities, BridgeChainIdentifier>;
  token?: "USDC";
}

Properties

Name	Type	Description
amount	string	The amount to transfer
config	BridgeConfig	Optional bridge configuration (e.g., transfer speed). If omitted, defaults will be used
from	`AdapterContext`	The source adapter context (wallet and chain) for the transfer.
invocationMeta	InvocationMeta	Optional invocation metadata for tracing and correlation. When provided, the `traceId` is used to correlate all events emitted during the bridge operation. If not provided, an OpenTelemetry-compatible `traceId` will be auto-generated.
to	`BridgeDestination`	The destination for the transfer, supporting explicit or derived recipient addresses
token	`'USDC'`	The token to transfer. Defaults to `USDC`. If omitted, the provider will use `USDC` by default.

Returns Promise<EstimateResult>

EstimateResult

Cost estimation result for a crosschain transfer operation. This interface provides detailed information about the expected costs for a transfer, including gas fees on different chains and protocol fees. It also includes the input context (token, amount, source, destination) to provide a complete view of the transfer being estimated.

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

Properties

Name	Type	Description
amount	string	The amount being transferred
destination	`{ address: string; chain: Blockchain; recipientAddress?: string }`	Information about the destination chain and address
fees	`{ amount: string \| null; error?: unknown; token: 'USDC'; type: 'kit' \| 'provider' \| 'forwarder' }[]`	Array of protocol and service fees for the transfer
gasFees	`{ blockchain: Blockchain; error?: unknown; fees: EstimatedGas \| null; name: string; token: string }[]`	Array of gas fees required for the transfer on different blockchains
source	`{ address: string; chain: Blockchain }`	Information about the source chain and address
token	`'USDC'`	The token being transferred

Usage Example

const estimate = await kit.estimateBridge({
  from: { adapter: sourceAdapter, chain: "Ethereum" },
  to: { adapter: destAdapter, chain: "Polygon" },
  amount: "100.50",
  token: "USDC",
});

console.log("Estimated fees:", estimate.fees);

estimateSend(params)

Estimate network fees for a send operation. Prepare the send (validation + recipient resolution) and returns the gas estimate without executing the actual transaction. This allows developers to show users the cost before committing to the transfer.

estimateSend(params: SendParams): Promise<EstimatedGas>

Parameters

Name	Type	Description
params	`SendParams`	Send parameters: source, destination (address or adapter), amount, token.

SendParams

Parameters for sending USDC, USDT, native tokens, or custom ERC-20/SPL tokens. This interface is the canonical input for send operations in App Kit. It supports sending to either a destination Adapter (recipient derives from the adapter’s default account) or an explicit recipient string address.

The from field provides the source signing context and chain.
The to field identifies the destination as an adapter or an explicit address.
The amount field is a human-readable decimal string (for example, '10.5').
The token field selects the asset to move and defaults to 'USDC'.

interface SendParams {
  amount: string
  from: AdapterContext
  to: string \| Adapter<AdapterCapabilities>
  token?: TokenAlias \| TokenAddress
}

Properties

Name	Type	Description
amount	string	The amount to transfer.
from	AdapterContext	The source adapter context (wallet and chain) for the transfer.
to	`string \| Adapter`	The destination for the transfer, supporting explicit or derived recipient addresses.
token	`TokenAlias \| TokenAddress`	The token to transfer. Defaults to `USDC`. If omitted, the provider will use `USDC` by default. Supports both known aliases and custom token contract addresses: - Known aliases: `USDC`, `USDT`, `NATIVE` - Custom token addresses: EVM addresses or Solana SPL token mint addresses

Returns Promise<EstimatedGas>

EstimatedGas

Estimated gas information for a blockchain transaction. This interface provides a unified way to represent gas costs across different blockchain networks, supporting both EVM-style gas calculations and other fee models.

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

Usage Examples

const estimate = await kit.estimateSend({
  from: { adapter: sourceAdapter, chain: "Ethereum" },
  to: recipientAdapter,
  amount: "100.50",
  token: "USDC",
});

console.log("Estimated gas:", estimate.gas);

const estimate = await kit.estimateSend({
  from: { adapter: sourceAdapter, chain: "Ethereum" },
  to: "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
  amount: "50.0",
  token: "USDT",
});

console.log("Estimated gas:", estimate.gas);

estimateSwap(params)

Estimate the output and fees for a swap operation. Calculates the expected output amount, minimum output (with slippage), and fee breakdown for a token swap without executing the transaction.

estimateSwap(params: SwapParams): Promise<SwapEstimate>

Parameters

Name	Type	Description
params	`SwapParams`	Swap parameters containing source, tokens, amount, and config

SwapParams

Parameters for initiating a same-chain stablecoin swap. This type is used as the primary input to swap operations, allowing users to specify the source context, input/output tokens, swap amount, and optional configuration. SwapKit supports swaps between stablecoins (USDC, USDT, EURC, USDe, DAI, PYUSD), wrapped tokens (WBTC, WETH, WSOL, WAVAX, WPOL), and native tokens (e.g., ETH on Ethereum, SOL on Solana) via the NATIVE alias.

The from field specifies the source adapter context (wallet and chain). The chain must be a SwapChain member (or its corresponding string literal) so IDE autocomplete only surfaces swap-supported networks.
The tokenIn field specifies the input token (see SupportedToken).
The tokenOut field specifies the output token (see SupportedToken).
The amountIn field is a human-readable decimal string (e.g., 10.5).
The config field allows customization of swap behavior.

interface SwapParams<
  TFromAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities,
> {
  from: SwapAdapterContext<TFromAdapterCapabilities>;
  tokenIn: SupportedSwapToken;
  tokenOut: SupportedSwapToken;
  amountIn: string;
  config?: SwapConfig;
}

Properties

Name	Type	Description
amountIn	string	The amount of the input token to swap. Expressed as a human-readable decimal string in token units (e.g., `'0.05'` for 0.05 USDC or 0.05 ETH).
config	SwapConfig	Optional configuration for swap behavior. If omitted, defaults will be used: - `allowanceStrategy`: `permit` (fallback to `approve`) - `slippageBps`: 300 (3%)
from	`SwapAdapterContext`	The source adapter context (wallet and chain) for the swap.
tokenIn	SupportedSwapToken	The input token to swap from. Supports stablecoins (USDC, USDT, EURC, USDe, DAI, PYUSD), wrapped tokens (WBTC, WETH, WSOL, WAVAX, WPOL), and native tokens (NATIVE or chain-specific symbols).
tokenOut	SupportedSwapToken	The output token to swap to. Supports stablecoins (USDC, USDT, EURC, USDe, DAI, PYUSD), wrapped tokens (WBTC, WETH, WSOL, WAVAX, WPOL), and native tokens (NATIVE or chain-specific symbols).

Returns Promise<SwapEstimate>

SwapEstimate

Estimation result for a swap operation. Contains the provider’s swap quote including minimum output (stop limit), estimated output amount, fee breakdown, and input context fields

interface SwapEstimate {
  readonly tokenIn: SupportedSwapToken;
  readonly tokenOut: SupportedSwapToken;
  readonly amountIn: string;
  readonly chain: Blockchain;
  readonly fromAddress: string;
  readonly toAddress: string;
  readonly stopLimit: TokenAmount;
  readonly estimatedOutput: TokenAmount;
  readonly fees?: readonly ServiceSwapFee[];
}

Properties

Name	Type	Description
amountIn	string	The input amount that will be swapped. Expressed as a human-readable decimal string in token units (e.g., `'0.05'` for 0.05 USDC or 0.05 ETH).
chain	Blockchain	The chain where the swap will be executed. Returns the chain name (e.g., Blockchain.Ethereum) Use `getChainByEnum(chain)` to resolve back to a full ChainDefinition if needed.
estimatedOutput	TokenAmount	Estimated output amount with token information.
fees	readonly ServiceSwapFee[]	Detailed fee breakdown for the swap operation.
fromAddress	string	The address that will initiate the swap.
stopLimit	TokenAmount	Estimated minimum token out amount with token information. This represents the minimum amount of tokens the user should receive after accounting for slippage. Amount is in human-readable decimal format.
toAddress	string	The address that will receive the swapped tokens.
tokenIn	SupportedSwapToken	The input token that will be swapped from.
tokenOut	SupportedSwapToken	The output token that will be swapped to.

Usage Example

const estimate = await kit.estimateSwap({
  from: { adapter, chain: "Ethereum" },
  tokenIn: "USDC",
  tokenOut: "USDT",
  amountIn: "100.50",
  config: {
    slippageBps: 300,
    kitKey: "KIT_KEY:id:secret",
  },
});

console.log("Stop limit:", estimate.stopLimit.amount, estimate.stopLimit.token);
console.log(
  "Estimated output:",
  estimate.estimatedOutput.amount,
  estimate.estimatedOutput.token,
);
console.log("Fees:", estimate.fees);

getSupportedChains(operationType)

Get chains supported by AppKit operations. Returns blockchain networks that support specific stablecoin operations. When no operation type is specified, returns all chains supporting any operation (bridge, swap, earn, or unified balance).

getSupportedChains(operationType?: OperationType): ChainDefinition[]

Parameters

Name	Type	Description
operationType	`OperationType`	Optional operation type to filter chains (`bridge` \| `swap` \| `earn` \| `unifiedBalance`)

OperationType

Union type of all supported operation types in the AppKit. This type ensures type safety when specifying operation types and enables proper parameter validation based on the selected operation.

type OperationType = FeeOperationType | "earn" | "unifiedBalance";

Returns ChainDefinition[] Usage Examples

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

const kit = new AppKit();
const allChains = kit.getSupportedChains();

console.log(`Total supported chains: ${allChains.length}`);
allChains.forEach((chain) => {
  console.log(`- ${chain.name} (${chain.type})`);
});

const kit = new AppKit();
const bridgeChains = kit.getSupportedChains("bridge");

console.log(
  "Chains supporting bridge:",
  bridgeChains.map((c) => c.name),
);

off(action)

Unregister an event handler for a specific AppKit action. This method removes a previously registered event handler. You must pass the exact same handler function reference that was used during registration. Use the wildcard * to remove handlers listening to all actions.

off<K extends AppKitActionName>(action: K, handler: (payload: AppKitActions[K]) => void): void
off(action: '*', handler: (payload: AppKitActions[keyof AppKitActions]) => void): void

Parameters

Name	Type	Description
action	`K`	The namespaced action name or `*` for all actions
handler	`(payload: unknown) => void`	The handler function to remove (must be the same reference)

Usage Example

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

const kit = new AppKit();

// Define handler
const handler = (payload) => {
  console.log("Approval:", payload);
};

// Register
kit.on("bridge.approve", handler);

// Later, unregister
kit.off("bridge.approve", handler);

on(action)

Register an event handler for a specific AppKit action. Subscribe to events emitted during bridge or unified balance operations. Bridge events are prefixed with bridge. and unified balance events with unifiedBalance. to namespace them within the AppKit event system. Handlers receive strongly-typed payloads based on the action name. Multiple handlers can be registered for the same action, and all will be invoked when the action occurs. Use the wildcard * to listen to all actions.

on<K extends AppKitActionName>(action: K, handler: (payload: AppKitActions[K]) => void): void
on(action: '*', handler: (payload: AppKitActions[keyof AppKitActions]) => void): void

Parameters

Name	Type	Description
action	`K`	The namespaced action name or `*` for all actions
handler	`(payload: unknown) => void`	Callback function to invoke when the action occurs

Usage Example

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

const kit = new AppKit();

// Listen to specific bridge action
kit.on("bridge.approve", (payload) => {
  console.log("Approval transaction:", payload.values.txHash);
});

// Listen to unified balance action
kit.on("unifiedBalance.gateway.spend.succeeded", (payload) => {
  console.log("Spend succeeded:", payload.data);
});

// Listen to all actions
kit.on("*", (payload) => {
  console.log("Action:", payload);
});

retryBridge(result)

Retry a failed crosschain USDC bridge transfer. Resume a bridge operation that failed due to a transient error. Use isRetryableError to check whether a failed step’s error is eligible for retry before calling this method.

retryBridge(result: BridgeResult, retryContext: RetryContext): Promise<BridgeResult>

Parameters

Name	Type	Description
result	`BridgeResult`	The bridge result from the failed operation
retryContext	`RetryContext`	The retry context with source and optional destination adapters

BridgeResult

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

Properties

Name	Type	Description
amount	string	The amount that was transferred (as a string to avoid precision issues)
config	BridgeConfig	The bridge configuration that was used for this operation
destination	`{ address: string; chain: ChainDefinition; recipientAddress?: string; useForwarder?: boolean }`	Information about the destination chain and address
provider	string	The provider that was used for this operation
source	`{ address: string; chain: ChainDefinition }`	Information about the source chain and address
state	`'pending' \| 'success' \| 'error'`	The state of the transfer
steps	BridgeStep[]	Array of steps that were executed during the bridge process
token	`'USDC'`	The token that was transferred (currently only USDC is supported)

RetryContext

Context for retry operations containing source and destination adapter contexts. This interface provides the necessary context for retry operations, including both the source adapter context (where the retry originates) and the destination adapter context (where the retry is targeted). This ensures that retry operations have access to both the source and destination chain information needed for validation and execution. The destination adapter (to) is optional to support forwarder-only destinations where Circle’s Orbit relayer handles the mint transaction without requiring a destination adapter. When to is undefined, the retry operation relies on IRIS API confirmation instead of on-chain transaction confirmation.

interface RetryContext {
  from: Adapter<TFromAdapterCapabilities>;
  to?: Adapter<TToAdapterCapabilities>;
}

Properties

Name	Type	Description
from	`Adapter`	The source adapter context for the retry operation
to	`Adapter`	The destination adapter context for the retry operation. Optional for forwarder-only destinations where Circle’s Orbit relayer handles the mint transaction. When undefined, the retry operation relies on IRIS API confirmation (`forwardState === 'CONFIRMED'`) instead of on-chain transaction confirmation via the adapter.

Returns Promise<BridgeResult>

BridgeResult

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

Properties

Name	Type	Description
amount	string	The amount that was transferred (as a string to avoid precision issues)
config	BridgeConfig	The bridge configuration that was used for this operation
destination	`{ address: string; chain: ChainDefinition; recipientAddress?: string; useForwarder?: boolean }`	Information about the destination chain and address
provider	string	The provider that was used for this operation
source	`{ address: string; chain: ChainDefinition }`	Information about the source chain and address
state	`'pending' \| 'success' \| 'error'`	The state of the transfer
steps	BridgeStep[]	Array of steps that were executed during the bridge process
token	`'USDC'`	The token that was transferred (currently only USDC is supported)

Usage Example

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

const kit = new AppKit();

const result = await kit.bridge({
  from: { adapter: sourceAdapter, chain: "Ethereum" },
  to: { adapter: destAdapter, chain: "Polygon" },
  amount: "100.50",
});

const failedStep = result.steps.find((s) => s.error);
if (
  result.state === "error" &&
  failedStep?.error &&
  isRetryableError(failedStep.error)
) {
  const retried = await kit.retryBridge(result, {
    from: sourceAdapter,
    to: destAdapter,
  });
  console.log("Retry result:", retried.state);
}

send(params)

Execute a send operation for known token aliases (USDC, USDT, NATIVE) or custom ERC-20/SPL tokens. For custom tokens, the token address must be provided. This method handles the complete send transfer flow using the underlying AppKit infrastructure. It supports sending to either a destination adapter or an explicit recipient address, with full type safety and comprehensive error handling.

send(params: SendParams): Promise<BridgeStep>

Parameters

Name	Type	Description
params	`SendParams`	Send parameters containing source, destination, amount, and token

SendParams

The from field provides the source signing context and chain.
The to field identifies the destination as an adapter or an explicit address.
The amount field is a human-readable decimal string (for example, '10.5').
The token field selects the asset to move and defaults to 'USDC'.

interface SendParams {
  amount: string
  from: AdapterContext
  to: string \| Adapter<AdapterCapabilities>
  token?: TokenAlias \| TokenAddress
}

Properties

Name	Type	Description
amount	string	The amount to transfer.
from	AdapterContext	The source adapter context (wallet and chain) for the transfer.
to	`string \| Adapter`	The destination for the transfer, supporting explicit or derived recipient addresses.
token	`TokenAlias \| TokenAddress`	The token to transfer. Defaults to `USDC`. If omitted, the provider will use `USDC` by default. Supports both known aliases and custom token contract addresses: - Known aliases: `USDC`, `USDT`, `NATIVE` - Custom token addresses: EVM addresses or Solana SPL token mint addresses

Returns Promise<BridgeStep>

BridgeStep

A step in the bridge process.

interface BridgeStep {
  batched?: boolean
  batchId?: string
  data?: unknown
  error?: unknown
  errorCategory?: BridgeStepErrorCategory
  errorMessage?: string
  explorerUrl?: string
  forwarded?: boolean
  name: string
  state: 'pending' \| 'success' \| 'error' \| 'noop'
  txHash?: string
}

Properties

Name	Type	Description
batched	boolean	Whether this step was executed as part of an EIP-5792 batched `wallet_sendCalls` request. - `true`: The step was included in a batched call bundle - `undefined`: The step was executed individually (sequential flow)
batchId	string	The wallet-assigned batch identifier from `wallet_sendCalls`. Present only when batched is `true`. Can be used with `wallet_getCallsStatus` to query the status of the entire bundle.
data	unknown	Optional data for the step
error	unknown	Optional raw error object (can be Viem/Ethers/Chain error)
errorCategory	BridgeStepErrorCategory	Optional machine-readable classification of the error. Present when the step is in `state: 'error'` and the SDK was able to categorize the failure. See BridgeStepErrorCategory for the list of categories and how they map to underlying error shapes.
errorMessage	string	Optional human-readable error message
explorerUrl	string	Optional explorer URL for viewing this transaction on a block explorer
forwarded	boolean	Whether this step was executed via Circle’s Forwarder (relay service). Only applicable for mint steps. - `true`: The mint was handled by Circle’s Orbit relayer - `false`: The user submitted the mint transaction directly - `undefined`: Not applicable (non-mint steps)
name	string	Human-readable name of the step (e.g., “Approve”, “Burn”, “Mint”)
state	`'pending' \| 'success' \| 'error' \| 'noop'`	The state of the step
txHash	string	Optional transaction hash for this step (if applicable)

Usage Examples

// Send USDC to a recipient adapter (same chain)
const result = await kit.send({
  from: { adapter: sourceAdapter, chain: "Ethereum" },
  to: recipientAdapter,
  amount: "100.50",
  token: "USDC",
});

console.log("Send completed:", result.txHash);

// Send a custom token to an explicit address
const result = await kit.send({
  from: { adapter: sourceAdapter, chain: "Ethereum" },
  to: "0x742d35Cc4634C0532925a3b8D1d7",
  amount: "100.50",
  token: "0x6B175474E89094C44Da98b954EedeAC495271d0F", // DAI on Ethereum
});
console.log("Send completed:", result.txHash);

// Send USDT to an explicit address
const result = await kit.send({
  from: { adapter: sourceAdapter, chain: "Ethereum" },
  to: "0x742d35Cc4634C0532925a3b8D1d7",
  amount: "50.25",
  token: "USDT",
});

console.log("Send completed:", result.txHash);

swap(params)

Execute a same-chain token swap operation. Swaps between USDC, USDT, and native tokens on the same blockchain with configurable slippage tolerance and allowance strategies.

swap(params: SwapParams): Promise<SwapResult>

Parameters

Name	Type	Description
params	`SwapParams`	Swap parameters containing source, tokens, amount, and config

SwapParams

The from field specifies the source adapter context (wallet and chain). The chain must be a SwapChain member (or its corresponding string literal) so IDE autocomplete only surfaces swap-supported networks.
The tokenIn field specifies the input token (see SupportedToken).
The tokenOut field specifies the output token (see SupportedToken).
The amountIn field is a human-readable decimal string (e.g., 10.5).
The config field allows customization of swap behavior.

interface SwapParams<
  TFromAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities,
> {
  from: SwapAdapterContext<TFromAdapterCapabilities>;
  tokenIn: SupportedSwapToken;
  tokenOut: SupportedSwapToken;
  amountIn: string;
  config?: SwapConfig;
}

Properties

Name	Type	Description
amountIn	string	The amount of the input token to swap. Expressed as a human-readable decimal string in token units (e.g., `'0.05'` for 0.05 USDC or 0.05 ETH).
config	SwapConfig	Optional configuration for swap behavior. If omitted, defaults will be used: - `allowanceStrategy`: `permit` (fallback to `approve`) - `slippageBps`: 300 (3%)
from	`SwapAdapterContext`	The source adapter context (wallet and chain) for the swap.
tokenIn	SupportedSwapToken	The input token to swap from. Supports stablecoins (USDC, USDT, EURC, USDe, DAI, PYUSD), wrapped tokens (WBTC, WETH, WSOL, WAVAX, WPOL), and native tokens (NATIVE or chain-specific symbols).
tokenOut	SupportedSwapToken	The output token to swap to. Supports stablecoins (USDC, USDT, EURC, USDe, DAI, PYUSD), wrapped tokens (WBTC, WETH, WSOL, WAVAX, WPOL), and native tokens (NATIVE or chain-specific symbols).

Returns Promise<SwapResult>

SwapResult

Result of an executed swap operation. Captures the outcome of a swap transaction, including input/output tokens, transaction hash, and fee information. This is the high-level result returned to users after a swap operation completes.

interface SwapResult {
  readonly tokenIn: SupportedSwapToken;
  readonly tokenOut: SupportedSwapToken;
  readonly chain: Blockchain;
  readonly amountIn: string;
  readonly amountOut?: string;
  readonly fromAddress: string;
  readonly toAddress: string;
  readonly config?: SwapResultConfig;
  readonly txHash: string;
  readonly explorerUrl?: string;
  fees?: readonly ServiceSwapFee[];
}

Properties

Name	Type	Description
amountIn	string	The input amount that was swapped. Expressed as a human-readable decimal string in token units (e.g., `'0.05'` for 0.05 USDC or 0.05 ETH).
amountOut	string	The actual output amount received from the completed swap. Expressed as a human-readable decimal string in output token units. Populated via a best-effort LI.FI status lookup after the on-chain transaction confirms. May be `undefined` if the lookup fails or the chain type is unsupported.
chain	Blockchain	The chain where the swap was executed. Returns the chain name (e.g., Blockchain.Ethereum) Use `getChainByEnum(chain)` to resolve back to a full ChainDefinition if needed.
config	SwapResultConfig	The swap configuration that was used for this operation.
explorerUrl	string	The formatted explorer URL for viewing this transaction on a block explorer. Only present when `txHash` is non-empty.
fees	readonly ServiceSwapFee[]	Detailed fee breakdown for the swap operation. Includes both provider fees (charged by the DEX aggregator/protocol) and kit fees (if configured).
fromAddress	string	The address that initiated the swap.
toAddress	string	The address that received the swapped tokens.
tokenIn	SupportedSwapToken	The input token that was swapped from.
tokenOut	SupportedSwapToken	The output token that was swapped to.
txHash	string	The transaction hash for the executed swap. Available once the transaction has been submitted to the network.

Usage Example

const result = await kit.swap({
  from: { adapter, chain: "Ethereum" },
  tokenIn: "USDC",
  tokenOut: "USDT",
  amountIn: "100.50",
  config: {
    slippageBps: 300, // 3% slippage
    allowanceStrategy: "permit",
    kitKey: "KIT_KEY:id:secret",
  },
});

console.log("Swap completed:", result.txHash);

kit.unifiedBalance Methods

unifiedBalance is a property on every AppKit instance. Call these methods as kit.unifiedBalance.methodName().

addDelegate(params)

Grant spending rights to another address on the owner’s account.

addDelegate(params: UpdateDelegateParams): Promise<UpdateDelegateResult>

Parameters

Name	Type	Description
params	`UpdateDelegateParams`	The owner’s adapter context and the delegate address.

UpdateDelegateParams

Parameters for adding or removing a delegate on a Gateway account.

interface UpdateDelegateParams {
  delegateAddress: string;
  from: AdapterContext<TAdapterCapabilities, TChainIdentifier>;
  token?: SupportedTokenInput;
}

Properties

Name	Type	Description
delegateAddress	string	The address being added or removed as an authorized delegate.
from	`AdapterContext`	The owner’s adapter context identifying the account and chain to which the delegate will be authorized.
token	SupportedTokenInput	The token for which delegation applies. Accepts any case (e.g. `'usdc'`, `'Usdc'`); normalised to uppercase internally.

Returns Promise<UpdateDelegateResult>

UpdateDelegateResult

Result returned after a successful add or remove delegate operation.

interface UpdateDelegateResult {
  account: string
  chain: Blockchain
  delegateAddress: string
  explorerUrl?: string
  state: 'added' \| 'removed'
  txHash: string
}

Properties

Name	Type	Description
account	string	The Gateway account that was modified.
chain	Blockchain	The chain on which the delegate was updated.
delegateAddress	string	The delegate address that was added or removed.
explorerUrl	string	Link to view the transaction details on the appropriate blockchain explorer.
state	`'added' \| 'removed'`	Whether the delegate was added or removed.
txHash	string	Unique identifier returned by the blockchain once the transaction is mined.

Usage Example

const result = await kit.unifiedBalance.addDelegate({
  from: { adapter, chain: "Ethereum" },
  delegateAddress: "0xDelegate…",
});

deposit(params)

Deposit USDC into the caller’s account on a specific chain.

deposit(params: DepositParams): Promise<DepositResult>

Parameters

Name	Type	Description
params	`DepositParams`	Deposit details including the depositor context and amount.

DepositParams

Parameters for depositing tokens into the caller’s own Gateway account on a specific chain.

interface DepositParams<
  TAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities,
  TChainIdentifier extends UnifiedBalanceChainIdentifier =
    UnifiedBalanceChainIdentifier,
> {
  from: AdapterContext<TAdapterCapabilities, TChainIdentifier>;
  amount: string;
  token?: SupportedTokenInput;
  allowanceStrategy?: AllowanceStrategy;
}

Properties

Name	Type	Description
allowanceStrategy	AllowanceStrategy	The token allowance strategy to authorize the deposit.
amount	string	The amount of tokens to deposit (human-readable decimal string).
from	`AdapterContext`	The adapter context identifying the depositor and chain.
token	SupportedTokenInput	The token to deposit. Accepts any case (e.g. `'usdc'`, `'Usdc'`); normalised to uppercase internally.

Returns Promise<DepositResult>

DepositResult

Result returned after a successful deposit operation.

interface DepositResult {
  amount: string;
  token: SupportedToken;
  depositedTo: string;
  depositedBy: string;
  chain: Blockchain;
  txHash: string;
  explorerUrl?: string;
}

Properties

Name	Type	Description
amount	string	The deposited amount (human-readable decimal string).
chain	Blockchain	The chain on which the deposit occurred.
depositedBy	string	The address that signed and funded the deposit.
depositedTo	string	The Gateway account address credited by the deposit.
explorerUrl	string	Link to view the transaction details on the appropriate blockchain explorer.
token	SupportedToken	The token that was deposited.
txHash	string	Unique identifier returned by the blockchain once the transaction is mined.

Usage Example

const result = await kit.unifiedBalance.deposit({
  from: { adapter, chain: "Ethereum" },
  amount: "100",
  token: "USDC",
});

depositFor(params)

Deposit USDC into another account (not the caller’s).

depositFor(params: DepositForParams): Promise<DepositResult>

Parameters

Name	Type	Description
params	`DepositForParams`	Deposit details including the depositor context, amount, and the account address to credit.

DepositForParams

Parameters for depositing tokens into another Gateway account.

interface DepositForParams<
  TAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities,
  TChainIdentifier extends UnifiedBalanceChainIdentifier =
    UnifiedBalanceChainIdentifier,
> extends Omit<
  DepositParams<TAdapterCapabilities, TChainIdentifier>,
  "allowanceStrategy"
> {
  depositAccount: string;
}

Properties

Name	Type	Description
amount	string	The amount of tokens to deposit (human-readable decimal string).
depositAccount	string	The Gateway account address to credit with the deposit. When provided the deposit is credited to this account rather than the caller’s own.
from	`AdapterContext`	The adapter context identifying the depositor and chain.
token	SupportedTokenInput	The token to deposit. Accepts any case (e.g. `'usdc'`, `'Usdc'`); normalised to uppercase internally.

Returns Promise<DepositResult>

DepositResult

Result returned after a successful deposit operation.

interface DepositResult {
  amount: string;
  token: SupportedToken;
  depositedTo: string;
  depositedBy: string;
  chain: Blockchain;
  txHash: string;
  explorerUrl?: string;
}

Properties

Name	Type	Description
amount	string	The deposited amount (human-readable decimal string).
chain	Blockchain	The chain on which the deposit occurred.
depositedBy	string	The address that signed and funded the deposit.
depositedTo	string	The Gateway account address credited by the deposit.
explorerUrl	string	Link to view the transaction details on the appropriate blockchain explorer.
token	SupportedToken	The token that was deposited.
txHash	string	Unique identifier returned by the blockchain once the transaction is mined.

Usage Example

const result = await kit.unifiedBalance.depositFor({
  from: { adapter, chain: "Ethereum" },
  amount: "50",
  depositAccount: "0x742d35Cc6634C0532925a3b844D97D35e2B60E53",
});

estimateSpend(params)

Estimate the fees for a spend operation without executing it.

estimateSpend(params: SpendParams): Promise<EstimateSpendResult>

Parameters

Name	Type	Description
params	`SpendParams`	The same spend parameters used in AppKitUnifiedBalance.spend.

SpendParams

Parameters for spending (minting) USDC on a destination chain from one or more Gateway account sources.

type SpendParams =
  | SpendParamsWithFrom<
      TFromAdapterCapabilities,
      TToAdapterCapabilities,
      TChainIdentifier
    >
  | SpendParamsRetry<
      TFromAdapterCapabilities,
      TToAdapterCapabilities,
      TChainIdentifier
    >;

Returns Promise<EstimateSpendResult>

EstimateSpendResult

Cost estimation for a spend (mint) operation.

interface EstimateSpendResult {
  fees: FeeEntry[];
}

Properties

Name	Type	Description
fees	FeeEntry[]	Itemised fee breakdown for the spend operation.

Usage Example

const estimate = await kit.unifiedBalance.estimateSpend({
  from: { adapter, allocations: [{ amount: "100", chain: "Ethereum" }] },
  to: { adapter, chain: "Base" },
  token: "USDC",
});

getBalances(params)

Fetch aggregated and per-chain balances for one or more accounts.

getBalances(params: GetBalancesParams): Promise<GetBalancesResult>

Parameters

Name	Type	Description
params	`GetBalancesParams`	Balance query parameters (adapter or account address).

GetBalancesParams

Parameters for the balances and pending-deposits API requests. Specify the token to query and one or more sources identifying the accounts or adapters whose balances should be retrieved. When includePending is true, the result includes pending balances and pending transaction details per chain.

interface GetBalancesParams<
  TAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities,
> {
  token?: SupportedTokenInput;
  sources: Sources<TAdapterCapabilities>;
  includePending?: boolean;
  networkType?: NetworkType;
}

Properties

Name	Type	Description
includePending	boolean	When true, the result includes pending balances. When false or omitted, only confirmed balances are returned.
networkType	NetworkType	Network to use when no chains are specified on a source. When omitted, mainnet is used when chains cannot be derived.
sources	`Sources`	One or more sources identifying the accounts or adapters to query. Accepts a single object or an array.
token	SupportedTokenInput	The token to query balances for. Accepts any case (e.g. `'usdc'`, `'Usdc'`); normalised to uppercase internally.

Returns Promise<GetBalancesResult>

GetBalancesResult

Result returned from the provider’s getBalances method (combined confirmed and pending). When includePending is false (default), only totalConfirmedBalance and breakdown with confirmed fields are returned. When includePending is true, totalPendingBalance is present and breakdown entries include pending amounts and pendingTransactions per chain.

interface GetBalancesResult {
  token: SupportedToken;
  totalConfirmedBalance: string;
  totalPendingBalance?: string;
  breakdown: BalanceWithPendingBreakdown[];
}

Properties

Name	Type	Description
breakdown	BalanceWithPendingBreakdown[]	Per-account, per-chain breakdown.
token	SupportedToken	Token that was queried.
totalConfirmedBalance	string	Total confirmed balance across all accounts and chains (human-readable decimal string).
totalPendingBalance	string	Total pending balance across all accounts and chains. Present only when `includePending` is true.

Usage Example

const balances = await kit.unifiedBalance.getBalances({
  token: "USDC",
  sources: { address: "0x1234…abcd" },
});

getDelegateStatus(params)

Check the finality-aware delegate status of an address.

getDelegateStatus(params: GetDelegateStatusParams): Promise<DelegateStatus>

Parameters

Name	Type	Description
params	`GetDelegateStatusParams`	The adapter context and delegate address to check.

GetDelegateStatusParams

Parameters for checking the delegate status of an address on a Gateway account.

interface GetDelegateStatusParams {
  delegateAddress: string;
  from: AdapterContext<TAdapterCapabilities, TChainIdentifier>;
  token?: SupportedTokenInput;
}

Properties

Name	Type	Description
delegateAddress	string	The address to check for delegate status.
from	`AdapterContext`	The adapter context identifying the account owner and chain.
token	SupportedTokenInput	The token for which delegation is checked. Accepts any case (e.g. `'usdc'`, `'Usdc'`); normalised to uppercase internally.

Returns Promise<DelegateStatus> Usage Example

const status = await kit.unifiedBalance.getDelegateStatus({
  from: { adapter, chain: 'Ethereum' },
  delegateAddress: '0xDelegate…',
})
if (status === 'ready') { // safe to spend }

getSupportedChains(token)

Get all chains supported by the unified balance operations.

getSupportedChains(token?: SupportedToken, options?: GetSupportedChainsOptions): ChainDefinition[]

Parameters

Name	Type	Description
token	`'USDC'`	Optional token filter (defaults to USDC).
options	`GetSupportedChainsOptions`	Optional filtering (e.g. forwarder support).

GetSupportedChainsOptions

Options for filtering supported chains.

type GetSupportedChainsOptions =
  | {
      chainType: CCTPV2SupportedChainType | CCTPV2SupportedChainType[];
      isTestnet?: boolean;
      forwarderSupported?: boolean;
    }
  | {
      chainType?: CCTPV2SupportedChainType | CCTPV2SupportedChainType[];
      isTestnet: boolean;
      forwarderSupported?: boolean;
    }
  | {
      chainType?: CCTPV2SupportedChainType | CCTPV2SupportedChainType[];
      isTestnet?: boolean;
      forwarderSupported: boolean;
    };

Properties

Name	Type	Description
forwarderSupported	`'source' \| 'destination'`	Filter chains by forwarder support. When set, only chains whose `gateway.forwarderSupported.source` or `gateway.forwarderSupported.destination` matches the specified value are returned. - `undefined` (default) — no forwarder filtering; all supported chains are returned. - `'source'` — only chains that support forwarding as a source. - `'destination'` — only chains that support forwarding as a destination.

Returns ChainDefinition[] Usage Example

const chains = kit.unifiedBalance.getSupportedChains();
const usdcChains = kit.unifiedBalance.getSupportedChains("USDC");

initiateRemoveFund(params)

Kick off a delayed fund removal from an account.

initiateRemoveFund(params: InitiateRemoveFundParams): Promise<InitiateRemoveFundResult>

Parameters

Name	Type	Description
params	`InitiateRemoveFundParams`	The account owner’s adapter context, amount, and token.

InitiateRemoveFundParams

Parameters for initiating a delayed fund removal from a Gateway account.

interface InitiateRemoveFundParams<
  TAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities,
  TChainIdentifier extends UnifiedBalanceChainIdentifier =
    UnifiedBalanceChainIdentifier,
> {
  from: AdapterContext<TAdapterCapabilities, TChainIdentifier>;
  amount: string;
  token?: SupportedTokenInput;
}

Properties

Name	Type	Description
amount	string	The amount to remove (human-readable decimal string).
from	`AdapterContext`	The account owner’s adapter context identifying the account, chain, and address.
token	SupportedTokenInput	The token to remove. Accepts any case (e.g. `'usdc'`, `'Usdc'`); normalised to uppercase internally.

Returns Promise<InitiateRemoveFundResult>

InitiateRemoveFundResult

Result returned after successfully initiating a fund removal.

interface InitiateRemoveFundResult {
  amount: string;
  token: SupportedToken;
  account: string;
  chain: Blockchain;
  withdrawingBalance: string;
  withdrawalBlock: number;
  txHash: string;
  explorerUrl?: string;
}

Properties

Name	Type	Description
account	string	The Gateway account from which this removal will occur.
amount	string	The amount requested for removal.
chain	Blockchain	The chain on which this removal was initiated.
explorerUrl	string	Link to view the transaction details on the appropriate blockchain explorer.
token	SupportedToken	The token type (always USDC).
txHash	string	Unique identifier returned by the blockchain once the transaction is mined.
withdrawalBlock	number	The block number at which the removal can be completed.
withdrawingBalance	string	The balance currently in the withdrawing state for this account.

Usage Example

const result = await kit.unifiedBalance.initiateRemoveFund({
  from: { adapter, chain: "Ethereum" },
  amount: "50",
  token: "USDC",
});

off(action)

Unregister an event handler for a specific gateway lifecycle action. Removes a previously registered event handler. You must pass the exact same handler function reference that was used during registration.

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

Parameters

Name	Type	Description
action	`string`	The action name or `'*'` for all actions.
handler	`(payload: unknown) => void`	The exact handler reference to remove.

Usage Example

const kit = new AppKit();
const handler = (payload: unknown) => console.log(payload);

kit.unifiedBalance.on("gateway.deposit.succeeded", handler);
kit.unifiedBalance.off("gateway.deposit.succeeded", handler);

on(action)

Register an event handler for a specific gateway lifecycle action. Subscribe to events emitted during gateway operations such as deposit, spend, getBalances, etc. Handlers receive strongly-typed payloads based on the action name. Multiple handlers can be registered for the same action, and all will be invoked when the action occurs. Use the wildcard '*' to listen to all actions. Note: TypeScript autocomplete may only show '*' due to internal type erasure. The following action names are available at runtime and can be imported as GatewayActionName from @circle-fin/provider-gateway-v1:

Action	Stages
`gateway.deposit`	`.started` `.succeeded` `.failed`
`gateway.depositFor`	`.started` `.succeeded` `.failed`
`gateway.spend`	`.started` `.succeeded` `.failed`
`gateway.spend.step`	`.buildBurnIntents` `.signBurnIntents` `.fetchAttestation` `.mint`
`gateway.estimateSpend`	`.started` `.succeeded` `.failed`
`gateway.getBalances`	`.started` `.succeeded` `.failed`
`gateway.addDelegate`	`.started` `.succeeded` `.failed`
`gateway.removeDelegate`	`.started` `.succeeded` `.failed`
`gateway.initiateRemoveFund`	`.started` `.succeeded` `.failed`
`gateway.removeFund`	`.started` `.succeeded` `.failed`

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

Parameters

Name	Type	Description
action	`string`	The action name or `'*'` for all actions.
handler	`(payload: unknown) => void`	Callback to invoke when the action occurs.

Usage Example

const kit = new AppKit();

kit.unifiedBalance.on("gateway.spend.started", (payload) => {
  console.log("Spend started:", payload);
});

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

removeCustomFeePolicy()

Remove the custom fee policy for the kit.

removeCustomFeePolicy(): void

Usage Example

kit.unifiedBalance.removeCustomFeePolicy();

removeDelegate(params)

Revoke spending rights from a delegate on the owner’s account.

removeDelegate(params: UpdateDelegateParams): Promise<UpdateDelegateResult>

Parameters

Name	Type	Description
params	`UpdateDelegateParams`	The owner’s adapter context and the delegate address.

UpdateDelegateParams

Parameters for adding or removing a delegate on a Gateway account.

interface UpdateDelegateParams {
  delegateAddress: string;
  from: AdapterContext<TAdapterCapabilities, TChainIdentifier>;
  token?: SupportedTokenInput;
}

Properties

Name	Type	Description
delegateAddress	string	The address being added or removed as an authorized delegate.
from	`AdapterContext`	The owner’s adapter context identifying the account and chain to which the delegate will be authorized.
token	SupportedTokenInput	The token for which delegation applies. Accepts any case (e.g. `'usdc'`, `'Usdc'`); normalised to uppercase internally.

Returns Promise<UpdateDelegateResult>

UpdateDelegateResult

Result returned after a successful add or remove delegate operation.

interface UpdateDelegateResult {
  account: string
  chain: Blockchain
  delegateAddress: string
  explorerUrl?: string
  state: 'added' \| 'removed'
  txHash: string
}

Properties

Name	Type	Description
account	string	The Gateway account that was modified.
chain	Blockchain	The chain on which the delegate was updated.
delegateAddress	string	The delegate address that was added or removed.
explorerUrl	string	Link to view the transaction details on the appropriate blockchain explorer.
state	`'added' \| 'removed'`	Whether the delegate was added or removed.
txHash	string	Unique identifier returned by the blockchain once the transaction is mined.

Usage Example

const result = await kit.unifiedBalance.removeDelegate({
  from: { adapter, chain: "Ethereum" },
  delegateAddress: "0xDelegate…",
});

removeFund(params)

Complete a fund removal once the activation period has passed.

removeFund(params: RemoveFundParams): Promise<RemoveFundResult>

Parameters

Name	Type	Description
params	`RemoveFundParams`	The account owner context matching the original initiation.

RemoveFundParams

Parameters for completing a fund removal after the activation period.

interface RemoveFundParams<
  TAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities,
  TChainIdentifier extends UnifiedBalanceChainIdentifier =
    UnifiedBalanceChainIdentifier,
> {
  from: AdapterContext<TAdapterCapabilities, TChainIdentifier>;
  token?: SupportedTokenInput;
}

Properties

Name	Type	Description
from	`AdapterContext`	The account owner’s adapter context. Must match the one used when initiating the fund removal.
token	SupportedTokenInput	The token to remove. Accepts any case (e.g. `'usdc'`, `'Usdc'`); normalised to uppercase internally.

Returns Promise<RemoveFundResult>

RemoveFundResult

Result returned after successfully completing a fund removal.

interface RemoveFundResult {
  amount: string;
  token: SupportedToken;
  account: string;
  chain: Blockchain;
  txHash: string;
  explorerUrl?: string;
}

Properties

Name	Type	Description
account	string	The Gateway account from which the tokens were removed.
amount	string	The final removed amount.
chain	Blockchain	The chain on which the removal occurred.
explorerUrl	string	Link to view the transaction details on the appropriate blockchain explorer.
token	SupportedToken	The token type (always USDC).
txHash	string	Unique identifier returned by the blockchain once the transaction is mined.

Usage Example

const result = await kit.unifiedBalance.removeFund({
  from: { adapter, chain: "Ethereum" },
  token: "USDC",
});

setCustomFeePolicy(policy)

Set a custom fee policy for spend operations. Once set, every subsequent spend() and estimateSpend() call will include the computed fee unless overridden by per-call config.customFee.

setCustomFeePolicy(policy: CustomFeePolicy): void

Parameters

Name	Type	Description
policy	`CustomFeePolicy`	The fee computation and recipient resolution policy.

CustomFeePolicy

interface CustomFeePolicy {
  computeFee: <TFromAdapterCapabilities extends AdapterCapabilities>(
    context: SwapFeeContext<TFromAdapterCapabilities>,
  ) => Promise<string> | string;
  resolveFeeRecipientAddress: <
    TFromAdapterCapabilities extends AdapterCapabilities,
  >(
    feePayoutChain: ChainDefinition,
    context: SwapFeeContext<TFromAdapterCapabilities>,
  ) => Promise<string> | string;
}

Usage Example

kit.unifiedBalance.setCustomFeePolicy({
  computeFee: () => "0.10",
  resolveFeeRecipientAddress: () => "0xFeeRecipient…",
});

spend(params)

Spend (mint) USDC on a destination chain by pulling funds from one or more account sources.

spend(params: SpendParams): Promise<SpendResult>

Parameters

Name	Type	Description
params	`SpendParams`	Spend details including source(s), destination, and token.

SpendParams

Parameters for spending (minting) USDC on a destination chain from one or more Gateway account sources.

type SpendParams =
  | SpendParamsWithFrom<
      TFromAdapterCapabilities,
      TToAdapterCapabilities,
      TChainIdentifier
    >
  | SpendParamsRetry<
      TFromAdapterCapabilities,
      TToAdapterCapabilities,
      TChainIdentifier
    >;

Returns Promise<SpendResult>

SpendResult

Result returned after a successful spend (mint) operation.

interface SpendResult {
  allocations?: AllocationResult[];
  destinationChain: Blockchain;
  expirationBlock?: string;
  explorerUrl?: string;
  fees?: FeeEntry[];
  recipientAddress: string;
  steps?: SpendStep[];
  transferId?: string;
  txHash: string;
}

Properties

Name	Type	Description
allocations	AllocationResult[]	Flattened list of allocations that were executed, each with its source Gateway account. Only present for non-retry spends.
destinationChain	Blockchain	The destination chain on which the recipient received the USDC.
expirationBlock	string	Block height after which the transfer attestation expires. Returned by the Gateway transfer API.
explorerUrl	string	Link to view the transaction details on the appropriate blockchain explorer.
fees	FeeEntry[]	Fee breakdown (provider, gasFee, optional kit, forwarder) for the executed spend. Same shape as estimateSpend fees. Omitted when using config.retry.
recipientAddress	string	The address that received the minted USDC.
steps	SpendStep[]	Ordered list of steps executed during the spend operation.
transferId	string	Gateway transfer identifier. Present when `useForwarder` is enabled and can be used to query transfer status via `GET /v1/transfer/{id}`.
txHash	string	Unique identifier returned by the blockchain once the transaction is mined.

Usage Example

const result = await kit.unifiedBalance.spend({
  from: { adapter, allocations: [{ amount: "100", chain: "Ethereum" }] },
  to: { adapter, chain: "Base" },
  token: "USDC",
});

Supporting Types

BridgeConfig

Configuration options for customizing bridge behavior.

interface BridgeConfig {
  batchTransactions?: boolean
  customFee?: CustomFee
  maxFee?: string
  transferSpeed?: TransferSpeed \| 'FAST' \| 'SLOW'
}

Properties

Name	Type	Description
batchTransactions	boolean	Enable or disable EIP-5792 batched transaction execution. When `true` (or `undefined` / omitted), the bridge will attempt to batch the approve and burn calls into a single `wallet_sendCalls` request if the connected wallet supports it. Set to `false` to explicitly opt out and always use the sequential approve -> burn flow.
customFee	CustomFee	The custom fee to charge for the transfer. Whatever value you provide here is added on top of the transfer amount. The user must have enough balance for `amount + customFee`, and the wallet signs for that total on the source chain. The custom fee is split automatically: - 10% routes to Circle. - 90% routes to your `recipientAddress`. The original transfer amount proceeds through CCTPv2 unchanged, and the protocol fee (1–14 bps in FAST mode, 0% in STANDARD) is taken from that transfer amount.
maxFee	string	The maximum fee to pay for the burn operation. Provide the amount as a base-10 numeric string representing the token amount in human-readable format. For example: to set a maximum fee of 1 USDC, pass `"1"`. Decimal values are supported (e.g., `"0.5"` for half a USDC).
transferSpeed	`TransferSpeed \| 'FAST' \| 'SLOW'`	The transfer speed mode for CCTPv2 transfers. Controls whether to use fast burn mode (FAST) or standard mode (SLOW). Fast burn may reduce transfer time but could have different fee implications.

TransferSpeed

Transfer speed options for crosschain operations. Defines the available speed modes for CCTPv2 transfers, affecting both transfer time and potential fee implications.

enum TransferSpeed {
  FAST = 'FAST'
  SLOW = 'SLOW'
}

Values FAST, SLOW

AdapterContext

Represents the context of an adapter used for crosschain operations. An AdapterContext must always specify both the adapter and the chain explicitly. The address field behavior is determined by the adapter’s address control model:

Developer-controlled adapters: The address field is required because each operation must explicitly specify which address to use.
User-controlled adapters: The address field is forbidden because the address is automatically resolved from the connected wallet or signer.
Legacy adapters: The address field remains optional for backward compatibility.

This ensures clear, debuggable code where the intended chain is always visible at the call site, and address requirements are enforced at compile time based on adapter capabilities.

type AdapterContext = {
  adapter: Adapter<TAdapterCapabilities>;
  chain: TChainIdentifier;
} & AddressField<ExtractAddressContext<TAdapterCapabilities>>;

Properties

Name	Type	Description
adapter	`Adapter<TAdapterCapabilities>`	The adapter instance for blockchain operations
chain	TChainIdentifier	The chain reference, which can be a ChainDefinition, Blockchain enum, or string literal

ChainDefinition

Public chain definition type.

type ChainDefinition = EVMChainDefinition | NonEVMChainDefinition;

EVMChainDefinition

Represents chain definitions for Ethereum Virtual Machine (EVM) compatible blockchains.

interface EVMChainDefinition {
  cctp: CCTPConfig \| null
  chain: Blockchain
  chainId: number
  eurcAddress: string \| null
  explorerUrl: string
  gateway?: GatewayConfig
  isTestnet: boolean
  kitContracts?: Partial<Record<KitContractType, string>>
  name: string
  nativeCurrency: Currency
  rpcEndpoints: readonly string[]
  title?: string
  type: 'evm'
  usdcAddress: string \| null
  usdtAddress: string \| null
}

Properties

Name	Type	Description
cctp	`CCTPConfig \| null`	Optional CCTP configuration.
chain	Blockchain	The blockchain identifier from the Blockchain enum.
chainId	number	The unique identifier for the blockchain.
eurcAddress	`string \| null`	The contract address for EURC.
explorerUrl	string	Template URL for the blockchain explorer to view transactions.
gateway	GatewayConfig	Optional Gateway contract configuration for Gateway protocol support.
isTestnet	boolean	Indicates whether this is a testnet or mainnet.
kitContracts	`Partial<Record<KitContractType, string>>`	Optional kit-specific contract addresses for enhanced chain functionality.
name	string	The display name of the blockchain.
nativeCurrency	Currency	Information about the native currency of the blockchain.
rpcEndpoints	readonly string[]	Default RPC endpoints for connecting to the blockchain network.
title	string	Optional title or alternative name for the blockchain.
type	`'evm'`	Discriminator for EVM chains.
usdcAddress	`string \| null`	The contract address for USDC.
usdtAddress	`string \| null`	The contract address for USDT.

CCTPConfig

Configuration for the Cross-Chain Transfer Protocol (CCTP).

interface CCTPConfig {
  contracts: CCTPContracts;
  domain: number;
  forwarderSupported: { destination: boolean; source: boolean };
}

Properties

Name	Type	Description
contracts	CCTPContracts	The contracts required for CCTP.
domain	number	The CCTP domain identifier.
forwarderSupported	`{ destination: boolean; source: boolean }`	Indicates whether the chain supports forwarder for source and destination.

Blockchain

Enumeration of all blockchains known to this library. This enum contains every blockchain that has a chain definition, regardless of whether bridging is currently supported. For chains that support bridging via CCTPv2, see BridgeChain.

enum Blockchain {
  Algorand = 'Algorand'
  Algorand_Testnet = 'Algorand_Testnet'
  Aptos = 'Aptos'
  Aptos_Testnet = 'Aptos_Testnet'
  Arbitrum = 'Arbitrum'
  Arbitrum_Sepolia = 'Arbitrum_Sepolia'
  Arc_Testnet = 'Arc_Testnet'
  Avalanche = 'Avalanche'
  Avalanche_Fuji = 'Avalanche_Fuji'
  Base = 'Base'
  Base_Sepolia = 'Base_Sepolia'
  Celo = 'Celo'
  Celo_Alfajores_Testnet = 'Celo_Alfajores_Testnet'
  Codex = 'Codex'
  Codex_Testnet = 'Codex_Testnet'
  Edge = 'Edge'
  Edge_Testnet = 'Edge_Testnet'
  Ethereum = 'Ethereum'
  Ethereum_Sepolia = 'Ethereum_Sepolia'
  Hedera = 'Hedera'
  Hedera_Testnet = 'Hedera_Testnet'
  HyperEVM = 'HyperEVM'
  HyperEVM_Testnet = 'HyperEVM_Testnet'
  Injective = 'Injective'
  Injective_Testnet = 'Injective_Testnet'
  Ink = 'Ink'
  Ink_Testnet = 'Ink_Testnet'
  Linea = 'Linea'
  Linea_Sepolia = 'Linea_Sepolia'
  Monad = 'Monad'
  Monad_Testnet = 'Monad_Testnet'
  Morph = 'Morph'
  Morph_Testnet = 'Morph_Testnet'
  NEAR = 'NEAR'
  NEAR_Testnet = 'NEAR_Testnet'
  Noble = 'Noble'
  Noble_Testnet = 'Noble_Testnet'
  Optimism = 'Optimism'
  Optimism_Sepolia = 'Optimism_Sepolia'
  Pharos = 'Pharos'
  Pharos_Testnet = 'Pharos_Testnet'
  Plume = 'Plume'
  Plume_Testnet = 'Plume_Testnet'
  Polkadot_Asset_Hub = 'Polkadot_Asset_Hub'
  Polkadot_Westmint = 'Polkadot_Westmint'
  Polygon = 'Polygon'
  Polygon_Amoy_Testnet = 'Polygon_Amoy_Testnet'
  Sei = 'Sei'
  Sei_Testnet = 'Sei_Testnet'
  Solana = 'Solana'
  Solana_Devnet = 'Solana_Devnet'
  Sonic = 'Sonic'
  Sonic_Testnet = 'Sonic_Testnet'
  Stellar = 'Stellar'
  Stellar_Testnet = 'Stellar_Testnet'
  Sui = 'Sui'
  Sui_Testnet = 'Sui_Testnet'
  Unichain = 'Unichain'
  Unichain_Sepolia = 'Unichain_Sepolia'
  World_Chain = 'World_Chain'
  World_Chain_Sepolia = 'World_Chain_Sepolia'
  XDC = 'XDC'
  XDC_Apothem = 'XDC_Apothem'
  ZKSync_Era = 'ZKSync_Era'
  ZKSync_Sepolia = 'ZKSync_Sepolia'
}

Values Algorand, Algorand_Testnet, Aptos, Aptos_Testnet, Arbitrum, Arbitrum_Sepolia, Arc_Testnet, Avalanche, Avalanche_Fuji, Base, Base_Sepolia, Celo, Celo_Alfajores_Testnet, Codex, Codex_Testnet, Edge, Edge_Testnet, Ethereum, Ethereum_Sepolia, Hedera, Hedera_Testnet, HyperEVM, HyperEVM_Testnet, Injective, Injective_Testnet, Ink, Ink_Testnet, Linea, Linea_Sepolia, Monad, Monad_Testnet, Morph, Morph_Testnet, NEAR, NEAR_Testnet, Noble, Noble_Testnet, Optimism, Optimism_Sepolia, Pharos, Pharos_Testnet, Plume, Plume_Testnet, Polkadot_Asset_Hub, Polkadot_Westmint, Polygon, Polygon_Amoy_Testnet, Sei, Sei_Testnet, Solana, Solana_Devnet, Sonic, Sonic_Testnet, Stellar, Stellar_Testnet, Sui, Sui_Testnet, Unichain, Unichain_Sepolia, World_Chain, World_Chain_Sepolia, XDC, XDC_Apothem, ZKSync_Era, ZKSync_Sepolia

KitContractType

Available kit contract types for enhanced chain functionality.

type KitContractType = "bridge" | "adapter";

Currency

Represents basic information about a currency or token.

interface Currency {
  decimals: number;
  name: string;
  symbol: string;
}

NonEVMChainDefinition

Represents chain definitions for non-EVM blockchains.

interface NonEVMChainDefinition {
  cctp: CCTPConfig \| null
  chain: Blockchain
  eurcAddress: string \| null
  explorerUrl: string
  gateway?: GatewayConfig
  isTestnet: boolean
  kitContracts?: Partial<Record<KitContractType, string>>
  name: string
  nativeCurrency: Currency
  rpcEndpoints: readonly string[]
  title?: string
  type: 'algorand' \| 'avalanche' \| 'solana' \| 'aptos' \| 'near' \| 'stellar' \| 'sui' \| 'hedera' \| 'noble' \| 'polkadot'
  usdcAddress: string \| null
  usdtAddress: string \| null
}

Properties

Name	Type	Description
cctp	`CCTPConfig \| null`	Optional CCTP configuration.
chain	Blockchain	The blockchain identifier from the Blockchain enum.
eurcAddress	`string \| null`	The contract address for EURC.
explorerUrl	string	Template URL for the blockchain explorer to view transactions.
gateway	GatewayConfig	Optional Gateway contract configuration for Gateway protocol support.
isTestnet	boolean	Indicates whether this is a testnet or mainnet.
kitContracts	`Partial<Record<KitContractType, string>>`	Optional kit-specific contract addresses for enhanced chain functionality.
name	string	The display name of the blockchain.
nativeCurrency	Currency	Information about the native currency of the blockchain.
rpcEndpoints	readonly string[]	Default RPC endpoints for connecting to the blockchain network.
title	string	Optional title or alternative name for the blockchain.
type	`'algorand' \| 'avalanche' \| 'solana' \| 'aptos' \| 'near' \| 'stellar' \| 'sui' \| 'hedera' \| 'noble' \| 'polkadot'`	Discriminator for non-EVM chains.
usdcAddress	`string \| null`	The contract address for USDC.
usdtAddress	`string \| null`	The contract address for USDT.

SwapConfig

Configuration options for swap operations. Controls swap behavior including allowance strategy, slippage tolerance, minimum output amounts, custom fees, and kit identification.

interface SwapConfig {
  allowanceStrategy?: AllowanceStrategy;
  slippageBps?: number;
  stopLimit?: string;
  customFee?: {
    percentageBps: number;
    recipientAddress: string;
  };
  kitKey?: string;
}

Properties

Name	Type	Description
allowanceStrategy	AllowanceStrategy	Strategy for granting token allowances to the swap contract. Defaults to `permit` with fallback to `approve`.
customFee	`{ percentageBps: number; recipientAddress: string; }`	Custom fee configuration for this swap (percentage-based approach). Allows specifying a percentage fee and recipient address at the transaction level. This is mutually exclusive with kit-level callback fee policy. If both are set, transaction-level takes precedence. For complex fee logic (VIP tiers, database lookups), use kit-level callback approach via `setCustomFeePolicy()` instead.
kitKey	string	Identifier for the kit instance initiating this swap. Used for tracking and analytics purposes.
slippageBps	number	Maximum acceptable slippage in basis points (BPS). 1 BPS = 0.01%, so 300 BPS = 3% slippage. Defaults to 300 BPS (3%).
stopLimit	string	Minimum acceptable output amount in human-readable format (stop-limit). If the estimated output falls below this value, the swap will fail. Expressed as a decimal string (e.g., `0.4` for 0.4 USDT). The value is automatically converted to base units using the tokenOut decimals.

AllowanceStrategy

Allowance strategy for token approvals during swap operations. Defines how token allowances should be granted to the swap contract:

permit: Use EIP-2612 permit signature (gas-efficient, no approval transaction)
approve: Traditional approval transaction

The default strategy is permit with fallback to approve if permit is not supported.

type AllowanceStrategy = "approve" | "permit" | "authorize";

FeeOperationType

Operation types that support the getFee/getFeeRecipient hooks.

type FeeOperationType = "bridge" | "swap";

AppKitActions

All actions available in AppKit.

type AppKitActions = AppKitBridgeActions & AppKitUnifiedBalanceActions;

AppKitBridgeActions

Prefixed bridge actions for AppKit. All BridgeKit events are prefixed with bridge. to namespace them within the AppKit event system.

type AppKitBridgeActions = PrefixActions<"bridge", DefaultBridgeKitActions>;

AppKitUnifiedBalanceActions

Prefixed unified balance actions for AppKit. All UnifiedBalanceKit (Gateway) events are prefixed with unifiedBalance. to namespace them within the AppKit event system.

type AppKitUnifiedBalanceActions = PrefixActions<
  "unifiedBalance",
  GatewayV1Actions
>;

DeveloperFeeHooks

interface DeveloperFeeHooks {
  getFee: (params: BridgeParams) => bigint \| Promise<bigint>
  getFeeRecipient: (chain: ChainDefinition) => string \| Promise<string>
}

Properties

Name	Type	Description
getFee	`(params: BridgeParams) => bigint \| Promise<bigint>`	Returns the developer fee in USDC’s smallest units (e.g. 6 decimals).
getFeeRecipient	`(chain: ChainDefinition) => string \| Promise<string>`	Returns the fee recipient for the given chain.

UnifiedBalanceKitConfig

Configuration options for initializing a UnifiedBalanceKit instance. When no providers are specified, the kit uses the default Gateway v1 provider. Any additional providers supplied via config are appended to the defaults.

interface UnifiedBalanceKitConfig {
  disableAnalytics?: boolean;
  disableErrorReporting?: boolean;
  excludeDefaultProviders?: boolean;
  providers?: TExtraProviders;
}

Properties

Name	Type	Description
disableAnalytics	boolean	Disable analytics telemetry (success events with `txHash`). When `true`, the SDK will not POST to the telemetry endpoint after successful verb operations. Defaults to `false` (enabled).
disableErrorReporting	boolean	Disable error telemetry. When `true`, the SDK will not POST error details to the telemetry endpoint when public methods throw. Defaults to `false` (enabled).
excludeDefaultProviders	boolean	Skip the built-in default providers when assembling the context. By default the kit prepends the standard Gateway v1 provider so `providers` is treated as additive. Pass `true` to use only the providers supplied in UnifiedBalanceKitConfig.providers. Useful when stubbing the gateway in integration tests, when running against a self-hosted gateway replacement, or any time you want full control over which provider serves a given chain.
providers	TExtraProviders	Optional array of additional Gateway providers. If not provided, default providers will be initialized.

SupportedTokenInput

Case-insensitive variant of SupportedToken for user-facing input. Accepts the canonical uppercase form, fully lowercase, and title-case (e.g. 'USDC', 'usdc', 'Usdc'). Arbitrary mixed-case input like 'uSdC' is handled at runtime by the Zod schema and normalizeToken, so exhaustive compile-time permutations are unnecessary. Avoiding a recursive CasePermutations type prevents 2^N type-literal explosion as the token list grows.

type SupportedTokenInput =
  | SupportedToken
  | Lowercase<SupportedToken>
  | Capitalize<Lowercase<SupportedToken>>;

SupportedToken

type SupportedToken = (typeof SUPPORTED_TOKENS)[number];

FeeEntry

A single fee line item within an estimate.

interface FeeEntry {
  allocations?: FeeAllocation[];
  amount: string;
  recipientAddress?: string;
  token: string;
  type: FeeType;
}

Properties

Name	Type	Description
allocations	FeeAllocation[]	Per-chain breakdown of the fee. Omitted for flat fees (e.g. forwarder).
amount	string	Aggregate fee amount (human-readable decimal string).
recipientAddress	string	When `type === 'kit'`, the address that receives the kit fee. Omitted for other fee types.
token	string	The token in which this fee is denominated (e.g. `'USDC'`, `'ETH'`).
type	FeeType	The category of this fee.

FeeAllocation

Per-chain breakdown of a fee amount.

interface FeeAllocation {
  amount: string;
  chain: Blockchain;
}

Properties

Name	Type	Description
amount	string	The fee amount on this chain (human-readable decimal string).
chain	Blockchain	The chain to which this portion of the fee applies.

FeeType

Fee category describing the origin of a fee line item.

'provider' — Fee charged by the crosschain provider (e.g. protocol fee).
'gasFee' — On-chain gas cost denominated in the transfer token (e.g. USDC).
'kit' — Fee charged by the kit / developer integration.
'forwarder' — Fee charged by Circle’s Forwarding Service for automatic mint.

type FeeType = "provider" | "gasFee" | "kit" | "forwarder";

NetworkType

Network type for balance queries when the target chain(s) are not explicitly specified. Default is mainnet.

type NetworkType = "mainnet" | "testnet";

BalanceWithPendingBreakdown

Per-account balance breakdown used in GetBalancesResult. When includePending is true, totalPending is present and each chain entry may include pendingBalance and pendingTransactions.

interface BalanceWithPendingBreakdown {
  depositor: string;
  totalConfirmed: string;
  totalPending?: string;
  breakdown: ChainBalanceBreakdown[];
}

Properties

Name	Type	Description
breakdown	ChainBalanceBreakdown[]	Per-chain breakdown for this depositor.
depositor	string	Gateway account (depositor) address.
totalConfirmed	string	Total confirmed balance across chains (human-readable decimal string).
totalPending	string	Total pending balance across chains. Present only when `includePending` is true.

ChainBalanceBreakdown

Per-chain balance within a breakdown in GetBalancesResult. When includePending is true, pendingBalance and pendingTransactions are present.

interface ChainBalanceBreakdown {
  chain: Blockchain;
  confirmedBalance: string;
  pendingBalance?: string;
  pendingTransactions?: PendingBalanceTransaction[];
}

Properties

Name	Type	Description
chain	Blockchain	The chain.
confirmedBalance	string	Confirmed balance (human-readable decimal string).
pendingBalance	string	Pending balance on this chain. Present only when GetBalancesParams.includePending is true.
pendingTransactions	PendingBalanceTransaction[]	Pending deposit transactions on this chain. Present only when GetBalancesParams.includePending is true.

PendingBalanceTransaction

A pending transaction included in GetBalancesResult when includePending is true.

interface PendingBalanceTransaction {
  transactionHash: string;
  amount: string;
  blockTimestamp: string;
}

DelegateStatus

The finality-aware status of a delegate on a Gateway account.

'none' — not a delegate on-chain.
'pending' — delegate set on-chain but Gateway hasn’t finalized it yet; spend will fail until the status advances to 'ready'.
'ready' — finalized at Gateway; spend will succeed.

type DelegateStatus = "none" | "pending" | "ready";

AllocationResult

Extends Allocation with the resolved source Gateway account address.

interface AllocationResult {
  amount: string;
  chain: UnifiedBalanceChainIdentifier;
  sourceAccount: string;
}

Properties

Name	Type	Description
amount	string	The amount to pull from this chain (human-readable decimal string).
chain	UnifiedBalanceChainIdentifier	The chain from which to pull the funds.
sourceAccount	string	The Gateway account address from which this amount was pulled.

UnifiedBalanceChainIdentifier

Type representing valid unified-balance chain identifiers. Constrains chain parameters to only accept chains that support Gateway V1 operations. Accepts:

An UnifiedBalanceChain enum value (e.g., UnifiedBalanceChain.Ethereum)
A string literal matching an UnifiedBalanceChain value (e.g., 'Ethereum')
A ChainDefinition object for a supported chain

type UnifiedBalanceChainIdentifier =
  | ChainDefinition
  | UnifiedBalanceChain
  | unknown;

UnifiedBalanceChain

Enumeration of blockchains that support Gateway V1 operations (deposit, spend, balance, delegate, removeFund). Derived from the full Blockchain enum but filtered to only include chains with active Gateway V1 contract support. When new chains gain Gateway V1 support, they are added to this enum.

enum UnifiedBalanceChain {
  Arbitrum = 'Arbitrum'
  Arbitrum_Sepolia = 'Arbitrum_Sepolia'
  Arc_Testnet = 'Arc_Testnet'
  Avalanche = 'Avalanche'
  Avalanche_Fuji = 'Avalanche_Fuji'
  Base = 'Base'
  Base_Sepolia = 'Base_Sepolia'
  Ethereum = 'Ethereum'
  Ethereum_Sepolia = 'Ethereum_Sepolia'
  HyperEVM = 'HyperEVM'
  HyperEVM_Testnet = 'HyperEVM_Testnet'
  Optimism = 'Optimism'
  Optimism_Sepolia = 'Optimism_Sepolia'
  Polygon = 'Polygon'
  Polygon_Amoy_Testnet = 'Polygon_Amoy_Testnet'
  Sei = 'Sei'
  Sei_Testnet = 'Sei_Testnet'
  Solana = 'Solana'
  Solana_Devnet = 'Solana_Devnet'
  Sonic = 'Sonic'
  Sonic_Testnet = 'Sonic_Testnet'
  Unichain = 'Unichain'
  Unichain_Sepolia = 'Unichain_Sepolia'
  World_Chain = 'World_Chain'
  World_Chain_Sepolia = 'World_Chain_Sepolia'
}

Values Arbitrum, Arbitrum_Sepolia, Arc_Testnet, Avalanche, Avalanche_Fuji, Base, Base_Sepolia, Ethereum, Ethereum_Sepolia, HyperEVM, HyperEVM_Testnet, Optimism, Optimism_Sepolia, Polygon, Polygon_Amoy_Testnet, Sei, Sei_Testnet, Solana, Solana_Devnet, Sonic, Sonic_Testnet, Unichain, Unichain_Sepolia, World_Chain, World_Chain_Sepolia

SpendStep

Data payload for a single step in a spend operation.

interface SpendStep {
  data?: unknown
  error?: unknown
  errorMessage?: string
  explorerUrl?: string
  name: string
  state: 'pending' \| 'success' \| 'error'
  txHash?: string
}

Properties

Name	Type	Description
data	unknown	Optional data for the step.
error	unknown	Optional raw error object.
errorMessage	string	Optional human-readable error message.
explorerUrl	string	Optional explorer URL for viewing this transaction on a block explorer.
name	string	Human-readable name of the step (e.g., “buildBurnIntents”, “mint”).
state	`'pending' \| 'success' \| 'error'`	The state of the step.
txHash	string	Optional transaction hash for this step (if applicable).

CCTPSplitConfig

Split CCTP contract configuration. Used by chains that deploy separate TokenMessenger and MessageTransmitter contracts. This is the traditional CCTP architecture used by most EVM chains.

interface CCTPSplitConfig {
  confirmations: number;
  messageTransmitter: string;
  tokenMessenger: string;
  type: "split";
}

CCTPMergedConfig

Merged CCTP contract configuration. Used by chains that deploy a single unified CCTP contract. This simplified architecture is used by newer chain integrations.

interface CCTPMergedConfig {
  confirmations: number;
  contract: string;
  type: "merged";
}

BaseChainDefinition

Base information that all chain definitions must include.

interface BaseChainDefinition {
  cctp: CCTPConfig \| null
  chain: Blockchain
  eurcAddress: string \| null
  explorerUrl: string
  gateway?: GatewayConfig
  isTestnet: boolean
  kitContracts?: Partial<Record<KitContractType, string>>
  name: string
  nativeCurrency: Currency
  rpcEndpoints: readonly string[]
  title?: string
  usdcAddress: string \| null
  usdtAddress: string \| null
}

Properties

Name	Type	Description
cctp	`CCTPConfig \| null`	Optional CCTP configuration.
chain	Blockchain	The blockchain identifier from the Blockchain enum.
eurcAddress	`string \| null`	The contract address for EURC.
explorerUrl	string	Template URL for the blockchain explorer to view transactions.
gateway	GatewayConfig	Optional Gateway contract configuration for Gateway protocol support.
isTestnet	boolean	Indicates whether this is a testnet or mainnet.
kitContracts	`Partial<Record<KitContractType, string>>`	Optional kit-specific contract addresses for enhanced chain functionality.
name	string	The display name of the blockchain.
nativeCurrency	Currency	Information about the native currency of the blockchain.
rpcEndpoints	readonly string[]	Default RPC endpoints for connecting to the blockchain network.
title	string	Optional title or alternative name for the blockchain.
usdcAddress	`string \| null`	The contract address for USDC.
usdtAddress	`string \| null`	The contract address for USDT.

TokenInfo

Represents the metadata associated with a token.

interface TokenInfo {
  decimals: number;
  name: string;
  symbol: string;
}

Event Types

Bridge Events

Bridge events are emitted for each provider in the kit. Events for the built-in CCTP provider follow its transaction steps. You can subscribe to each event multiple times with different callbacks. Bridge events are prefixed with bridge. to namespace them within AppKit:

Event	Description
`bridge.approve`	Token approval transaction completed
`bridge.burn`	Source chain burn transaction completed
`bridge.attestation`	CCTP attestation received
`bridge.mint`	Destination chain mint transaction completed
`*`	Wildcard listener for all events

Usage Example

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

const kit = new AppKit();

// Listen to specific bridge action
kit.on("bridge.approve", (payload) => {
  console.log("Approval transaction:", payload.values.txHash);
});

// Listen to unified balance action
kit.on("unifiedBalance.gateway.spend.succeeded", (payload) => {
  console.log("Spend succeeded:", payload.data);
});

// Listen to all actions
kit.on("*", (payload) => {
  console.log("Action:", payload);
});

Swap tokens across chains

⌘I

​AppKit Class

​constructor(config?)

​AppKitConfig

​Methods

​bridge(params)

​BridgeParams

​BridgeResult

​estimateBridge(params)

​BridgeParams

​EstimateResult

​estimateSend(params)

​SendParams

​EstimatedGas

​estimateSwap(params)

​SwapParams

​SwapEstimate

​getSupportedChains(operationType)

​OperationType

​off(action)

​on(action)

​retryBridge(result)

​BridgeResult

​RetryContext

​BridgeResult

​send(params)

​SendParams

​BridgeStep

​swap(params)

​SwapParams

​SwapResult

​kit.unifiedBalance Methods

​addDelegate(params)

​UpdateDelegateParams

​UpdateDelegateResult

​deposit(params)

​DepositParams

​DepositResult

​depositFor(params)

​DepositForParams

​DepositResult

​estimateSpend(params)

​SpendParams

​EstimateSpendResult

​getBalances(params)

​GetBalancesParams

​GetBalancesResult

​getDelegateStatus(params)

​GetDelegateStatusParams

​getSupportedChains(token)

​GetSupportedChainsOptions

​initiateRemoveFund(params)

​InitiateRemoveFundParams

​InitiateRemoveFundResult

​off(action)

​on(action)

​removeCustomFeePolicy()

​removeDelegate(params)

​UpdateDelegateParams

​UpdateDelegateResult

​removeFund(params)

​RemoveFundParams

​RemoveFundResult

​setCustomFeePolicy(policy)

​CustomFeePolicy

​spend(params)

​SpendParams

​SpendResult

​Supporting Types

​BridgeConfig

​TransferSpeed

​AdapterContext

​ChainDefinition

​EVMChainDefinition

​CCTPConfig

​Blockchain

​KitContractType

​Currency

​NonEVMChainDefinition

​SwapConfig

​AllowanceStrategy

AppKit Class

constructor(config?)

AppKitConfig

Methods

bridge(params)

BridgeParams

BridgeResult

estimateBridge(params)

BridgeParams

EstimateResult

estimateSend(params)

SendParams

EstimatedGas

estimateSwap(params)

SwapParams

SwapEstimate

getSupportedChains(operationType)

OperationType

off(action)

on(action)

retryBridge(result)

BridgeResult

RetryContext

BridgeResult

send(params)

SendParams

BridgeStep

swap(params)

SwapParams

SwapResult

kit.unifiedBalance Methods

addDelegate(params)

UpdateDelegateParams

UpdateDelegateResult

deposit(params)

DepositParams

DepositResult

depositFor(params)

DepositForParams

DepositResult

estimateSpend(params)

SpendParams

EstimateSpendResult

getBalances(params)

GetBalancesParams

GetBalancesResult

getDelegateStatus(params)

GetDelegateStatusParams

getSupportedChains(token)

GetSupportedChainsOptions

initiateRemoveFund(params)

InitiateRemoveFundParams

InitiateRemoveFundResult

off(action)

on(action)

removeCustomFeePolicy()

removeDelegate(params)

UpdateDelegateParams

UpdateDelegateResult

removeFund(params)

RemoveFundParams

RemoveFundResult

setCustomFeePolicy(policy)

CustomFeePolicy

spend(params)

SpendParams

SpendResult

Supporting Types

BridgeConfig

TransferSpeed

AdapterContext

ChainDefinition

EVMChainDefinition

CCTPConfig

Blockchain

KitContractType

Currency

NonEVMChainDefinition

SwapConfig

AllowanceStrategy