App Kit SDK Reference

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

AppKit Class

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

constructor(config?)

Creates a new AppKit instance.

constructor(config?: AppKitConfig)

Parameters

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

Usage

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

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

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

AppKitConfig

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

Properties

Name	Type	Description
developerFee	`Partial<DeveloperFeeHooks>`	Optional developer fee hooks passed through to BridgeKit when both are provided
disableAnalytics	boolean	Disable success analytics for the underlying EarnKit, SwapKit, and UnifiedBalanceKit. When `true`, completed earn, swap, and unified balance operations will not POST analytics events. This does not disable error reporting; use AppKitConfig.disableErrorReporting for that. Defaults to `false`.
disableErrorReporting	boolean	Disable error telemetry for all underlying kits. When `true`, BridgeKit, SwapKit, EarnKit, and UnifiedBalanceKit will not POST error details to the telemetry endpoint. Defaults to `false`.
unifiedBalance	UnifiedBalanceKitConfig	Optional config forwarded to the underlying UnifiedBalanceKit.

Methods

bridge(params)

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

bridge(params: BridgeParams): Promise<BridgeResult>

Parameters

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

BridgeParams

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

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

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

Properties

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

Returns Promise<BridgeResult>

BridgeResult

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

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

Properties

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

Usage Example

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

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

estimateBridge(params)

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

estimateBridge(params: BridgeParams): Promise<EstimateResult>

Parameters

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

BridgeParams

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

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

Properties

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

Returns Promise<EstimateResult>

EstimateResult

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

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

Properties

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

Usage Example

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

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

estimateSend(params)

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

estimateSend(params: SendParams): Promise<EstimatedGas>

Parameters

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

SendParams

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

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

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

Properties

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

Returns Promise<EstimatedGas>

EstimatedGas

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

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

Usage Examples

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

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

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

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

estimateSwap(params)

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

estimateSwap(params: SwapParams): Promise<SwapEstimate>

Parameters

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

SwapParams

interface SwapParams<
  TFromAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities,
> {
  from: SwapAdapterContext<TFromAdapterCapabilities>;
  tokenIn: SupportedSwapToken;
  tokenOut: SupportedSwapToken;
  amountIn: string;
  to?: SwapDestination;
  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.
to	SwapDestination	Optional destination chain/address. For same-chain swaps this may be omitted and the source wallet address is used as the recipient. crosschain swaps require `recipientAddress`.
tokenIn	SupportedSwapToken	The input token to swap from. Supports stablecoins (USDC, USDT, EURC, USDe, DAI, PYUSD), wrapped tokens (WBTC, WETH, WSOL, WAVAX, WPOL), and native tokens (NATIVE or chain-specific symbols).
tokenOut	SupportedSwapToken	The output token to swap to. Supports stablecoins (USDC, USDT, EURC, USDe, DAI, PYUSD), wrapped tokens (WBTC, WETH, WSOL, WAVAX, WPOL), and native tokens (NATIVE or chain-specific symbols).

Returns Promise<SwapEstimate>

SwapEstimate

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

interface SwapEstimate {
  readonly tokenIn: SupportedSwapToken;
  readonly tokenOut: SupportedSwapToken;
  readonly amountIn: string;
  readonly chainIn: Blockchain;
  readonly chainOut: Blockchain;
  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
chainIn	Blockchain	The source chain of the swap. Returns the chain name (e.g. `Blockchain.Ethereum`). Use `getChainByEnum(chainIn)` to resolve back to a full `ChainDefinition`.
chainOut	Blockchain	Destination chain of the swap. Equal to `chainIn` for same-chain estimates; different for crosschain estimates. Always populated.
estimatedOutput	TokenAmount	Estimated output amount with token information.
fees	readonly ServiceSwapFee[]	Detailed fee breakdown for the swap operation.
fromAddress	string	The address that will initiate the swap.
stopLimit	TokenAmount	Estimated minimum token out amount with token information. This represents the minimum amount of tokens the user should receive after accounting for slippage. Amount is in human-readable decimal format.
toAddress	string	The address that will receive the swapped tokens.
tokenIn	SupportedSwapToken	The input token that will be swapped from.
tokenOut	SupportedSwapToken	The output token that will be swapped to.

Usage Example

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

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

getSupportedChains(operationType)

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

getSupportedChains(operationType?: OperationType): ChainDefinition[]

Parameters

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

OperationType

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

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

Returns ChainDefinition[]

FeeOperationType

Operation types that support the getFee/getFeeRecipient hooks.

type FeeOperationType = "bridge" | "swap";

GetSupportedChainsOptions

Options for filtering supported chains.

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

Properties

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

Usage Examples

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

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

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

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

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

getSwapStatus(params)

Fetch the current status of a swap from the Stablecoin Service. Delegates to SwapKit.getSwapStatus. Performs a single HTTP request and returns the service’s snapshot of the swap’s state. For crosschain swaps the status can remain 'PENDING' for several minutes while attestation and destination-chain mint complete; callers are responsible for polling — re-calling this method with a delay — until progress.status is terminal ('DONE', 'FAILED', or 'NOT_FOUND'). Use AppKit.waitForSwap if you’d rather not write the polling loop yourself.

getSwapStatus(params: GetSwapStatusParams): Promise<SwapStatusResult>

Parameters

Name	Type	Description
params	`GetSwapStatusParams`	`txHash` and `chainIn`, plus optional `chainOut` and `kitKey`.

GetSwapStatusParams

Parameters for SwapKit.getSwapStatus.

interface GetSwapStatusParams {
  txHash: string;
  chainIn: SwapChainIdentifier | Blockchain;
  chainOut?: SwapChainIdentifier | Blockchain;
  kitKey?: string;
}

Properties

Name	Type	Description
chainIn	`SwapChainIdentifier \| Blockchain`	Chain the swap was initiated on. Accepts a Blockchain enum value, a string literal of the enum, or a full ChainDefinition (for convenience when piping through resolved parameters).
chainOut	`SwapChainIdentifier \| Blockchain`	Destination chain for crosschain swaps. Must be supplied when the source and destination chains differ. Omit (or match `chainIn`) for same-chain swaps.
kitKey	string	Stablecoin Service Kit Key used as a bearer credential for the status request. Treat this value as a secret and do not log it. Optional — when omitted, the request is made without an `Authorization` header (permissionless mode).
txHash	string	The source-chain transaction hash returned by SwapKit.swap.

Returns Promise<SwapStatusResult>

SwapStatusResult

Result of a swap status lookup — a single snapshot of the swap’s state at the time of the call.

interface SwapStatusResult {
  readonly progress: SwapProgress;
  readonly source?: SwapSourceLeg;
  readonly destination?: SwapDestinationLeg;
}

Properties

Name	Type	Description
destination	SwapDestinationLeg	Destination-leg transaction, token, and amount metadata. Omitted until the service reports destination-chain data (typically once the swap reaches `'DONE'`). The received amount lives under `destination.amount`.
progress	SwapProgress	Lifecycle snapshot: `status`, `substatus`, and `substatusMessage`.
source	SwapSourceLeg	Source-leg transaction and token metadata. `source.txHash` is populated from the service’s `sendingTxHash`; `source.token` is shape-reserved pending service support.

Usage Examples

Single snapshot:
```typescript
const result = await kit.swap(swapParams)

const status = await kit.getSwapStatus({
  txHash: result.txHash,
  chainIn: result.chainIn,
  chainOut: result.chainOut,
  kitKey: process.env.KIT_KEY ?? '',
})

console.log(status.progress.status, status.progress.substatus)

Poll until terminal (or just call `kit.waitForSwap` instead):
```typescript
let status = await kit.getSwapStatus({
  txHash: result.txHash,
  chainIn: result.chainIn,
  chainOut: result.chainOut,
  kitKey: process.env.KIT_KEY ?? '',
})
while (status.progress.status === 'PENDING') {
  await new Promise((r) => setTimeout(r, 3_000))
  status = await kit.getSwapStatus({
    txHash: result.txHash,
    chainIn: result.chainIn,
    chainOut: result.chainOut,
    kitKey: process.env.KIT_KEY ?? '',
  })
}

getTokenRates(params)

Fetch cached USD rates for one or more tokens from the Stablecoin Service. Two lookup modes are supported:

Per-chain dump: omit tokens to retrieve every rate cached for chain.
Targeted lookup: supply tokens (up to 100) to retrieve a specific set of rates on chain. Each entry may be a registered token symbol (e.g. 'USDC', 'EURC'), the literal 'NATIVE', the chain’s native gas symbol (e.g. 'ETH' on Ethereum), or a raw EVM address / Solana mint. Unknown strings are rejected with a KitError.

The rates pipeline is broader than the swap pipeline — chain accepts any Blockchain value or ChainDefinition, not just the swap-supported subset. Chains the cron does not track return an empty rates map. Response keys preserve the service’s canonical casing: EVM hex addresses are lowercased, Solana base58 mints are case-preserved. Lowercase EVM addresses before indexing into result.rates[chain]. Native gas rates: 'NATIVE' (or a chain’s native currency symbol) translates to the chain’s native sentinel address — 0xEee… for EVM, 1111… for Solana — before querying the service.

getTokenRates(params: GetTokenRatesParams): Promise<GetTokenRatesResult>

Parameters

Name	Type	Description
params	`GetTokenRatesParams`	`chain`, plus optional `tokens` and `kitKey`.

GetTokenRatesParams

Parameters for SwapKit.getTokenRates.

interface GetTokenRatesParams {
  chain: ChainIdentifier;
  tokens?: readonly TokenSymbol[];
  kitKey?: string;
}

Properties

Name	Type	Description
chain	ChainIdentifier	Chain to look up rates for. Accepts a Blockchain enum value, a string literal of the enum, or a full ChainDefinition.
kitKey	string	Stablecoin Service Kit Key used as a bearer credential for the rates request. Treat this value as a secret and do not log it. Optional — when omitted, the request is made without an `Authorization` header (permissionless mode).
tokens	readonly TokenSymbol[]	Optional list of tokens (max 100) to look up on `chain`. Each entry may be: - A registered TokenSymbol (e.g. `'USDC'`, `'EURC'`). The kit resolves it to the chain’s address via the built-in `TokenRegistry`. Symbol matching is case-insensitive. - The literal `'NATIVE'`, or the chain’s native gas symbol (e.g. `'ETH'` on Ethereum, `'POL'` on Polygon). Both translate to the chain’s native sentinel address — `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee` for EVM, `11111111111111111111111111111111` for Solana — before querying the service. - A raw on-chain address (EVM `0x` hex) or mint (Solana base58), passed through verbatim (EVM lowercased to match service response casing). Omit the field to get every cached rate for the chain. Unknown strings that are neither a registered symbol nor a well-formed address are rejected with a `KitError` to surface typos at the call site instead of returning a silently empty rate map.

Returns Promise<GetTokenRatesResponse>

ChainIdentifier

Chain identifier that can be used in transfer parameters and factory functions. This can be either:

A ChainDefinition object
A Blockchain enum value (e.g., Blockchain.Ethereum)
A string literal of the blockchain value (e.g., “Ethereum”)

type ChainIdentifier = ChainDefinition | Blockchain | unknown;

Usage Example

const { rates } = await kit.getTokenRates({
  chain: "Ethereum",
  tokens: ["USDC", "EURC"],
  kitKey: process.env.KIT_KEY ?? "",
});

const usdc = rates["Ethereum"]?.["0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"];
console.log(`USDC: $${usdc?.priceUSD ?? "unknown"}`);

off(action)

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

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

Parameters

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

Usage Example

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

const kit = new AppKit();

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

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

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

on(action)

Register an event handler for a specific AppKit action. Subscribe to step events from bridge, earn, or unified balance operations. Action names are namespaced: bridge., earn., and unifiedBalance.. Use '' to receive every action. Handlers receive strongly-typed payloads for the chosen action. Multiple handlers may be registered for the same action.

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

Parameters

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

Usage Example

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

const kit = new AppKit();

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

// Listen to earn deposit steps
kit.on("earn.deposit", (payload) => {
  console.log("Earn deposit step:", payload.values.state);
});

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

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

retryBridge(result)

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

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

Parameters

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

BridgeResult

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

Properties

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

RetryContext

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

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

Properties

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

Returns Promise<BridgeResult>

BridgeResult

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

Properties

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

Usage Example

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

const kit = new AppKit();

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

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

send(params)

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

send(params: SendParams): Promise<BridgeStep>

Parameters

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

SendParams

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

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

Properties

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

Returns Promise<BridgeStep>

BridgeStep

A step in the bridge process.

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

Properties

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

Usage Examples

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

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

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

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

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

swap(params)

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

swap(params: SwapParams): Promise<SwapResult>

Parameters

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

SwapParams

interface SwapParams<
  TFromAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities,
> {
  from: SwapAdapterContext<TFromAdapterCapabilities>;
  tokenIn: SupportedSwapToken;
  tokenOut: SupportedSwapToken;
  amountIn: string;
  to?: SwapDestination;
  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.
to	SwapDestination	Optional destination chain/address. For same-chain swaps this may be omitted and the source wallet address is used as the recipient. crosschain swaps require `recipientAddress`.
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 source-chain execution outcome for a swap transaction.

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

Properties

Name	Type	Description
amountIn	string	The input amount that was swapped, as a human-readable decimal string in token units (e.g. `'0.05'` for 0.05 USDC or 0.05 ETH).
amountOut	string	Output amount when `.swap()` can confirm the result inline. Expressed as a human-readable decimal string in output-token units (run through the output-token transform), never base units. Populated for same-chain swaps when the best-effort status peek reaches `DONE`. Undefined for crosschain swaps; call SwapKit.getSwapStatus to retrieve destination-leg details.
chain	Blockchain
chainIn	Blockchain	The source chain of the swap. Returns the chain name (e.g. `Blockchain.Ethereum`). Use `getChainByEnum(chainIn)` to resolve back to a full `ChainDefinition`.
chainOut	Blockchain	Destination chain of the swap. Equal to `chainIn` for same-chain swaps; different for crosschain swaps. Always populated so consumers don’t have to fall back to `chainIn` when the destination is implicit.
config	SwapResultConfig	The swap configuration that was used for this operation.
explorerUrl	string	The formatted explorer URL for the source-chain transaction. 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.
fromAddress	string	The address that initiated the swap.
progress	SwapProgress	Lifecycle snapshot: `status`, `substatus`, and `substatusMessage`. `status` is `'DONE'` when the swap completed end-to-end (same-chain only), `'PENDING'` while the destination leg is still in-flight, or a terminal failure value (`'FAILED'` / `'NOT_FOUND'`).
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 source-chain transaction hash for the executed swap.

Usage Example

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

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

waitForSwap(params)

Poll the Stablecoin Service until a swap reaches a terminal status ('DONE', 'FAILED', 'NOT_FOUND') or timeoutMs elapses. Delegates to SwapKit.waitForSwap. Use this after kit.swap() to collapse the while (status === 'PENDING') polling loop into a single awaitable. Same-chain swaps return on the first poll because they are already terminal at swap time; crosschain swaps follow an escalating backoff (3s → 6s → 12s → 24s → 24s) until the wait budget expires. Timeouts surface as a RETRYABLE KitError so callers can re-invoke with the same txHash.

waitForSwap(params: WaitForSwapParams): Promise<SwapStatusResult>

Parameters

Name	Type	Description
params	`WaitForSwapParams`	Wait configuration: identifiers, kit key, and optional `timeoutMs` / `onProgress`.

WaitForSwapParams

Parameters for SwapKit.waitForSwap.

type WaitForSwapParams = WaitForSwapResultParams | WaitForSwapDiscreteParams;

Returns Promise<SwapStatusResult>

SwapStatusResult

Result of a swap status lookup — a single snapshot of the swap’s state at the time of the call.

interface SwapStatusResult {
  readonly progress: SwapProgress;
  readonly source?: SwapSourceLeg;
  readonly destination?: SwapDestinationLeg;
}

Properties

Name	Type	Description
destination	SwapDestinationLeg	Destination-leg transaction, token, and amount metadata. Omitted until the service reports destination-chain data (typically once the swap reaches `'DONE'`). The received amount lives under `destination.amount`.
progress	SwapProgress	Lifecycle snapshot: `status`, `substatus`, and `substatusMessage`.
source	SwapSourceLeg	Source-leg transaction and token metadata. `source.txHash` is populated from the service’s `sendingTxHash`; `source.token` is shape-reserved pending service support.

WaitForSwapResultParams

waitForSwap parameter shape that pipes a SwapResult straight through — the most ergonomic form when you’ve just called SwapKit.swap or SwapKit.executeSwap.

interface WaitForSwapResultParams extends WaitForSwapCommonParams {
  readonly result: SwapResult;
}

Properties

Name	Type	Description
kitKey	string	Stablecoin Service Kit Key used as a bearer credential. Treat as a secret and do not log it. Optional — when omitted, the request is made without an `Authorization` header (permissionless mode).
onProgress	(status: SwapStatusResult) => void	Fired on every poll that produces a status snapshot. Useful for surfacing `substatus` transitions to a UI (e.g. spinner copy, log lines). Not called on retried 429/5xx responses.
result	SwapResult	The SwapResult returned by SwapKit.swap or SwapKit.executeSwap. `txHash`, `chainIn`, and `chainOut` are read directly from this object.
timeoutMs	number	Overall wait budget, in milliseconds. The promise rejects with a RETRYABLE KitError when this elapses without a terminal status. crosschain swaps typically settle within 30s–3min; pad the budget if production traffic shows occasional outliers. Default: `300_000` (5 minutes).

WaitForSwapDiscreteParams

waitForSwap parameter shape for callers that don’t have a SwapResult on hand — e.g. picking up an in-flight swap from a persisted record or a copy-pasted tx hash.

interface WaitForSwapDiscreteParams extends WaitForSwapCommonParams {
  readonly txHash: string;
  readonly chainIn: SwapChainIdentifier | Blockchain;
  readonly chainOut?: SwapChainIdentifier | Blockchain;
}

Properties

Name	Type	Description
chainIn	`SwapChainIdentifier \| Blockchain`	Chain the swap was initiated on. Accepts a Blockchain enum value, a string literal of the enum, or a full ChainDefinition.
chainOut	`SwapChainIdentifier \| Blockchain`	Destination chain for crosschain swaps. Omit (or match `chainIn`) for same-chain swaps.
kitKey	string	Stablecoin Service Kit Key used as a bearer credential. Treat as a secret and do not log it. Optional — when omitted, the request is made without an `Authorization` header (permissionless mode).
onProgress	(status: SwapStatusResult) => void	Fired on every poll that produces a status snapshot. Useful for surfacing `substatus` transitions to a UI (e.g. spinner copy, log lines). Not called on retried 429/5xx responses.
timeoutMs	number	Overall wait budget, in milliseconds. The promise rejects with a RETRYABLE KitError when this elapses without a terminal status. crosschain swaps typically settle within 30s–3min; pad the budget if production traffic shows occasional outliers. Default: `300_000` (5 minutes).
txHash	string	The source-chain transaction hash returned by SwapKit.swap or SwapKit.executeSwap.

Usage Examples

Pipe a `SwapResult` straight in — the common case:
```typescript
const result = await kit.swap(swapParams)

const final = await kit.waitForSwap({
  result,
  kitKey: process.env.KIT_KEY ?? '',
  onProgress: (snap) => console.log(snap.progress.status),
})

if (final.progress.status === 'DONE') {
  console.log(`Received ${final.destination?.amount}`)
}

Resume from a persisted tx hash (no `SwapResult` on hand):
```typescript
const final = await kit.waitForSwap({
  txHash: persisted.txHash,
  chainIn: persisted.chainIn,
  chainOut: persisted.chainOut,
  kitKey: process.env.KIT_KEY ?? '',
})

kit.unifiedBalance Methods

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

addDelegate(params)

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

addDelegate(params: UpdateDelegateParams): Promise<UpdateDelegateResult>

Parameters

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

UpdateDelegateParams

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

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

Properties

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

Returns Promise<UpdateDelegateResult>

UpdateDelegateResult

Result returned after a successful add or remove delegate operation.

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

Properties

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

Usage Example

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

deposit(params)

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

deposit(params: DepositParams): Promise<DepositResult>

Parameters

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

DepositParams

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

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

Properties

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

Returns Promise<DepositResult>

DepositResult

Result returned after a successful deposit operation.

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

Properties

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

Usage Example

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

depositFor(params)

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

depositFor(params: DepositForParams): Promise<DepositResult>

Parameters

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

DepositForParams

Parameters for depositing tokens into another Gateway account.

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

Properties

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

Returns Promise<DepositResult>

DepositResult

Result returned after a successful deposit operation.

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

Properties

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

Usage Example

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

estimateSpend(params)

Estimate the fees for a spend operation without executing it.

estimateSpend(params: SpendParams): Promise<EstimateSpendResult>

Parameters

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

SpendParams

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

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

Returns Promise<EstimateSpendResult>

EstimateSpendResult

Cost estimation for a spend (mint) operation.

interface EstimateSpendResult {
  fees: FeeEntry[];
}

Properties

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

Usage Example

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

getBalances(params)

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

getBalances(params: GetBalancesParams): Promise<GetBalancesResult>

Parameters

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

GetBalancesParams

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

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

Properties

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

Returns Promise<GetBalancesResult>

GetBalancesResult

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

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

Properties

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

NetworkType

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

type NetworkType = "mainnet" | "testnet";

BalanceWithPendingBreakdown

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

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

Properties

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

ChainBalanceBreakdown

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

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

Properties

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

PendingBalanceTransaction

A pending transaction included in GetBalancesResult when includePending is true.

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

Usage Example

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

getDelegateStatus(params)

Check the finality-aware delegate status of an address.

getDelegateStatus(params: GetDelegateStatusParams): Promise<DelegateStatus>

Parameters

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

GetDelegateStatusParams

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

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

Properties

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

Returns Promise<DelegateStatus>

DelegateStatus

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

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

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

Usage Example

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

getSupportedChains(token)

Get all chains supported by the unified balance operations.

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

Parameters

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

GetSupportedChainsOptions

Options for filtering supported chains.

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

Properties

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

Returns ChainDefinition[] Usage Example

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

initiateRemoveFund(params)

Initiate a trustless recovery removal from an account. Use spend for normal movement out of a Unified Balance. removeFund is a recovery path for situations where the normal spend flow is unavailable. Calling this method starts the 7-day withdrawal delay before the removal can be completed.

initiateRemoveFund(params: InitiateRemoveFundParams): Promise<InitiateRemoveFundResult>

Parameters

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

InitiateRemoveFundParams

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

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

Properties

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

Returns Promise<InitiateRemoveFundResult>

InitiateRemoveFundResult

Result returned after successfully initiating a fund removal.

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

Properties

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

Usage Example

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

off(action)

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

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

Parameters

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

Usage Example

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

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

on(action)

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

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

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

Parameters

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

Usage Example

const kit = new AppKit();

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

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

removeCustomFeePolicy()

Remove the custom fee policy for the kit.

removeCustomFeePolicy(): void

Usage Example

kit.unifiedBalance.removeCustomFeePolicy();

removeDelegate(params)

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

removeDelegate(params: UpdateDelegateParams): Promise<UpdateDelegateResult>

Parameters

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

UpdateDelegateParams

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

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

Properties

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

Returns Promise<UpdateDelegateResult>

UpdateDelegateResult

Result returned after a successful add or remove delegate operation.

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

Properties

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

Usage Example

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

removeFeeRecipients()

Remove the declarative fee recipient map for the kit.

removeFeeRecipients(): void

Usage Example

kit.unifiedBalance.removeFeeRecipients();

removeFund(params)

Complete a trustless recovery removal after the withdrawal delay. Use spend for normal movement out of a Unified Balance. removeFund is a recovery path for situations where the normal spend flow is unavailable. Both EVM and Solana removals require a 7-day withdrawal delay after initiateRemoveFund before funds can be removed.

removeFund(params: RemoveFundParams): Promise<RemoveFundResult>

Parameters

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

RemoveFundParams

Parameters for completing a recovery fund removal after the withdrawal delay.

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

Properties

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

Returns Promise<RemoveFundResult>

RemoveFundResult

Result returned after successfully completing a fund removal.

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

Properties

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

Usage Example

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

setCustomFeePolicy(policy)

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

setCustomFeePolicy(policy: CustomFeePolicy): void

Parameters

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

CustomFeePolicy

interface CustomFeePolicy {
  computeFee: SpendFeeFunction;
  resolveFeeRecipientAddress?: SpendFeeRecipientFunction;
}

Usage Example

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

setFeeRecipients(config)

Set a declarative fee recipient map, keyed by chain type. Once set, spend()/estimateSpend() resolve the fee recipient by looking up the spend’s destination chain type in this map — taking priority over customFeePolicy’s resolveFeeRecipientAddress callback.

setFeeRecipients(config: FeeRecipientsConfig): void

Parameters

Name	Type	Description
config	`FeeRecipientsConfig`	Fee recipient addresses keyed by chain type (e.g. `{ evm: '0x...', solana: 'Sol...' }`).

FeeRecipientsConfig

type FeeRecipientsConfig = Partial<Record<FeeRecipientChainType, string>>;

Usage Example

kit.unifiedBalance.setFeeRecipients({
  evm: "0x1234567890123456789012345678901234567890",
  solana: "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
});

spend(params)

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

spend(params: SpendParams): Promise<SpendResult>

Parameters

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

SpendParams

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

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

Returns Promise<SpendResult>

SpendResult

Result returned after a successful spend (mint) operation.

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

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.

AllocationResult

Extends Allocation with the resolved source Gateway account address.

interface AllocationResult extends Allocation {
  sourceAccount: string;
}

Properties

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

UnifiedBalanceChainIdentifier

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

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

type UnifiedBalanceChainIdentifier =
  ChainDefinition | UnifiedBalanceChain | unknown;

UnifiedBalanceChain

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

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

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

SpendStep

Data payload for a single step in a spend operation.

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

Properties

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

Usage Example

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

Supporting Types

Common

AdapterContext

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

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

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

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

Properties

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

DeveloperFeeHooks

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

Properties

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

Chains

BaseChainDefinition

Base information that all chain definitions must include.

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

Properties

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

Blockchain

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

enum Blockchain {
  Algorand = 'Algorand'
  Algorand_Testnet = 'Algorand_Testnet'
  Aptos = 'Aptos'
  Aptos_Testnet = 'Aptos_Testnet'
  Arbitrum = 'Arbitrum'
  Arbitrum_Sepolia = 'Arbitrum_Sepolia'
  Arc_Testnet = 'Arc_Testnet'
  Avalanche = 'Avalanche'
  Avalanche_Fuji = 'Avalanche_Fuji'
  Base = 'Base'
  Base_Sepolia = 'Base_Sepolia'
  Celo = 'Celo'
  Celo_Alfajores_Testnet = 'Celo_Alfajores_Testnet'
  Codex = 'Codex'
  Codex_Testnet = 'Codex_Testnet'
  Cronos = 'Cronos'
  Cronos_Testnet = 'Cronos_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, Cronos, Cronos_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

ChainDefinition

Public chain definition type.

type ChainDefinition = EVMChainDefinition | NonEVMChainDefinition;

Currency

Represents basic information about a currency or token.

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

EVMChainDefinition

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

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

Properties

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

KitContractType

Available kit contract types for enhanced chain functionality.

type KitContractType = "bridge" | "adapter";

NonEVMChainDefinition

Represents chain definitions for non-EVM blockchains.

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

Properties

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

TokenInfo

Represents the metadata associated with a token.

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

Event Actions

AppKitActions

All actions available in AppKit.

type AppKitActions = AppKitBridgeActions &
  AppKitUnifiedBalanceActions &
  AppKitEarnActions;

AppKitBridgeActions

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

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

AppKitEarnActions

Prefixed earn actions for AppKit. Earn step events are exposed under the earn. namespace (for example earn.deposit, earn.approve, earn.withdraw) so they can be subscribed to via kit.on() alongside bridge and unified balance events.

type AppKitEarnActions = PrefixActions<"earn", EarnActions>;

AppKitUnifiedBalanceActions

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

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

Bridge

BridgeConfig

Configuration options for customizing bridge behavior.

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

Properties

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

CCTPConfig

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

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

Properties

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

CCTPMergedConfig

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

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

CCTPSplitConfig

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

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

TransferSpeed

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

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

Values FAST, SLOW

Swap

AllowanceStrategy

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

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

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

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

SwapConfig

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

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

Properties

Name	Type	Description
allowanceStrategy	AllowanceStrategy	Strategy for granting token allowances to the swap contract. Defaults to `permit` with fallback to `approve`.
customFee	`{ percentageBps: number; recipientAddress: string; }`	Custom fee configuration for this swap (percentage-based approach). Allows specifying a percentage fee and recipient address at the transaction level. This is mutually exclusive with kit-level callback fee policy. If both are set, transaction-level takes precedence. For complex fee logic (VIP tiers, database lookups), use kit-level callback approach via `setCustomFeePolicy()` instead.
kitKey	string	Stablecoin Service Kit Key used to authenticate service-backed swap requests. Treat this value as a credential. Do not log it, embed it in client-side source, or expose it in telemetry.
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.

SwapDestinationLeg

Destination-leg transaction and token information reported by the service. Present on SwapStatusResult once the service reports destination data. Omitted while the destination leg is still in-flight.

interface SwapDestinationLeg {
  readonly txHash?: string;
  readonly token?: {
    readonly symbol?: string;
    readonly address?: string;
  };
  readonly amount?: string;
}

Properties

Name	Type	Description
amount	string	Amount received on the destination leg, as a human-readable decimal string (e.g. `'0.082927'`). Present once the destination leg has landed and the service has reported both `amountOut` and `receivingTokenDecimals`. Omitted otherwise — never a raw base-unit value, so consumers can render `destination.amount` directly in a UI without worrying about unit conversion.
token	`{ readonly symbol?: string; readonly address?: string; }`	Destination-token metadata reported by the service.
txHash	string	Destination-chain transaction hash reported by the service.

SwapProgress

Lifecycle snapshot for a swap. Grouped so progress signals live in one place on both SwapResult and SwapStatusResult.

interface SwapProgress {
  readonly status: SwapStatus;
  readonly substatus?: string;
  readonly substatusMessage?: string;
}

Properties

Name	Type	Description
status	SwapStatus	Current swap status. Only `'DONE'`, `'FAILED'`, and `'NOT_FOUND'` are terminal. `'PENDING'` means the caller should re-invoke SwapKit.getSwapStatus until a terminal status is observed.
substatus	string	Provider-specific status detail (e.g. `'WAIT_DESTINATION_TRANSACTION'`, `'COMPLETED'`). Surfaced as-is from the Stablecoin Service.
substatusMessage	string	Human-readable provider status explanation.

SwapSourceLeg

Source-leg transaction and token information reported by the service. Populated on SwapStatusResult from the service’s sendingTxHash. token is shape-reserved for future service support (the status endpoint does not report source-token metadata today) so consumers can rely on a symmetric source / destination layout.

interface SwapSourceLeg {
  readonly txHash?: string;
  readonly token?: {
    readonly symbol?: string;
    readonly address?: string;
  };
}

Properties

Name	Type	Description
token	`{ readonly symbol?: string; readonly address?: string; }`	Source-token metadata. Shape-reserved — not populated by the current Stablecoin Service status endpoint, but exposed here so this field mirrors SwapDestinationLeg.token if/when the service starts returning it.
txHash	string	Source-chain transaction hash reported by the service.

SwapStatus

All possible status values for a swap tracked by the Stablecoin Service. 'PENDING' means the swap is still in-flight. Callers should keep calling SwapKit.getSwapStatus on 'PENDING' until the status becomes terminal (see SwapTerminalStatus).

type SwapStatus = SwapTerminalStatus | "PENDING";

SwapTerminalStatus

Terminal status values for a swap tracked by the Stablecoin Service. 'DONE' indicates the swap completed (including any crosschain delivery). 'FAILED' indicates the swap failed after on-chain submission. 'NOT_FOUND' indicates the service has no record of the transaction.

type SwapTerminalStatus = "DONE" | "FAILED" | "NOT_FOUND";

Unified Balance

FeeAllocation

Per-chain breakdown of a fee amount.

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

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.

FeeEntry

A single fee line item within an estimate.

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

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.

FeeType

Fee category describing the origin of a fee line item.

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

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

SupportedToken

type SupportedToken = (typeof SUPPORTED_TOKENS)[number];

SupportedTokenInput

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

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

UnifiedBalanceKitConfig

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

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

Properties

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

Event Types

Bridge Events

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

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

Usage Example

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

const kit = new AppKit();

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

// Listen to earn deposit steps
kit.on("earn.deposit", (payload) => {
  console.log("Earn deposit step:", payload.values.state);
});

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

⌘I

​AppKit Class

​constructor(config?)

​AppKitConfig

​Methods

​bridge(params)

​BridgeParams

​BridgeResult

​estimateBridge(params)

​BridgeParams

​EstimateResult

​estimateSend(params)

​SendParams

​EstimatedGas

​estimateSwap(params)

​SwapParams

​SwapEstimate

​getSupportedChains(operationType)

​OperationType

​FeeOperationType

​GetSupportedChainsOptions

​getSwapStatus(params)

​GetSwapStatusParams

​SwapStatusResult

​getTokenRates(params)

​GetTokenRatesParams

​ChainIdentifier

​off(action)

​on(action)

​retryBridge(result)

​BridgeResult

​RetryContext

​BridgeResult

​send(params)

​SendParams

​BridgeStep

​swap(params)

​SwapParams

​SwapResult

​waitForSwap(params)

​WaitForSwapParams

​SwapStatusResult

​WaitForSwapResultParams

​WaitForSwapDiscreteParams

​kit.unifiedBalance Methods

​addDelegate(params)

​UpdateDelegateParams

​UpdateDelegateResult

​deposit(params)

​DepositParams

​DepositResult

​depositFor(params)

​DepositForParams

​DepositResult

​estimateSpend(params)

​SpendParams

​EstimateSpendResult

​getBalances(params)

​GetBalancesParams

​GetBalancesResult

​NetworkType

​BalanceWithPendingBreakdown

​ChainBalanceBreakdown

​PendingBalanceTransaction

​getDelegateStatus(params)

​GetDelegateStatusParams

​DelegateStatus

​getSupportedChains(token)

​GetSupportedChainsOptions

​initiateRemoveFund(params)

​InitiateRemoveFundParams

​InitiateRemoveFundResult

​off(action)

​on(action)

​removeCustomFeePolicy()

​removeDelegate(params)

​UpdateDelegateParams

​UpdateDelegateResult

​removeFeeRecipients()

​removeFund(params)

​RemoveFundParams

AppKit Class

constructor(config?)

AppKitConfig

Methods

bridge(params)

BridgeParams

BridgeResult

estimateBridge(params)

BridgeParams

EstimateResult

estimateSend(params)

SendParams

EstimatedGas

estimateSwap(params)

SwapParams

SwapEstimate

getSupportedChains(operationType)

OperationType

FeeOperationType

GetSupportedChainsOptions

getSwapStatus(params)

GetSwapStatusParams

SwapStatusResult

getTokenRates(params)

GetTokenRatesParams

ChainIdentifier

off(action)

on(action)

retryBridge(result)

BridgeResult

RetryContext

BridgeResult

send(params)

SendParams

BridgeStep

swap(params)

SwapParams

SwapResult

waitForSwap(params)

WaitForSwapParams

SwapStatusResult

WaitForSwapResultParams

WaitForSwapDiscreteParams

kit.unifiedBalance Methods

addDelegate(params)

UpdateDelegateParams

UpdateDelegateResult

deposit(params)

DepositParams

DepositResult

depositFor(params)

DepositForParams

DepositResult

estimateSpend(params)

SpendParams

EstimateSpendResult

getBalances(params)

GetBalancesParams

GetBalancesResult

NetworkType

BalanceWithPendingBreakdown

ChainBalanceBreakdown

PendingBalanceTransaction

getDelegateStatus(params)

GetDelegateStatusParams

DelegateStatus

getSupportedChains(token)

GetSupportedChainsOptions

initiateRemoveFund(params)

InitiateRemoveFundParams

InitiateRemoveFundResult

off(action)

on(action)

removeCustomFeePolicy()

removeDelegate(params)

UpdateDelegateParams

UpdateDelegateResult

removeFeeRecipients()

removeFund(params)

RemoveFundParams