@circle-fin/app-kit 1.12.1 → 1.14.0

package/unifiedBalance.d.cts

@@ -558,6 +558,19 @@ interface GatewayV1Contracts {
      * @example "0xD05E7D2E7d30b92c5F17d7d0fC575fce231F1A48"
      */
     depositForHandler?: string;
+    /**
+     * The address of the `GenericExecutor` contract.
+     *
+     * @description Optional. The contract that acts as `mintRecipient` and
+     * `destinationCaller` for the CCTP v2 prepaid FORWARD path. It receives the
+     * CCTP mint and calls {@link GatewayV1Contracts.depositForHandler} to
+     * complete the fast deposit into the {@link GatewayV1Contracts.wallet}.
+     * Present only on chains that are fast-deposit destinations; other Gateway
+     * chains omit it.
+     *
+     * @example "0xFa7be2f04F3Ad4ca969260729c6d45B5625984A7"
+     */
+    genericExecutor?: string;
 }
 /**
  * Versioned map of Gateway contract configurations.
@@ -717,6 +730,8 @@ declare enum Blockchain {
     Optimism_Sepolia = "Optimism_Sepolia",
     Pharos = "Pharos",
     Pharos_Testnet = "Pharos_Testnet",
+    Plasma = "Plasma",
+    Plasma_Testnet = "Plasma_Testnet",
     Polkadot_Asset_Hub = "Polkadot_Asset_Hub",
     Polkadot_Westmint = "Polkadot_Westmint",
     Plume = "Plume",
@@ -744,6 +759,134 @@ declare enum Blockchain {
     ZKSync_Era = "ZKSync_Era",
     ZKSync_Sepolia = "ZKSync_Sepolia"
 }
+/**
+ * Enumeration of blockchains that support cross-chain bridging via CCTPv2.
+ *
+ * The enum is derived from the full {@link Blockchain} enum but filtered to only
+ * include chains with active CCTPv2 support. When new chains gain CCTPv2 support,
+ * they are added to this enum.
+ *
+ * @enum
+ * @category Enums
+ *
+ * @remarks
+ * - This enum is the **canonical source** of bridging-supported chains.
+ * - Use this enum (or its string literals) in `kit.bridge()` calls for type safety.
+ * - Attempting to use a chain not in this enum will produce a TypeScript compile error.
+ *
+ * @example
+ * ```typescript
+ * import { BridgeKit, BridgeChain } from '@circle-fin/bridge-kit'
+ *
+ * const kit = new BridgeKit()
+ *
+ * // ✅ Valid - autocomplete suggests only supported chains
+ * await kit.bridge({
+ *   from: { adapter, chain: BridgeChain.Ethereum },
+ *   to: { adapter, chain: BridgeChain.Base },
+ *   amount: '100'
+ * })
+ *
+ * // ✅ Also valid - string literals work with autocomplete
+ * await kit.bridge({
+ *   from: { adapter, chain: 'Ethereum_Sepolia' },
+ *   to: { adapter, chain: 'Base_Sepolia' },
+ *   amount: '100'
+ * })
+ *
+ * // ❌ Compile error - Algorand is not in BridgeChain
+ * await kit.bridge({
+ *   from: { adapter, chain: 'Algorand' }, // TypeScript error!
+ *   to: { adapter, chain: 'Base' },
+ *   amount: '100'
+ * })
+ * ```
+ *
+ * @see {@link Blockchain} for the complete list of all known blockchains.
+ * @see {@link BridgeChainIdentifier} for the type that accepts these values.
+ */
+declare enum BridgeChain {
+    Arbitrum = "Arbitrum",
+    Avalanche = "Avalanche",
+    Base = "Base",
+    Codex = "Codex",
+    Cronos = "Cronos",
+    Edge = "Edge",
+    Ethereum = "Ethereum",
+    HyperEVM = "HyperEVM",
+    Injective = "Injective",
+    Ink = "Ink",
+    Linea = "Linea",
+    Monad = "Monad",
+    Morph = "Morph",
+    Optimism = "Optimism",
+    Pharos = "Pharos",
+    Plasma = "Plasma",
+    Plume = "Plume",
+    Polygon = "Polygon",
+    Sei = "Sei",
+    Solana = "Solana",
+    Sonic = "Sonic",
+    Unichain = "Unichain",
+    World_Chain = "World_Chain",
+    XDC = "XDC",
+    X_Layer = "X_Layer",
+    Arc_Testnet = "Arc_Testnet",
+    Arbitrum_Sepolia = "Arbitrum_Sepolia",
+    Avalanche_Fuji = "Avalanche_Fuji",
+    Base_Sepolia = "Base_Sepolia",
+    Codex_Testnet = "Codex_Testnet",
+    Cronos_Testnet = "Cronos_Testnet",
+    Edge_Testnet = "Edge_Testnet",
+    Ethereum_Sepolia = "Ethereum_Sepolia",
+    HyperEVM_Testnet = "HyperEVM_Testnet",
+    Injective_Testnet = "Injective_Testnet",
+    Ink_Testnet = "Ink_Testnet",
+    Linea_Sepolia = "Linea_Sepolia",
+    Monad_Testnet = "Monad_Testnet",
+    Morph_Testnet = "Morph_Testnet",
+    Optimism_Sepolia = "Optimism_Sepolia",
+    Pharos_Testnet = "Pharos_Testnet",
+    Plasma_Testnet = "Plasma_Testnet",
+    Plume_Testnet = "Plume_Testnet",
+    Polygon_Amoy_Testnet = "Polygon_Amoy_Testnet",
+    Sei_Testnet = "Sei_Testnet",
+    Solana_Devnet = "Solana_Devnet",
+    Sonic_Testnet = "Sonic_Testnet",
+    Unichain_Sepolia = "Unichain_Sepolia",
+    World_Chain_Sepolia = "World_Chain_Sepolia",
+    XDC_Apothem = "XDC_Apothem",
+    X_Layer_Testnet = "X_Layer_Testnet"
+}
+/**
+ * Type representing valid bridge chain identifiers.
+ *
+ * This type constrains chain parameters to only accept chains that support CCTPv2 bridging
+ *
+ * Accepts:
+ * - A {@link BridgeChain} enum value (e.g., `BridgeChain.Ethereum`)
+ * - A string literal matching a BridgeChain value (e.g., `'Ethereum'`)
+ * - A {@link ChainDefinition} object for a supported chain
+ *
+ * @example
+ * ```typescript
+ * import type { BridgeChainIdentifier } from '@circle-fin/bridge-kit'
+ * import { BridgeChain } from '@circle-fin/bridge-kit'
+ * import { Solana } from '@circle-fin/bridge-kit/chains'
+ *
+ * // All of these are valid BridgeChainIdentifier values:
+ * const chain1: BridgeChainIdentifier = BridgeChain.Ethereum
+ * const chain2: BridgeChainIdentifier = 'Base_Sepolia'
+ * const chain3: BridgeChainIdentifier = Solana // ChainDefinition
+ *
+ * // This will cause a TypeScript error:
+ * const chain4: BridgeChainIdentifier = 'Algorand' // Error!
+ * ```
+ *
+ * @see {@link BridgeChain} for the enum of supported chains.
+ * @see {@link ChainIdentifier} for the less restrictive type accepting all chains.
+ */
+type BridgeChainIdentifier = ChainDefinition | BridgeChain | `${BridgeChain}`;
 /**
  * Enumeration of blockchains that support Gateway V1 operations
  * (deposit, spend, balance, delegate, removeFund).
@@ -2299,7 +2442,7 @@ interface ExecuteParams {
  *   fromAddress: '0x...',
  *   toAddress: '0x...',
  *   amount: '1000000',
- *   apiKey: 'KIT_KEY:...',
+ *   apiKey: 'TEST_API_KEY:...',
  * })
  *
  * // Build token inputs with permit
@@ -2443,7 +2586,7 @@ interface ExecuteSwapEVMParams extends ActionParameters {
  *   fromAddress: 'YubQzu18FDqJRyNfG8JqHmsdbxhnoQqcKUHBdUkN6tP',
  *   toAddress: 'YubQzu18FDqJRyNfG8JqHmsdbxhnoQqcKUHBdUkN6tP',
  *   amount: '1000000',
- *   apiKey: 'KIT_KEY:...',
+ *   apiKey: 'TEST_API_KEY:...',
  * })
  *
  * // Prepare action parameters
@@ -3917,6 +4060,49 @@ interface ErrorInfo {
     type?: string;
 }
 
+/**
+ * Configuration options for the API polling utility.
+ *
+ * @remarks
+ * These settings control the behavior of the API polling process:
+ * - timeout: Maximum time (ms) to wait for each request before aborting
+ * - maxRetries: Maximum number of retry attempts for failed requests
+ * - retryDelay: Base delay (ms); constant wait for `'fixed'` or exponential seed for `'exponential'`
+ * - backoff: Retry-delay strategy, `'fixed'` (default) or `'exponential'`
+ * - maxRetryDelayMs: Optional ceiling (ms) for a single backoff wait
+ * - headers: Optional HTTP headers to include with each request
+ */
+interface ApiPollingConfig {
+    /** Maximum time in milliseconds to wait for each request */
+    timeout: number;
+    /** Maximum number of retry attempts for failed requests */
+    maxRetries: number;
+    /**
+     * Delay in milliseconds between retry attempts. With the default
+     * `backoff: 'fixed'` strategy this is the constant wait; with
+     * `backoff: 'exponential'` it is the base the exponential backoff grows
+     * from (see {@link pollApiWithValidation}).
+     */
+    retryDelay: number;
+    /**
+     * Retry-delay strategy. `'fixed'` (the default when omitted) waits a
+     * constant `retryDelay` between attempts; `'exponential'` grows the wait
+     * exponentially off `retryDelay` and randomizes it with full jitter, which
+     * spreads out retries so rate-limited (429) bursts do not retry in
+     * lockstep. Opt in per caller; existing callers keep the fixed delay.
+     */
+    backoff?: 'fixed' | 'exponential' | undefined;
+    /**
+     * Optional ceiling, in milliseconds, for a single backoff wait. Only
+     * applies when `backoff` is `'exponential'`: the exponential delay is
+     * capped at this value before jitter is applied. Defaults to
+     * {@link DEFAULT_MAX_RETRY_DELAY_MS} when omitted.
+     */
+    maxRetryDelayMs?: number | undefined;
+    /** Optional HTTP headers to include with requests */
+    headers?: Record<string, string> | undefined;
+}
+
 /**
  * A type-safe event emitter for managing action-based event subscriptions.
  *
@@ -4362,6 +4548,83 @@ interface DepositResult$1 {
     explorerUrl?: string;
 }
 
+/**
+ * Fee category describing the origin of a fee line item.
+ *
+ * - `'provider'`  — Fee charged by the cross-chain 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';
+/**
+ * Per-chain breakdown of a fee amount.
+ *
+ * @example
+ * ```typescript
+ * import type { FeeAllocation } from '@core/types'
+ * import { Blockchain } from '@core/chains'
+ *
+ * const allocation: FeeAllocation = {
+ *   chain: Blockchain.Ethereum,
+ *   amount: '0.00005',
+ * }
+ * ```
+ */
+interface FeeAllocation {
+    /** The chain to which this portion of the fee applies. */
+    chain: Blockchain;
+    /** The fee amount on this chain (human-readable decimal string). */
+    amount: string;
+}
+/**
+ * A single fee line item within an estimate.
+ *
+ * @remarks
+ * Each entry describes a fee category (`type`), the token it is
+ * denominated in, the aggregate `amount`, and an optional per-chain
+ * `allocations` breakdown.
+ *
+ * @example
+ * ```typescript
+ * import type { FeeEntry } from '@core/types'
+ * import { Blockchain } from '@core/chains'
+ *
+ * // Fee with per-chain allocation breakdown
+ * const providerFee: FeeEntry = {
+ *   type: 'provider',
+ *   token: 'USDC',
+ *   amount: '0.00011',
+ *   allocations: [
+ *     { chain: Blockchain.Ethereum, amount: '0.00005' },
+ *     { chain: Blockchain.Polygon, amount: '0.00006' },
+ *   ],
+ * }
+ *
+ * // Flat fee without allocations (e.g. forwarder)
+ * const forwarderFee: FeeEntry = {
+ *   type: 'forwarder',
+ *   token: 'USDC',
+ *   amount: '0.005',
+ * }
+ * ```
+ */
+interface FeeEntry {
+    /** The category of this fee. */
+    type: FeeType;
+    /** The token in which this fee is denominated (e.g. `'USDC'`, `'ETH'`). */
+    token: string;
+    /** Aggregate fee amount (human-readable decimal string). */
+    amount: string;
+    /** Per-chain breakdown of the fee. Omitted for flat fees (e.g. forwarder). */
+    allocations?: FeeAllocation[];
+    /**
+     * When `type === 'kit'`, the address that receives the kit fee.
+     * Omitted for other fee types.
+     */
+    recipientAddress?: string;
+}
+
 /**
  * Data payload for a single step in a spend operation.
  *
@@ -4663,6 +4926,15 @@ interface SpendOptions {
      * @internal
      */
     onBroadcast?: (txHash: string) => void;
+    /**
+     * Partial polling config forwarded to every Gateway API request the spend
+     * makes (estimate, transfer, forwarder status, and the balance lookups on
+     * the auto-allocation path). The provider factory populates this from its
+     * `headers` config so a configured header reaches all spend-path calls.
+     *
+     * @internal
+     */
+    requestConfig?: Partial<ApiPollingConfig>;
 }
 /**
  * Result returned after a successful spend (mint) operation.
@@ -4712,7 +4984,7 @@ interface SpendResult$1 {
      * executed spend. Same shape as {@link EstimateSpendResult.fees}.
      * Omitted when using `config.retry` (no estimate was run).
      */
-    fees?: FeeEntry$1[];
+    fees?: FeeEntry[];
     /**
      * Gateway transfer identifier. Present when `useForwarder` is enabled
      * and can be used to query transfer status via `GET /v1/transfer/{id}`.
@@ -4734,80 +5006,6 @@ interface SpendResult$1 {
      */
     steps?: SpendStep[];
 }
-/**
- * Fee category describing the origin of a fee line item.
- *
- * - `'provider'`  — Fee charged by the cross-chain 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$1 = 'provider' | 'gasFee' | 'kit' | 'forwarder';
-/**
- * Per-chain breakdown of a fee amount.
- *
- * @example
- * ```typescript
- * import type { FeeAllocation } from '@circle-fin/provider-gateway-v1'
- *
- * const allocation: FeeAllocation = {
- *   chain: 'Ethereum',
- *   amount: '0.00005',
- * }
- * ```
- */
-interface FeeAllocation$1 {
-    /** The chain to which this portion of the fee applies. */
-    chain: Blockchain;
-    /** The fee amount on this chain (human-readable decimal string). */
-    amount: string;
-}
-/**
- * A single fee line item within an estimate.
- *
- * @remarks
- * Each entry describes a fee category (`type`), the token it is
- * denominated in, the aggregate `amount`, and an optional per-chain
- * `allocations` breakdown.
- *
- * @example
- * ```typescript
- * import type { FeeEntry } from '@circle-fin/provider-gateway-v1'
- *
- * // Fee with per-chain allocation breakdown
- * const providerFee: FeeEntry = {
- *   type: 'provider',
- *   token: 'USDC',
- *   amount: '0.00011',
- *   allocations: [
- *     { chain: 'Ethereum', amount: '0.00005' },
- *     { chain: 'Polygon', amount: '0.00006' },
- *   ],
- * }
- *
- * // Flat fee without allocations (e.g. forwarder)
- * const forwarderFee: FeeEntry = {
- *   type: 'forwarder',
- *   token: 'USDC',
- *   amount: '0.005',
- * }
- * ```
- */
-interface FeeEntry$1 {
-    /** The category of this fee. */
-    type: FeeType$1;
-    /** The token in which this fee is denominated (e.g. `'USDC'`, `'ETH'`). */
-    token: string;
-    /** Aggregate fee amount (human-readable decimal string). */
-    amount: string;
-    /** Per-chain breakdown of the fee. Omitted for flat fees (e.g. forwarder). */
-    allocations?: FeeAllocation$1[];
-    /**
-     * When `type === 'kit'`, the address that receives the kit fee.
-     * Omitted for other fee types.
-     */
-    recipientAddress?: string;
-}
 /**
  * Cost estimation for a spend (mint) operation.
  *
@@ -4855,7 +5053,7 @@ interface FeeEntry$1 {
  */
 interface EstimateSpendResult$1 {
     /** Itemised fee breakdown for the spend operation. */
-    fees: FeeEntry$1[];
+    fees: FeeEntry[];
 }
 
 /**
@@ -6242,80 +6440,7 @@ type FeeRecipientChainType = 'evm' | 'solana';
  * ```
  */
 type FeeRecipientsConfig = Partial<Record<FeeRecipientChainType, string>>;
-/**
- * Fee category describing the origin of a fee line item.
- *
- * - `'provider'`  — Fee charged by the cross-chain 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';
-/**
- * Per-chain breakdown of a fee amount.
- *
- * @example
- * ```typescript
- * import type { FeeAllocation } from '@circle-fin/unified-balance-kit'
- *
- * const allocation: FeeAllocation = {
- *   chain: 'Ethereum',
- *   amount: '0.00005',
- * }
- * ```
- */
-interface FeeAllocation {
-    /** The chain to which this portion of the fee applies. */
-    chain: Blockchain;
-    /** The fee amount on this chain (human-readable decimal string). */
-    amount: string;
-}
-/**
- * A single fee line item within an estimate.
- *
- * @remarks
- * Each entry describes a fee category (`type`), the token it is
- * denominated in, the aggregate `amount`, and an optional per-chain
- * `allocations` breakdown.
- *
- * @example
- * ```typescript
- * import type { FeeEntry } from '@circle-fin/unified-balance-kit'
- *
- * // Fee with per-chain allocation breakdown
- * const providerFee: FeeEntry = {
- *   type: 'provider',
- *   token: 'USDC',
- *   amount: '0.00011',
- *   allocations: [
- *     { chain: 'Ethereum', amount: '0.00005' },
- *     { chain: 'Polygon', amount: '0.00006' },
- *   ],
- * }
- *
- * // Flat fee without allocations (e.g. forwarder)
- * const forwarderFee: FeeEntry = {
- *   type: 'forwarder',
- *   token: 'USDC',
- *   amount: '0.005',
- * }
- * ```
- */
-interface FeeEntry {
-    /** The category of this fee. */
-    type: FeeType;
-    /** The token in which this fee is denominated (e.g. `'USDC'`, `'ETH'`). */
-    token: string;
-    /** Aggregate fee amount (human-readable decimal string). */
-    amount: string;
-    /** Per-chain breakdown of the fee. Omitted for flat fees (e.g. forwarder). */
-    allocations?: FeeAllocation[];
-    /**
-     * When `type === 'kit'`, the address that receives the kit fee.
-     * Omitted for other fee types.
-     */
-    recipientAddress?: string;
-}
+
 /**
  * Cost estimation for a spend (mint) operation.
  *
@@ -6494,6 +6619,41 @@ interface UnifiedBalanceKitConfig<TExtraProviders extends FlexibleGatewayProvide
      * @defaultValue false
      */
     excludeDefaultProviders?: boolean;
+    /**
+     * Custom HTTP headers forwarded with every Circle Gateway API request the
+     * default Gateway v1 provider makes (balances, deposits, spend estimate,
+     * transfer, forwarder status, and `/v1/info`).
+     *
+     * @remarks
+     * Headers are merged on top of the SDK defaults (such as `Content-Type`)
+     * rather than replacing them. Each header is forwarded as-is to Circle's
+     * API; the SDK does not interpret it. Only applies to the default provider —
+     * has no effect when `excludeDefaultProviders` is `true` or on custom
+     * providers supplied via `providers`.
+     *
+     * @example
+     * ```typescript
+     * const kit = new UnifiedBalanceKit({
+     *   headers: { 'X-Access-Key': process.env.GATEWAY_ACCESS_KEY! },
+     * })
+     * ```
+     */
+    headers?: Record<string, string>;
+}
+
+/**
+ * USD exchange-rate metadata.
+ *
+ * Non-binding, useful for USD-denominated fee estimates. `feeTokenUsd` prices
+ * the source-chain fee token (the token `feeTotalAmount` is denominated in).
+ *
+ * @internal
+ */
+interface FeeQuoteExchangeRates {
+    /** USD price of the fee token, as a decimal string. */
+    readonly feeTokenUsd: string;
+    /** USD price of the destination token, as a decimal string. */
+    readonly destinationTokenUsd: string;
 }
 
 /**
@@ -6535,7 +6695,7 @@ type AllowanceStrategy = 'approve' | 'permit' | 'authorize';
  * }
  * ```
  */
-interface DepositParams<TAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities, TChainIdentifier extends UnifiedBalanceChainIdentifier = UnifiedBalanceChainIdentifier> {
+interface DepositParams<TAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities, TChainIdentifier extends BridgeChainIdentifier = BridgeChainIdentifier> {
     /**
      * The adapter context identifying the depositor and chain.
      */
@@ -6548,7 +6708,7 @@ interface DepositParams<TAdapterCapabilities extends AdapterCapabilities = Adapt
     amount: string;
     /**
      * The token to deposit.
-     * Accepts any case (e.g. `'usdc'`, `'Usdc'`); normalised to uppercase internally.
+     * Accepts any case (e.g. `'usdc'`, `'Usdc'`); normalized to uppercase internally.
      *
      * @defaultValue 'USDC'
      */
@@ -6556,9 +6716,40 @@ interface DepositParams<TAdapterCapabilities extends AdapterCapabilities = Adapt
     /**
      * The token allowance strategy to authorize the deposit.
      *
+     * Only valid for same-chain (STANDARD) deposits. Must not be set when
+     * `to` is provided (FAST cross-chain deposits do not use an allowance
+     * strategy).
+     *
      * @defaultValue 'authorize'
      */
     allowanceStrategy?: AllowanceStrategy;
+    /**
+     * Destination chain for a FAST cross-chain deposit.
+     *
+     * When set, the deposit follows the prepaid-FORWARD CCTP v2 path:
+     * the burned USDC is minted to the GenericExecutor on the destination
+     * chain, which then calls Gateway `deposit` in a single relayed flow.
+     *
+     * Must not be set when `config.transferSpeed` is `'STANDARD'`.
+     */
+    to?: {
+        chain: UnifiedBalanceChainIdentifier;
+    };
+    /**
+     * Transfer configuration for the deposit.
+     *
+     * @defaultValue `{ transferSpeed: 'STANDARD' }`. Set `transferSpeed: 'FAST'`
+     *   explicitly for cross-chain deposits (when `to` is provided).
+     */
+    config?: DepositConfig;
+    /**
+     * Opaque signed fee-quote bytes from the Quote API.
+     *
+     * Pass this to commit to the fee price returned by a previous
+     * {@link estimateDeposit} call (see {@link EstimateDepositResult.quote}).
+     * When omitted a fresh quote is fetched automatically (FAST path only).
+     */
+    quote?: string;
 }
 /**
  * Parameters for depositing tokens into *another* Gateway account.
@@ -6585,7 +6776,7 @@ interface DepositParams<TAdapterCapabilities extends AdapterCapabilities = Adapt
  * }
  * ```
  */
-interface DepositForParams<TAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities, TChainIdentifier extends UnifiedBalanceChainIdentifier = UnifiedBalanceChainIdentifier> extends Omit<DepositParams<TAdapterCapabilities, TChainIdentifier>, 'allowanceStrategy'> {
+interface DepositForParams<TAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities, TChainIdentifier extends BridgeChainIdentifier = BridgeChainIdentifier> extends Omit<DepositParams<TAdapterCapabilities, TChainIdentifier>, 'allowanceStrategy'> {
     /**
      * The Gateway account address to credit with the deposit.
      *
@@ -6594,6 +6785,34 @@ interface DepositForParams<TAdapterCapabilities extends AdapterCapabilities = Ad
      */
     depositAccount: string;
 }
+/**
+ * Relay progress for a cross-chain (FAST) deposit.
+ *
+ * Set after `depositFastCrossChain` completes the ~60-second relay wait.
+ * Always present on the FAST path; absent on same-chain STANDARD deposits.
+ *
+ * @example
+ * ```typescript
+ * if (result.progress?.status === 'DONE') {
+ *   console.log('Minted on destination:', result.txHash)
+ * } else if (result.progress?.status === 'PENDING') {
+ *   console.log('Relay still in progress — poll getDepositStatus later')
+ * } else if (result.progress?.status === 'FAILED') {
+ *   console.log('Relay failed — manual mint may be required')
+ * }
+ * ```
+ */
+interface DepositProgress {
+    /**
+     * Relay outcome after the burn is confirmed on the source chain.
+     *
+     * - `'DONE'`    — Circle's relayer minted USDC on the destination chain.
+     * - `'PENDING'` — Relay timed out (~60 s); the mint may still complete.
+     * - `'FAILED'`  — Relayer reported a permanent failure; manual mint may
+     *                 be required.
+     */
+    status: 'DONE' | 'PENDING' | 'FAILED';
+}
 /**
  * Result returned after a successful deposit operation.
  *
@@ -6623,22 +6842,232 @@ interface DepositResult {
     depositedTo: string;
     /** The address that signed and funded the deposit. */
     depositedBy: string;
-    /** The chain on which the deposit occurred. */
+    /**
+     * The chain where the deposit balance lands.
+     *
+     * @remarks For cross-chain (FAST) deposits this is the destination chain
+     * where the minted USDC is credited. For same-chain (STANDARD) deposits it
+     * is the chain the deposit occurred on. Prefer `sourceChain` /
+     * `destinationChain` for cross-chain flows.
+     */
     chain: Blockchain;
     /**
-     * Unique identifier returned by the blockchain once the
-     * transaction is mined.
+     * Transaction hash of the completed deposit.
+     *
+     * @remarks
+     * For same-chain (STANDARD) deposits this is the on-chain deposit
+     * transaction. For cross-chain (FAST) deposits with
+     * `progress.status === 'DONE'` this is the Circle-relayed mint on the
+     * destination chain; when the relay is still pending or has failed it
+     * falls back to the source-chain burn hash.
      */
     txHash: string;
     /**
-     * Link to view the transaction details on the appropriate
-     * blockchain explorer.
+     * Link to view the transaction on a block explorer.
      *
      * @remarks
-     * May be `undefined` when the explorer URL cannot be resolved
-     * for the chain.
+     * Follows the same chain as {@link txHash}: points to the destination-chain
+     * mint for a completed FAST deposit, or the source-chain burn otherwise.
+     * May be `undefined` when the chain has no configured explorer URL.
      */
     explorerUrl?: string;
+    /**
+     * Source chain of the cross-chain deposit (FAST path only).
+     *
+     * Present when `to` was specified in the deposit params.
+     */
+    sourceChain?: Blockchain;
+    /**
+     * Destination chain of the cross-chain deposit (FAST path only).
+     *
+     * Present when `to` was specified in the deposit params.
+     */
+    destinationChain?: Blockchain;
+    /**
+     * Itemised fee breakdown for the cross-chain deposit (FAST path only).
+     *
+     * Contains at least a `gasFee` entry and a `forwarder` entry (Circle
+     * FORWARD fee). The `gasFee` covers the source-chain burn gas; when a
+     * `usdc.approve` was required it also includes the actual on-chain approve
+     * gas derived from the transaction receipt.
+     */
+    fees?: FeeEntry[];
+    /**
+     * Relay progress after the source-chain burn (FAST path only).
+     *
+     * Present on every FAST deposit result. Use this to determine whether
+     * the destination-chain mint completed within the ~60-second relay window.
+     */
+    progress?: DepositProgress;
+}
+/**
+ * Transfer-speed configuration for a deposit operation.
+ *
+ * @example
+ * ```typescript
+ * import type { DepositConfig } from '@circle-fin/unified-balance-kit'
+ *
+ * const config: DepositConfig = { transferSpeed: 'FAST' }
+ * ```
+ */
+interface DepositConfig {
+    /**
+     * Requested transfer speed for a cross-chain fast deposit.
+     *
+     * @defaultValue `'STANDARD'`
+     */
+    transferSpeed?: 'FAST' | 'STANDARD';
+}
+/**
+ * Parameters for estimating the fees of a fast cross-chain deposit.
+ *
+ * The result is plain, serializable data — no live adapter reference is
+ * included. Pass the result (plus `from`) directly to
+ * {@link DepositParams} or {@link DepositForParams} for execution:
+ *
+ * ```typescript
+ * const estimate = await kit.estimateDeposit({ from, amount, token, to })
+ * const result   = await kit.deposit({ ...estimate, from })
+ * ```
+ *
+ * @typeParam TAdapterCapabilities - Adapter capability constraints.
+ * @typeParam TChainIdentifier - Accepted chain identifier type.
+ *
+ * @example
+ * ```typescript
+ * import type { EstimateDepositParams } from '@circle-fin/unified-balance-kit'
+ *
+ * const params: EstimateDepositParams = {
+ *   from: { adapter: evmAdapter, chain: 'Ethereum' },
+ *   amount: '100',
+ *   to: { chain: 'Arc_Testnet' },
+ *   config: { transferSpeed: 'FAST' },
+ * }
+ * ```
+ */
+interface EstimateDepositParams<TAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities, TChainIdentifier extends BridgeChainIdentifier = BridgeChainIdentifier> {
+    /**
+     * The adapter context identifying the depositor and source chain.
+     * The adapter is used for source-chain gas estimation.
+     */
+    from: AdapterContext<TAdapterCapabilities, TChainIdentifier>;
+    /**
+     * The amount of tokens to deposit (human-readable decimal string).
+     *
+     * @example "100", "0.5"
+     */
+    amount: string;
+    /**
+     * The token to deposit.
+     *
+     * @defaultValue 'USDC'
+     */
+    token?: SupportedTokenInput;
+    /**
+     * Destination chain for a FAST cross-chain deposit.
+     *
+     * Required when `config.transferSpeed` is `'FAST'`.
+     * Must not be set when `config.transferSpeed` is `'STANDARD'` (the default).
+     */
+    to?: {
+        chain: UnifiedBalanceChainIdentifier;
+    };
+    /**
+     * Transfer configuration.
+     *
+     * @defaultValue `{ transferSpeed: 'STANDARD' }`
+     */
+    config?: DepositConfig;
+    /**
+     * Gateway account address to credit (for a `depositFor` round-trip).
+     *
+     * When provided, this value is echoed on the result so
+     * `kit.depositFor({ ...estimate, from })` works without re-specifying it.
+     */
+    depositAccount?: string;
+    /**
+     * Allowance strategy echoed to the result for round-trip convenience.
+     */
+    allowanceStrategy?: AllowanceStrategy;
+}
+/**
+ * Fee-preview result returned by `estimateDeposit`.
+ *
+ * Plain, serializable data — no live adapter reference. Pass the result
+ * directly to `deposit` or `depositFor` (re-attaching only `from`):
+ *
+ * ```typescript
+ * const estimate = await kit.estimateDeposit({ from, amount, token, to })
+ * const result   = await kit.deposit({ ...estimate, from })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import type { EstimateDepositResult } from '@circle-fin/unified-balance-kit'
+ *
+ * const result: EstimateDepositResult = {
+ *   amount: '100',
+ *   token: 'USDC',
+ *   to: { chain: 'Arc_Testnet' },
+ *   config: { transferSpeed: 'FAST' },
+ *   fees: [
+ *     { type: 'gasFee',    token: 'ETH',  amount: '0.0002' },
+ *     { type: 'forwarder', token: 'USDC', amount: '0.12'   },
+ *   ],
+ *   quote: '0x…',
+ * }
+ * ```
+ */
+interface EstimateDepositResult {
+    /** Deposit amount (human-readable decimal string). */
+    amount: string;
+    /** Normalized token to deposit. */
+    token: SupportedToken;
+    /**
+     * Destination chain (echoed from input).
+     *
+     * Present for FAST transfers; absent for STANDARD.
+     */
+    to?: {
+        chain: UnifiedBalanceChainIdentifier;
+    };
+    /** Transfer configuration (echoed with defaults applied). */
+    config: Required<DepositConfig>;
+    /**
+     * Itemized fee breakdown.
+     *
+     * Always contains at least a `gasFee` entry. For FAST transfers the gas
+     * cost includes the source-chain burn; when the current USDC allowance is
+     * insufficient it also includes the `usdc.approve` transaction. For
+     * STANDARD deposits on EVM with `allowanceStrategy: 'approve'`, or any
+     * `depositFor` on EVM, the gas cost includes both the
+     * `usdc.increaseAllowance` and the deposit transaction. A `forwarder`
+     * entry is always present for FAST cross-chain transfers.
+     */
+    fees: FeeEntry[];
+    /**
+     * Opaque signed fee-quote bytes from the Quote API.
+     *
+     * Present for FAST cross-chain deposits; absent for STANDARD or
+     * same-chain. Pass this to {@link deposit} or {@link depositFor} to
+     * commit to the quoted price.
+     */
+    quote?: string;
+    /**
+     * Gateway account to credit (echoed from input for `depositFor` round-trip).
+     */
+    depositAccount?: string;
+    /**
+     * Allowance strategy (echoed from input for `deposit` round-trip).
+     */
+    allowanceStrategy?: AllowanceStrategy;
+    /**
+     * Optional USD exchange-rate metadata from the Quote API.
+     *
+     * Present when the Quote API returns exchange rates for the fee token
+     * and destination token. Non-binding; useful for USD-denominated display.
+     */
+    exchangeRates?: FeeQuoteExchangeRates;
 }
 
 /**
@@ -7386,6 +7815,35 @@ declare class AppKitUnifiedBalance {
      * ```
      */
     depositFor(params: DepositForParams): Promise<DepositResult>;
+    /**
+     * Estimate the fees for a deposit without executing it.
+     *
+     * Return plain, serializable data that can be spread directly into
+     * {@link AppKitUnifiedBalance.deposit} or
+     * {@link AppKitUnifiedBalance.depositFor}.
+     *
+     * @param params - Estimate details including the depositor context, amount,
+     *   destination chain, and optional transfer speed.
+     * @returns Promise resolving to the itemised fee estimate.
+     * @throws {KitError} If the estimate parameters are invalid or the route is
+     *   unsupported.
+     *
+     * @example
+     * ```typescript
+     * const estimate = await kit.unifiedBalance.estimateDeposit({
+     *   from: { adapter, chain: 'Ethereum' },
+     *   amount: '100',
+     *   to: { chain: 'Polygon' },
+     *   config: { transferSpeed: 'FAST' },
+     * })
+     *
+     * const result = await kit.unifiedBalance.deposit({
+     *   ...estimate,
+     *   from: { adapter, chain: 'Ethereum' },
+     * })
+     * ```
+     */
+    estimateDeposit(params: EstimateDepositParams): Promise<EstimateDepositResult>;
     /**
      * Spend (mint) USDC on a destination chain by pulling funds from one or
      * more account sources.