@circle-fin/app-kit 1.12.1 → 1.14.0

package/swap.d.cts

@@ -559,6 +559,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.
@@ -718,6 +731,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",
@@ -946,6 +961,7 @@ declare enum BridgeChain {
     Morph = "Morph",
     Optimism = "Optimism",
     Pharos = "Pharos",
+    Plasma = "Plasma",
     Plume = "Plume",
     Polygon = "Polygon",
     Sei = "Sei",
@@ -971,6 +987,7 @@ declare enum BridgeChain {
     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",
@@ -2652,7 +2669,7 @@ interface ExecuteParams {
  *   fromAddress: '0x...',
  *   toAddress: '0x...',
  *   amount: '1000000',
- *   apiKey: 'KIT_KEY:...',
+ *   apiKey: 'TEST_API_KEY:...',
  * })
  *
  * // Build token inputs with permit
@@ -2796,7 +2813,7 @@ interface ExecuteSwapEVMParams extends ActionParameters {
  *   fromAddress: 'YubQzu18FDqJRyNfG8JqHmsdbxhnoQqcKUHBdUkN6tP',
  *   toAddress: 'YubQzu18FDqJRyNfG8JqHmsdbxhnoQqcKUHBdUkN6tP',
  *   amount: '1000000',
- *   apiKey: 'KIT_KEY:...',
+ *   apiKey: 'TEST_API_KEY:...',
  * })
  *
  * // Prepare action parameters
@@ -5459,6 +5476,48 @@ TChainDefinition extends ChainDefinition = ChainDefinition> extends WalletContex
      * Must be a valid address format for the specified blockchain.
      */
     recipientAddress?: string;
+    /**
+     * Optional destination dApp deposit action for a fast cross-chain transfer.
+     *
+     * When set, the burned USDC is minted to Circle's GenericExecutor on the
+     * destination chain, which calls the registered dApp (for example, a Gateway
+     * `depositFor`) in the same relayed flow. Consumed by the CCTP v2 provider's
+     * executor-deposit path; requires `useForwarder: true`.
+     *
+     * @see {@link BridgeDepositAction}
+     */
+    deposit?: BridgeDepositAction;
+}
+/**
+ * Destination dApp deposit action for a fast cross-chain transfer.
+ *
+ * When present on a bridge destination, the CCTP v2 provider routes the
+ * transfer through Circle's GenericExecutor: the burned USDC is minted to the
+ * executor on the destination chain, which then calls the registered dApp (for
+ * example, a Gateway `depositFor`) in the same relayed flow. Encoded into
+ * executor hookData via `buildDepositForGenericExecutorPayload`.
+ *
+ * @example
+ * ```typescript
+ * import type { BridgeDepositAction } from '@core/provider'
+ *
+ * const deposit: BridgeDepositAction = {
+ *   dappId: 'gateway_deposit',
+ *   params: ['0xTokenMessengerWithFees', '0xDepositAccount', 0n],
+ * }
+ * ```
+ */
+interface BridgeDepositAction {
+    /**
+     * Registered dApp identifier the GenericExecutor invokes on the destination
+     * chain (for example, `'gateway_deposit'`).
+     */
+    dappId: string;
+    /**
+     * Positional arguments for the dApp function, in ABI order. Dynamic amount
+     * slots are filled in by the executor from the minted amount.
+     */
+    params: readonly unknown[];
 }
 /**
  * Parameters for executing a cross-chain bridge operation.
@@ -5909,12 +5968,21 @@ interface ServiceSwapConfig {
         recipientAddress?: string;
     };
     /**
-     * Stablecoin Service Kit Key used to authenticate service-backed swap
-     * requests.
+     * Circle API key used to authenticate service-backed swap requests.
+     *
+     * Format: `<ENV>_API_KEY:<keyId>:<keySecret>`. A legacy
+     * `KIT_KEY:<keyId>:<keySecret>` value is also accepted.
      *
      * Treat this value as a credential. Do not log it, embed it in client-side
      * source, or expose it in telemetry.
      */
+    apiKey?: string | undefined;
+    /**
+     * Circle API key used to authenticate service-backed swap requests.
+     *
+     * @deprecated Use {@link ServiceSwapConfig.apiKey} instead. Still honored
+     * when `apiKey` is omitted, and `apiKey` takes precedence when both are set.
+     */
     kitKey?: string;
     /**
      * DEX aggregator identifier used to source the swap route.
@@ -6445,12 +6513,21 @@ interface SwapConfig {
         recipientAddress: string;
     };
     /**
-     * Stablecoin Service Kit Key used to authenticate service-backed swap
-     * requests.
+     * Circle API key used to authenticate service-backed swap requests.
+     *
+     * Format: `<ENV>_API_KEY:<keyId>:<keySecret>`. A legacy
+     * `KIT_KEY:<keyId>:<keySecret>` value is also accepted.
      *
      * Treat this value as a credential. Do not log it, embed it in client-side
      * source, or expose it in telemetry.
      */
+    apiKey?: string | undefined;
+    /**
+     * Circle API key used to authenticate service-backed swap requests.
+     *
+     * @deprecated Use {@link SwapConfig.apiKey} instead. Still honored when
+     * `apiKey` is omitted, and `apiKey` takes precedence when both are set.
+     */
     kitKey?: string;
 }
 /**
@@ -6490,7 +6567,13 @@ interface ResolvedSwapConfig extends Omit<SwapConfig, 'customFee'> {
         recipientAddress?: string;
     };
 }
-type SwapResultConfig = Omit<ResolvedSwapConfig, 'kitKey'>;
+/**
+ * Swap config as echoed back on a result, with credentials removed.
+ *
+ * Both credential fields are omitted so a returned {@link SwapResult} can be
+ * logged or serialized without leaking the secret used to authenticate it.
+ */
+type SwapResultConfig = Omit<ResolvedSwapConfig, 'apiKey' | 'kitKey'>;
 /**
  * Result of an executed swap operation.
  *
@@ -6786,6 +6869,30 @@ interface SwapParams<TFromAdapterCapabilities extends AdapterCapabilities = Adap
     config?: SwapConfig;
 }
 
+/**
+ * Configure how CCTP and forwarding fees are collected for a bridge.
+ *
+ * @remarks
+ * Use `'source'` with `to.useForwarder: true` to treat `amount` as the exact
+ * destination amount. Bridge Kit obtains a signed fee quote, collects the fee
+ * in source-chain USDC, and leaves the destination mint unreduced. Omit the
+ * option (or use `'destination'`) to preserve the existing max-fee behavior.
+ *
+ * @example
+ * ```typescript
+ * import type { BridgeExecutionConfig } from '@circle-fin/bridge-kit'
+ *
+ * const config: BridgeExecutionConfig = {
+ *   transferSpeed: 'FAST',
+ *   feePayment: 'source',
+ * }
+ * ```
+ * @since 1.14.0
+ */
+interface BridgeExecutionConfig extends BridgeConfig {
+    /** Select source-side signed fees or the legacy destination-side fee path. */
+    feePayment?: 'source' | 'destination';
+}
 type FeeFunction<TFromAdapterCapabilities extends AdapterCapabilities, TToAdapterCapabilities extends AdapterCapabilities> = (params: BridgeParams$1<TFromAdapterCapabilities, TToAdapterCapabilities>) => Promise<string> | string;
 type FeeRecipientFunction<TFromAdapterCapabilities extends AdapterCapabilities, TToAdapterCapabilities extends AdapterCapabilities> = (feePayoutChain: ChainDefinition, params: BridgeParams$1<TFromAdapterCapabilities, TToAdapterCapabilities>) => Promise<string> | string;
 /**
@@ -6946,7 +7053,7 @@ interface BridgeParams<TFromAdapterCapabilities extends AdapterCapabilities = Ad
      * Optional bridge configuration (e.g., transfer speed).
      * If omitted, defaults will be used
      */
-    config?: BridgeConfig;
+    config?: BridgeExecutionConfig;
     /**
      * The token to transfer. Defaults to 'USDC'.
      * If omitted, the provider will use 'USDC' by default.
@@ -6973,6 +7080,16 @@ interface BridgeParams<TFromAdapterCapabilities extends AdapterCapabilities = Ad
      * ```
      */
     invocationMeta?: InvocationMeta;
+    /**
+     * Reuse the opaque signed quote returned by a receive-exact estimate.
+     *
+     * @remarks
+     * Bridge Kit validates a supplied quote against the exact transfer and fails
+     * when it is invalid, mismatched, expired, or too close to expiry. Omit this
+     * value to let Bridge Kit fetch a fresh quote automatically. Never log or
+     * decode it.
+     */
+    quote?: string;
 }
 
 /**
@@ -7017,29 +7134,37 @@ type EarnAdapterContext<TAdapterCapabilities extends AdapterCapabilities = Adapt
  * Configuration options for earn operations.
  *
  * EarnKit supports dual-mode authentication: operations work both with
- * and without a Kit Key. When present, the Kit Key enables permissioned
+ * and without an API key. When present, the API key enables permissioned
  * features like integrator attribution tracking.
  *
  * @example
  * ```typescript
- * // Permissionless (no Kit Key)
+ * // Permissionless (no API key)
  * const config: EarnConfig = {}
  *
- * // Permissioned (with Kit Key)
+ * // Permissioned (with API key)
  * const config: EarnConfig = {
- *   kitKey: 'KIT_KEY:keyId:keySecret',
+ *   apiKey: 'TEST_API_KEY:keyId:keySecret',
  * }
  * ```
  */
 interface EarnConfig {
     /**
-     * Optional Kit Key for permissioned access.
+     * Optional Circle API key for permissioned access.
      *
      * When provided, enables integrator attribution tracking and
      * higher rate limits. When omitted, the SDK operates in
      * permissionless mode.
      *
-     * Format: `KIT_KEY:<keyId>:<keySecret>`
+     * Format: `<ENV>_API_KEY:<keyId>:<keySecret>`. A legacy
+     * `KIT_KEY:<keyId>:<keySecret>` value is also accepted.
+     */
+    readonly apiKey?: string | undefined;
+    /**
+     * Optional Circle API key for permissioned access.
+     *
+     * @deprecated Use {@link EarnConfig.apiKey} instead. Still honored when
+     * `apiKey` is omitted, and `apiKey` takes precedence when both are set.
      */
     readonly kitKey?: string | undefined;
     /**
@@ -7806,13 +7931,18 @@ interface AppKitContext {
      */
     disableErrorReporting?: boolean;
     /**
-     * Custom HTTP headers forwarded with the underlying CCTP provider's
-     * attestation (Iris) API requests made by bridge operations.
+     * Custom HTTP headers forwarded with Circle API requests made by the
+     * underlying kits: the CCTP provider's attestation (Iris) requests for
+     * bridge operations, and the Gateway API requests for unified-balance
+     * operations.
      *
      * @remarks
      * Headers are merged on top of the SDK defaults (such as `Content-Type`)
-     * rather than replacing them. The header is forwarded as-is to Circle's API;
-     * the SDK does not interpret it.
+     * rather than replacing them. Each header is forwarded as-is to Circle's API;
+     * the SDK does not interpret it. The same map is forwarded to every relevant
+     * kit, so a header a given API ignores is simply a no-op there. A
+     * `unifiedBalance.headers` value, if provided, takes precedence for the
+     * unified-balance kit.
      */
     headers?: Record<string, string>;
 }

package/swap.d.mts

@@ -559,6 +559,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.
@@ -718,6 +731,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",
@@ -946,6 +961,7 @@ declare enum BridgeChain {
     Morph = "Morph",
     Optimism = "Optimism",
     Pharos = "Pharos",
+    Plasma = "Plasma",
     Plume = "Plume",
     Polygon = "Polygon",
     Sei = "Sei",
@@ -971,6 +987,7 @@ declare enum BridgeChain {
     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",
@@ -2652,7 +2669,7 @@ interface ExecuteParams {
  *   fromAddress: '0x...',
  *   toAddress: '0x...',
  *   amount: '1000000',
- *   apiKey: 'KIT_KEY:...',
+ *   apiKey: 'TEST_API_KEY:...',
  * })
  *
  * // Build token inputs with permit
@@ -2796,7 +2813,7 @@ interface ExecuteSwapEVMParams extends ActionParameters {
  *   fromAddress: 'YubQzu18FDqJRyNfG8JqHmsdbxhnoQqcKUHBdUkN6tP',
  *   toAddress: 'YubQzu18FDqJRyNfG8JqHmsdbxhnoQqcKUHBdUkN6tP',
  *   amount: '1000000',
- *   apiKey: 'KIT_KEY:...',
+ *   apiKey: 'TEST_API_KEY:...',
  * })
  *
  * // Prepare action parameters
@@ -5459,6 +5476,48 @@ TChainDefinition extends ChainDefinition = ChainDefinition> extends WalletContex
      * Must be a valid address format for the specified blockchain.
      */
     recipientAddress?: string;
+    /**
+     * Optional destination dApp deposit action for a fast cross-chain transfer.
+     *
+     * When set, the burned USDC is minted to Circle's GenericExecutor on the
+     * destination chain, which calls the registered dApp (for example, a Gateway
+     * `depositFor`) in the same relayed flow. Consumed by the CCTP v2 provider's
+     * executor-deposit path; requires `useForwarder: true`.
+     *
+     * @see {@link BridgeDepositAction}
+     */
+    deposit?: BridgeDepositAction;
+}
+/**
+ * Destination dApp deposit action for a fast cross-chain transfer.
+ *
+ * When present on a bridge destination, the CCTP v2 provider routes the
+ * transfer through Circle's GenericExecutor: the burned USDC is minted to the
+ * executor on the destination chain, which then calls the registered dApp (for
+ * example, a Gateway `depositFor`) in the same relayed flow. Encoded into
+ * executor hookData via `buildDepositForGenericExecutorPayload`.
+ *
+ * @example
+ * ```typescript
+ * import type { BridgeDepositAction } from '@core/provider'
+ *
+ * const deposit: BridgeDepositAction = {
+ *   dappId: 'gateway_deposit',
+ *   params: ['0xTokenMessengerWithFees', '0xDepositAccount', 0n],
+ * }
+ * ```
+ */
+interface BridgeDepositAction {
+    /**
+     * Registered dApp identifier the GenericExecutor invokes on the destination
+     * chain (for example, `'gateway_deposit'`).
+     */
+    dappId: string;
+    /**
+     * Positional arguments for the dApp function, in ABI order. Dynamic amount
+     * slots are filled in by the executor from the minted amount.
+     */
+    params: readonly unknown[];
 }
 /**
  * Parameters for executing a cross-chain bridge operation.
@@ -5909,12 +5968,21 @@ interface ServiceSwapConfig {
         recipientAddress?: string;
     };
     /**
-     * Stablecoin Service Kit Key used to authenticate service-backed swap
-     * requests.
+     * Circle API key used to authenticate service-backed swap requests.
+     *
+     * Format: `<ENV>_API_KEY:<keyId>:<keySecret>`. A legacy
+     * `KIT_KEY:<keyId>:<keySecret>` value is also accepted.
      *
      * Treat this value as a credential. Do not log it, embed it in client-side
      * source, or expose it in telemetry.
      */
+    apiKey?: string | undefined;
+    /**
+     * Circle API key used to authenticate service-backed swap requests.
+     *
+     * @deprecated Use {@link ServiceSwapConfig.apiKey} instead. Still honored
+     * when `apiKey` is omitted, and `apiKey` takes precedence when both are set.
+     */
     kitKey?: string;
     /**
      * DEX aggregator identifier used to source the swap route.
@@ -6445,12 +6513,21 @@ interface SwapConfig {
         recipientAddress: string;
     };
     /**
-     * Stablecoin Service Kit Key used to authenticate service-backed swap
-     * requests.
+     * Circle API key used to authenticate service-backed swap requests.
+     *
+     * Format: `<ENV>_API_KEY:<keyId>:<keySecret>`. A legacy
+     * `KIT_KEY:<keyId>:<keySecret>` value is also accepted.
      *
      * Treat this value as a credential. Do not log it, embed it in client-side
      * source, or expose it in telemetry.
      */
+    apiKey?: string | undefined;
+    /**
+     * Circle API key used to authenticate service-backed swap requests.
+     *
+     * @deprecated Use {@link SwapConfig.apiKey} instead. Still honored when
+     * `apiKey` is omitted, and `apiKey` takes precedence when both are set.
+     */
     kitKey?: string;
 }
 /**
@@ -6490,7 +6567,13 @@ interface ResolvedSwapConfig extends Omit<SwapConfig, 'customFee'> {
         recipientAddress?: string;
     };
 }
-type SwapResultConfig = Omit<ResolvedSwapConfig, 'kitKey'>;
+/**
+ * Swap config as echoed back on a result, with credentials removed.
+ *
+ * Both credential fields are omitted so a returned {@link SwapResult} can be
+ * logged or serialized without leaking the secret used to authenticate it.
+ */
+type SwapResultConfig = Omit<ResolvedSwapConfig, 'apiKey' | 'kitKey'>;
 /**
  * Result of an executed swap operation.
  *
@@ -6786,6 +6869,30 @@ interface SwapParams<TFromAdapterCapabilities extends AdapterCapabilities = Adap
     config?: SwapConfig;
 }
 
+/**
+ * Configure how CCTP and forwarding fees are collected for a bridge.
+ *
+ * @remarks
+ * Use `'source'` with `to.useForwarder: true` to treat `amount` as the exact
+ * destination amount. Bridge Kit obtains a signed fee quote, collects the fee
+ * in source-chain USDC, and leaves the destination mint unreduced. Omit the
+ * option (or use `'destination'`) to preserve the existing max-fee behavior.
+ *
+ * @example
+ * ```typescript
+ * import type { BridgeExecutionConfig } from '@circle-fin/bridge-kit'
+ *
+ * const config: BridgeExecutionConfig = {
+ *   transferSpeed: 'FAST',
+ *   feePayment: 'source',
+ * }
+ * ```
+ * @since 1.14.0
+ */
+interface BridgeExecutionConfig extends BridgeConfig {
+    /** Select source-side signed fees or the legacy destination-side fee path. */
+    feePayment?: 'source' | 'destination';
+}
 type FeeFunction<TFromAdapterCapabilities extends AdapterCapabilities, TToAdapterCapabilities extends AdapterCapabilities> = (params: BridgeParams$1<TFromAdapterCapabilities, TToAdapterCapabilities>) => Promise<string> | string;
 type FeeRecipientFunction<TFromAdapterCapabilities extends AdapterCapabilities, TToAdapterCapabilities extends AdapterCapabilities> = (feePayoutChain: ChainDefinition, params: BridgeParams$1<TFromAdapterCapabilities, TToAdapterCapabilities>) => Promise<string> | string;
 /**
@@ -6946,7 +7053,7 @@ interface BridgeParams<TFromAdapterCapabilities extends AdapterCapabilities = Ad
      * Optional bridge configuration (e.g., transfer speed).
      * If omitted, defaults will be used
      */
-    config?: BridgeConfig;
+    config?: BridgeExecutionConfig;
     /**
      * The token to transfer. Defaults to 'USDC'.
      * If omitted, the provider will use 'USDC' by default.
@@ -6973,6 +7080,16 @@ interface BridgeParams<TFromAdapterCapabilities extends AdapterCapabilities = Ad
      * ```
      */
     invocationMeta?: InvocationMeta;
+    /**
+     * Reuse the opaque signed quote returned by a receive-exact estimate.
+     *
+     * @remarks
+     * Bridge Kit validates a supplied quote against the exact transfer and fails
+     * when it is invalid, mismatched, expired, or too close to expiry. Omit this
+     * value to let Bridge Kit fetch a fresh quote automatically. Never log or
+     * decode it.
+     */
+    quote?: string;
 }
 
 /**
@@ -7017,29 +7134,37 @@ type EarnAdapterContext<TAdapterCapabilities extends AdapterCapabilities = Adapt
  * Configuration options for earn operations.
  *
  * EarnKit supports dual-mode authentication: operations work both with
- * and without a Kit Key. When present, the Kit Key enables permissioned
+ * and without an API key. When present, the API key enables permissioned
  * features like integrator attribution tracking.
  *
  * @example
  * ```typescript
- * // Permissionless (no Kit Key)
+ * // Permissionless (no API key)
  * const config: EarnConfig = {}
  *
- * // Permissioned (with Kit Key)
+ * // Permissioned (with API key)
  * const config: EarnConfig = {
- *   kitKey: 'KIT_KEY:keyId:keySecret',
+ *   apiKey: 'TEST_API_KEY:keyId:keySecret',
  * }
  * ```
  */
 interface EarnConfig {
     /**
-     * Optional Kit Key for permissioned access.
+     * Optional Circle API key for permissioned access.
      *
      * When provided, enables integrator attribution tracking and
      * higher rate limits. When omitted, the SDK operates in
      * permissionless mode.
      *
-     * Format: `KIT_KEY:<keyId>:<keySecret>`
+     * Format: `<ENV>_API_KEY:<keyId>:<keySecret>`. A legacy
+     * `KIT_KEY:<keyId>:<keySecret>` value is also accepted.
+     */
+    readonly apiKey?: string | undefined;
+    /**
+     * Optional Circle API key for permissioned access.
+     *
+     * @deprecated Use {@link EarnConfig.apiKey} instead. Still honored when
+     * `apiKey` is omitted, and `apiKey` takes precedence when both are set.
      */
     readonly kitKey?: string | undefined;
     /**
@@ -7806,13 +7931,18 @@ interface AppKitContext {
      */
     disableErrorReporting?: boolean;
     /**
-     * Custom HTTP headers forwarded with the underlying CCTP provider's
-     * attestation (Iris) API requests made by bridge operations.
+     * Custom HTTP headers forwarded with Circle API requests made by the
+     * underlying kits: the CCTP provider's attestation (Iris) requests for
+     * bridge operations, and the Gateway API requests for unified-balance
+     * operations.
      *
      * @remarks
      * Headers are merged on top of the SDK defaults (such as `Content-Type`)
-     * rather than replacing them. The header is forwarded as-is to Circle's API;
-     * the SDK does not interpret it.
+     * rather than replacing them. Each header is forwarded as-is to Circle's API;
+     * the SDK does not interpret it. The same map is forwarded to every relevant
+     * kit, so a header a given API ignores is simply a no-op there. A
+     * `unifiedBalance.headers` value, if provided, takes precedence for the
+     * unified-balance kit.
      */
     headers?: Record<string, string>;
 }