@circle-fin/app-kit 1.9.0 → 1.10.0

package/swap.mjs

@@ -18,13 +18,14 @@
 
 import { z } from 'zod';
 import 'pino';
+import { hexlify, hexZeroPad } from '@ethersproject/bytes';
+import '@ethersproject/abi';
+import { getAddress } from '@ethersproject/address';
 import { PublicKey } from '@solana/web3.js';
 import 'bn.js';
 import '@coral-xyz/anchor';
 import bs58 from 'bs58';
 import '@noble/curves/ed25519';
-import { hexlify, hexZeroPad } from '@ethersproject/bytes';
-import { getAddress } from '@ethersproject/address';
 import { formatUnits as formatUnits$1 } from '@ethersproject/units';
 import { keccak256 } from '@ethersproject/keccak256';
 
@@ -3527,7 +3528,10 @@ var EarnChain;
         contracts: {
             v1: {
                 wallet: GATEWAY_WALLET_EVM_TESTNET,
-                minter: GATEWAY_MINTER_EVM_TESTNET
+                minter: GATEWAY_MINTER_EVM_TESTNET,
+                // DepositForHandler the GenericExecutor calls to run a fast cross-chain
+                // deposit into the GatewayWallet above.
+                depositForHandler: '0xD05E7D2E7d30b92c5F17d7d0fC575fce231F1A48'
             }
         },
         forwarderSupported: {
@@ -6595,7 +6599,10 @@ var Chains = /*#__PURE__*/Object.freeze({
     minter: z.string({
         required_error: 'Gateway minter address is required. Please provide a valid contract address.',
         invalid_type_error: 'Gateway minter address must be a string.'
-    }).min(1, 'Gateway minter address cannot be empty.')
+    }).min(1, 'Gateway minter address cannot be empty.'),
+    depositForHandler: z.string({
+        invalid_type_error: 'Gateway depositForHandler address must be a string.'
+    }).min(1, 'Gateway depositForHandler address cannot be empty.').optional()
 }).strict() // Reject any additional properties not defined in the schema
 ;
 /**
@@ -9480,6 +9487,13 @@ const swapTokenEnumSchema = z.enum([
     return explorerUrl;
 }
 
+/**
+ * CCTP forwarding magic bytes prefix.
+ *
+ * The ASCII string "cctp-forward" (12 bytes) that identifies a forwarding request.
+ * This prefix is right-padded to 24 bytes in the final hookData.
+ */ const CCTP_FORWARD_MAGIC_PREFIX = 'cctp-forward';
+
 /**
  * Project an arbitrary payload onto the exact set of fields the telemetry
  * endpoint accepts.
@@ -9856,7 +9870,7 @@ const swapTokenEnumSchema = z.enum([
 }
 
 var name$2 = "@circle-fin/bridge-kit";
-var version$2 = "1.12.0";
+var version$2 = "1.12.1";
 var pkg$2 = {
 	name: name$2,
 	version: version$2};
@@ -10714,6 +10728,11 @@ var TransferSpeed;
     clock: z.any().optional()
 }).passthrough();
 
+/**
+ * The ASCII "cctp-forward" magic, hex-encoded (no `0x`), that a forward-friendly
+ * hookData must start with.
+ */ Buffer.from(CCTP_FORWARD_MAGIC_PREFIX, 'ascii').toString('hex');
+
 /**
  * The minimum finality threshold for CCTPv2 transfers.
  *
@@ -10746,7 +10765,7 @@ var TransferSpeed;
 registerKit(`${pkg$2.name}/${pkg$2.version}`);
 
 var name$1 = "@circle-fin/swap-kit";
-var version$1 = "1.3.2";
+var version$1 = "1.4.0";
 var pkg$1 = {
 	name: name$1,
 	version: version$1};
@@ -10811,7 +10830,10 @@ const optionalChainIdentifierField = chainIdentifierField.optional();
     }).min(1, 'kitKey must be a non-empty string').optional(),
     provider: z.string({
         invalid_type_error: 'provider must be a string'
-    }).min(1, 'provider must be a non-empty string').optional()
+    }).min(1, 'provider must be a non-empty string').optional(),
+    batchTransactions: z.boolean({
+        invalid_type_error: 'batchTransactions must be a boolean'
+    }).optional()
 });
 /**
  * Zod schema for adapter context.
@@ -11342,7 +11364,7 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
     /**
      * Circle Stablecoin Service API Key.
      * Must be a valid API key format.
-     */ apiKey: apiKeySchema
+     */ apiKey: apiKeySchema.optional()
 }).superRefine(requireCrossChainQuoteToAddress);
 /**
  * Zod schema for validating CreateSwapRequest parameters.
@@ -11400,7 +11422,7 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
     /**
    * Circle Stablecoin Service API Key.
    * Must be a valid API key format.
-   */ apiKey: apiKeySchema
+   */ apiKey: apiKeySchema.optional()
 });
 /**
  * Zod schema for validating GetSwapStatusResponse data.
@@ -11436,7 +11458,7 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
     toChain: z.string({
         invalid_type_error: 'toChain must be a string'
     }).min(1, 'toChain must be a non-empty string if provided').optional(),
-    apiKey: apiKeySchema
+    apiKey: apiKeySchema.optional()
 });
 /**
  * Zod schema for validating CreateSwapResponse payloads.
@@ -11445,13 +11467,15 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
         required_error: 'fee token is required',
         invalid_type_error: 'fee token must be a string'
     }).min(1, 'fee token must be a non-empty string'),
-    amount: feeAmountSchema
+    amount: feeAmountSchema,
+    decimals: z.number().int('fee token decimals must be an integer').nonnegative('fee token decimals must be a non-negative integer').optional(),
+    symbol: z.string({
+        invalid_type_error: 'fee token symbol must be a string'
+    }).min(1, 'fee token symbol must be a non-empty string').optional()
 });
 /**
  * Developer fee item schema with basis field.
- */ const createSwapDeveloperFeeItemSchema = z.object({
-    token: z.string().min(1, 'fee token must be a non-empty string'),
-    amount: feeAmountSchema,
+ */ const createSwapDeveloperFeeItemSchema = createSwapFeeItemSchema.extend({
     basis: z.enum([
         'inputAmount',
         'estimatedAmount'
@@ -11543,7 +11567,7 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
     addresses: z.array(z.string({
         invalid_type_error: 'addresses entries must be strings'
     }).min(1, 'addresses entries must be non-empty strings')).min(1, 'addresses must contain at least one entry when provided').max(MAX_RATE_ADDRESSES_PER_REQUEST, `addresses supports at most ${String(MAX_RATE_ADDRESSES_PER_REQUEST)} values per request`).optional(),
-    apiKey: apiKeySchema
+    apiKey: apiKeySchema.optional()
 });
 /**
  * Zod schema for validating GetTokenRatesResponse payloads.
@@ -11721,7 +11745,10 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
         ...DEFAULT_CONFIG,
         headers: {
             ...DEFAULT_CONFIG.headers,
-            Authorization: `Bearer ${apiKey}`
+            // Permissionless mode: no Authorization header when the kit key is absent.
+            ...apiKey !== undefined && {
+                Authorization: `Bearer ${apiKey}`
+            }
         }
     };
     try {
@@ -11875,7 +11902,10 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
         ...DEFAULT_CONFIG,
         headers: {
             ...DEFAULT_CONFIG.headers,
-            Authorization: `Bearer ${validatedParams.apiKey}`
+            // Permissionless mode: no Authorization header when the kit key is absent.
+            ...validatedParams.apiKey !== undefined && {
+                Authorization: `Bearer ${validatedParams.apiKey}`
+            }
         }
     };
     return pollApiGet(url, isGetQuoteResponse, effectiveConfig);
@@ -11930,7 +11960,9 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
     const validatedParams = {
         txHash: result.data.txHash,
         chain: result.data.chain,
-        apiKey: result.data.apiKey,
+        ...result.data.apiKey !== undefined && {
+            apiKey: result.data.apiKey
+        },
         ...result.data.toChain !== undefined && {
             toChain: result.data.toChain
         }
@@ -11940,7 +11972,10 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
         ...DEFAULT_CONFIG,
         headers: {
             ...DEFAULT_CONFIG.headers,
-            Authorization: `Bearer ${validatedParams.apiKey}`
+            // Permissionless mode: no Authorization header when the kit key is absent.
+            ...validatedParams.apiKey !== undefined && {
+                Authorization: `Bearer ${validatedParams.apiKey}`
+            }
         }
     };
     return pollApiGet(url, isGetSwapStatusResponse, effectiveConfig);
@@ -12029,7 +12064,9 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
     }
     const validatedParams = {
         chain: result.data.chain,
-        apiKey: result.data.apiKey,
+        ...result.data.apiKey !== undefined && {
+            apiKey: result.data.apiKey
+        },
         ...result.data.addresses !== undefined && {
             addresses: result.data.addresses
         }
@@ -12039,7 +12076,10 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
         ...DEFAULT_CONFIG,
         headers: {
             ...DEFAULT_CONFIG.headers,
-            Authorization: `Bearer ${validatedParams.apiKey}`
+            // Permissionless mode: no Authorization header when the kit key is absent.
+            ...validatedParams.apiKey !== undefined && {
+                Authorization: `Bearer ${validatedParams.apiKey}`
+            }
         }
     };
     return pollApiGet(url, isGetTokenRatesResponse, effectiveConfig);
@@ -12849,6 +12889,47 @@ const S_HEX_LENGTH = 32 * HEX_CHARS_PER_BYTE$1 // 32 bytes for 's'
  */ function hasSignTypedData(adapter) {
     return typeof adapter === 'object' && adapter !== null && 'signTypedData' in adapter && typeof adapter.signTypedData === 'function';
 }
+/**
+ * Type guard to check if an adapter can actually produce an EIP-712
+ * typed-data signature.
+ *
+ * @remarks
+ * Strengthens {@link hasSignTypedData}: having a `signTypedData` method
+ * does not guarantee it can succeed. Adapters whose signer is delegated
+ * (e.g. through a signing strategy backed by a smart contract account)
+ * expose the method but reject typed-data payloads at runtime. Such
+ * adapters report their real capability through an optional
+ * `supportsSignTypedData()` method, which this guard consults when
+ * present. Adapters without the capability method are assumed able to
+ * sign, preserving the previous duck-typing behavior.
+ *
+ * @param adapter - The adapter to check
+ * @returns True if calling `signTypedData` can be expected to succeed
+ *
+ * @example
+ * ```typescript
+ * import { canSignTypedData } from '@core/adapter-evm'
+ *
+ * if (canSignTypedData(adapter)) {
+ *   const signature = await adapter.signTypedData(typedData, context)
+ * } else {
+ *   // take an on-chain approval path instead of a permit signature
+ * }
+ * ```
+ */ function canSignTypedData(adapter) {
+    if (!hasSignTypedData(adapter)) {
+        return false;
+    }
+    if (typeof adapter.supportsSignTypedData === 'function') {
+        // The value is `boolean` per the interface, but a plain-JS adapter may
+        // return anything; treat it as untrusted and coerce to a strict
+        // boolean. Comparing an `unknown` (not a `boolean`) also keeps the
+        // lint autofix from stripping this as a redundant `=== true`.
+        const supported = adapter.supportsSignTypedData();
+        return supported === true;
+    }
+    return true;
+}
 
 /**
  * Build EIP-2612 typed data for permit signing.
@@ -13271,10 +13352,13 @@ enc.encode('used_transfer_spec_hash');
  * at usage time rather than construction time.
  *
  * Validates:
- * - Kit key is present and matches required format (KIT_KEY:id:secret)
+ * - Kit key matches the required format (KIT_KEY:id:secret) when provided.
+ *   An absent or empty kit key is permitted (permissionless mode) — the swap
+ *   service now treats the key as optional.
  *
- * @param kitKey - The inline kit key from the swap operation config
- * @throws KitError with VALIDATION_FAILED if kit key is invalid or missing
+ * @param kitKey - The inline kit key from the swap operation config (optional)
+ * @throws KitError with VALIDATION_FAILED if a kit key is provided but does not
+ *   match the KIT_KEY:<keyId>:<keySecret> format
  *
  * @example
  * ```typescript
@@ -13286,9 +13370,11 @@ enc.encode('used_transfer_spec_hash');
  * assertKitKey(kitKey)
  * ```
  */ function assertKitKey(kitKey) {
-    // Validate API key format using existing schema from service-client
+    // Permissionless mode: the swap service treats the kit key as optional, so an
+    // absent (or empty) key is valid. Only validate the format when a key is
+    // actually provided.
     if (!kitKey) {
-        throw createValidationFailedError$1('kitKey', kitKey, 'Kit key is required. Expected format: KIT_KEY:<keyId>:<keySecret>. Provide it inline via config.kitKey parameter. Get your free Kit Key at: https://developers.circle.com/w3s/keys#kit-keys');
+        return;
     }
     const apiKeyResult = apiKeySchema.safeParse(kitKey);
     if (!apiKeyResult.success) {
@@ -13585,8 +13671,8 @@ function resolveFeePayoutChain(tokenIn, tokenOut, sourceChain, destinationChain)
     validateResolvedAddress(resolvedTokenInAddress, chain);
     validateResolvedAddress(resolvedTokenOutAddress, destinationChain);
     validateResolvedAddress(to, destinationChain);
-    const kitKey = config?.kitKey ?? '';
-    // Validates the kit key
+    const kitKey = config?.kitKey;
+    // Validate the kit key format when one is provided (permissionless otherwise).
     assertKitKey(kitKey);
     // Validate custom fee configuration if present
     const customFee = config?.customFee;
@@ -13631,7 +13717,10 @@ function resolveFeePayoutChain(tokenIn, tokenOut, sourceChain, destinationChain)
                 }
             }
         },
-        apiKey: kitKey
+        // Map kitKey → apiKey for the service client; omitted in permissionless mode.
+        ...kitKey ? {
+            apiKey: kitKey
+        } : {}
     };
 }
 
@@ -14285,6 +14374,37 @@ function resolveFeePayoutChain(tokenIn, tokenOut, sourceChain, destinationChain)
     }
 }
 
+/**
+ * Determine whether an adapter can produce an EIP-2612 permit signature.
+ *
+ * @remarks
+ * A gasless permit needs two adapter capabilities: fetching the token's
+ * EIP-2612 nonce and producing an EIP-712 typed-data signature. The
+ * typed-data check uses {@link canSignTypedData} rather than a bare
+ * `hasSignTypedData` guard so that an adapter routed through a signing
+ * strategy that cannot produce typed-data signatures — one whose manifest
+ * omits `evm-typed-data`, surfaced through an optional `supportsSignTypedData()`
+ * — is correctly excluded. Such an adapter falls back to an on-chain approval
+ * (batched into a single submission when it supports atomic execution) instead
+ * of attempting a permit its strategy would reject.
+ *
+ * @param adapter - The source adapter to inspect.
+ * @returns `true` when the adapter can both fetch a nonce and sign typed data.
+ *
+ * @example
+ * ```typescript
+ * import { adapterSupportsPermit } from './utils'
+ *
+ * if (adapterSupportsPermit(adapter)) {
+ *   // gasless permit path — fold the approval into the swap transaction
+ * } else {
+ *   // on-chain approval path (batched when supportsAtomicBatch is true)
+ * }
+ * ```
+ */ function adapterSupportsPermit(adapter) {
+    return hasEIP2612NonceFetching(adapter) && canSignTypedData(adapter);
+}
+
 /**
  * Generate EIP-2612 permit signature for token approval.
  *
@@ -14420,8 +14540,7 @@ function resolveFeePayoutChain(tokenIn, tokenOut, sourceChain, destinationChain)
     }
     // Skip permit generation if the adapter lacks the required capabilities.
     // handleEvmTokenApproval will have already sent an on-chain approval in this case.
-    const adapterSupportsPermit = hasEIP2612NonceFetching(adapter) && hasSignTypedData(adapter);
-    if (!adapterSupportsPermit) {
+    if (!adapterSupportsPermit(adapter)) {
         return [
             createFallbackTokenInput(tokenInAddress, inputAmount)
         ];
@@ -14980,6 +15099,65 @@ const TOKEN_REGISTRY$2 = createTokenRegistry();
     return `Insufficient ${displaySymbol} balance for swap operation.\n\n` + `Wallet: ${walletAddress}\n` + `Current balance: ${currentDisplay}\n` + `Required: ${requiredDisplay}\n` + `Shortfall: ${shortfallDisplay}\n\n` + `This swap requires ${requiredSummary} to complete the transaction.\n\n` + `Action: Add at least ${actionAmount} to your wallet to complete this swap.`;
 }
 
+/**
+ * Determine which chain a fee token should be resolved and formatted against.
+ *
+ * @remarks
+ * Fees returned by the service may be denominated in either the input token
+ * (on the source chain) or the output token (on the destination chain). A
+ * contract address only resolves on the chain it belongs to, so formatting a
+ * destination-denominated fee against the source chain causes
+ * {@link resolveTokenSymbol} to miss and the amount to be returned as raw base
+ * units (e.g. a cross-chain swap charging a fee in the destination output
+ * token — an EURC-on-Base address shows `'13202'` instead of `'0.013202'` when
+ * resolved against the source chain). This is the fallback for fee items that
+ * are not self-described with their own `decimals`/`chain`.
+ *
+ * Prefer the source chain (covers same-chain swaps and input-denominated
+ * fees), then fall back to the destination chain when the token only resolves
+ * there. When neither chain recognises the token, default to the source chain
+ * so existing on-chain decimal lookups via the source adapter still apply.
+ *
+ * Symbol tokens (`'USDC'`, `'NATIVE'`) resolve on either chain, so the
+ * source-first preference keeps them on the source chain. That is correct for
+ * registry stablecoins, and for `'NATIVE'` only when both chains share native
+ * decimals (EVM↔EVM, 18). It does NOT honor per-chain native decimals: a
+ * `'NATIVE'`-denominated fee on a Solana↔EVM swap (9 vs 18) would be
+ * mis-scaled. This is latent — providers emit the address form, and
+ * self-describing fee items carry their own `decimals` and never reach this
+ * helper — so the gap only opens for a future `'NATIVE'` fee that arrives
+ * without `decimals` on a cross-native-decimal route.
+ *
+ * @param token - The fee token identifier — a symbol (`'USDC'`) or contract address.
+ * @param sourceChain - The chain the swap originates from.
+ * @param destinationChain - The chain the swap settles on (equals `sourceChain` for same-chain swaps).
+ * @returns The chain definition the fee token should be resolved against.
+ *
+ * @example
+ * ```typescript
+ * import { resolveFeeChain } from './resolveFeeChain'
+ * import { Ethereum, Base } from '@core/chains'
+ *
+ * // Cross-chain swap fee charged in the destination (output) token
+ * resolveFeeChain('0x60a3E35Cc302bFA44Cb288Bc5a4F316Fdb1adb42', Ethereum, Base)
+ * // => Base (EURC resolves on Base, not Ethereum)
+ *
+ * // Symbol or source-token fees stay on the source chain
+ * resolveFeeChain('USDC', Ethereum, Base) // => Ethereum
+ * ```
+ */ function resolveFeeChain(token, sourceChain, destinationChain) {
+    if (sourceChain.chain === destinationChain.chain) {
+        return sourceChain;
+    }
+    if (resolveTokenSymbol(token, sourceChain) !== null) {
+        return sourceChain;
+    }
+    if (resolveTokenSymbol(token, destinationChain) !== null) {
+        return destinationChain;
+    }
+    return sourceChain;
+}
+
 const TOKEN_REGISTRY$1 = createTokenRegistry();
 /**
  * Format a raw base-unit amount into a human-readable decimal string.
@@ -15070,6 +15248,186 @@ const TOKEN_REGISTRY$1 = createTokenRegistry();
     }
 }
 
+/**
+ * Runtime guard for {@link BatchCapableSwapAdapter}.
+ *
+ * @param adapter - The adapter to inspect.
+ * @returns `true` when the adapter exposes both batch methods.
+ *
+ * @example
+ * ```typescript
+ * if (isBatchCapableSwapAdapter(adapter)) {
+ *   // adapter.supportsAtomicBatch / adapter.batchExecute are available
+ * }
+ * ```
+ */ function isBatchCapableSwapAdapter(adapter) {
+    return typeof adapter === 'object' && adapter !== null && typeof adapter.supportsAtomicBatch === 'function' && typeof adapter.batchExecute === 'function';
+}
+/**
+ * Decide whether the EVM swap should take the batched approve-and-swap path.
+ *
+ * @remarks
+ * Batching only helps when an on-chain approval would otherwise be required, so
+ * it is skipped for native tokens (no approval) and for the gasless permit path
+ * (already a single transaction). USDT is skipped because its reset-to-zero
+ * allowance flow cannot be expressed as a fixed approve+swap pair. When those
+ * gates pass, the adapter's actual atomic-batch capability is queried; any
+ * failure resolves to `false` so the swap falls back to the sequential path.
+ *
+ * @param args - The decision inputs.
+ * @param args.adapter - The source adapter.
+ * @param args.chain - The source chain definition.
+ * @param args.tokenInAddress - The resolved input-token address.
+ * @param args.allowanceStrategy - Optional allowance strategy override.
+ * @param args.batchTransactions - Optional explicit opt-out (`false` disables).
+ * @returns `true` when the batched approve-and-swap path should be used.
+ *
+ * @example
+ * ```typescript
+ * const useBatched = await shouldUseBatchedSwap({
+ *   adapter,
+ *   chain,
+ *   tokenInAddress: '0xA0b8...',
+ *   allowanceStrategy: config?.allowanceStrategy,
+ *   batchTransactions: config?.batchTransactions,
+ * })
+ * ```
+ */ async function shouldUseBatchedSwap({ adapter, chain, tokenInAddress, allowanceStrategy, batchTransactions }) {
+    // Explicit opt-out.
+    if (batchTransactions === false) {
+        return false;
+    }
+    // Batching is an EVM capability (EIP-5792 or a signing strategy).
+    if (chain.type !== 'evm') {
+        return false;
+    }
+    // Native tokens need no approval — the swap is already a single transaction.
+    if (isNativeEvmAddress(tokenInAddress)) {
+        return false;
+    }
+    // A gasless permit folds the approval into the swap transaction, so there is
+    // nothing to batch. Mirrors the permit gate in handleEvmTokenApproval.
+    const canUsePermit = allowanceStrategy !== 'approve' && supportsEIP2612(tokenInAddress, chain) && adapterSupportsPermit(adapter);
+    if (canUsePermit) {
+        return false;
+    }
+    // USDT's reset-to-zero allowance dance cannot be expressed as a fixed
+    // approve+swap pair; leave it on the sequential path.
+    const usdt = chain.usdtAddress?.toLowerCase();
+    if (usdt !== undefined && tokenInAddress.toLowerCase() === usdt) {
+        return false;
+    }
+    if (!isBatchCapableSwapAdapter(adapter)) {
+        return false;
+    }
+    try {
+        return await adapter.supportsAtomicBatch(chain);
+    } catch  {
+        return false;
+    }
+}
+/**
+ * Execute the approval and swap as a single atomic batch.
+ *
+ * @remarks
+ * Extracts the raw call data from both prepared requests, submits them as one
+ * batch via `adapter.batchExecute`, and maps the swap receipt back to a
+ * transaction hash. The `fromAddress` is threaded for adapters routed through a
+ * signing strategy (which have no wallet account to read the sender from); the
+ * wallet-client path ignores it.
+ *
+ * Following the batch contract, `batchExecute` never throws once the batch is
+ * submitted — a missing or failed swap receipt is surfaced here as a thrown
+ * {@link KitError} (FATAL) so the caller does not resubmit an already-broadcast
+ * batch and double-swap.
+ *
+ * @param args - The execution inputs.
+ * @param args.adapter - The batch-capable source adapter.
+ * @param args.chain - The EVM chain to execute on.
+ * @param args.approveRequest - The prepared ERC-20 approval request.
+ * @param args.swapRequest - The prepared swap request (pre-approval / NONE permit).
+ * @param args.fromAddress - The address authorizing the batch.
+ * @returns The swap transaction hash and the executed approval + swap records.
+ * @throws {@link KitError} when the prepared requests cannot yield call data.
+ * @throws {@link KitError} when the batch does not confirm or the swap reverts.
+ *
+ * @example
+ * ```typescript
+ * const { swapTxHash, executedTransactions } = await executeBatchedApproveAndSwap({
+ *   adapter,
+ *   chain,
+ *   approveRequest,
+ *   swapRequest,
+ *   fromAddress: '0x742d...',
+ * })
+ * ```
+ */ async function executeBatchedApproveAndSwap({ adapter, chain, approveRequest, swapRequest, fromAddress }) {
+    if (approveRequest.type !== 'evm' || swapRequest.type !== 'evm' || !approveRequest.getCallData || !swapRequest.getCallData) {
+        throw new KitError({
+            ...InputError.UNSUPPORTED_ACTION,
+            recoverability: 'FATAL',
+            message: 'Batched swap requires EVM prepared requests with getCallData() support.'
+        });
+    }
+    const approveCallData = approveRequest.getCallData();
+    const swapCallData = swapRequest.getCallData();
+    const batchResult = await adapter.batchExecute([
+        approveCallData,
+        swapCallData
+    ], chain, {
+        fromAddress
+    });
+    const swapReceipt = batchResult.receipts[1];
+    // A missing swap receipt means the batch never confirmed (polling timed out
+    // or the wallet returned fewer receipts than calls). Re-throw the underlying
+    // error when present (already FATAL); otherwise surface a FATAL timeout so the
+    // caller checks the batch status rather than resubmitting.
+    if (swapReceipt === undefined || swapReceipt.txHash === '') {
+        if (isKitError(batchResult.error)) {
+            throw batchResult.error;
+        }
+        throw new KitError({
+            ...NetworkError.TIMEOUT,
+            recoverability: 'FATAL',
+            message: `Batched swap did not confirm on-chain (batchId: ${batchResult.batchId}). ` + 'The batch was already submitted — check its status before retrying.',
+            // Preserve the underlying confirmation failure when it isn't a KitError —
+            // the signing-strategy path returns a raw viem error (e.g. a dropped or
+            // replaced tx) — so the root cause survives behind the generic timeout.
+            cause: {
+                trace: {
+                    batchId: batchResult.batchId,
+                    ...batchResult.error != null && {
+                        error: batchResult.error
+                    }
+                }
+            }
+        });
+    }
+    if (swapReceipt.status !== 'success') {
+        throw createTransactionRevertedError(chain.name, 'Batched swap transaction reverted on-chain', undefined, swapReceipt.txHash, buildExplorerUrl(chain, swapReceipt.txHash));
+    }
+    const executedTransactions = [];
+    const approveReceipt = batchResult.receipts[0];
+    // An atomic batch is a single on-chain transaction, so the approve and swap
+    // receipts share one hash. Only surface a distinct approval record when it is
+    // genuinely a separate transaction; otherwise the lone swap record represents
+    // the batch, avoiding a phantom duplicate tx in executedTransactions.
+    if (approveReceipt !== undefined && approveReceipt.txHash !== '' && approveReceipt.txHash !== swapReceipt.txHash) {
+        executedTransactions.push({
+            type: 'approval',
+            txHash: approveReceipt.txHash
+        });
+    }
+    executedTransactions.push({
+        type: 'swap',
+        txHash: swapReceipt.txHash
+    });
+    return {
+        swapTxHash: swapReceipt.txHash,
+        executedTransactions
+    };
+}
+
 /**
  * Safety multiplier applied to locally estimated gas for EVM swap execution.
  * Derived from refund cap (max 1/5 of total gas used) plus an extra 0.1 margin,
@@ -15196,7 +15554,9 @@ async function fetchSameChainStatusSnapshot({ isCrossChainSwap, txHash, chain, a
             const statusResult = await getSwapStatus$1({
                 txHash,
                 chain: chain.chain,
-                apiKey
+                ...apiKey !== undefined && {
+                    apiKey
+                }
             });
             if (statusResult.status === 'DONE' && statusResult.amountOut !== undefined) {
                 return {
@@ -15787,8 +16147,7 @@ async function fetchSameChainStatusSnapshot({ isCrossChainSwap, txHash, chain, a
         // Note: tokenInAddress from executionCtx is already resolved (handles NATIVE alias, ETH, etc.)
         const isNativeToken = isNativeEvmAddress(executionCtx.tokenInAddress);
         const tokenSupportsPermit = supportsEIP2612(executionCtx.tokenInAddress, chain);
-        const adapterSupportsPermit = hasEIP2612NonceFetching(adapter) && hasSignTypedData(adapter);
-        const canUsePermitFlow = tokenSupportsPermit && adapterSupportsPermit && allowanceStrategy !== 'approve';
+        const canUsePermitFlow = tokenSupportsPermit && adapterSupportsPermit(adapter) && allowanceStrategy !== 'approve';
         const needsApproval = !isNativeToken && !canUsePermitFlow;
         if (!needsApproval) {
             return;
@@ -16067,34 +16426,55 @@ async function fetchSameChainStatusSnapshot({ isCrossChainSwap, txHash, chain, a
         const serviceResponse = await createSwap(serviceParams);
         // Track executed transactions
         const executedTransactions = [];
-        // Prepare swap action based on chain type
-        let preparedAction;
-        if (chain.type === 'solana') {
-            // Solana: No approval needed, directly prepare swap action
-            preparedAction = await prepareSolanaSwapAction(adapter, serviceResponse, resolvedContext);
-        } else {
-            // EVM chains: Handle token approval if needed
-            await this.handleEvmTokenApproval(adapter, chain, executionCtx, resolvedContext, executedTransactions, config?.allowanceStrategy);
-            // EVM chains: prepareEvmSwapAction handles EIP-2612 permit generation
-            // Adapter contract address is read from chain.kitContracts.adapter
-            // Use the already-resolved context from above
-            preparedAction = await prepareEvmSwapAction(adapter, serviceResponse, resolvedContext, config?.allowanceStrategy);
-        }
+        // Prepare swap action(s) based on chain type and batch capability.
+        // Returns either a single prepared action (Solana / sequential EVM) or a
+        // batched approve+swap plan (EVM atomic-batch path).
+        const { preparedAction, batchedSwapPlan } = await this.prepareSwapRequests({
+            adapter,
+            chain,
+            serviceResponse,
+            resolvedContext,
+            executionCtx,
+            config,
+            executedTransactions
+        });
         // Execute swap transaction via adapter
         // For EVM chains, use gas limit from proxy service API
         let txHash;
         const evmGasLimit = 'gasLimit' in serviceResponse.transaction ? serviceResponse.transaction.gasLimit : undefined;
         try {
-            txHash = await this.executeSwapTransaction(preparedAction, evmGasLimit);
-            executedTransactions.push({
-                type: 'swap',
-                txHash
-            });
-            // Wait for transaction confirmation and verify success
-            const txReceipt = await adapter.waitForTransaction(txHash, undefined, chain);
-            if (txReceipt.status === 'reverted') {
-                const explorerUrl = buildExplorerUrl(chain, txHash);
-                throw createTransactionRevertedError(chain.name, 'Swap transaction reverted on-chain', undefined, txHash, explorerUrl);
+            if (batchedSwapPlan) {
+                // Approve + swap submitted as one atomic batch. batchExecute confirms
+                // the swap internally, so no separate waitForTransaction is needed.
+                const batched = await executeBatchedApproveAndSwap({
+                    adapter: adapter,
+                    chain: chain,
+                    approveRequest: batchedSwapPlan.approveRequest,
+                    swapRequest: batchedSwapPlan.swapRequest,
+                    fromAddress: executionCtx.fromAddress
+                });
+                txHash = batched.swapTxHash;
+                executedTransactions.push(...batched.executedTransactions);
+            } else if (preparedAction) {
+                txHash = await this.executeSwapTransaction(preparedAction, evmGasLimit);
+                executedTransactions.push({
+                    type: 'swap',
+                    txHash
+                });
+                // Wait for transaction confirmation and verify success
+                const txReceipt = await adapter.waitForTransaction(txHash, undefined, chain);
+                if (txReceipt.status === 'reverted') {
+                    const explorerUrl = buildExplorerUrl(chain, txHash);
+                    throw createTransactionRevertedError(chain.name, 'Swap transaction reverted on-chain', undefined, txHash, explorerUrl);
+                }
+            } else {
+                // Unreachable: the preparation step always yields either a batched plan
+                // or a prepared action.
+                throw new KitError({
+                    ...InputError.UNSUPPORTED_ACTION,
+                    recoverability: 'FATAL',
+                    message: 'No swap execution path was prepared.'
+                });
             }
         } catch (err) {
             handleSwapExecutionError(err, txHash, chain);
@@ -16113,7 +16493,9 @@ async function fetchSameChainStatusSnapshot({ isCrossChainSwap, txHash, chain, a
             isCrossChainSwap,
             txHash,
             chain,
-            apiKey: serviceParams.apiKey
+            ...serviceParams.apiKey !== undefined && {
+                apiKey: serviceParams.apiKey
+            }
         });
         // Build and return SwapResult
         return {
@@ -16138,6 +16520,79 @@ async function fetchSameChainStatusSnapshot({ isCrossChainSwap, txHash, chain, a
         };
     }
     /**
+   * Prepare the swap execution request(s) for the source wallet's chain.
+   *
+   * Produces either a single {@link PreparedChainRequest} (Solana, or the
+   * sequential EVM approve-then-swap path) or a `batchedSwapPlan` (the EVM
+   * atomic approve+swap path chosen when the adapter supports EIP-5792 atomic
+   * batching). The caller executes whichever field is populated. Any on-chain
+   * approval sent on the sequential path is appended to `executedTransactions`.
+   *
+   * @typeParam TFromAdapterCapabilities - Source-adapter capability set.
+   * @param args - Inputs derived from the validated swap request.
+   * @param args.adapter - Source-chain wallet adapter.
+   * @param args.chain - Source chain definition.
+   * @param args.serviceResponse - Validated createSwap response.
+   * @param args.resolvedContext - Resolved operation context.
+   * @param args.executionCtx - Minimal on-chain execution context.
+   * @param args.config - Optional swap configuration (allowance/batch flags).
+   * @param args.executedTransactions - Array appended with any sent approval.
+   * @returns The prepared action or the batched approve+swap plan.
+   * @throws KitError when the EVM atomic-batch path is selected but the chain
+   *   has no configured adapter contract.
+   */ async prepareSwapRequests(args) {
+        const { adapter, chain, serviceResponse, resolvedContext, executionCtx, config, executedTransactions } = args;
+        if (chain.type === 'solana') {
+            // Solana: No approval needed, directly prepare swap action
+            return {
+                preparedAction: await prepareSolanaSwapAction(adapter, serviceResponse, resolvedContext)
+            };
+        }
+        const useBatch = await shouldUseBatchedSwap({
+            adapter,
+            chain,
+            tokenInAddress: executionCtx.tokenInAddress,
+            allowanceStrategy: config?.allowanceStrategy,
+            batchTransactions: config?.batchTransactions
+        });
+        if (useBatch) {
+            // EVM chains: fuse the ERC-20 approval and the swap into a single atomic
+            // batch (one signing challenge for smart-contract wallets). Force the
+            // swap onto the pre-approval (PermitType.NONE) path since the approval
+            // rides in the same batch.
+            const adapterContractAddress = chain.kitContracts?.adapter;
+            if (!adapterContractAddress) {
+                throw new KitError({
+                    ...InputError.VALIDATION_FAILED,
+                    recoverability: 'FATAL',
+                    message: `Adapter contract not configured for chain ${chain.name}. Swap operations require an adapter contract.`,
+                    cause: {
+                        trace: {
+                            chain: chain.name
+                        }
+                    }
+                });
+            }
+            const [approveRequest, swapRequest] = await Promise.all([
+                this.approve(adapter, executionCtx.amount, executionCtx.tokenInAddress, adapterContractAddress, resolvedContext),
+                prepareEvmSwapAction(adapter, serviceResponse, resolvedContext, 'approve')
+            ]);
+            return {
+                batchedSwapPlan: {
+                    approveRequest,
+                    swapRequest
+                }
+            };
+        }
+        // EVM chains: Handle token approval if needed, then prepare the swap.
+        // prepareEvmSwapAction handles EIP-2612 permit generation; the adapter
+        // contract address is read from chain.kitContracts.adapter.
+        await this.handleEvmTokenApproval(adapter, chain, executionCtx, resolvedContext, executedTransactions, config?.allowanceStrategy);
+        return {
+            preparedAction: await prepareEvmSwapAction(adapter, serviceResponse, resolvedContext, config?.allowanceStrategy)
+        };
+    }
+    /**
    * Executes a swap transaction with the appropriate gas limit for the chain type.
    *
    * For EVM chains, performs a local eth_estimateGas call, applies a 1.3x safety
@@ -16186,8 +16641,8 @@ async function fetchSameChainStatusSnapshot({ isCrossChainSwap, txHash, chain, a
    */ async buildFormattedFees(fees, chain, destinationChain, adapter, recipientAddress) {
         if (!fees) return [];
         const [providerFees, swapFees, developerFees] = await Promise.all([
-            this.formatServiceFees(fees.provider, chain, 'provider', adapter),
-            this.formatServiceFees(fees.swap, chain, 'swap', adapter),
+            this.formatServiceFees(fees.provider, chain, destinationChain, 'provider', adapter),
+            this.formatServiceFees(fees.swap, chain, destinationChain, 'swap', adapter),
             recipientAddress ? this.formatDeveloperFees(fees.developer, chain, destinationChain, recipientAddress, adapter) : Promise.resolve([])
         ]);
         return [
@@ -16197,6 +16652,45 @@ async function fetchSameChainStatusSnapshot({ isCrossChainSwap, txHash, chain, a
         ];
     }
     /**
+   * Resolve a single fee item to its display token and human-readable amount.
+   *
+   * @remarks
+   * Prefer the self-describing metadata the service attaches to each fee:
+   * `decimals` (and `symbol`) come straight from the provider quote, so they
+   * are authoritative even for a token absent from the SDK registry on both
+   * chains. That is the case {@link resolveFeeChain} cannot recover — a
+   * destination-denominated fee token resolves on neither the source registry
+   * nor the source-bound adapter, leaving the amount as raw base units. When
+   * the service omits `decimals` (optional during rollout), fall back to
+   * inferring the fee token's chain and resolving via the registry/adapter.
+   *
+   * Like {@link formatTokenValue}, this never throws: fee display is cosmetic
+   * and must not fail an estimate/swap. A malformed self-describing `decimals`
+   * (e.g. a non-numeric `amount` or invalid decimal count that makes
+   * {@link formatUnits} throw) falls through to chain-based resolution rather
+   * than propagating out of {@link buildFormattedFees}.
+   *
+   * @param fee - The fee item from the service response.
+   * @param chain - The source chain definition.
+   * @param destinationChain - The destination chain definition.
+   * @param adapter - The adapter for on-chain decimals lookup of unregistered tokens.
+   * @returns Promise resolving to the formatted amount and display token.
+   */ async formatFeeValue(fee, chain, destinationChain, adapter) {
+        if (fee.decimals != null) {
+            try {
+                return {
+                    amount: formatUnits(fee.amount, fee.decimals),
+                    token: fee.symbol ?? fee.token
+                };
+            } catch  {
+            // Malformed service metadata — fall through to chain-based resolution,
+            // which never throws (worst case: raw passthrough).
+            }
+        }
+        const feeChain = resolveFeeChain(fee.token, chain, destinationChain);
+        return formatTokenValue(fee.amount, fee.token, feeChain, adapter);
+    }
+    /**
    * Format service fee items into the SDK's ServiceSwapFee structure.
    *
    * @remarks
@@ -16207,14 +16701,15 @@ async function fetchSameChainStatusSnapshot({ isCrossChainSwap, txHash, chain, a
    * - Raw passthrough only when both registry and adapter fail
    *
    * @param feeItems - Array of fee items from the service response.
-   * @param chain - The chain definition for token resolution and formatting.
+   * @param chain - The source chain definition for token resolution and formatting.
+   * @param destinationChain - The destination chain, used to resolve fees denominated in the output token.
    * @param type - The fee type to assign ('provider' or 'swap').
    * @param adapter - The adapter for on-chain decimals lookup of unregistered tokens.
    * @returns Promise resolving to formatted ServiceSwapFee array.
-   */ async formatServiceFees(feeItems, chain, type, adapter) {
+   */ async formatServiceFees(feeItems, chain, destinationChain, type, adapter) {
         if (!feeItems) return [];
         return Promise.all(feeItems.map(async (fee)=>{
-            const formatted = await formatTokenValue(fee.amount, fee.token, chain, adapter);
+            const formatted = await this.formatFeeValue(fee, chain, destinationChain, adapter);
             return {
                 token: formatted.token,
                 amount: formatted.amount,
@@ -16226,16 +16721,15 @@ async function fetchSameChainStatusSnapshot({ isCrossChainSwap, txHash, chain, a
    * Format developer fee items into the SDK's ServiceSwapFee structure.
    *
    * @param feeItems - Array of developer fee items from the service response.
-   * @param chain - The chain definition for token resolution and formatting.
+   * @param chain - The source chain definition for token resolution and formatting.
+   * @param destinationChain - The destination chain, used to resolve fees denominated in the output token.
    * @param recipientAddress - The developer's fee recipient address from config.
    * @param adapter - The adapter for on-chain decimals lookup of unregistered tokens.
    * @returns Promise resolving to formatted ServiceSwapFee array with developer entries.
    */ async formatDeveloperFees(feeItems, chain, destinationChain, recipientAddress, adapter) {
         if (!feeItems) return [];
-        const isCrossChainSwap = destinationChain.chain !== chain.chain;
         return Promise.all(feeItems.map(async (fee)=>{
-            const feeChain = !isCrossChainSwap && fee.basis === 'estimatedAmount' ? destinationChain : chain;
-            const formatted = await formatTokenValue(fee.amount, fee.token, feeChain, adapter);
+            const formatted = await this.formatFeeValue(fee, chain, destinationChain, adapter);
             return {
                 token: formatted.token,
                 amount: formatted.amount,
@@ -18630,22 +19124,9 @@ const transformAmount = (value, direction, decimals)=>formatUnits(value, decimal
     try {
         // Step 1: Build quote params directly (no need for buildServiceParams)
         // Use chain.chain (Blockchain enum value like "World_Chain") not chain.name
+        // The kit key is optional (permissionless mode); when absent the quote is
+        // fetched without an Authorization header.
         const kitKey = params.config?.kitKey;
-        if (!kitKey) {
-            throw new KitError({
-                code: 1098,
-                name: 'INPUT_VALIDATION_FAILED',
-                type: 'INPUT',
-                recoverability: 'FATAL',
-                message: 'kitKey is required in config for callback-based fees',
-                cause: {
-                    trace: {
-                        operation: 'handleOutputFeeCallback',
-                        params
-                    }
-                }
-            });
-        }
         // Resolve token aliases to addresses for the quote API
         // The quote endpoint requires resolved addresses, not aliases like 'USDC'
         const chain = params.from.chain;
@@ -18670,7 +19151,9 @@ const transformAmount = (value, direction, decimals)=>formatUnits(value, decimal
             ...params.config?.slippageBps !== undefined && {
                 slippageBps: params.config.slippageBps
             },
-            apiKey: kitKey
+            ...kitKey ? {
+                apiKey: kitKey
+            } : {}
         };
         // Step 2: Get quote from service
         const quoteResponse = await getQuote(quoteParams);
@@ -19112,7 +19595,9 @@ const sleep$1 = async (ms)=>new Promise((resolve)=>setTimeout(resolve, ms));
         ...isCrossChain && {
             toChain: chainOut
         },
-        apiKey: params.kitKey
+        ...params.kitKey ? {
+            apiKey: params.kitKey
+        } : {}
     };
     let raw = await getSwapStatus$1(request);
     // When the service hasn't finished indexing a just-submitted swap it
@@ -19252,7 +19737,9 @@ const isResultShape = (params)=>'result' in params;
         ...chainOut !== undefined && {
             chainOut
         },
-        kitKey: params.kitKey
+        ...params.kitKey ? {
+            kitKey: params.kitKey
+        } : {}
     };
     const deadline = Date.now() + timeoutMs;
     let pollIndex = 0;
@@ -19413,7 +19900,9 @@ function resolveTokenEntry(entry, index, chain, chainDef, context) {
     const resolvedAddresses = params.tokens?.map((entry, index)=>resolveTokenEntry(entry, index, chain, chainDef, context));
     return getTokenRates$1({
         chain,
-        apiKey: params.kitKey,
+        ...params.kitKey ? {
+            apiKey: params.kitKey
+        } : {},
         ...resolvedAddresses !== undefined && {
             addresses: resolvedAddresses
         }
@@ -20410,7 +20899,7 @@ registerKit(`${pkg$1.name}/${pkg$1.version}`);
 };
 
 var name = "@circle-fin/earn-kit";
-var version = "1.2.2";
+var version = "1.3.0";
 var pkg = {
 	name: name,
 	version: version};
@@ -20540,7 +21029,11 @@ const bridgeFeeTokenSchema = hexAddressSchema;
     asset: z.string(),
     assetAddress: z.string(),
     lltv: z.number(),
-    supplyUsd: z.number()
+    supplyUsd: z.number(),
+    // Optional during the expand/contract window (a backend that predates the
+    // field omits the key), mirroring the `.optional()` facets on the base
+    // schema; `null` when the product exposes no per-market allocation (V2).
+    allocationPct: z.number().nullable().optional()
 });
 /**
  * Zod schema for a Morpho vault warning in the API response.
@@ -20554,7 +21047,74 @@ const bridgeFeeTokenSchema = hexAddressSchema;
     ])
 });
 /**
- * Zod schema for a single vault info object in the API response.
+ * Zod schema for the manager (curator) facet in the API response.
+ *
+ * @internal
+ */ const managerSchema = z.object({
+    name: z.string(),
+    address: z.string().optional(),
+    // Only 'curator' is emitted today (Morpho V1/V2). Additional manager roles
+    // are added here as the providers that emit them land, rather than shipped
+    // speculatively.
+    type: z.enum([
+        'curator'
+    ])
+});
+/**
+ * Zod schema for the APY profile facet in the API response.
+ *
+ * @internal
+ */ const apyProfileSchema = z.object({
+    current: z.number(),
+    native: z.number().nullable(),
+    d7: z.number().nullable(),
+    d30: z.number().nullable(),
+    d90: z.number().nullable(),
+    rewardShare: z.number().nullable(),
+    source: z.string().optional(),
+    asOf: z.string().optional()
+});
+/**
+ * Zod schema for the fee split facet in the API response.
+ *
+ * @internal
+ */ const feeInfoSchema = z.object({
+    performance: z.number().nullable(),
+    management: z.number().nullable()
+});
+/**
+ * Zod schema for the liquidity profile facet in the API response.
+ *
+ * `totalSupply` is the outstanding vault share tokens (ERC4626 totalSupply);
+ * it is validated as a raw JSON amount, like `totalDeposits`/`available`.
+ *
+ * @internal
+ */ const liquidityProfileSchema = z.object({
+    totalDeposits: amountJsonSchema,
+    available: amountJsonSchema,
+    totalSupply: amountJsonSchema,
+    status: z.enum([
+        'active',
+        'low_liquidity'
+    ])
+});
+/**
+ * Zod schema for the risk signals facet in the API response.
+ *
+ * @internal
+ */ const riskSignalsSchema = z.object({
+    circleSentinel: z.boolean(),
+    warnings: z.array(vaultWarningSchema).optional(),
+    earnKitWarnings: z.array(z.string()).optional()
+});
+/**
+ * Zod schema for the universal earn-opportunity base in the API response.
+ *
+ * Retains every existing deprecated flat field (kept validated through the
+ * expand/contract window so default-strip does not drop them) and adds the
+ * new nested facets. The nested facets are `.optional()` during the
+ * transition so the SDK still validates against a not-yet-fully-deployed
+ * backend; they become required after Expand ships.
  *
  * @internal
  */ const vaultInfoResponseSchema = z.object({
@@ -20579,6 +21139,96 @@ const bridgeFeeTokenSchema = hexAddressSchema;
     warnings: z.array(vaultWarningSchema).optional(),
     earnKitWarnings: z.array(z.string()).optional()
 });
+/**
+ * Shared base schema: existing flat fields (kept) plus the new nested
+ * facets and neutral identity. Facets are `.optional()` during the
+ * transition; flip to required once the backend is confirmed emitting.
+ *
+ * @internal
+ */ const earnBaseSchema = vaultInfoResponseSchema.extend({
+    address: z.string().optional(),
+    asOf: z.string().optional(),
+    manager: managerSchema.nullable().optional(),
+    apyProfile: apyProfileSchema.optional(),
+    fee: feeInfoSchema.optional(),
+    liquidityProfile: liquidityProfileSchema.optional(),
+    riskSignals: riskSignalsSchema.optional()
+});
+/**
+ * Zod schema for the `vault` opportunity variant.
+ *
+ * @internal
+ */ const vaultOpportunitySchema = earnBaseSchema.extend({
+    productType: z.literal('vault'),
+    collateral: z.array(collateralSchema)
+});
+/**
+ * Discriminated union over `productType`. Add union members here as new
+ * product types (e.g. `lending_market`, `rwa_token`) land.
+ *
+ * @internal
+ */ const earnOpportunityVariants = [
+    vaultOpportunitySchema
+];
+/** @internal */ const earnOpportunitySchema = z.discriminatedUnion('productType', earnOpportunityVariants);
+/** Product types this SDK version knows how to parse. */ const knownProductTypes = new Set(earnOpportunityVariants.map((variant)=>variant.shape.productType.value));
+/**
+ * Tolerant list parser for earn opportunities.
+ *
+ * `z.discriminatedUnion` throws on an unrecognized discriminant and
+ * `z.array` fails the whole array if any element fails. Two migration-window
+ * cases are smoothed over here so neither breaks an already-shipped SDK:
+ *
+ * - A backend that predates `productType` omits it entirely. `'vault'` was the
+ *   only opportunity type then, so default a missing discriminant to `'vault'`
+ *   rather than dropping every vault the backend returns.
+ * - A future backend adds a *second* `productType` this SDK version does not
+ *   know. Drop those elements (a present-but-unrecognized discriminant) instead
+ *   of rejecting the whole list.
+ *
+ * Only the drop above is a *tolerant* case. Anything that is not a plain object
+ * with a present-but-unknown string `productType` — `null`, `undefined`,
+ * primitives, or an object whose `productType` is malformed — is passed through
+ * untouched so `z.array(earnOpportunitySchema)` reports it as a normal
+ * validation failure. It is deliberately not silently dropped (which would hide
+ * malformed backend data) and never throws here (an unguarded property read on
+ * a non-object would escape `safeParse` as a raw `TypeError` instead of a
+ * `ZodError`).
+ *
+ * @internal
+ */ const earnOpportunityListSchema = z.preprocess((raw)=>{
+    if (!Array.isArray(raw)) {
+        return raw;
+    }
+    // Array.isArray narrows `raw` to `any[]`; view it as `unknown[]` so the
+    // map/filter chain stays type-safe and no `any` leaks into the return.
+    const entries = raw;
+    return entries.map((entry)=>{
+        // Only touch plain objects; non-objects fall through to fail validation.
+        if (typeof entry !== 'object' || entry === null) {
+            return entry;
+        }
+        const record = entry;
+        // Older backend predating productType: default to the only type then.
+        return record.productType === undefined ? {
+            ...record,
+            productType: 'vault'
+        } : record;
+    }).filter((entry)=>{
+        // Drop ONLY a present-but-unknown string discriminant (a future
+        // productType this SDK version doesn't know). Everything else —
+        // non-objects, a non-string productType — flows through to
+        // z.array(earnOpportunitySchema) and fails/passes validation normally.
+        if (typeof entry !== 'object' || entry === null) {
+            return true;
+        }
+        const productType = entry.productType;
+        if (typeof productType !== 'string') {
+            return true;
+        }
+        return knownProductTypes.has(productType);
+    });
+}, z.array(earnOpportunitySchema));
 // ---------------------------------------------------------------------------
 // Position response schema
 // ---------------------------------------------------------------------------
@@ -20708,6 +21358,7 @@ const positionPnlSchema = z.discriminatedUnion('status', [
  *
  * @internal
  */ const depositPayloadSchema = z.object({
+    execId: bridgeDepositExecIdSchema,
     executionParams: depositExecutionParamsSchema,
     signature: hexSignatureSchema
 });
@@ -20799,6 +21450,21 @@ const bridgeDepositPrepareReviewSchema = z.object({
     amount: amountJsonSchema,
     vaultAddress: hexAddressSchema
 }).passthrough();
+/** @internal */ const bridgeQuoteExpirySchema = z.discriminatedUnion('mode', [
+    z.object({
+        mode: z.literal('TIMESTAMP'),
+        expiresAt: z.string().datetime({
+            offset: true
+        })
+    }),
+    z.object({
+        mode: z.literal('BLOCK_NUMBER'),
+        expiresAtBlock: z.number().int(),
+        blockEstimatedAt: z.string().datetime({
+            offset: true
+        }).optional()
+    })
+]).optional().catch(undefined);
 /**
  * Zod schema for the bridge deposit prepare payload.
  *
@@ -20810,6 +21476,10 @@ const bridgeDepositPrepareReviewSchema = z.object({
     execId: bridgeDepositExecIdSchema,
     erc3009TypedData: bridgeDepositPreparedBundleSchema,
     expiresAt: z.string().datetime(),
+    quoteIssuedAt: z.string().datetime({
+        offset: true
+    }).optional().catch(undefined),
+    quoteExpiry: bridgeQuoteExpirySchema,
     review: bridgeDepositPrepareReviewSchema
 });
 /**
@@ -20875,6 +21545,7 @@ const bridgeDepositPrepareReviewSchema = z.object({
  *
  * @internal
  */ const withdrawPayloadSchema = z.object({
+    execId: bridgeDepositExecIdSchema,
     executionParams: withdrawExecutionParamsSchema,
     signature: hexSignatureSchema
 });
@@ -20888,6 +21559,27 @@ const bridgeDepositPrepareReviewSchema = z.object({
     data: withdrawPayloadSchema
 });
 // ---------------------------------------------------------------------------
+// Transaction report response schema
+// ---------------------------------------------------------------------------
+/**
+ * Zod schema for the transaction report payload inside the API `data` envelope.
+ *
+ * The Earn Service returns an empty payload (`{"data":{}}`) on success, so the
+ * schema accepts any object shape and does not require specific fields.
+ *
+ * @internal
+ */ const transactionReportPayloadSchema = z.object({}).passthrough();
+/**
+ * Zod schema for the `POST /v1/earnKit/transactions/report` API response.
+ *
+ * The Earn Service API wraps the transaction report payload in a `data`
+ * envelope.
+ *
+ * @internal
+ */ z.object({
+    data: transactionReportPayloadSchema
+});
+// ---------------------------------------------------------------------------
 // Claim rewards response schema
 // ---------------------------------------------------------------------------
 /**
@@ -20948,6 +21640,30 @@ const bridgeDepositPrepareReviewSchema = z.object({
     token: z.string(),
     amount: amountJsonSchema
 });
+/**
+ * Zod schema for a native gas-fee entry in an EarnKit quote response.
+ *
+ * The Earn Service backend estimates gas server-side and returns one entry per
+ * action (`Approve`, `Deposit`, `Withdraw`). A successful estimate carries
+ * `fees` in the SDK `EstimatedGas` shape (`{ gas, gasPrice, fee }`), each a raw
+ * integer string in the chain's native base units. When the backend cannot
+ * estimate an action it returns `fees: null` with an `error` message instead.
+ *
+ * The schema deliberately validates almost nothing beyond the envelope: `name`
+ * is optional and `fees` is entirely unvalidated (`unknown`). ALL validation
+ * of `fees` — that it is an object at all, and that `gas`, `gasPrice`, and
+ * `fee` are parseable integer strings — is deferred to {@link toQuoteGasFees},
+ * which degrades a malformed entry to a `fees: null` soft failure. This is
+ * intentional: gas is best-effort, so a single unparseable gas entry (a wrong
+ * type such as `fees: 123` or `fees: 'bad'`, a missing field, or a non-numeric
+ * `fee`) must never fail Zod validation and reject the entire quote.
+ *
+ * @internal
+ */ const quoteGasFeeSchema = z.object({
+    name: z.string().optional(),
+    fees: z.unknown(),
+    error: z.string().optional()
+}).passthrough();
 /**
  * Zod schema for the inner deposit quote payload.
  *
@@ -20963,7 +21679,8 @@ const bridgeDepositPrepareReviewSchema = z.object({
     expectedShares: amountJsonSchema,
     sharePrice: z.string(),
     currentApy: z.number(),
-    fees: z.array(feeSchema).optional()
+    fees: z.array(feeSchema).optional(),
+    gasFees: z.array(quoteGasFeeSchema).optional()
 });
 /**
  * Zod schema for the `POST /v1/earnKit/deposit/quote` API response.
@@ -20990,6 +21707,7 @@ const bridgeDepositPrepareReviewSchema = z.object({
     sharePrice: z.string(),
     maxWithdrawable: amountJsonSchema,
     fees: z.array(feeSchema),
+    gasFees: z.array(quoteGasFeeSchema).optional(),
     warnings: z.array(z.string()).optional()
 });
 /**
@@ -21047,7 +21765,7 @@ const bridgeDepositPrepareReviewSchema = z.object({
  *
  * @internal
  */ const getVaultsPayloadSchema = z.object({
-    vaults: z.array(vaultInfoResponseSchema),
+    vaults: earnOpportunityListSchema,
     errors: z.array(vaultErrorSchema)
 });
 /**
@@ -21077,7 +21795,7 @@ const bridgeDepositPrepareReviewSchema = z.object({
  *
  * @internal
  */ const exploreVaultsPayloadSchema = z.object({
-    vaults: z.array(vaultInfoResponseSchema),
+    vaults: earnOpportunityListSchema,
     pagination: explorePaginationSchema
 });
 /**