@circle-fin/app-kit 1.12.1 → 1.13.0

package/context.d.mts

@@ -718,6 +718,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 +948,7 @@ declare enum BridgeChain {
     Morph = "Morph",
     Optimism = "Optimism",
     Pharos = "Pharos",
+    Plasma = "Plasma",
     Plume = "Plume",
     Polygon = "Polygon",
     Sei = "Sei",
@@ -971,6 +974,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 +2656,7 @@ interface ExecuteParams {
  *   fromAddress: '0x...',
  *   toAddress: '0x...',
  *   amount: '1000000',
- *   apiKey: 'KIT_KEY:...',
+ *   apiKey: 'TEST_API_KEY:...',
  * })
  *
  * // Build token inputs with permit
@@ -2796,7 +2800,7 @@ interface ExecuteSwapEVMParams extends ActionParameters {
  *   fromAddress: 'YubQzu18FDqJRyNfG8JqHmsdbxhnoQqcKUHBdUkN6tP',
  *   toAddress: 'YubQzu18FDqJRyNfG8JqHmsdbxhnoQqcKUHBdUkN6tP',
  *   amount: '1000000',
- *   apiKey: 'KIT_KEY:...',
+ *   apiKey: 'TEST_API_KEY:...',
  * })
  *
  * // Prepare action parameters
@@ -5796,6 +5800,30 @@ type BridgeDestination<TAdapterCapabilities extends AdapterCapabilities = Adapte
     useForwarder?: boolean;
 }) | ForwarderDestination<TChainIdentifier>;
 
+/**
+ * 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;
 /**
@@ -5956,7 +5984,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.
@@ -5983,6 +6011,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;
 }
 
 /**
@@ -6098,12 +6136,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.
@@ -6581,12 +6628,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;
 }
 /**
@@ -6715,29 +6771,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;
     /**
@@ -7504,13 +7568,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/context.d.ts

@@ -718,6 +718,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 +948,7 @@ declare enum BridgeChain {
     Morph = "Morph",
     Optimism = "Optimism",
     Pharos = "Pharos",
+    Plasma = "Plasma",
     Plume = "Plume",
     Polygon = "Polygon",
     Sei = "Sei",
@@ -971,6 +974,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 +2656,7 @@ interface ExecuteParams {
  *   fromAddress: '0x...',
  *   toAddress: '0x...',
  *   amount: '1000000',
- *   apiKey: 'KIT_KEY:...',
+ *   apiKey: 'TEST_API_KEY:...',
  * })
  *
  * // Build token inputs with permit
@@ -2796,7 +2800,7 @@ interface ExecuteSwapEVMParams extends ActionParameters {
  *   fromAddress: 'YubQzu18FDqJRyNfG8JqHmsdbxhnoQqcKUHBdUkN6tP',
  *   toAddress: 'YubQzu18FDqJRyNfG8JqHmsdbxhnoQqcKUHBdUkN6tP',
  *   amount: '1000000',
- *   apiKey: 'KIT_KEY:...',
+ *   apiKey: 'TEST_API_KEY:...',
  * })
  *
  * // Prepare action parameters
@@ -5796,6 +5800,30 @@ type BridgeDestination<TAdapterCapabilities extends AdapterCapabilities = Adapte
     useForwarder?: boolean;
 }) | ForwarderDestination<TChainIdentifier>;
 
+/**
+ * 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;
 /**
@@ -5956,7 +5984,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.
@@ -5983,6 +6011,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;
 }
 
 /**
@@ -6098,12 +6136,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.
@@ -6581,12 +6628,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;
 }
 /**
@@ -6715,29 +6771,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;
     /**
@@ -7504,13 +7568,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>;
 }