@circle-fin/app-kit 1.9.0 → 1.11.0

package/swap.mjs

@@ -16,15 +16,27 @@
  * limitations under the License.
  */
 
+// Buffer polyfill setup - executes before any other code
+// Ensures globalThis.Buffer is available for Solana libraries
+import { Buffer } from 'buffer';
+if (typeof globalThis !== 'undefined' && typeof globalThis.Buffer === 'undefined') {
+    globalThis.Buffer = Buffer;
+}
+if (typeof window !== 'undefined' && typeof window.Buffer === 'undefined') {
+    window.Buffer = Buffer;
+}
+
+
 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';
 
@@ -43,6 +55,51 @@ import { keccak256 } from '@ethersproject/keccak256';
  * }
  * ```
  */ const isNodeEnvironment = ()=>typeof process !== 'undefined' && typeof process.versions === 'object' && typeof process.versions.node === 'string';
+/**
+ * Check whether the current runtime exposes a browser DOM.
+ *
+ * @remarks
+ * This intentionally does not treat every non-Node runtime as a browser.
+ * Server-side edge runtimes such as Cloudflare Workers, Deno, and Supabase
+ * Edge Functions do not expose Node globals but can safely use server
+ * credentials. A Node.js runtime remains server-side even when a test or SSR
+ * environment provides a DOM shim.
+ *
+ * @returns `true` when running in a browser window, `false` otherwise.
+ *
+ * @example
+ * ```typescript
+ * import { isBrowserEnvironment } from '@core/utils'
+ *
+ * if (isBrowserEnvironment()) {
+ *   throw new Error('Server-only secrets must not be used in the browser')
+ * }
+ * ```
+ */ const isBrowserEnvironment = ()=>{
+    const browserWindow = globalThis.window;
+    return !isNodeEnvironment() && browserWindow?.document !== undefined;
+};
+/**
+ * Return the SDK User-Agent request header only when running in Node.js.
+ *
+ * Browsers forbid manually setting `User-Agent`, and a custom fallback header
+ * can trigger CORS preflight. Non-Node server runtimes also omit this optional
+ * attribution header because they cannot set it reliably.
+ *
+ * @returns A User-Agent header in Node.js, or an empty object otherwise.
+ *
+ * @example
+ * ```typescript
+ * import { getNodeUserAgentHeader } from '@core/utils'
+ *
+ * const headers = {
+ *   'Content-Type': 'application/json',
+ *   ...getNodeUserAgentHeader(),
+ * }
+ * ```
+ */ const getNodeUserAgentHeader = ()=>isNodeEnvironment() ? {
+        'User-Agent': getUserAgent()
+    } : {};
 /**
  * Detect the runtime environment and return a shortened identifier.
  *
@@ -3527,7 +3584,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 +6655,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
 ;
 /**
@@ -8014,13 +8077,12 @@ const swapTokenEnumSchema = z.enum([
         headers: {
             ...DEFAULT_CONFIG$1.headers,
             ...config.headers ?? {},
-            // In browser environments, directly setting the 'User-Agent' or similar headers is restricted and may be ignored or cause errors.
-            // This is why we use the 'X-User-Agent' header instead.
-            ...typeof window === 'undefined' ? {
-                'User-Agent': getUserAgent()
-            } : {
-                'X-User-Agent': getUserAgent()
-            }
+            // Browsers forbid setting a user-agent request header, and the custom
+            // fallback header the SDK used instead trips CORS preflight against the
+            // Circle APIs (it isn't in their `Access-Control-Allow-Headers`),
+            // blocking the request. So send the SDK user agent only in Node;
+            // browsers omit it entirely.
+            ...getNodeUserAgentHeader()
         }
     };
     let lastError;
@@ -9480,6 +9542,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.
@@ -9514,6 +9583,7 @@ const swapTokenEnumSchema = z.enum([
     if (payload.tokenIn !== undefined) safe['tokenIn'] = payload.tokenIn;
     if (payload.tokenOut !== undefined) safe['tokenOut'] = payload.tokenOut;
     if (payload.txHash !== undefined) safe['txHash'] = payload.txHash;
+    if (payload.correlationId !== undefined) safe['correlationId'] = payload.correlationId;
     if (payload.errorDetails !== undefined) {
         const errorDetails = {
             ...payload.errorDetails.errorCode !== undefined && {
@@ -9584,18 +9654,15 @@ const swapTokenEnumSchema = z.enum([
         timeoutHandle.unref();
     }
     try {
-        const isNode = isNodeEnvironment();
-        const userAgent = getUserAgent();
         await fetch(getLogsUrl(), {
             method: 'POST',
             headers: {
                 'Content-Type': 'application/json',
-                // Browser restricts setting User-Agent; use X-User-Agent instead.
-                ...isNode ? {
-                    'User-Agent': userAgent
-                } : {
-                    'X-User-Agent': userAgent
-                }
+                // Browsers forbid setting a user-agent request header, and the custom
+                // fallback header the SDK used instead trips CORS preflight (it isn't
+                // in the telemetry endpoint's `Access-Control-Allow-Headers`), so send
+                // it only in Node; browsers omit it entirely.
+                ...getNodeUserAgentHeader()
             },
             body: JSON.stringify(toSafePayload(payload)),
             signal: controller.signal
@@ -9763,7 +9830,7 @@ const swapTokenEnumSchema = z.enum([
         // discards the stack trace, nested `cause`, and any custom Error
         // properties — exactly the context an on-call needs when a
         // resolver-closure regression triggers this path.
-        console.warn(`[stablecoin-kits telemetry] dropped error event '${eventType}':`, cause);
+        console.warn(`[stablecoin-kits telemetry] dropped event '${eventType}':`, cause);
     } catch  {
     // console.warn itself throwing is the user's environment; nothing more we
     // can do without risking the original operation error.
@@ -9779,7 +9846,9 @@ const swapTokenEnumSchema = z.enum([
         sdkVersion: config.sdkVersion,
         eventType,
         timestamp: new Date().toISOString(),
-        errorDetails,
+        ...errorDetails !== undefined && {
+            errorDetails
+        },
         clientContext: buildClientContext(),
         ...context?.sourceChain != null && {
             sourceChain: context.sourceChain
@@ -9795,9 +9864,45 @@ const swapTokenEnumSchema = z.enum([
         },
         ...context?.txHash != null && {
             txHash: context.txHash
+        },
+        ...context?.correlationId != null && {
+            correlationId: context.correlationId
         }
     };
 }
+/**
+ * Emit telemetry for a completed operation without affecting its caller.
+ *
+ * No-ops when `config.disabled` is `true`. Like {@link withErrorTelemetry},
+ * failures while constructing or submitting the telemetry payload are reported
+ * as a soft warning and never change a completed operation's result.
+ *
+ * @param eventType - The telemetry event type for the completed operation.
+ * @param config - Per-kit SDK identity and disabled flag.
+ * @param context - Optional chain, token, and transaction context.
+ * @returns Nothing.
+ * @throws Never — telemetry failures are reported as warnings.
+ *
+ * @example
+ * ```typescript
+ * import { emitSuccessTelemetry } from '@core/utils'
+ *
+ * emitSuccessTelemetry(
+ *   'bridge_bridge',
+ *   { sdkName: 'bridge-kit', sdkVersion: '1.0.0', disabled: false },
+ *   { sourceChain: 'Ethereum', destinationChain: 'Base', tokenIn: 'USDC' },
+ * )
+ * ```
+ */ function emitSuccessTelemetry(eventType, config, context) {
+    if (config.disabled) {
+        return;
+    }
+    try {
+        void emitAnalyticsLog(buildPayload(config, eventType, undefined, context));
+    } catch (telemetryError) {
+        warnTelemetryDrop(eventType, telemetryError);
+    }
+}
 /**
  * Wrap an async operation with error telemetry.
  *
@@ -9856,7 +9961,7 @@ const swapTokenEnumSchema = z.enum([
 }
 
 var name$2 = "@circle-fin/bridge-kit";
-var version$2 = "1.12.0";
+var version$2 = "1.12.2";
 var pkg$2 = {
 	name: name$2,
 	version: version$2};
@@ -10714,6 +10819,17 @@ var TransferSpeed;
     clock: z.any().optional()
 }).passthrough();
 
+/**
+ * The ASCII "cctp-forward" magic, hex-encoded (no `0x`), that a forward-friendly
+ * hookData must start with.
+ *
+ * Encoded with `TextEncoder` (a browser-safe Web API) rather than `Buffer.from`
+ * so this module-level constant does not reference the Node `Buffer` global at
+ * import time. App Kit inlines this provider into its bundle without a Buffer polyfill, and a
+ * bare `Buffer` here crashes browser bundles (e.g. Vite) on load — even for apps
+ * that never touch the prepaid FORWARD path. Mirrors `buildForwardingHookData`.
+ */ Array.from(new TextEncoder().encode(CCTP_FORWARD_MAGIC_PREFIX)).map((byte)=>byte.toString(16).padStart(2, '0')).join('');
+
 /**
  * The minimum finality threshold for CCTPv2 transfers.
  *
@@ -10746,7 +10862,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.5.0";
 var pkg$1 = {
 	name: name$1,
 	version: version$1};
@@ -10811,7 +10927,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 +11461,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 +11519,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 +11555,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 +11564,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 +11664,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.
@@ -11574,6 +11695,16 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
         required_error: 'estimatedAmount is required',
         invalid_type_error: 'estimatedAmount must be a string'
     }).min(1, 'estimatedAmount must be a non-empty string'),
+    // Per-swap join key echoed back verbatim on success telemetry. Optional so a
+    // not-yet-upgraded service (no field) still validates during rollout. A
+    // malformed/non-UUID value is coerced to `undefined` (no telemetry id) rather
+    // than throwing: this is a telemetry-only field (stripped from the developer
+    // result, never used for control flow), so it must not be able to abort the
+    // swap via `parseCreateSwapResponse().parse()`. Mirrors the best-effort,
+    // never-throw contract of the rest of the telemetry stack. Implemented with
+    // `preprocess` rather than Zod's `.catch()` because static analysis misreads
+    // `.catch` on the schema chain as an unhandled Promise (S7785).
+    correlationId: z.preprocess((value)=>z.string().uuid().safeParse(value).success ? value : undefined, z.string().optional()),
     config: createSwapRequestBaseSchema.shape.config.optional(),
     fees: createSwapFeesSchema.optional(),
     transaction: createSwapTransactionSchema
@@ -11660,6 +11791,45 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
  * }
  * ```
  */ const isGetTokenRatesResponse = (obj)=>getTokenRatesResponseSchema.safeParse(obj).success;
+/**
+ * Assert that a Stablecoin Service kit key is not being supplied from a browser.
+ *
+ * The kit key (`KIT_KEY:<id>:<secret>`) is a server-only secret. Every
+ * Stablecoin Service request that attaches an `Authorization: Bearer` header
+ * funnels through this package, so calling this guard before that header is
+ * built prevents the secret from being sent from — and thus bundled into — a
+ * client application. In Node.js the check is a no-op, preserving the
+ * legitimate "hold the kit key on the server, forward the prepared transaction
+ * to the client" flow. When no kit key is supplied the permissionless (keyless)
+ * client path remains fully allowed.
+ *
+ * @param apiKey - The inline kit key for the request, or `undefined` when none
+ *   was supplied (permissionless mode).
+ * @returns Nothing.
+ * @throws KitError with VALIDATION_FAILED when a kit key is supplied while
+ *   running in a browser environment. The secret value is never echoed.
+ *
+ * @example
+ * ```typescript
+ * import { assertBrowserSafeApiKey } from '@core/service-client'
+ *
+ * // Server (Node.js): no-op, request proceeds with the Authorization header.
+ * assertBrowserSafeApiKey('KIT_KEY:my-id:my-secret')
+ *
+ * // Browser: throws to stop the secret from leaking into the client bundle.
+ * assertBrowserSafeApiKey('KIT_KEY:my-id:my-secret')
+ *
+ * // Browser, permissionless: allowed.
+ * assertBrowserSafeApiKey(undefined)
+ * ```
+ */ const assertBrowserSafeApiKey = (apiKey)=>{
+    if (apiKey === undefined) {
+        return;
+    }
+    if (isBrowserEnvironment()) {
+        throw createValidationFailedError$1('kitKey', '[redacted]', 'kitKey must not be provided in a browser environment — it is a server-only secret. Run kit operations that use a kit key on your server, or omit kitKey to use the permissionless (keyless) client path');
+    }
+};
 
 /**
  * Create a cross-chain bridge and swap transaction through the Stablecoin Service.
@@ -11717,11 +11887,16 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
     const url = new URL('/v1/stablecoinKits/swap', STABLECOIN_SERVICE_BASE_URL).toString();
     // Remove the API key from the request body
     const { apiKey, ...requestBody } = validatedParams;
+    // Never let a server-only kit key leave a browser (no-op in Node.js).
+    assertBrowserSafeApiKey(apiKey);
     const effectiveConfig = {
         ...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 {
@@ -11868,6 +12043,8 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
     }
     // Use validated data
     const validatedParams = result.data;
+    // Never let a server-only kit key leave a browser (no-op in Node.js).
+    assertBrowserSafeApiKey(validatedParams.apiKey);
     // Build the API URL
     const url = buildQuoteUrl(validatedParams);
     // Merge default config with Authorization header
@@ -11875,7 +12052,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,17 +12110,24 @@ 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
         }
     };
+    // Never let a server-only kit key leave a browser (no-op in Node.js).
+    assertBrowserSafeApiKey(validatedParams.apiKey);
     const url = buildSwapStatusUrl(validatedParams);
     const effectiveConfig = {
         ...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,17 +12216,24 @@ 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
         }
     };
+    // Never let a server-only kit key leave a browser (no-op in Node.js).
+    assertBrowserSafeApiKey(validatedParams.apiKey);
     const url = buildTokenRatesUrl(validatedParams);
     const effectiveConfig = {
         ...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 +13043,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 +13506,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 +13524,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 +13825,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 +13871,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 +14528,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 +14694,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 +15253,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 +15402,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 +15708,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 +16301,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 +16580,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,8 +16647,15 @@ async function fetchSameChainStatusSnapshot({ isCrossChainSwap, txHash, chain, a
             isCrossChainSwap,
             txHash,
             chain,
-            apiKey: serviceParams.apiKey
+            ...serviceParams.apiKey !== undefined && {
+                apiKey: serviceParams.apiKey
+            }
         });
+        // Per-swap correlation id returned by the service as a top-level response
+        // field for every chain (EVM + Solana). Attached to success telemetry so a
+        // swap can be correlated across records; never used for control flow.
+        // Undefined only against a not-yet-upgraded service that omits it.
+        const correlationId = serviceResponse.correlationId;
         // Build and return SwapResult
         return {
             tokenIn,
@@ -16124,6 +16665,9 @@ async function fetchSameChainStatusSnapshot({ isCrossChainSwap, txHash, chain, a
             fromAddress: serviceParams.fromAddress,
             toAddress: serviceParams.toAddress,
             txHash,
+            ...correlationId !== undefined && {
+                correlationId
+            },
             executedTransactions,
             ...config !== undefined && {
                 config
@@ -16138,6 +16682,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 +16803,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 +16814,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 +16863,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 +16883,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 +19286,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 +19313,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);
@@ -18922,7 +19567,13 @@ async function resolveTokenDecimals(context, resolvedParams) {
  *   amountIn: '50.00'
  * })
  * ```
- */ async function swap$1(context, params, /** @internal */ onBroadcast) {
+ */ async function swap$1(context, params, /**
+   * @internal
+   * Invoked after a successful broadcast with the on-chain `txHash` and the
+   * service-issued `correlationId` (join key for success telemetry). The
+   * service returns `correlationId` for every chain (EVM + Solana); it is
+   * undefined only against a not-yet-upgraded service that omits the field.
+   */ onBroadcast) {
     // Step 1: Validate parameters using schema
     assertSwapParams(params, swapParamsSchema);
     // Step 2: Resolve parameters (chain definitions, wallet addresses, token aliases preserved)
@@ -18942,13 +19593,16 @@ async function resolveTokenDecimals(context, resolvedParams) {
     // Step 5: Execute swap via provider
     const swapParams = buildServiceSwapParams(resolvedParams, paramsWithFees);
     const providerResult = await provider.swap(swapParams);
+    // `correlationId` is an internal telemetry join key, not part of the public
+    // SwapResult — strip it here so it never leaks into the formatted result.
+    const { correlationId, ...providerResultPublic } = providerResult;
     // A throwing `onBroadcast` must never strand the caller after a
     // successful swap broadcast — the chain has moved. `safeInvokeCallback`
     // swallows the error and surfaces a `console.warn` prefixed with
     // `[stablecoin-kits swap-kit] callback threw and was swallowed:` so a
     // kit-side closure bug stays debuggable rather than vanishing.
     safeInvokeCallback('swap-kit', ()=>{
-        onBroadcast?.(providerResult.txHash);
+        onBroadcast?.(providerResultPublic.txHash, correlationId);
     });
     const { tokenInDecimals, tokenOutDecimals } = await resolveTokenDecimals(context, resolvedParams);
     // Step 6: Compose chain identity (owned by the kit, derived from the
@@ -18957,10 +19611,10 @@ async function resolveTokenDecimals(context, resolvedParams) {
     // resolves `progress` — the provider's snapshot, or a terminal `'DONE'` for
     // a provider that omits it (a synchronous same-chain completion).
     const composedResult = {
-        ...providerResult,
+        ...providerResultPublic,
         chainIn: resolvedParams.from.chain,
         chainOut: resolvedParams.toChain ?? resolvedParams.from.chain,
-        progress: providerResult.progress ?? {
+        progress: providerResultPublic.progress ?? {
             status: 'DONE'
         }
     };
@@ -19112,7 +19766,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 +19908,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 +20071,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
         }
@@ -19807,7 +20467,13 @@ function resolveTokenEntry(entry, index, chain, chainDef, context) {
  */ class SwapKit {
     context;
     /** Whether error telemetry is disabled. */ disableErrorReporting;
-    /** Per-kit telemetry identity for shared helpers. */ telemetryConfig;
+    /** Per-kit telemetry identity for error reporting. */ telemetryConfig;
+    /**
+   * Per-kit telemetry identity for success/analytics events. Gated by
+   * `disableAnalytics` (independent of `disableErrorReporting`) so a developer
+   * can opt out of volume analytics without also silencing error reports —
+   * mirrors EarnKit.
+   */ analyticsTelemetryConfig;
     /**
    * Create a new SwapKit instance.
    *
@@ -19861,6 +20527,11 @@ function resolveTokenEntry(entry, index, chain, chainDef, context) {
             sdkVersion: pkg$1.version,
             disabled: this.disableErrorReporting
         };
+        this.analyticsTelemetryConfig = {
+            sdkName: SDK_NAME,
+            sdkVersion: pkg$1.version,
+            disabled: config.disableAnalytics === true
+        };
     }
     /**
    * Estimate the output amount and fees for a swap operation.
@@ -19901,8 +20572,12 @@ function resolveTokenEntry(entry, index, chain, chainDef, context) {
    * console.log(`Fees:`, quote.fees)
    * ```
    */ async estimate(params) {
+        const destinationChain = params.to?.chain ? resolveChainName(params.to.chain) : undefined;
         return withErrorTelemetry(async ()=>estimate(this.context, params), SWAP_EVENT_TYPES.ESTIMATE, this.telemetryConfig, {
             sourceChain: resolveChainName(params.from.chain),
+            ...destinationChain != null && {
+                destinationChain
+            },
             tokenIn: params.tokenIn,
             tokenOut: params.tokenOut
         });
@@ -19961,16 +20636,54 @@ function resolveTokenEntry(entry, index, chain, chainDef, context) {
    * ```
    */ async swap(params) {
         let txHash;
-        return withErrorTelemetry(async ()=>swap$1(this.context, params, (h)=>{
-                txHash = h;
-            }), SWAP_EVENT_TYPES.SWAP, this.telemetryConfig, ()=>({
+        let correlationId;
+        // Shared context builder so the error resolver and the success emit stay in
+        // lockstep — a field added here reaches both call sites. Reads the per-call
+        // locals lazily, so txHash/correlationId (set during the swap) are captured
+        // whenever it is invoked.
+        // Destination chain is the primary attribution dimension for cross-chain
+        // swaps; resolved once from the (static) params. Omitted for same-chain
+        // swaps that leave `to.chain` unset (destination == source).
+        const destinationChain = params.to?.chain ? resolveChainName(params.to.chain) : undefined;
+        const buildTelemetryContext = ()=>({
                 sourceChain: resolveChainName(params.from.chain),
+                ...destinationChain != null && {
+                    destinationChain
+                },
                 tokenIn: params.tokenIn,
                 tokenOut: params.tokenOut,
                 ...txHash != null && {
                     txHash
+                },
+                ...correlationId != null && {
+                    correlationId
                 }
-            }));
+            });
+        const result = await withErrorTelemetry(async ()=>swap$1(this.context, params, (h, cId)=>{
+                txHash = h;
+                correlationId = cId;
+            }), SWAP_EVENT_TYPES.SWAP, this.telemetryConfig, buildTelemetryContext);
+        // withErrorTelemetry only emits on failure. Record the successful swap here
+        // so the backend can attribute swap volume to a developer: the client event
+        // carries the (burn) txHash + correlationId, which joins to the
+        // server-emitted event carrying entity_id. Best-effort; never throws.
+        //
+        // Emit whenever a broadcast happened, i.e. we have the source/burn txHash.
+        // For a cross-chain swap that is the source-chain burn (progress is still
+        // PENDING while the destination mint settles) — we intentionally attribute
+        // at broadcast using the burn txHash rather than tracking the destination
+        // leg, which keeps the capture simple and self-contained in swap().
+        //
+        // Guard against a terminal-failure result: the EVM provider throws on
+        // revert today, but the kit is provider-agnostic, so a provider that
+        // returns a FAILED/NOT_FOUND result without throwing must not be recorded
+        // as a successful swap. Routed through analyticsTelemetryConfig so it is
+        // gated by disableAnalytics, independent of error reporting.
+        const status = result.progress?.status;
+        if (txHash != null && status !== 'FAILED' && status !== 'NOT_FOUND') {
+            emitSuccessTelemetry(SWAP_EVENT_TYPES.SWAP, this.analyticsTelemetryConfig, buildTelemetryContext());
+        }
+        return result;
     }
     /**
    * Fetch the current status of a swap from the Stablecoin Service.
@@ -20349,6 +21062,9 @@ registerKit(`${pkg$1.name}/${pkg$1.version}`);
     const kit = new SwapKit({
         ...context.disableErrorReporting != null && {
             disableErrorReporting: context.disableErrorReporting
+        },
+        ...context.disableAnalytics != null && {
+            disableAnalytics: context.disableAnalytics
         }
     });
     if (hasBoth) {
@@ -20410,7 +21126,7 @@ registerKit(`${pkg$1.name}/${pkg$1.version}`);
 };
 
 var name = "@circle-fin/earn-kit";
-var version = "1.2.2";
+var version = "1.4.0";
 var pkg = {
 	name: name,
 	version: version};
@@ -20540,7 +21256,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 +21274,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 +21366,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 +21585,7 @@ const positionPnlSchema = z.discriminatedUnion('status', [
  *
  * @internal
  */ const depositPayloadSchema = z.object({
+    execId: bridgeDepositExecIdSchema,
     executionParams: depositExecutionParamsSchema,
     signature: hexSignatureSchema
 });
@@ -20799,6 +21677,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 +21703,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 +21772,7 @@ const bridgeDepositPrepareReviewSchema = z.object({
  *
  * @internal
  */ const withdrawPayloadSchema = z.object({
+    execId: bridgeDepositExecIdSchema,
     executionParams: withdrawExecutionParamsSchema,
     signature: hexSignatureSchema
 });
@@ -20888,6 +21786,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 +21867,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 +21906,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 +21934,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 +21992,7 @@ const bridgeDepositPrepareReviewSchema = z.object({
  *
  * @internal
  */ const getVaultsPayloadSchema = z.object({
-    vaults: z.array(vaultInfoResponseSchema),
+    vaults: earnOpportunityListSchema,
     errors: z.array(vaultErrorSchema)
 });
 /**
@@ -21077,7 +22022,7 @@ const bridgeDepositPrepareReviewSchema = z.object({
  *
  * @internal
  */ const exploreVaultsPayloadSchema = z.object({
-    vaults: z.array(vaultInfoResponseSchema),
+    vaults: earnOpportunityListSchema,
     pagination: explorePaginationSchema
 });
 /**
@@ -21645,6 +22590,8 @@ function hasCrossChainDepositQuoteShape(params) {
     config: earnConfigSchema.optional()
 });
 
+/** SDK name used in telemetry payloads. */ resolveKitSdkName(pkg.name);
+
 // Auto-register this kit for user agent tracking
 registerKit(`${pkg.name}/${pkg.version}`);