> ## Documentation Index > Fetch the complete documentation index at: https://docs.arc.io/llms.txt > Use this file to discover all available pages before exploring further. # App Kit SDK Reference > API reference for App Kit's public interfaces, methods, and types {/* Do not edit this file directly - regenerate using: yarn sdk-gen */} 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. ```typescript theme={null} constructor(config?: AppKitConfig) ``` **Parameters** | Name | Type | Description | | ------ | ------------------------------- | ------------------------------------------------------------------------------------------------ | | config | [`AppKitConfig`](#appkitconfig) | Optional configuration for fee estimation, developer fees, and the underlying UnifiedBalanceKit. | **Usage** ```typescript theme={null} 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 ```typescript theme={null} type AppKitConfig = CreateContextParams & { developerFee?: Partial; disableErrorReporting?: boolean; unifiedBalance?: UnifiedBalanceKitConfig; }; ``` **Properties** | Name | Type | Description | | --------------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | developerFee | `Partial` | 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. ```typescript theme={null} bridge(params: BridgeParams): Promise ``` **Parameters** | Name | Type | Description | | ------ | ------------------------------- | ------------------------------------------------------------------- | | params | [`BridgeParams`](#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. ```typescript theme={null} interface BridgeParams { amount: string; config?: BridgeConfig; from: AdapterContext; invocationMeta?: InvocationMeta; to: BridgeDestination; 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. ```typescript theme={null} 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** ```typescript theme={null} 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. ```typescript theme={null} estimateBridge(params: BridgeParams): Promise ``` **Parameters** | Name | Type | Description | | ------ | --------------------------------- | ------------------------------------------------------------------- | | params | [`BridgeParams`](#bridgeparams-2) | 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. ```typescript theme={null} interface BridgeParams { amount: string; config?: BridgeConfig; from: AdapterContext; invocationMeta?: InvocationMeta; to: BridgeDestination; 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. ```typescript theme={null} 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** ```typescript theme={null} 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. ```typescript theme={null} estimateSend(params: SendParams): Promise ``` **Parameters** | Name | Type | Description | | ------ | --------------------------- | ------------------------------------------------------------------------- | | params | [`SendParams`](#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'`. ```typescript theme={null} interface SendParams { amount: string from: AdapterContext to: string \| Adapter 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. ```typescript theme={null} interface EstimatedGas { fee: string; gas: bigint; gasPrice: bigint; } ``` **Usage Examples** ```typescript theme={null} const estimate = await kit.estimateSend({ from: { adapter: sourceAdapter, chain: "Ethereum" }, to: recipientAdapter, amount: "100.50", token: "USDC", }); console.log("Estimated gas:", estimate.gas); ``` ```typescript theme={null} 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. ```typescript theme={null} estimateSwap(params: SwapParams): Promise ``` **Parameters** | Name | Type | Description | | ------ | --------------------------- | ------------------------------------------------------------- | | params | [`SwapParams`](#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. ```typescript theme={null} interface SwapParams< TFromAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities, > { from: SwapAdapterContext; 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 ```typescript theme={null} 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** ```typescript theme={null} 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). ```typescript theme={null} getSupportedChains(operationType?: OperationType): ChainDefinition[] ``` **Parameters** | Name | Type | Description | | ------------- | --------------------------------- | ------------------------------------------------------------------------------------------- | | operationType | [`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. ```typescript theme={null} type OperationType = FeeOperationType | "earn" | "unifiedBalance"; ``` **Returns** ChainDefinition\[] **Usage Examples** ```typescript theme={null} 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})`); }); ``` ```typescript theme={null} 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. ```typescript theme={null} off(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** ```typescript theme={null} 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. ```typescript theme={null} on(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** ```typescript theme={null} 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. ```typescript theme={null} retryBridge(result: BridgeResult, retryContext: RetryContext): Promise ``` **Parameters** | Name | Type | Description | | ------------ | --------------------------------- | --------------------------------------------------------------- | | result | [`BridgeResult`](#bridgeresult-2) | The bridge result from the failed operation | | retryContext | [`RetryContext`](#retrycontext) | The retry context with source and optional destination adapters | #### 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. ```typescript theme={null} 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. ```typescript theme={null} interface RetryContext { from: Adapter; to?: Adapter; } ``` **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-3) #### 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. ```typescript theme={null} 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** ```typescript theme={null} 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. ```typescript theme={null} send(params: SendParams): Promise ``` **Parameters** | Name | Type | Description | | ------ | ----------------------------- | ----------------------------------------------------------------- | | params | [`SendParams`](#sendparams-2) | Send parameters containing source, destination, amount, and 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'`. ```typescript theme={null} interface SendParams { amount: string from: AdapterContext to: string \| Adapter 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. ```typescript theme={null} 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** ```typescript theme={null} // 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); ``` ```typescript theme={null} // 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); ``` ```typescript theme={null} // 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. ```typescript theme={null} swap(params: SwapParams): Promise ``` **Parameters** | Name | Type | Description | | ------ | ----------------------------- | ------------------------------------------------------------- | | params | [`SwapParams`](#swapparams-2) | 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. ```typescript theme={null} interface SwapParams< TFromAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities, > { from: SwapAdapterContext; 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. ```typescript theme={null} 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** ```typescript theme={null} 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. ```typescript theme={null} addDelegate(params: UpdateDelegateParams): Promise ``` **Parameters** | Name | Type | Description | | ------ | ----------------------------------------------- | ----------------------------------------------------- | | params | [`UpdateDelegateParams`](#updatedelegateparams) | The owner's adapter context and the delegate address. | #### UpdateDelegateParams Parameters for adding or removing a delegate on a Gateway account. ```typescript theme={null} interface UpdateDelegateParams { delegateAddress: string; from: AdapterContext; 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. ```typescript theme={null} 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** ```typescript theme={null} 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. ```typescript theme={null} deposit(params: DepositParams): Promise ``` **Parameters** | Name | Type | Description | | ------ | --------------------------------- | ----------------------------------------------------------- | | params | [`DepositParams`](#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. ```typescript theme={null} interface DepositParams< TAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities, TChainIdentifier extends UnifiedBalanceChainIdentifier = UnifiedBalanceChainIdentifier, > { from: AdapterContext; 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. ```typescript theme={null} 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** ```typescript theme={null} 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). ```typescript theme={null} depositFor(params: DepositForParams): Promise ``` **Parameters** | Name | Type | Description | | ------ | --------------------------------------- | ------------------------------------------------------------------------------------------- | | params | [`DepositForParams`](#depositforparams) | Deposit details including the depositor context, amount, and the account address to credit. | #### DepositForParams Parameters for depositing tokens into another Gateway account. ```typescript theme={null} interface DepositForParams< TAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities, TChainIdentifier extends UnifiedBalanceChainIdentifier = UnifiedBalanceChainIdentifier, > extends Omit< DepositParams, "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-2) #### DepositResult Result returned after a successful deposit operation. ```typescript theme={null} 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** ```typescript theme={null} 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. ```typescript theme={null} estimateSpend(params: SpendParams): Promise ``` **Parameters** | Name | Type | Description | | ------ | ----------------------------- | ------------------------------------------------------------- | | params | [`SpendParams`](#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. ```typescript theme={null} type SpendParams = | SpendParamsWithFrom< TFromAdapterCapabilities, TToAdapterCapabilities, TChainIdentifier > | SpendParamsRetry< TFromAdapterCapabilities, TToAdapterCapabilities, TChainIdentifier >; ``` **Returns** [`Promise`](#estimatespendresult) #### EstimateSpendResult Cost estimation for a spend (mint) operation. ```typescript theme={null} interface EstimateSpendResult { fees: FeeEntry[]; } ``` **Properties** | Name | Type | Description | | ---- | ----------- | ----------------------------------------------- | | fees | FeeEntry\[] | Itemised fee breakdown for the spend operation. | **Usage Example** ```typescript theme={null} 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. ```typescript theme={null} getBalances(params: GetBalancesParams): Promise ``` **Parameters** | Name | Type | Description | | ------ | ----------------------------------------- | ------------------------------------------------------ | | params | [`GetBalancesParams`](#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. ```typescript theme={null} interface GetBalancesParams< TAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities, > { token?: SupportedTokenInput; sources: Sources; 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. ```typescript theme={null} 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** ```typescript theme={null} const balances = await kit.unifiedBalance.getBalances({ token: "USDC", sources: { address: "0x1234…abcd" }, }); ``` *** ### getDelegateStatus(params) Check the finality-aware delegate status of an address. ```typescript theme={null} getDelegateStatus(params: GetDelegateStatusParams): Promise ``` **Parameters** | Name | Type | Description | | ------ | ----------------------------------------------------- | -------------------------------------------------- | | params | [`GetDelegateStatusParams`](#getdelegatestatusparams) | The adapter context and delegate address to check. | #### GetDelegateStatusParams Parameters for checking the delegate status of an address on a Gateway account. ```typescript theme={null} interface GetDelegateStatusParams { delegateAddress: string; from: AdapterContext; 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** ```typescript theme={null} 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. ```typescript theme={null} getSupportedChains(token?: SupportedToken, options?: GetSupportedChainsOptions): ChainDefinition[] ``` **Parameters** | Name | Type | Description | | ------- | --------------------------------------------------------- | -------------------------------------------- | | token | `'USDC'` | Optional token filter (defaults to USDC). | | options | [`GetSupportedChainsOptions`](#getsupportedchainsoptions) | Optional filtering (e.g. forwarder support). | #### GetSupportedChainsOptions Options for filtering supported chains. ```typescript theme={null} 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** ```typescript theme={null} const chains = kit.unifiedBalance.getSupportedChains(); const usdcChains = kit.unifiedBalance.getSupportedChains("USDC"); ``` *** ### initiateRemoveFund(params) Kick off a delayed fund removal from an account. ```typescript theme={null} initiateRemoveFund(params: InitiateRemoveFundParams): Promise ``` **Parameters** | Name | Type | Description | | ------ | ------------------------------------------------------- | ------------------------------------------------------- | | params | [`InitiateRemoveFundParams`](#initiateremovefundparams) | The account owner's adapter context, amount, and token. | #### InitiateRemoveFundParams Parameters for initiating a delayed fund removal from a Gateway account. ```typescript theme={null} interface InitiateRemoveFundParams< TAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities, TChainIdentifier extends UnifiedBalanceChainIdentifier = UnifiedBalanceChainIdentifier, > { from: AdapterContext; 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. ```typescript theme={null} 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** ```typescript theme={null} 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. ```typescript theme={null} 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** ```typescript theme={null} 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` | ```typescript theme={null} 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** ```typescript theme={null} 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. ```typescript theme={null} removeCustomFeePolicy(): void ``` **Usage Example** ```typescript theme={null} kit.unifiedBalance.removeCustomFeePolicy(); ``` *** ### removeDelegate(params) Revoke spending rights from a delegate on the owner's account. ```typescript theme={null} removeDelegate(params: UpdateDelegateParams): Promise ``` **Parameters** | Name | Type | Description | | ------ | ------------------------------------------------- | ----------------------------------------------------- | | params | [`UpdateDelegateParams`](#updatedelegateparams-2) | The owner's adapter context and the delegate address. | #### UpdateDelegateParams Parameters for adding or removing a delegate on a Gateway account. ```typescript theme={null} interface UpdateDelegateParams { delegateAddress: string; from: AdapterContext; 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-2) #### UpdateDelegateResult Result returned after a successful add or remove delegate operation. ```typescript theme={null} 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** ```typescript theme={null} const result = await kit.unifiedBalance.removeDelegate({ from: { adapter, chain: "Ethereum" }, delegateAddress: "0xDelegate…", }); ``` *** ### removeFund(params) Complete a fund removal once the activation period has passed. ```typescript theme={null} removeFund(params: RemoveFundParams): Promise ``` **Parameters** | Name | Type | Description | | ------ | --------------------------------------- | ----------------------------------------------------------- | | params | [`RemoveFundParams`](#removefundparams) | The account owner context matching the original initiation. | #### RemoveFundParams Parameters for completing a fund removal after the activation period. ```typescript theme={null} interface RemoveFundParams< TAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities, TChainIdentifier extends UnifiedBalanceChainIdentifier = UnifiedBalanceChainIdentifier, > { from: AdapterContext; 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. ```typescript theme={null} 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** ```typescript theme={null} 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`. ```typescript theme={null} setCustomFeePolicy(policy: CustomFeePolicy): void ``` **Parameters** | Name | Type | Description | | ------ | ------------------------------------- | ---------------------------------------------------- | | policy | [`CustomFeePolicy`](#customfeepolicy) | The fee computation and recipient resolution policy. | #### CustomFeePolicy ```typescript theme={null} interface CustomFeePolicy { computeFee: ( context: SwapFeeContext, ) => Promise | string; resolveFeeRecipientAddress: < TFromAdapterCapabilities extends AdapterCapabilities, >( feePayoutChain: ChainDefinition, context: SwapFeeContext, ) => Promise | string; } ``` **Usage Example** ```typescript theme={null} 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. ```typescript theme={null} spend(params: SpendParams): Promise ``` **Parameters** | Name | Type | Description | | ------ | ------------------------------- | ---------------------------------------------------------- | | params | [`SpendParams`](#spendparams-2) | 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. ```typescript theme={null} type SpendParams = | SpendParamsWithFrom< TFromAdapterCapabilities, TToAdapterCapabilities, TChainIdentifier > | SpendParamsRetry< TFromAdapterCapabilities, TToAdapterCapabilities, TChainIdentifier >; ``` **Returns** [`Promise`](#spendresult) #### SpendResult Result returned after a successful spend (mint) operation. ```typescript theme={null} 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** ```typescript theme={null} 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. ```typescript theme={null} 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. ```typescript theme={null} 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. ```typescript theme={null} type AdapterContext = { adapter: Adapter; chain: TChainIdentifier; } & AddressField>; ``` **Properties** | Name | Type | Description | | ------- | ------------------------------- | --------------------------------------------------------------------------------------- | | adapter | `Adapter` | 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. ```typescript theme={null} type ChainDefinition = EVMChainDefinition | NonEVMChainDefinition; ``` *** ### EVMChainDefinition Represents chain definitions for Ethereum Virtual Machine (EVM) compatible blockchains. ```typescript theme={null} interface EVMChainDefinition { cctp: CCTPConfig \| null chain: Blockchain chainId: number eurcAddress: string \| null explorerUrl: string gateway?: GatewayConfig isTestnet: boolean kitContracts?: Partial> 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>` | 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). ```typescript theme={null} 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. ```typescript theme={null} 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. ```typescript theme={null} type KitContractType = "bridge" | "adapter"; ``` *** ### Currency Represents basic information about a currency or token. ```typescript theme={null} interface Currency { decimals: number; name: string; symbol: string; } ``` *** ### NonEVMChainDefinition Represents chain definitions for non-EVM blockchains. ```typescript theme={null} interface NonEVMChainDefinition { cctp: CCTPConfig \| null chain: Blockchain eurcAddress: string \| null explorerUrl: string gateway?: GatewayConfig isTestnet: boolean kitContracts?: Partial> 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>` | 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. ```typescript theme={null} 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. ```typescript theme={null} type AllowanceStrategy = "approve" | "permit" | "authorize"; ``` *** ### FeeOperationType Operation types that support the `getFee`/`getFeeRecipient` hooks. ```typescript theme={null} type FeeOperationType = "bridge" | "swap"; ``` *** ### AppKitActions All actions available in AppKit. ```typescript theme={null} 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. ```typescript theme={null} 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. ```typescript theme={null} type AppKitUnifiedBalanceActions = PrefixActions< "unifiedBalance", GatewayV1Actions >; ``` *** ### DeveloperFeeHooks ```typescript theme={null} interface DeveloperFeeHooks { getFee: (params: BridgeParams) => bigint \| Promise getFeeRecipient: (chain: ChainDefinition) => string \| Promise } ``` **Properties** | Name | Type | Description | | --------------- | ------------------------------------------------------- | --------------------------------------------------------------------- | | getFee | `(params: BridgeParams) => bigint \| Promise` | Returns the developer fee in USDC's smallest units (e.g. 6 decimals). | | getFeeRecipient | `(chain: ChainDefinition) => string \| Promise` | 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. ```typescript theme={null} 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. ```typescript theme={null} type SupportedTokenInput = | SupportedToken | Lowercase | Capitalize>; ``` *** ### SupportedToken ```typescript theme={null} type SupportedToken = (typeof SUPPORTED_TOKENS)[number]; ``` *** ### FeeEntry A single fee line item within an estimate. ```typescript theme={null} 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. ```typescript theme={null} 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. ```typescript theme={null} type FeeType = "provider" | "gasFee" | "kit" | "forwarder"; ``` *** ### NetworkType Network type for balance queries when the target chain(s) are not explicitly specified. Default is mainnet. ```typescript theme={null} 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`. ```typescript theme={null} 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. ```typescript theme={null} 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. ```typescript theme={null} 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. ```typescript theme={null} type DelegateStatus = "none" | "pending" | "ready"; ``` *** ### AllocationResult Extends Allocation with the resolved source Gateway account address. ```typescript theme={null} 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 ```typescript theme={null} 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. ```typescript theme={null} 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. ```typescript theme={null} 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. ```typescript theme={null} 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. ```typescript theme={null} interface CCTPMergedConfig { confirmations: number; contract: string; type: "merged"; } ``` *** ### BaseChainDefinition Base information that all chain definitions must include. ```typescript theme={null} interface BaseChainDefinition { cctp: CCTPConfig \| null chain: Blockchain eurcAddress: string \| null explorerUrl: string gateway?: GatewayConfig isTestnet: boolean kitContracts?: Partial> 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>` | 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. ```typescript theme={null} 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** ```typescript theme={null} 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); }); ```