@circle-fin/app-kit 1.16.0 → 1.18.0

package/swap.d.cts

@@ -899,10 +899,10 @@ declare enum Blockchain {
  *
  * Unlike the full {@link Blockchain} enum, SwapChain includes mainnet
  * networks and explicitly whitelisted testnets (e.g., {@link Arc_Testnet})
- * where adapter contracts are deployed (CCTPv2 support).
+ * where Adapter contracts are deployed.
  *
  * Dynamic validation via {@link isSwapSupportedChain} ensures chains
- * automatically work when adapter contracts and supported tokens are deployed.
+ * automatically work when Adapter contracts and supported tokens are deployed.
  *
  * @example
  * ```typescript
@@ -942,20 +942,22 @@ declare enum SwapChain {
     HyperEVM = "HyperEVM",
     Monad = "Monad",
     Arc = "Arc",
+    Cronos = "Cronos",
+    Morph = "Morph",
     Arc_Testnet = "Arc_Testnet"
 }
 /**
  * Chain definition that supports swap operations.
  *
  * @remarks
- * Expanded from 4 to ~18 supported chains based on:
- * - CCTPv2 support (adapter contract deployed)
+ * Expanded from 4 to supported mainnets and whitelisted testnets based on:
+ * - A deployed Adapter contract, configured directly or through CCTP v2
  * - Mainnet chains plus whitelisted testnets (e.g., Arc Testnet)
  *
  * Use `isSwapSupportedChain()` for runtime validation.
  */
 type SwapChainDefinition = ChainDefinition & {
-    chain: Blockchain.Ethereum | Blockchain.Base | Blockchain.Polygon | Blockchain.Solana | Blockchain.Arbitrum | Blockchain.Optimism | Blockchain.Avalanche | Blockchain.Linea | Blockchain.Ink | Blockchain.World_Chain | Blockchain.Unichain | Blockchain.Plume | Blockchain.Sei | Blockchain.Sonic | Blockchain.XDC | Blockchain.HyperEVM | Blockchain.Monad | Blockchain.Arc | Blockchain.Arc_Testnet;
+    chain: Blockchain.Ethereum | Blockchain.Base | Blockchain.Polygon | Blockchain.Solana | Blockchain.Arbitrum | Blockchain.Optimism | Blockchain.Avalanche | Blockchain.Linea | Blockchain.Ink | Blockchain.World_Chain | Blockchain.Unichain | Blockchain.Plume | Blockchain.Sei | Blockchain.Sonic | Blockchain.XDC | Blockchain.HyperEVM | Blockchain.Monad | Blockchain.Arc | Blockchain.Cronos | Blockchain.Morph | Blockchain.Arc_Testnet;
 };
 /**
  * Chain identifier accepted by swap operations.
@@ -6207,6 +6209,44 @@ type BridgeDestination<TAdapterCapabilities extends AdapterCapabilities = Adapte
     useForwarder?: boolean;
 }) | ForwarderDestination<TChainIdentifier>;
 
+/** Token metadata for one side of a swap route step. */
+interface SwapRouteToken {
+    readonly symbol: string;
+    readonly address: string;
+    readonly decimals: number;
+}
+/** Amount estimates for a swap route step, expressed in base units. */
+interface SwapRouteStepEstimate {
+    readonly fromAmount: string;
+    readonly toAmount: string;
+    readonly gasCostUSD?: string;
+}
+/** A single swap or bridge hop selected by the route provider. */
+interface SwapRouteStep {
+    /** Hop kind, for example `swap` or `bridge`. */
+    readonly type: string;
+    /** Protocol identifier, for example `cctp-v2`. */
+    readonly tool: string;
+    /** Display name for {@link SwapRouteStep.tool}. */
+    readonly toolName: string;
+    readonly fromToken: SwapRouteToken;
+    readonly toToken: SwapRouteToken;
+    readonly estimate: SwapRouteStepEstimate;
+    /** Provider-specific details that are not part of the stable step shape. */
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/** Provider and executable hops selected for a swap. */
+interface SwapRoute {
+    /**
+     * Provider that routed the swap, for example `lifi` or `circle`. Treat as
+     * an opaque identifier; new providers can appear without an SDK release.
+     */
+    readonly provider: string;
+    readonly steps: readonly SwapRouteStep[];
+    /** Provider-specific details that are not part of the stable route shape. */
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+
 /**
  * Allowance strategy for token approvals during swap operations.
  *
@@ -6364,7 +6404,7 @@ interface ServiceSwapConfig {
      *
      * @defaultValue true
      */
-    batchTransactions?: boolean;
+    batchTransactions?: boolean | undefined;
 }
 /**
  * Parameters for initiating a swap operation through the Stablecoin Service.
@@ -6517,6 +6557,14 @@ interface ServiceSwapFee {
      * addresses are not available from the proxy response.
      */
     readonly recipientAddress?: string;
+    /** Provider-defined fee component (for example `FORWARD`). */
+    readonly component?: string;
+    /**
+     * Chain on which the fee is charged, as reported by the service
+     * (a `Blockchain` value such as `'Ethereum'`). Not validated
+     * against the `Blockchain` enum.
+     */
+    readonly chain?: string;
 }
 
 /**
@@ -6881,6 +6929,33 @@ interface SwapConfig {
      * `apiKey` is omitted, and `apiKey` takes precedence when both are set.
      */
     kitKey?: string;
+    /**
+     * Enable or disable atomic batched execution of the approval and swap.
+     *
+     * When `true` (or omitted), an EVM swap that needs an on-chain ERC-20
+     * approval submits the approval and the swap as one atomic batch if the
+     * connected wallet supports it (EIP-5792, or a signing strategy that
+     * declares atomic batching). Set to `false` to force the sequential
+     * approve-then-swap flow.
+     *
+     * @remarks
+     * Has no effect on the gasless permit path, native-token swaps, or Solana,
+     * which already execute as a single transaction. USDT input always uses the
+     * sequential path because its allowance must be reset to zero first. The
+     * batched path relies on the wallet's own gas estimation for the swap call;
+     * set `false` if your wallet under-estimates gas for complex routes or
+     * rejects batched calls.
+     *
+     * @defaultValue `undefined` (batching attempted when the wallet supports it)
+     *
+     * @example
+     * ```typescript
+     * const config: SwapConfig = {
+     *   batchTransactions: false, // force sequential approve → swap
+     * }
+     * ```
+     */
+    batchTransactions?: boolean | undefined;
 }
 /**
  * Configuration for swap results.
@@ -7021,6 +7096,8 @@ interface SwapResult {
      * fees (charged by the DEX aggregator/protocol) and kit fees.
      */
     fees?: readonly ServiceSwapFee[];
+    /** Provider and executable hops selected for the swap. */
+    readonly route?: SwapRoute;
     /**
      * Lifecycle snapshot: `status`, `substatus`, and `substatusMessage`.
      *
@@ -8491,11 +8568,11 @@ interface AppKitContext {
      */
     actions: Record<'bridge' | 'earn' | 'borrow', Record<string, ((payload: unknown) => void)[]>>;
     /**
-     * Disable success analytics for the underlying EarnKit, SwapKit,
+     * Disable success analytics for the underlying BridgeKit, EarnKit, SwapKit,
      * BorrowKit, and UnifiedBalanceKit.
      *
-     * When `true`, completed earn, swap, borrow, and unified balance operations
-     * will not POST analytics events. This does not disable error reporting; use
+     * When `true`, completed bridge, earn, swap, borrow, and unified balance
+     * operations will not POST analytics events. This does not disable error reporting; use
      * {@link AppKitContext.disableErrorReporting} for that. Defaults to `false`.
      *
      * @defaultValue false

package/swap.d.mts

@@ -899,10 +899,10 @@ declare enum Blockchain {
  *
  * Unlike the full {@link Blockchain} enum, SwapChain includes mainnet
  * networks and explicitly whitelisted testnets (e.g., {@link Arc_Testnet})
- * where adapter contracts are deployed (CCTPv2 support).
+ * where Adapter contracts are deployed.
  *
  * Dynamic validation via {@link isSwapSupportedChain} ensures chains
- * automatically work when adapter contracts and supported tokens are deployed.
+ * automatically work when Adapter contracts and supported tokens are deployed.
  *
  * @example
  * ```typescript
@@ -942,20 +942,22 @@ declare enum SwapChain {
     HyperEVM = "HyperEVM",
     Monad = "Monad",
     Arc = "Arc",
+    Cronos = "Cronos",
+    Morph = "Morph",
     Arc_Testnet = "Arc_Testnet"
 }
 /**
  * Chain definition that supports swap operations.
  *
  * @remarks
- * Expanded from 4 to ~18 supported chains based on:
- * - CCTPv2 support (adapter contract deployed)
+ * Expanded from 4 to supported mainnets and whitelisted testnets based on:
+ * - A deployed Adapter contract, configured directly or through CCTP v2
  * - Mainnet chains plus whitelisted testnets (e.g., Arc Testnet)
  *
  * Use `isSwapSupportedChain()` for runtime validation.
  */
 type SwapChainDefinition = ChainDefinition & {
-    chain: Blockchain.Ethereum | Blockchain.Base | Blockchain.Polygon | Blockchain.Solana | Blockchain.Arbitrum | Blockchain.Optimism | Blockchain.Avalanche | Blockchain.Linea | Blockchain.Ink | Blockchain.World_Chain | Blockchain.Unichain | Blockchain.Plume | Blockchain.Sei | Blockchain.Sonic | Blockchain.XDC | Blockchain.HyperEVM | Blockchain.Monad | Blockchain.Arc | Blockchain.Arc_Testnet;
+    chain: Blockchain.Ethereum | Blockchain.Base | Blockchain.Polygon | Blockchain.Solana | Blockchain.Arbitrum | Blockchain.Optimism | Blockchain.Avalanche | Blockchain.Linea | Blockchain.Ink | Blockchain.World_Chain | Blockchain.Unichain | Blockchain.Plume | Blockchain.Sei | Blockchain.Sonic | Blockchain.XDC | Blockchain.HyperEVM | Blockchain.Monad | Blockchain.Arc | Blockchain.Cronos | Blockchain.Morph | Blockchain.Arc_Testnet;
 };
 /**
  * Chain identifier accepted by swap operations.
@@ -6207,6 +6209,44 @@ type BridgeDestination<TAdapterCapabilities extends AdapterCapabilities = Adapte
     useForwarder?: boolean;
 }) | ForwarderDestination<TChainIdentifier>;
 
+/** Token metadata for one side of a swap route step. */
+interface SwapRouteToken {
+    readonly symbol: string;
+    readonly address: string;
+    readonly decimals: number;
+}
+/** Amount estimates for a swap route step, expressed in base units. */
+interface SwapRouteStepEstimate {
+    readonly fromAmount: string;
+    readonly toAmount: string;
+    readonly gasCostUSD?: string;
+}
+/** A single swap or bridge hop selected by the route provider. */
+interface SwapRouteStep {
+    /** Hop kind, for example `swap` or `bridge`. */
+    readonly type: string;
+    /** Protocol identifier, for example `cctp-v2`. */
+    readonly tool: string;
+    /** Display name for {@link SwapRouteStep.tool}. */
+    readonly toolName: string;
+    readonly fromToken: SwapRouteToken;
+    readonly toToken: SwapRouteToken;
+    readonly estimate: SwapRouteStepEstimate;
+    /** Provider-specific details that are not part of the stable step shape. */
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/** Provider and executable hops selected for a swap. */
+interface SwapRoute {
+    /**
+     * Provider that routed the swap, for example `lifi` or `circle`. Treat as
+     * an opaque identifier; new providers can appear without an SDK release.
+     */
+    readonly provider: string;
+    readonly steps: readonly SwapRouteStep[];
+    /** Provider-specific details that are not part of the stable route shape. */
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+
 /**
  * Allowance strategy for token approvals during swap operations.
  *
@@ -6364,7 +6404,7 @@ interface ServiceSwapConfig {
      *
      * @defaultValue true
      */
-    batchTransactions?: boolean;
+    batchTransactions?: boolean | undefined;
 }
 /**
  * Parameters for initiating a swap operation through the Stablecoin Service.
@@ -6517,6 +6557,14 @@ interface ServiceSwapFee {
      * addresses are not available from the proxy response.
      */
     readonly recipientAddress?: string;
+    /** Provider-defined fee component (for example `FORWARD`). */
+    readonly component?: string;
+    /**
+     * Chain on which the fee is charged, as reported by the service
+     * (a `Blockchain` value such as `'Ethereum'`). Not validated
+     * against the `Blockchain` enum.
+     */
+    readonly chain?: string;
 }
 
 /**
@@ -6881,6 +6929,33 @@ interface SwapConfig {
      * `apiKey` is omitted, and `apiKey` takes precedence when both are set.
      */
     kitKey?: string;
+    /**
+     * Enable or disable atomic batched execution of the approval and swap.
+     *
+     * When `true` (or omitted), an EVM swap that needs an on-chain ERC-20
+     * approval submits the approval and the swap as one atomic batch if the
+     * connected wallet supports it (EIP-5792, or a signing strategy that
+     * declares atomic batching). Set to `false` to force the sequential
+     * approve-then-swap flow.
+     *
+     * @remarks
+     * Has no effect on the gasless permit path, native-token swaps, or Solana,
+     * which already execute as a single transaction. USDT input always uses the
+     * sequential path because its allowance must be reset to zero first. The
+     * batched path relies on the wallet's own gas estimation for the swap call;
+     * set `false` if your wallet under-estimates gas for complex routes or
+     * rejects batched calls.
+     *
+     * @defaultValue `undefined` (batching attempted when the wallet supports it)
+     *
+     * @example
+     * ```typescript
+     * const config: SwapConfig = {
+     *   batchTransactions: false, // force sequential approve → swap
+     * }
+     * ```
+     */
+    batchTransactions?: boolean | undefined;
 }
 /**
  * Configuration for swap results.
@@ -7021,6 +7096,8 @@ interface SwapResult {
      * fees (charged by the DEX aggregator/protocol) and kit fees.
      */
     fees?: readonly ServiceSwapFee[];
+    /** Provider and executable hops selected for the swap. */
+    readonly route?: SwapRoute;
     /**
      * Lifecycle snapshot: `status`, `substatus`, and `substatusMessage`.
      *
@@ -8491,11 +8568,11 @@ interface AppKitContext {
      */
     actions: Record<'bridge' | 'earn' | 'borrow', Record<string, ((payload: unknown) => void)[]>>;
     /**
-     * Disable success analytics for the underlying EarnKit, SwapKit,
+     * Disable success analytics for the underlying BridgeKit, EarnKit, SwapKit,
      * BorrowKit, and UnifiedBalanceKit.
      *
-     * When `true`, completed earn, swap, borrow, and unified balance operations
-     * will not POST analytics events. This does not disable error reporting; use
+     * When `true`, completed bridge, earn, swap, borrow, and unified balance
+     * operations will not POST analytics events. This does not disable error reporting; use
      * {@link AppKitContext.disableErrorReporting} for that. Defaults to `false`.
      *
      * @defaultValue false

package/swap.d.ts

@@ -899,10 +899,10 @@ declare enum Blockchain {
  *
  * Unlike the full {@link Blockchain} enum, SwapChain includes mainnet
  * networks and explicitly whitelisted testnets (e.g., {@link Arc_Testnet})
- * where adapter contracts are deployed (CCTPv2 support).
+ * where Adapter contracts are deployed.
  *
  * Dynamic validation via {@link isSwapSupportedChain} ensures chains
- * automatically work when adapter contracts and supported tokens are deployed.
+ * automatically work when Adapter contracts and supported tokens are deployed.
  *
  * @example
  * ```typescript
@@ -942,20 +942,22 @@ declare enum SwapChain {
     HyperEVM = "HyperEVM",
     Monad = "Monad",
     Arc = "Arc",
+    Cronos = "Cronos",
+    Morph = "Morph",
     Arc_Testnet = "Arc_Testnet"
 }
 /**
  * Chain definition that supports swap operations.
  *
  * @remarks
- * Expanded from 4 to ~18 supported chains based on:
- * - CCTPv2 support (adapter contract deployed)
+ * Expanded from 4 to supported mainnets and whitelisted testnets based on:
+ * - A deployed Adapter contract, configured directly or through CCTP v2
  * - Mainnet chains plus whitelisted testnets (e.g., Arc Testnet)
  *
  * Use `isSwapSupportedChain()` for runtime validation.
  */
 type SwapChainDefinition = ChainDefinition & {
-    chain: Blockchain.Ethereum | Blockchain.Base | Blockchain.Polygon | Blockchain.Solana | Blockchain.Arbitrum | Blockchain.Optimism | Blockchain.Avalanche | Blockchain.Linea | Blockchain.Ink | Blockchain.World_Chain | Blockchain.Unichain | Blockchain.Plume | Blockchain.Sei | Blockchain.Sonic | Blockchain.XDC | Blockchain.HyperEVM | Blockchain.Monad | Blockchain.Arc | Blockchain.Arc_Testnet;
+    chain: Blockchain.Ethereum | Blockchain.Base | Blockchain.Polygon | Blockchain.Solana | Blockchain.Arbitrum | Blockchain.Optimism | Blockchain.Avalanche | Blockchain.Linea | Blockchain.Ink | Blockchain.World_Chain | Blockchain.Unichain | Blockchain.Plume | Blockchain.Sei | Blockchain.Sonic | Blockchain.XDC | Blockchain.HyperEVM | Blockchain.Monad | Blockchain.Arc | Blockchain.Cronos | Blockchain.Morph | Blockchain.Arc_Testnet;
 };
 /**
  * Chain identifier accepted by swap operations.
@@ -6207,6 +6209,44 @@ type BridgeDestination<TAdapterCapabilities extends AdapterCapabilities = Adapte
     useForwarder?: boolean;
 }) | ForwarderDestination<TChainIdentifier>;
 
+/** Token metadata for one side of a swap route step. */
+interface SwapRouteToken {
+    readonly symbol: string;
+    readonly address: string;
+    readonly decimals: number;
+}
+/** Amount estimates for a swap route step, expressed in base units. */
+interface SwapRouteStepEstimate {
+    readonly fromAmount: string;
+    readonly toAmount: string;
+    readonly gasCostUSD?: string;
+}
+/** A single swap or bridge hop selected by the route provider. */
+interface SwapRouteStep {
+    /** Hop kind, for example `swap` or `bridge`. */
+    readonly type: string;
+    /** Protocol identifier, for example `cctp-v2`. */
+    readonly tool: string;
+    /** Display name for {@link SwapRouteStep.tool}. */
+    readonly toolName: string;
+    readonly fromToken: SwapRouteToken;
+    readonly toToken: SwapRouteToken;
+    readonly estimate: SwapRouteStepEstimate;
+    /** Provider-specific details that are not part of the stable step shape. */
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/** Provider and executable hops selected for a swap. */
+interface SwapRoute {
+    /**
+     * Provider that routed the swap, for example `lifi` or `circle`. Treat as
+     * an opaque identifier; new providers can appear without an SDK release.
+     */
+    readonly provider: string;
+    readonly steps: readonly SwapRouteStep[];
+    /** Provider-specific details that are not part of the stable route shape. */
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+
 /**
  * Allowance strategy for token approvals during swap operations.
  *
@@ -6364,7 +6404,7 @@ interface ServiceSwapConfig {
      *
      * @defaultValue true
      */
-    batchTransactions?: boolean;
+    batchTransactions?: boolean | undefined;
 }
 /**
  * Parameters for initiating a swap operation through the Stablecoin Service.
@@ -6517,6 +6557,14 @@ interface ServiceSwapFee {
      * addresses are not available from the proxy response.
      */
     readonly recipientAddress?: string;
+    /** Provider-defined fee component (for example `FORWARD`). */
+    readonly component?: string;
+    /**
+     * Chain on which the fee is charged, as reported by the service
+     * (a `Blockchain` value such as `'Ethereum'`). Not validated
+     * against the `Blockchain` enum.
+     */
+    readonly chain?: string;
 }
 
 /**
@@ -6881,6 +6929,33 @@ interface SwapConfig {
      * `apiKey` is omitted, and `apiKey` takes precedence when both are set.
      */
     kitKey?: string;
+    /**
+     * Enable or disable atomic batched execution of the approval and swap.
+     *
+     * When `true` (or omitted), an EVM swap that needs an on-chain ERC-20
+     * approval submits the approval and the swap as one atomic batch if the
+     * connected wallet supports it (EIP-5792, or a signing strategy that
+     * declares atomic batching). Set to `false` to force the sequential
+     * approve-then-swap flow.
+     *
+     * @remarks
+     * Has no effect on the gasless permit path, native-token swaps, or Solana,
+     * which already execute as a single transaction. USDT input always uses the
+     * sequential path because its allowance must be reset to zero first. The
+     * batched path relies on the wallet's own gas estimation for the swap call;
+     * set `false` if your wallet under-estimates gas for complex routes or
+     * rejects batched calls.
+     *
+     * @defaultValue `undefined` (batching attempted when the wallet supports it)
+     *
+     * @example
+     * ```typescript
+     * const config: SwapConfig = {
+     *   batchTransactions: false, // force sequential approve → swap
+     * }
+     * ```
+     */
+    batchTransactions?: boolean | undefined;
 }
 /**
  * Configuration for swap results.
@@ -7021,6 +7096,8 @@ interface SwapResult {
      * fees (charged by the DEX aggregator/protocol) and kit fees.
      */
     fees?: readonly ServiceSwapFee[];
+    /** Provider and executable hops selected for the swap. */
+    readonly route?: SwapRoute;
     /**
      * Lifecycle snapshot: `status`, `substatus`, and `substatusMessage`.
      *
@@ -8491,11 +8568,11 @@ interface AppKitContext {
      */
     actions: Record<'bridge' | 'earn' | 'borrow', Record<string, ((payload: unknown) => void)[]>>;
     /**
-     * Disable success analytics for the underlying EarnKit, SwapKit,
+     * Disable success analytics for the underlying BridgeKit, EarnKit, SwapKit,
      * BorrowKit, and UnifiedBalanceKit.
      *
-     * When `true`, completed earn, swap, borrow, and unified balance operations
-     * will not POST analytics events. This does not disable error reporting; use
+     * When `true`, completed bridge, earn, swap, borrow, and unified balance
+     * operations will not POST analytics events. This does not disable error reporting; use
      * {@link AppKitContext.disableErrorReporting} for that. Defaults to `false`.
      *
      * @defaultValue false