@circle-fin/app-kit 1.9.0 → 1.10.0

package/index.mjs

@@ -20,9 +20,9 @@ import { z } from 'zod';
 import pino from 'pino';
 import { parseUnits as parseUnits$1, formatUnits as formatUnits$1 } from '@ethersproject/units';
 import { hexlify, hexZeroPad } from '@ethersproject/bytes';
+import '@ethersproject/abi';
 import { getAddress } from '@ethersproject/address';
 import bs58 from 'bs58';
-import '@ethersproject/abi';
 import { PublicKey } from '@solana/web3.js';
 import 'bn.js';
 import '@coral-xyz/anchor';
@@ -61,6 +61,7 @@ import { keccak256 } from '@ethersproject/keccak256';
         ...params,
         actions: {
             bridge: {},
+            earn: {},
             ...params.actions
         }
     };
@@ -3544,14 +3545,14 @@ class KitError extends Error {
 }
 
 /**
- * Standardized error definitions for Earn/Zenith operations.
+ * Standardized error definitions for Earn operations.
  *
  * These error codes provide fine-grained categorization of failures
- * from the Zenith earn service, enabling SDK consumers to distinguish
+ * from the Earn service, enabling SDK consumers to distinguish
  * between input errors (fix your request) and service errors (retry later).
  *
  * Error code ranges:
- * - 1100-1105: INPUT errors — invalid inputs, unsupported configurations
+ * - 1100-1106: INPUT errors — invalid, unsupported, or stale request state
  * - 8100-8105: SERVICE errors — retryable backend/provider failures
  *
  * @example
@@ -3604,6 +3605,14 @@ class KitError extends Error {
         name: 'EARN_UNSUPPORTED_BRIDGE_ROUTE',
         type: 'INPUT'
     },
+    /**
+   * The bridge quote expired. This is an INPUT error because the prepared
+   * request is stale and must be replaced instead of retried.
+   */ BRIDGE_QUOTE_EXPIRED: {
+        code: 1106,
+        name: 'EARN_BRIDGE_QUOTE_EXPIRED',
+        type: 'INPUT'
+    },
     /** The proxy signing call failed — retryable. */ SIGNING_FAILED: {
         code: 8100,
         name: 'EARN_SIGNING_FAILED',
@@ -3663,6 +3672,9 @@ function getOptionalString(value) {
  *   internal-error, vault-refresh-busy, off-chain-paused, position-PnL-pending,
  *   bridge failures/status lookup failures
  *
+ * Quote expiry is INPUT/FATAL because callers must start a fresh bridge prepare
+ * flow rather than retry the stale prepared bundle.
+ *
  * Unrecognized codes fall through to `parseApiError` for HTTP-status-based
  * handling.
  *
@@ -3896,6 +3908,13 @@ function getOptionalString(value) {
             errorDef: EarnError.PROVIDER_ERROR,
             recoverability: 'FATAL'
         }
+    ],
+    [
+        380506,
+        {
+            errorDef: EarnError.BRIDGE_QUOTE_EXPIRED,
+            recoverability: 'FATAL'
+        }
     ]
 ]);
 /**
@@ -4640,7 +4659,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: {
@@ -7795,7 +7817,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
 ;
 /**
@@ -8335,21 +8360,31 @@ const swapTokenEnumSchema = z.enum([
  * returning the appropriate address based on the requested contract type.
  *
  * @param chain - The chain definition to resolve the contract address for
- * @param contractType - The type of contract address to resolve ('tokenMessenger' or 'messageTransmitter')
+ * @param contractType - The type of contract address to resolve ('tokenMessenger', 'messageTransmitter', or 'tokenMessengerWithFees')
  * @returns The contract address for the specified contract type
  * @throws Error when chain does not support CCTP v2 or has unsupported contract configuration
+ * @throws Error when 'tokenMessengerWithFees' is requested but not configured on the chain
  */ const resolveCCTPV2ContractAddress = (chain, contractType)=>{
     // Handle custom bridge contract for tokenMessenger (burn transaction)
-    if (hasCustomContractSupport(chain, 'bridge') && chain.kitContracts?.bridge !== undefined) {
+    if (contractType === 'tokenMessenger' && hasCustomContractSupport(chain, 'bridge') && chain.kitContracts?.bridge !== undefined) {
         return chain.kitContracts.bridge;
     }
     // At this point we know CCTP v2 is supported, so contracts exist
     const cctpConfig = chain.cctp;
     const contracts = cctpConfig.contracts.v2;
+    // The `TokenMessengerWithFees` wrapper (prepaid FORWARD path) is an optional
+    // deployment carried alongside both split and merged configurations.
+    if (contractType === 'tokenMessengerWithFees') {
+        const wrapper = contracts.tokenMessengerWithFees;
+        if (wrapper === undefined || wrapper === '') {
+            throw new Error(`TokenMessengerWithFees is not configured on chain ${chain.name}. The prepaid FORWARD path is unavailable on this chain.`);
+        }
+        return wrapper;
+    }
     // Handle different contract types with explicit type checking
     switch(contracts.type){
         case 'split':
-            return contracts.tokenMessenger ;
+            return contractType === 'tokenMessenger' ? contracts.tokenMessenger : contracts.messageTransmitter;
         case 'merged':
             return contracts.contract;
         default:
@@ -11623,7 +11658,7 @@ function resolveOptions(options) {
 }
 
 var name$4 = "@circle-fin/bridge-kit";
-var version$5 = "1.12.0";
+var version$5 = "1.12.1";
 var pkg$5 = {
 	name: name$4,
 	version: version$5};
@@ -14166,6 +14201,144 @@ const FAST_TIER_FINALITY_THRESHOLD = 1000;
     return false;
 };
 
+/**
+ * The zero address, denoting a native-currency fee in a signed quote.
+ */ const ZERO_ADDRESS$1 = '0x0000000000000000000000000000000000000000';
+/**
+ * Resolve the fee payment channel for a prepaid-FORWARD burn via `TokenMessengerWithFees`.
+ *
+ * Determines the native `msg.value` and the ERC-20 approvals required, honouring
+ * the quote's `feeToken`:
+ * - Native fee (`feeToken` is the zero address): attach exactly `feeTotalAmount`
+ *   as `msg.value`; approve only the burn amount.
+ * - ERC-20 fee equal to the burn token (both USDC — the `isBurnTokenFee` case):
+ *   approve a single combined `amount + feeTotalAmount` and skip the redundant
+ *   second approval.
+ * - ERC-20 fee different from the burn token: approve the burn amount and the fee
+ *   amount separately.
+ *
+ * This encodes only balance/allowance intent; it does not fetch balances. The
+ * caller is responsible for a balance preflight against the fresh quote.
+ *
+ * @param params - The fee token, burn token, burn amount, and total fee amount.
+ * @returns The resolved fee payment plan.
+ * @throws KitError if `amount` or `feeTotalAmount` is negative.
+ *
+ * @example
+ * ```typescript
+ * // Native fee
+ * resolveFeePayment({
+ *   feeToken: '0x0000000000000000000000000000000000000000',
+ *   burnToken: '0xUSDC...',
+ *   amount: 1_000_000n,
+ *   feeTotalAmount: 3_500_000n,
+ * })
+ * // → { isNativeFee: true, isBurnTokenFee: false, nativeValue: 3_500_000n,
+ * //     approvals: [{ token: '0xUSDC...', amount: 1_000_000n }] }
+ * ```
+ */ const resolveFeePayment = (params)=>{
+    const { feeToken, burnToken, amount, feeTotalAmount } = params;
+    if (typeof amount !== 'bigint' || amount < 0n) {
+        throw createValidationFailedError$1('amount', amount, 'Must be a non-negative bigint');
+    }
+    if (typeof feeTotalAmount !== 'bigint' || feeTotalAmount < 0n) {
+        throw createValidationFailedError$1('feeTotalAmount', feeTotalAmount, 'Must be a non-negative bigint');
+    }
+    const isNativeFee = feeToken.toLowerCase() === ZERO_ADDRESS$1;
+    const isBurnTokenFee = !isNativeFee && feeToken.toLowerCase() === burnToken.toLowerCase();
+    if (isNativeFee) {
+        return {
+            isNativeFee: true,
+            isBurnTokenFee: false,
+            nativeValue: feeTotalAmount,
+            approvals: [
+                {
+                    token: burnToken,
+                    amount
+                }
+            ]
+        };
+    }
+    if (isBurnTokenFee) {
+        // Fee and burn draw on the same token — a single combined approval covers
+        // both; the redundant second approval is skipped.
+        return {
+            isNativeFee: false,
+            isBurnTokenFee: true,
+            nativeValue: 0n,
+            approvals: [
+                {
+                    token: burnToken,
+                    amount: amount + feeTotalAmount
+                }
+            ]
+        };
+    }
+    return {
+        isNativeFee: false,
+        isBurnTokenFee: false,
+        nativeValue: 0n,
+        approvals: [
+            {
+                token: burnToken,
+                amount
+            },
+            {
+                token: feeToken,
+                amount: feeTotalAmount
+            }
+        ]
+    };
+};
+
+/**
+ * The ASCII "cctp-forward" magic, hex-encoded (no `0x`), that a forward-friendly
+ * hookData must start with.
+ */ const CCTP_FORWARD_MAGIC_HEX = Buffer.from(CCTP_FORWARD_MAGIC_PREFIX, 'ascii').toString('hex');
+/**
+ * Determine whether a hookData blob begins with the `cctp-forward` envelope.
+ *
+ * The prepaid FORWARD path requires the GenericExecutor blob to be wrapped in a
+ * `cctp-forward` frame; without it the wrapper reverts `ForwardFeeWithoutHook`.
+ *
+ * @param hookData - The 0x-prefixed hookData hex string.
+ * @returns True when the hookData starts with the `cctp-forward` magic.
+ *
+ * @example
+ * ```typescript
+ * hasForwardHook('0x636374702d666f7277617264...') // true
+ * hasForwardHook('0xdeadbeef') // false
+ * ```
+ */ const hasForwardHook = (hookData)=>{
+    if (typeof hookData !== 'string') {
+        return false;
+    }
+    const normalized = (hookData.startsWith('0x') ? hookData.slice(2) : hookData).toLowerCase();
+    return normalized.startsWith(CCTP_FORWARD_MAGIC_HEX);
+};
+/**
+ * Assert that a hookData blob is forward-friendly for the prepaid FORWARD path.
+ *
+ * The prepaid FORWARD path always requests a FORWARD fee item, so the wrapper
+ * requires the hookData to start with a `cctp-forward` frame. Validating this
+ * before the burn surfaces the guaranteed `ForwardFeeWithoutHook` revert as a
+ * typed input error instead of an on-chain failure.
+ *
+ * @param hookData - The 0x-prefixed hookData hex string.
+ * @throws KitError (`INPUT_VALIDATION_FAILED`) if the hookData is missing or lacks
+ *   the `cctp-forward` frame.
+ *
+ * @example
+ * ```typescript
+ * assertForwardHookData(geForwardHookData) // ok
+ * assertForwardHookData('0xdeadbeef') // throws — would revert ForwardFeeWithoutHook
+ * ```
+ */ const assertForwardHookData = (hookData)=>{
+    if (!hasForwardHook(hookData)) {
+        throw createValidationFailedError$1('hookData', hookData, 'Prepaid FORWARD burns require a cctp-forward-wrapped hookData; without it the TokenMessengerWithFees wrapper reverts ForwardFeeWithoutHook');
+    }
+};
+
 /**
  * Type guard to validate the forwardFee object structure.
  *
@@ -15097,6 +15270,109 @@ const assertCCTPv2BridgeParamsSymbol = Symbol('assertCCTPv2BridgeParams');
     }
 }
 
+/**
+ * Assert that `params` is a well-formed {@link BurnWithFeesParams} object.
+ *
+ * Validates the full public-boundary input before any field destructuring,
+ * `BigInt()` coercion, or adapter preparation runs, so malformed JS-caller
+ * inputs always produce typed `KitError` validation failures.
+ *
+ * Checks performed (in order):
+ * - `params` must be a non-null plain object
+ * - `source` — valid CCTP v2 wallet context (via `assertCCTPv2WalletContext`)
+ * - `destinationChain` — present and supports CCTP v2
+ * - source and destination chains must both be testnet or both mainnet
+ * - source and destination chains must differ
+ * - `executor` — non-empty string
+ * - `amount` — bigint or non-empty string coercible to bigint
+ * - `feeTotalAmount` — bigint or non-empty string coercible to bigint
+ * - `feeToken` — valid EVM address (`0x` + 40 hex chars)
+ * - `claim.signedQuote` — valid `0x`-prefixed hex string
+ * - `claim.refundAddress` — valid EVM address
+ * - `hookData` — valid `0x`-prefixed hex string when present
+ *
+ * @param params - The value to validate.
+ * @throws {KitError} If any field is missing or invalid.
+ *
+ * @example
+ * ```typescript
+ * assertBurnWithFeesParams(params)
+ * // params is now typed as BurnWithFeesParams and safe to use
+ * const { source, destinationChain, amount } = params
+ * ```
+ */ function assertBurnWithFeesParams(params) {
+    if (params === null || typeof params !== 'object' || Array.isArray(params)) {
+        throw createValidationFailedError$1('params', params, 'Must be a non-null plain object');
+    }
+    const p = params;
+    // Source wallet context
+    assertCCTPv2WalletContext(p['source']);
+    const source = p['source'];
+    // destinationChain
+    const destinationChain = p['destinationChain'];
+    if (destinationChain === null || destinationChain === undefined || typeof destinationChain !== 'object') {
+        throw createValidationFailedError$1('destinationChain', destinationChain, 'Must be a chain definition object');
+    }
+    if (!isCCTPV2Supported(destinationChain)) {
+        throw createValidationFailedError$1('destinationChain', destinationChain, 'destinationChain must support CCTP v2');
+    }
+    const dest = destinationChain;
+    // Testnet / mainnet mismatch
+    if (source.chain.isTestnet !== dest.isTestnet) {
+        throw createNetworkMismatchError(source.chain, dest);
+    }
+    // Same-chain guard
+    if (source.chain.name === dest.name) {
+        throw createUnsupportedRouteError(source.chain.name, dest.name);
+    }
+    // executor
+    const executor = p['executor'];
+    if (typeof executor !== 'string' || executor === '') {
+        throw createValidationFailedError$1('executor', executor, 'A GenericExecutor address is required (used for both mintRecipient and destinationCaller)');
+    }
+    // amount
+    const rawAmount = p['amount'];
+    if (typeof rawAmount !== 'bigint' && typeof rawAmount !== 'string' || rawAmount === '') {
+        throw createValidationFailedError$1('amount', rawAmount, 'Must be a bigint or a numeric string');
+    }
+    try {
+        BigInt(rawAmount);
+    } catch  {
+        throw createValidationFailedError$1('amount', rawAmount, 'Must be a valid integer value coercible to bigint');
+    }
+    // feeTotalAmount
+    const rawFee = p['feeTotalAmount'];
+    if (typeof rawFee !== 'bigint' && typeof rawFee !== 'string' || rawFee === '') {
+        throw createValidationFailedError$1('feeTotalAmount', rawFee, 'Must be a bigint or a numeric string');
+    }
+    try {
+        BigInt(rawFee);
+    } catch  {
+        throw createValidationFailedError$1('feeTotalAmount', rawFee, 'Must be a valid integer value coercible to bigint');
+    }
+    // feeToken
+    if (!evmAddressSchema.safeParse(p['feeToken']).success) {
+        throw createValidationFailedError$1('feeToken', p['feeToken'], 'Must be a valid EVM address (use the zero address for a native fee)');
+    }
+    // claim
+    const rawClaim = p['claim'];
+    if (rawClaim === null || typeof rawClaim !== 'object' || Array.isArray(rawClaim)) {
+        throw createValidationFailedError$1('claim', rawClaim, 'Must be an object with signedQuote and refundAddress');
+    }
+    const claim = rawClaim;
+    if (!hexStringSchema.safeParse(claim['signedQuote']).success) {
+        throw createValidationFailedError$1('claim.signedQuote', claim['signedQuote'], 'Must be a valid hex string starting with 0x');
+    }
+    if (!evmAddressSchema.safeParse(claim['refundAddress']).success) {
+        throw createValidationFailedError$1('claim.refundAddress', claim['refundAddress'], 'Must be a valid EVM address');
+    }
+    // hookData (optional)
+    const hookData = p['hookData'];
+    if (hookData !== undefined && hookData !== '' && !hexStringSchema.safeParse(hookData).success) {
+        throw createValidationFailedError$1('hookData', hookData, 'Must be a valid hex string starting with 0x');
+    }
+}
+
 /**
  * CCTP bridge step names that can occur in the bridging flow.
  *
@@ -16305,10 +16581,15 @@ const mockAttestationMessage = {
     const burnCallData = burnRequest.getCallData();
     // batchExecute may throw before submission (wallet declined) but never
     // after — post-submission errors are returned as empty receipts.
+    // The sender is threaded for adapters whose execution is routed through a
+    // signing strategy (which has no wallet account to read it from); the
+    // wallet-client path ignores it.
     const batchResult = await adapter.batchExecute([
         approveCallData,
         burnCallData
-    ], chain);
+    ], chain, {
+        fromAddress: params.source.address
+    });
     const approveReceipt = batchResult.receipts[0];
     const burnReceipt = batchResult.receipts[1];
     const approveStep = await buildBatchedStep('approve', approveReceipt, batchResult.batchId, adapter, chain, batchResult.statusCode, batchResult.error);
@@ -16451,7 +16732,7 @@ const mockAttestationMessage = {
     return step;
 }
 
-var version$4 = "1.9.0";
+var version$4 = "1.10.0";
 var pkg$4 = {
 	version: version$4};
 
@@ -17044,7 +17325,7 @@ var pkg$4 = {
  *   }
  * )
  * ```
- */ async function retry(result, context, provider, invocationMeta) {
+ */ async function retry$1(result, context, provider, invocationMeta) {
     const analysis = analyzeSteps(result);
     // Resolve invocation context for retry operation
     const resolvedInvocation = resolveRetryInvocation(invocationMeta);
@@ -17145,7 +17426,7 @@ var pkg$4 = {
         // Continue with remaining steps.
         // Recursive call handles subsequent pending states (e.g., next step may also
         // be pending), allowing the retry logic to loop through all actionable steps.
-        return await retry(result, context, provider);
+        return await retry$1(result, context, provider);
     } catch (error) {
         // Re-throw FATAL validation errors - these indicate invalid input
         if (isFatalError(error)) {
@@ -17359,7 +17640,7 @@ function assertCCTPV2Config(config) {
    * const retryResult = await provider.retry(failedResult, retryContext)
    * ```
    */ async retry(result, context, invocationMeta) {
-        return retry(result, context, this, invocationMeta);
+        return retry$1(result, context, this, invocationMeta);
     }
     /**
    * Estimate the cost and fees for a CCTP v2 cross-chain bridge operation.
@@ -17606,7 +17887,7 @@ function assertCCTPV2Config(config) {
             throw new Error(`Failed to resolve operation context: ${error instanceof Error ? error.message : String(error)}`);
         }
         // Resolve spender address with proper error handling
-        const spenderAddress = resolveCCTPV2ContractAddress(chain);
+        const spenderAddress = resolveCCTPV2ContractAddress(chain, 'tokenMessenger');
         // Prepare action parameters
         const actionParams = {
             amount: BigInt(amount),
@@ -18086,6 +18367,106 @@ function assertCCTPV2Config(config) {
         return await source.adapter.prepareAction('cctp.v2.depositForBurn', actionParams, resolvedContext);
     }
     /**
+   * Prepare a prepaid-FORWARD burn through the `TokenMessengerWithFees` wrapper.
+   *
+   * Builds the source-chain `depositForBurnWithHookAndFees` call for the
+   * GenericExecutor FORWARD path: fees are collected up front on the source chain
+   * against a signed quote, `mintRecipient` and `destinationCaller` are both set to
+   * the GenericExecutor, and the GE `hookData` is passed through unchanged.
+   *
+   * This is the low-level on-chain primitive behind the UBK `fastCrossChainDeposit`
+   * and Bridge Kit `bridge({ deposit })` flows. The `hookData` and signed-quote
+   * `claim` are produced elsewhere and passed in here:
+   * - `hookData`: `buildForwardingHookDataWithPayload(version,
+   *   buildDepositForGenericExecutorPayload(...).hookData)` from `@core/utils`.
+   * - `claim.signedQuote` / `feeToken` / `feeTotalAmount`: from `fetchFeeQuote`
+   *   (`@circle-fin/provider-fee-v1`), whose FORWARD item must be bound to the
+   *   SAME `hookData` and executor `destinationCaller` used here.
+   *
+   * The returned approvals and burn are NOT executed — the caller executes the
+   * approvals first (in order) and then the burn. The fee payment channel matches
+   * the quote's `feeToken`:
+   * - Native fee: exactly `feeTotalAmount` is attached as the burn's `msg.value`;
+   *   only the burn amount is approved.
+   * - USDC fee (same token as the burn): a single combined `amount + feeTotalAmount`
+   *   approval covers both; the redundant second approval is skipped.
+   *
+   * @typeParam TFromAdapterCapabilities - The source adapter's capabilities.
+   * @param params - The burn amount, executor, hookData, signed-quote claim, and fee.
+   * @returns The prepared approvals, the prepared burn, and the resolved fee plan.
+   * @throws {KitError} If the wallet context is invalid, `destinationChain` does not
+   *   support CCTP v2, the executor is missing, `amount` or `feeTotalAmount` is not
+   *   a bigint or a numeric string coercible to bigint, the hookData lacks a
+   *   `cctp-forward` frame (guaranteed `ForwardFeeWithoutHook`), or the operation
+   *   context cannot be resolved.
+   *
+   * @example
+   * ```typescript
+   * const { approvals, burn } = await provider.burnWithFees({
+   *   source,
+   *   destinationChain: Arc,
+   *   amount: 1_000_000n,
+   *   executor: genericExecutorAddress,
+   *   hookData: geForwardHookData,
+   *   claim: { signedQuote: '0x01...', refundAddress: userAddress },
+   *   feeToken: '0x0000000000000000000000000000000000000000', // native
+   *   feeTotalAmount: 3_500_000n,
+   * })
+   * for (const approval of approvals) await approval.execute()
+   * const txHash = await burn.execute()
+   * ```
+   */ async burnWithFees(params) {
+        assertBurnWithFeesParams(params);
+        const { source, destinationChain, executor, hookData, claim, feeToken } = params;
+        const amount = BigInt(params.amount);
+        const feeTotalAmount = BigInt(params.feeTotalAmount);
+        // Coupling guard: the prepaid FORWARD path always requests a FORWARD fee item,
+        // so the hookData must carry a cctp-forward frame; otherwise the wrapper
+        // reverts ForwardFeeWithoutHook. Surface it as a typed input error up front.
+        assertForwardHookData(hookData);
+        const burnToken = source.chain.usdcAddress;
+        const feePayment = resolveFeePayment({
+            feeToken,
+            burnToken,
+            amount,
+            feeTotalAmount
+        });
+        // Resolve operation context from the source wallet context.
+        const operationContext = this.extractOperationContext(source);
+        let resolvedContext;
+        try {
+            resolvedContext = await resolveOperationContext(source.adapter, operationContext);
+        } catch (error) {
+            throw createValidationFailedError$1('source.adapter', undefined, `Failed to resolve operation context: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const context = resolvedContext;
+        const wrapperAddress = resolveCCTPV2ContractAddress(source.chain, 'tokenMessengerWithFees');
+        // Build the ERC-20 approvals to the wrapper (burn token, plus a distinct fee
+        // token only when the fee is not paid in the burn token).
+        const approvals = await Promise.all(feePayment.approvals.map(async (approval)=>source.adapter.prepareAction('token.approve', {
+                tokenAddress: approval.token,
+                delegate: wrapperAddress,
+                amount: approval.amount
+            }, context)));
+        // Build the burn: mintRecipient AND destinationCaller are both the executor.
+        const burn = await source.adapter.prepareAction('cctp.v2.depositForBurnWithFees', {
+            fromChain: source.chain,
+            toChain: destinationChain,
+            amount,
+            mintRecipient: executor,
+            destinationCaller: executor,
+            hookData,
+            claim,
+            feeToken,
+            feeTotalAmount
+        }, context);
+        return {
+            approvals,
+            burn,
+            feePayment
+        };
+    }
+    /**
    * Waits for a transaction to be mined and confirmed on the blockchain.
    *
    * This method should block until the transaction is confirmed on the blockchain.
@@ -18965,7 +19346,7 @@ registerKit(`${pkg$5.name}/${pkg$5.version}`);
 };
 
 var name$3 = "@circle-fin/swap-kit";
-var version$3 = "1.3.2";
+var version$3 = "1.4.0";
 var pkg$3 = {
 	name: name$3,
 	version: version$3};
@@ -19030,7 +19411,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.
@@ -19561,7 +19945,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.
@@ -19619,7 +20003,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.
@@ -19655,7 +20039,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.
@@ -19664,13 +20048,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'
@@ -19762,7 +20148,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.
@@ -19979,7 +20365,10 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
         ...DEFAULT_CONFIG$1,
         headers: {
             ...DEFAULT_CONFIG$1.headers,
-            Authorization: `Bearer ${apiKey}`
+            // Permissionless mode: no Authorization header when the kit key is absent.
+            ...apiKey !== undefined && {
+                Authorization: `Bearer ${apiKey}`
+            }
         }
     };
     try {
@@ -20133,7 +20522,10 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
         ...DEFAULT_CONFIG$1,
         headers: {
             ...DEFAULT_CONFIG$1.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);
@@ -20188,7 +20580,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
         }
@@ -20198,7 +20592,10 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
         ...DEFAULT_CONFIG$1,
         headers: {
             ...DEFAULT_CONFIG$1.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);
@@ -20287,7 +20684,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
         }
@@ -20297,7 +20696,10 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
         ...DEFAULT_CONFIG$1,
         headers: {
             ...DEFAULT_CONFIG$1.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);
@@ -22342,6 +22744,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.
@@ -23874,10 +24317,13 @@ function writeBytes32(buffer, hex, offset) {
  * 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
@@ -23889,9 +24335,11 @@ function writeBytes32(buffer, hex, offset) {
  * 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) {
@@ -24188,8 +24636,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;
@@ -24234,7 +24682,10 @@ function resolveFeePayoutChain(tokenIn, tokenOut, sourceChain, destinationChain)
                 }
             }
         },
-        apiKey: kitKey
+        // Map kitKey → apiKey for the service client; omitted in permissionless mode.
+        ...kitKey ? {
+            apiKey: kitKey
+        } : {}
     };
 }
 
@@ -24888,6 +25339,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.
  *
@@ -25023,8 +25505,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)
         ];
@@ -25583,6 +26064,65 @@ const TOKEN_REGISTRY$3 = 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$2 = createTokenRegistry();
 /**
  * Format a raw base-unit amount into a human-readable decimal string.
@@ -25673,6 +26213,186 @@ const TOKEN_REGISTRY$2 = 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,
@@ -25799,7 +26519,9 @@ async function fetchSameChainStatusSnapshot({ isCrossChainSwap, txHash, chain, a
             const statusResult = await getSwapStatus$2({
                 txHash,
                 chain: chain.chain,
-                apiKey
+                ...apiKey !== undefined && {
+                    apiKey
+                }
             });
             if (statusResult.status === 'DONE' && statusResult.amountOut !== undefined) {
                 return {
@@ -26390,8 +27112,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;
@@ -26670,34 +27391,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);
@@ -26716,7 +27458,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 {
@@ -26741,6 +27485,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
@@ -26789,8 +27606,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 [
@@ -26800,6 +27617,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
@@ -26810,14 +27666,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,
@@ -26829,16 +27686,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,
@@ -28878,7 +29734,7 @@ const isCrossChain = (fromChain, toChain)=>toChain !== undefined && toChain.chai
 /**
  * Resolve fee recipient address from context or policy.
  * @internal
- */ async function resolveFeeRecipient(context, params, existingRecipient) {
+ */ async function resolveFeeRecipient$1(context, params, existingRecipient) {
     if (existingRecipient) {
         return existingRecipient;
     }
@@ -28906,7 +29762,7 @@ const isCrossChain = (fromChain, toChain)=>toChain !== undefined && toChain.chai
  * @internal
  */ async function applyExistingFeeAmount(context, params, existingAmount, existingFeeRecipient) {
     await validateFeeAmount(context, params, existingAmount);
-    const feeRecipient = await resolveFeeRecipient(context, params, existingFeeRecipient);
+    const feeRecipient = await resolveFeeRecipient$1(context, params, existingFeeRecipient);
     if (feeRecipient) {
         params.config = {
             ...params.config,
@@ -28940,7 +29796,7 @@ const isCrossChain = (fromChain, toChain)=>toChain !== undefined && toChain.chai
         ...params,
         type: 'input'
     };
-    const feeRecipient = await resolveFeeRecipient(context, params, existingFeeRecipient);
+    const feeRecipient = await resolveFeeRecipient$1(context, params, existingFeeRecipient);
     const amount = await context.customFeePolicy?.computeFee(feeContext);
     if (amount !== undefined) {
         await validateInputFee(context, params, BigInt(amount), amount);
@@ -29233,22 +30089,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;
@@ -29273,7 +30116,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);
@@ -29715,7 +30560,9 @@ const sleep$2 = async (ms)=>new Promise((resolve)=>setTimeout(resolve, ms));
         ...isCrossChain && {
             toChain: chainOut
         },
-        apiKey: params.kitKey
+        ...params.kitKey ? {
+            apiKey: params.kitKey
+        } : {}
     };
     let raw = await getSwapStatus$2(request);
     // When the service hasn't finished indexing a just-submitted swap it
@@ -29855,7 +30702,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;
@@ -30016,7 +30865,9 @@ function resolveTokenEntry(entry, index, chain, chainDef, context) {
     const resolvedAddresses = params.tokens?.map((entry, index)=>resolveTokenEntry(entry, index, chain, chainDef, context));
     return getTokenRates$2({
         chain,
-        apiKey: params.kitKey,
+        ...params.kitKey ? {
+            apiKey: params.kitKey
+        } : {},
         ...resolvedAddresses !== undefined && {
             addresses: resolvedAddresses
         }
@@ -31013,7 +31864,7 @@ registerKit(`${pkg$3.name}/${pkg$3.version}`);
 };
 
 var name$2 = "@circle-fin/earn-kit";
-var version$2 = "1.2.2";
+var version$2 = "1.3.0";
 var pkg$2 = {
 	name: name$2,
 	version: version$2};
@@ -31480,7 +32331,7 @@ const GAS_SAFETY_MULTIPLIER_DENOMINATOR = 10n;
  *
  * @param params - Adapter, chain, token/delegate/wallet addresses, the required
  *   allowance for the signed payload, and a revert message for on-chain failure.
- * @returns The approval transaction hash when an approval was submitted, or
+ * @returns The approval transaction result when an approval was submitted, or
  *   `undefined` when the existing allowance already covers `requiredAllowance`
  *   (or `requiredAllowance` is zero).
  * @throws {@link KitError} If the `token.allowance` response is malformed.
@@ -31488,7 +32339,7 @@ const GAS_SAFETY_MULTIPLIER_DENOMINATOR = 10n;
  *
  * @example
  * ```typescript
- * const txHash = await approveAllowanceIfNeeded({
+ * const approval = await approveAllowanceIfNeeded({
  *   adapter,
  *   chain,
  *   tokenAddress: usdcAddress,
@@ -31550,7 +32401,15 @@ const GAS_SAFETY_MULTIPLIER_DENOMINATOR = 10n;
         maxAttempts: params.allowancePropagation?.maxAttempts ?? DEFAULT_PROPAGATION_ATTEMPTS,
         delayMs: params.allowancePropagation?.delayMs ?? DEFAULT_PROPAGATION_DELAY_MS
     });
-    return approvalTxHash;
+    return {
+        txHash: approvalTxHash,
+        ...approvalReceipt.gasUsed !== undefined && {
+            gasUsed: approvalReceipt.gasUsed
+        },
+        ...approvalReceipt.effectiveGasPrice !== undefined && {
+            effectiveGasPrice: approvalReceipt.effectiveGasPrice
+        }
+    };
 }
 
 /** @internal */ function isSameAddress(actual, expected) {
@@ -31698,7 +32557,13 @@ const GAS_SAFETY_MULTIPLIER_DENOMINATOR = 10n;
     }
     return {
         txHash,
-        explorerUrl
+        explorerUrl,
+        ...receipt.gasUsed !== undefined && {
+            gasUsed: receipt.gasUsed
+        },
+        ...receipt.effectiveGasPrice !== undefined && {
+            effectiveGasPrice: receipt.effectiveGasPrice
+        }
     };
 }
 
@@ -32010,112 +32875,6 @@ const EARN_OPERATIONS = new Set([
     return hasEarnServiceParamsShape(operation, candidate['params']);
 }
 
-function buildGasFeeBase(name, chain) {
-    return {
-        name,
-        token: chain.nativeCurrency.symbol,
-        blockchain: chain.chain
-    };
-}
-function buildGasFeeSuccess(name, chain, fees) {
-    return {
-        ...buildGasFeeBase(name, chain),
-        fees
-    };
-}
-function buildGasFeeFailure(name, chain, error) {
-    return {
-        ...buildGasFeeBase(name, chain),
-        fees: null,
-        error: getErrorMessage(error)
-    };
-}
-async function estimatePreparedGasFee(name, chain, prepared) {
-    try {
-        const estimate = bufferEstimatedGas(await prepared.estimate());
-        if (estimate.gas <= 0n) {
-            throw createValidationFailedError$1('estimate.gas', estimate.gas.toString(), 'gas estimate must be greater than zero');
-        }
-        return buildGasFeeSuccess(name, chain, estimate);
-    } catch (error) {
-        return buildGasFeeFailure(name, chain, error);
-    }
-}
-async function estimateApprovalGasFeeIfNeeded(params) {
-    const { adapter, chain, address, tokenAddress, delegate, requiredAllowance } = params;
-    if (requiredAllowance <= 0n) {
-        return undefined;
-    }
-    try {
-        const allowancePrepared = await adapter.prepareAction('token.allowance', {
-            tokenAddress,
-            delegate
-        }, {
-            chain,
-            address
-        });
-        const allowanceRaw = await allowancePrepared.execute();
-        const currentAllowance = parseAllowanceResponse(allowanceRaw);
-        if (currentAllowance >= requiredAllowance) {
-            return undefined;
-        }
-        // Reuse the execute path's approval builder so the estimate simulates the
-        // exact approval (action, amount, and WARM_SLOT_RESIDUAL) that
-        // approveAllowanceIfNeeded later submits.
-        const approvalPrepared = await prepareApprovalAction({
-            adapter,
-            chain,
-            address,
-            tokenAddress,
-            delegate,
-            currentAllowance,
-            requiredAllowance
-        });
-        return await estimatePreparedGasFee('Approve', chain, approvalPrepared);
-    } catch (error) {
-        return buildGasFeeFailure('Approve', chain, error);
-    }
-}
-/**
- * Estimate gas fee entries for an earn quote without submitting transactions.
- *
- * Each entry is produced by simulating the prepared transaction against
- * current chain state. When an approval is required (allowance below the
- * signed payload's required amount), the subsequent action simulation runs
- * without that approval in place and is expected to revert — the action entry
- * then carries `fees: null` with the revert message while the approval entry
- * still estimates normally. Quote consumers must treat that as "estimate
- * pending approval", not a hard failure.
- *
- * @internal
- */ async function estimateEarnQuoteGasFees(params) {
-    const { adapter, chain, address, actionName, actionKey, actionParams, approval } = params;
-    const gasFees = [];
-    if (approval !== undefined) {
-        const approvalEstimate = await estimateApprovalGasFeeIfNeeded({
-            adapter,
-            chain,
-            address,
-            tokenAddress: approval.token,
-            delegate: approval.delegate,
-            requiredAllowance: approval.requiredAllowance
-        });
-        if (approvalEstimate !== undefined) {
-            gasFees.push(approvalEstimate);
-        }
-    }
-    try {
-        const actionPrepared = await adapter.prepareAction(actionKey, actionParams, {
-            chain,
-            address
-        });
-        gasFees.push(await estimatePreparedGasFee(actionName, chain, actionPrepared));
-    } catch (error) {
-        gasFees.push(buildGasFeeFailure(actionName, chain, error));
-    }
-    return gasFees;
-}
-
 // ---------------------------------------------------------------------------
 // Shared primitives
 // ---------------------------------------------------------------------------
@@ -32193,7 +32952,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.
@@ -32207,7 +32970,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({
@@ -32232,6 +33062,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
 // ---------------------------------------------------------------------------
@@ -32361,6 +33281,7 @@ const positionPnlSchema = z.discriminatedUnion('status', [
  *
  * @internal
  */ const depositPayloadSchema = z.object({
+    execId: bridgeDepositExecIdSchema,
     executionParams: depositExecutionParamsSchema,
     signature: hexSignatureSchema
 });
@@ -32452,6 +33373,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.
  *
@@ -32463,6 +33399,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
 });
 /**
@@ -32528,6 +33468,7 @@ const bridgeDepositPrepareReviewSchema = z.object({
  *
  * @internal
  */ const withdrawPayloadSchema = z.object({
+    execId: bridgeDepositExecIdSchema,
     executionParams: withdrawExecutionParamsSchema,
     signature: hexSignatureSchema
 });
@@ -32541,6 +33482,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
+ */ const transactionReportResponseSchema = z.object({
+    data: transactionReportPayloadSchema
+});
+// ---------------------------------------------------------------------------
 // Claim rewards response schema
 // ---------------------------------------------------------------------------
 /**
@@ -32601,6 +33563,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.
  *
@@ -32616,7 +33602,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.
@@ -32643,6 +33630,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()
 });
 /**
@@ -32700,7 +33688,7 @@ const bridgeDepositPrepareReviewSchema = z.object({
  *
  * @internal
  */ const getVaultsPayloadSchema = z.object({
-    vaults: z.array(vaultInfoResponseSchema),
+    vaults: earnOpportunityListSchema,
     errors: z.array(vaultErrorSchema)
 });
 /**
@@ -32730,7 +33718,7 @@ const bridgeDepositPrepareReviewSchema = z.object({
  *
  * @internal
  */ const exploreVaultsPayloadSchema = z.object({
-    vaults: z.array(vaultInfoResponseSchema),
+    vaults: earnOpportunityListSchema,
     pagination: explorePaginationSchema
 });
 /**
@@ -32823,6 +33811,16 @@ const bridgeDepositPrepareReviewSchema = z.object({
  */ function isWithdrawResponse(value) {
     return withdrawResponseSchema.safeParse(value).success;
 }
+/**
+ * Type guard for the transaction report API response.
+ *
+ * @param value - Unknown response value to validate
+ * @returns True when the value matches the transaction report response shape
+ *
+ * @internal
+ */ function isTransactionReportResponse(value) {
+    return transactionReportResponseSchema.safeParse(value).success;
+}
 /**
  * Type guard for the claim rewards API response.
  *
@@ -32865,7 +33863,7 @@ const bridgeDepositPrepareReviewSchema = z.object({
 }
 
 var name$1 = "@circle-fin/provider-earn-service";
-var version$1 = "1.2.2";
+var version$1 = "1.3.0";
 var pkg$1 = {
 	name: name$1,
 	version: version$1};
@@ -32985,7 +33983,7 @@ var pkg$1 = {
 }
 
 /**
- * Convert an API vault info object into the SDK {@link VaultInfo} shape.
+ * Convert an API vault info object into the SDK {@link EarnOpportunity} shape.
  *
  * Map the API chain code back to the SDK chain identifier and hydrate the
  * amount payloads into {@link Amount} instances.
@@ -32996,16 +33994,29 @@ var pkg$1 = {
  *
  * @internal
  */ function toVaultInfo(data) {
-    const { totalDeposits, liquidity, ...vault } = data;
+    const { totalDeposits, liquidity, liquidityProfile, ...vault } = data;
     const chain = toSdkChain(vault.chain);
     if (chain === undefined) {
         throw createInvalidChainError(vault.chain, 'Chain returned by the Earn Service is not supported by the SDK');
     }
+    // The nested facets are `.optional()` in the schema (a backend that predates
+    // them omits them) and are typed optional on `EarnOpportunity` to match.
+    // Convert the nested liquidity amounts when present and pass the remaining
+    // facets straight through; each absent facet stays absent rather than being
+    // asserted present by a cast.
     return {
         ...vault,
         chain,
         totalDeposits: Amount.fromJSON(totalDeposits),
-        liquidity: Amount.fromJSON(liquidity)
+        liquidity: Amount.fromJSON(liquidity),
+        ...liquidityProfile !== undefined && {
+            liquidityProfile: {
+                ...liquidityProfile,
+                totalDeposits: Amount.fromJSON(liquidityProfile.totalDeposits),
+                available: Amount.fromJSON(liquidityProfile.available),
+                totalSupply: Amount.fromJSON(liquidityProfile.totalSupply)
+            }
+        }
     };
 }
 
@@ -33040,8 +34051,11 @@ function toVaultError(error) {
     }
     try {
         const response = await pollApiGet(url.toString(), isGetVaultsResponse, pollingConfig);
+        // `pollApiGet` validates via a boolean guard and returns the raw JSON — it
+        // does not run the schema's preprocess. Parse explicitly so unknown
+        // `productType` values are dropped before `toVaultInfo`.
         return {
-            vaults: response.data.vaults.map(toVaultInfo),
+            vaults: earnOpportunityListSchema.parse(response.data.vaults).map(toVaultInfo),
             errors: response.data.errors.map(toVaultError)
         };
     } catch (error) {
@@ -33090,8 +34104,11 @@ function toVaultError(error) {
     }
     try {
         const response = await pollApiGet(url.toString(), isExploreVaultsResponse, pollingConfig);
+        // `pollApiGet` validates via a boolean guard and returns the raw JSON — it
+        // does not run the schema's preprocess. Parse explicitly so unknown
+        // `productType` values are dropped before `toVaultInfo`.
         return {
-            vaults: response.data.vaults.map(toVaultInfo),
+            vaults: earnOpportunityListSchema.parse(response.data.vaults).map(toVaultInfo),
             pagination: response.data.pagination
         };
     } catch (error) {
@@ -33255,6 +34272,12 @@ function toPositionInfo(data) {
             execId: response.data.execId,
             preparedBundle,
             expiresAt: response.data.expiresAt,
+            ...response.data.quoteIssuedAt !== undefined && {
+                quoteIssuedAt: response.data.quoteIssuedAt
+            },
+            ...response.data.quoteExpiry !== undefined && {
+                quoteExpiry: response.data.quoteExpiry
+            },
             review: response.data.review
         };
     } catch (error) {
@@ -33596,7 +34619,110 @@ function toClaimedAmount(reward) {
     }
 }
 
-function toDepositQuoteInfo(data) {
+/**
+ * Map the Earn Service's server-side quote gas estimates into the SDK
+ * {@link EarnGasFeeEstimate} shape.
+ *
+ * The Earn Service estimates gas for each action (`Approve`, `Deposit`,
+ * `Withdraw`) and returns `{ name, fees: { gas, gasPrice, fee } }` with raw
+ * integer strings.
+ * The SDK type additionally carries `token` (the chain's native currency
+ * symbol) and `blockchain`, which are filled in here from the chain
+ * definition.
+ *
+ * Gas reporting is best-effort: a malformed entry (e.g. a non-integer string
+ * that fails `BigInt` parsing) degrades to a `{ fees: null, error }` estimate
+ * rather than throwing, so one bad entry never fails the whole quote.
+ *
+ * @param gasFees - Backend gas-fee entries from the quote response, if any.
+ * @param chain - Chain definition, used for the native token symbol and
+ *   blockchain identifier.
+ * @returns One {@link EarnGasFeeEstimate} per backend entry (empty when the
+ *   backend returned none).
+ *
+ * @example
+ * ```typescript
+ * toQuoteGasFees(
+ *   [{ name: 'Deposit', fees: { gas: '364142', gasPrice: '21000000000', fee: '7646982000000000' } }],
+ *   arcTestnet,
+ * )
+ * // [{ name: 'Deposit', token: 'USDC', blockchain: 'Arc_Testnet',
+ * //    fees: { gas: 364142n, gasPrice: 21000000000n, fee: '7646982000000000' } }]
+ * ```
+ *
+ * @internal
+ */ function toQuoteGasFees(gasFees, chain) {
+    if (gasFees === undefined) {
+        return [];
+    }
+    return gasFees.map((entry)=>{
+        const base = {
+            // `name` is optional on the wire; label an unnamed entry rather than
+            // emitting `name: undefined`.
+            name: entry.name ?? 'Unknown',
+            token: chain.nativeCurrency.symbol,
+            blockchain: chain.chain
+        };
+        // The Earn Service itself reports a failed estimate as `fees: null` with
+        // an error; propagate that soft failure verbatim.
+        if (entry.fees === null || entry.fees === undefined) {
+            return {
+                ...base,
+                fees: null,
+                error: entry.error ?? 'gas estimate unavailable'
+            };
+        }
+        // `fees` is `unknown` at the schema layer, so ALL validation happens here:
+        // that it is an object at all, and that `gas`, `gasPrice`, and `fee` are
+        // each parseable integer strings (including `fee`, which the SDK contract
+        // requires be a numeric base-unit string). Any failure — a wrong type
+        // (`fees: 123`), a missing field, or a non-numeric value — degrades the
+        // whole entry to a `fees: null` soft failure rather than surfacing a
+        // malformed "successful" estimate or rejecting the quote.
+        try {
+            if (typeof entry.fees !== 'object') {
+                throw new TypeError(`gas fees must be an object (got ${typeof entry.fees})`);
+            }
+            const { gas, gasPrice, fee } = entry.fees;
+            return {
+                ...base,
+                fees: {
+                    gas: toBigInt('gas', gas),
+                    gasPrice: toBigInt('gasPrice', gasPrice),
+                    fee: toBigInt('fee', fee).toString()
+                }
+            };
+        } catch (error) {
+            return {
+                ...base,
+                fees: null,
+                error: getErrorMessage(error)
+            };
+        }
+    });
+}
+/**
+ * Parse an unknown value into a `bigint`, rejecting anything that is not a
+ * non-empty integer string. `BigInt` alone is too permissive for this path —
+ * it accepts numbers, booleans, and empty strings — so guard the type first.
+ *
+ * @param field - Field name, used in the thrown error message.
+ * @param value - Raw value from the backend gas entry.
+ * @returns The parsed `bigint`.
+ * @throws {TypeError} When `value` is not a non-empty integer string.
+ */ function toBigInt(field, value) {
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new TypeError(`gas fee field "${field}" must be an integer string`);
+    }
+    try {
+        // BigInt throws on non-integer strings (e.g. "1.5", "not-a-number").
+        return BigInt(value);
+    } catch  {
+        throw new Error(`gas fee field "${field}" is not a valid integer string: ${value}`);
+    }
+}
+
+function toDepositQuoteInfo(data, chain) {
     const fees = (data.fees ?? []).map(({ token: feeTokenSymbol, ...fee })=>{
         // Earn Service returns fee.token as a display symbol, for example "USDC".
         return {
@@ -33625,7 +34751,10 @@ function toDepositQuoteInfo(data) {
         sharePrice: data.sharePrice,
         currentApy: data.currentApy,
         fees,
-        gasFees: []
+        // The Earn Service estimates gas server-side; the chain fills token/blockchain.
+        // Cross-chain quotes resolve no local chain definition, so gasFees stays
+        // empty there (unchanged behavior).
+        gasFees: chain === undefined ? [] : toQuoteGasFees(data.gasFees, chain)
     };
 }
 /**
@@ -33660,7 +34789,7 @@ function toDepositQuoteInfo(data) {
     };
     try {
         const response = await pollApiPost(url.toString(), requestBody, isDepositQuoteResponse, pollingConfig);
-        return toDepositQuoteInfo(response.data);
+        return toDepositQuoteInfo(response.data, params.chainDefinition);
     } catch (error) {
         throw parseEarnApiError(error, {
             operation: 'getDepositQuote'
@@ -33668,7 +34797,7 @@ function toDepositQuoteInfo(data) {
     }
 }
 
-function toWithdrawalQuoteInfo(data) {
+function toWithdrawalQuoteInfo(data, chain) {
     return {
         vaultAddress: data.vaultAddress,
         vaultName: data.vaultName,
@@ -33696,7 +34825,7 @@ function toWithdrawalQuoteInfo(data) {
                     status
                 }
             })),
-        gasFees: [],
+        gasFees: chain === undefined ? [] : toQuoteGasFees(data.gasFees, chain),
         // Wire format uses `warnings`, but the SDK surface uses
         // `earnKitWarnings` to match the precedent set by `VaultInfo` —
         // `warnings` is reserved for the structured `VaultWarning` shape.
@@ -33728,7 +34857,7 @@ function toWithdrawalQuoteInfo(data) {
     };
     try {
         const response = await pollApiPost(url.toString(), requestBody, isWithdrawalQuoteResponse, pollingConfig);
-        return toWithdrawalQuoteInfo(response.data);
+        return toWithdrawalQuoteInfo(response.data, params.chainDefinition);
     } catch (error) {
         throw parseEarnApiError(error, {
             operation: 'getWithdrawalQuote'
@@ -33764,6 +34893,8 @@ function toWithdrawalQuoteInfo(data) {
                     amount: Amount.fromJSON(r.amount),
                     address: r.token
                 })),
+            // The claimRewards/quote response does not carry a gas estimate (unlike
+            // deposit/withdrawal quotes), so there is nothing to surface here.
             gasFees: []
         };
     } catch (error) {
@@ -33773,6 +34904,83 @@ function toWithdrawalQuoteInfo(data) {
     }
 }
 
+/**
+ * Build the native gas triple the backend expects for `gasUsed`.
+ *
+ * Returns `undefined` unless both receipt components are present, so the
+ * caller can omit the field entirely — the Earn Service treats a missing
+ * triple as "skip the gas cache write, still return 200".
+ *
+ * @param gasUsed - Receipt gas units used.
+ * @param effectiveGasPrice - Receipt effective gas price.
+ * @returns The `{ gas, gasPrice, fee }` triple, or `undefined` when either
+ *   component is missing.
+ *
+ * @example
+ * ```typescript
+ * buildReportedGasUsed(362454n, 29466364605n)
+ * // { gas: '362454', gasPrice: '29466364605', fee: '10680201716540670' }
+ * ```
+ *
+ * @internal
+ */ function buildReportedGasUsed(gasUsed, effectiveGasPrice) {
+    if (gasUsed === undefined || effectiveGasPrice === undefined) {
+        return undefined;
+    }
+    return {
+        gas: gasUsed.toString(),
+        gasPrice: effectiveGasPrice.toString(),
+        fee: (gasUsed * effectiveGasPrice).toString()
+    };
+}
+/**
+ * Report the outcome of an SDK-submitted same-chain Earn transaction.
+ *
+ * @param params - Transaction report parameters.
+ * @throws {@link KitError} When the API call fails.
+ *
+ * @internal
+ */ async function reportEarnTransaction(params) {
+    const { pollingConfig, baseUrl } = buildConfig(params.config);
+    const url = new URL(`${EARN_KIT_API_PREFIX}/transactions/report`, baseUrl);
+    // The report endpoint is not idempotent: success reports refresh the gas
+    // cache and failure reports increment counts. If the first request succeeds
+    // server-side but the client times out or sees a transient 5xx, retrying
+    // would duplicate the report (double-writing an outcome or inflating failure
+    // counts). Reporting is best-effort (see the fire-and-forget caller), so
+    // make exactly one attempt and never retry — a single dropped report is
+    // preferable to a duplicated one. `maxRetries` here is the total attempt
+    // count in pollApiWithValidation (loop runs `attempt <= maxRetries`), so 1
+    // means one request with no retry; 0 would skip the request entirely.
+    const reportConfig = {
+        ...pollingConfig,
+        maxRetries: 1
+    };
+    const gasUsed = buildReportedGasUsed(params.gasUsed, params.effectiveGasPrice);
+    const requestBody = {
+        execId: params.execId,
+        chain: params.chain,
+        status: params.status,
+        action: params.action,
+        ...params.txHash !== undefined && {
+            txHash: params.txHash
+        },
+        ...gasUsed !== undefined && {
+            gasUsed
+        },
+        ...params.errorCode !== undefined && {
+            errorCode: params.errorCode
+        }
+    };
+    try {
+        await pollApiPost(url.toString(), requestBody, isTransactionReportResponse, reportConfig);
+    } catch (error) {
+        throw parseEarnApiError(error, {
+            operation: 'transactionReport'
+        });
+    }
+}
+
 /**
  * Sum the amounts across every token input to size the allowance approval.
  *
@@ -33883,6 +35091,59 @@ function toWithdrawalQuoteInfo(data) {
 // Intentionally built-ins-only: Earn bridge support is limited to SDK-known
 // token contracts plus the explicit ERC-3009 domain allowlist below.
 const TOKEN_REGISTRY = createTokenRegistry();
+function submitTransactionReport(reportContext, action, status, details) {
+    void reportEarnTransaction({
+        execId: reportContext.execId,
+        chain: reportContext.chain,
+        config: reportContext.config,
+        action,
+        status,
+        ...details
+    }).catch(()=>undefined);
+}
+function reportTransactionSuccess(reportContext, action, result) {
+    if (result === undefined) {
+        return;
+    }
+    submitTransactionReport(reportContext, action, 'success', {
+        txHash: result.txHash,
+        gasUsed: result.gasUsed,
+        effectiveGasPrice: result.effectiveGasPrice
+    });
+}
+function reportTransactionFailure(reportContext, action, error) {
+    submitTransactionReport(reportContext, action, 'failure', {
+        txHash: transactionReportTxHash(error),
+        errorCode: transactionReportErrorCode(error)
+    });
+}
+function transactionReportErrorCode(error) {
+    if (isKitError(error)) {
+        return error.name;
+    }
+    const message = getErrorMessage(error);
+    if (/user (rejected|denied)|rejected by user/i.test(message)) {
+        return 'USER_REJECTED';
+    }
+    if (/insufficient funds/i.test(message)) {
+        return 'INSUFFICIENT_FUNDS';
+    }
+    if (/timeout|timed out/i.test(message)) {
+        return 'TIMEOUT';
+    }
+    return 'UNKNOWN_ERROR';
+}
+function transactionReportTxHash(error) {
+    if (!isKitError(error)) {
+        return undefined;
+    }
+    const trace = error.cause?.trace;
+    if (typeof trace !== 'object' || trace === null) {
+        return undefined;
+    }
+    const txHash = trace['txHash'];
+    return typeof txHash === 'string' && txHash !== '' ? txHash : undefined;
+}
 /**
  * Build the typed error raised when a cross-chain wait is cancelled via its
  * `AbortSignal`. Mirrors `@core/adapter-base`'s `createAbortError` (same
@@ -34214,7 +35475,7 @@ function finishElapsedWait(lastStatus, lastError) {
             const adapterContractAddress = requireAdapterContract(chain);
             const { adapter } = params.from;
             const vaultAddress = assertHexAddress('vaultAddress', params.vaultAddress, 'Vault address must be a 0x-prefixed 20-byte hex address.');
-            const { executionParams, signature } = await this.runPhase(ctx, 'deposit', 'fetchParams', async ()=>fetchDeposit({
+            const { execId, executionParams, signature } = await this.runPhase(ctx, 'deposit', 'fetchParams', async ()=>fetchDeposit({
                     vaultAddress,
                     amount: params.amount,
                     address,
@@ -34222,32 +35483,55 @@ function finishElapsedWait(lastStatus, lastError) {
                     config
                 }), ()=>undefined);
             validateExecutionDeadline(executionParams);
+            const transactionReportContext = {
+                execId,
+                chain: apiChain,
+                config
+            };
             const approvalToken = resolveEarnApprovalToken(executionParams);
             const tokenInputs = approvalToken === undefined ? [] : buildEarnTokenInputs(executionParams, approvalToken);
             const requiredAllowance = sumTokenInputAmounts(tokenInputs);
             if (!options.skipApprove && approvalToken !== undefined && requiredAllowance > 0n) {
-                await this.runPhase(ctx, 'approve', 'approve', async ()=>approveAllowanceIfNeeded({
+                await this.runPhase(ctx, 'approve', 'approve', async ()=>{
+                    try {
+                        const approval = await approveAllowanceIfNeeded({
+                            adapter,
+                            chain,
+                            tokenAddress: approvalToken,
+                            delegate: adapterContractAddress,
+                            address,
+                            requiredAllowance,
+                            revertMessage: 'Earn deposit token approval reverted on-chain'
+                        });
+                        reportTransactionSuccess(transactionReportContext, 'Approve', approval);
+                        return approval;
+                    } catch (error) {
+                        reportTransactionFailure(transactionReportContext, 'Approve', error);
+                        throw error;
+                    }
+                }, (approval)=>approval?.txHash);
+            }
+            const { txHash, explorerUrl } = await this.runPhase(ctx, 'deposit', 'execute', async ()=>{
+                try {
+                    const result = await executeEarnAction({
                         adapter,
                         chain,
-                        tokenAddress: approvalToken,
-                        delegate: adapterContractAddress,
                         address,
-                        requiredAllowance,
-                        revertMessage: 'Earn deposit token approval reverted on-chain'
-                    }), (txHash)=>txHash);
-            }
-            const { txHash, explorerUrl } = await this.runPhase(ctx, 'deposit', 'execute', async ()=>executeEarnAction({
-                    adapter,
-                    chain,
-                    address,
-                    actionKey: 'earn.deposit',
-                    actionParams: {
-                        executeParams: executionParams,
-                        tokenInputs,
-                        signature
-                    },
-                    revertMessage: 'Earn deposit reverted on-chain'
-                }), ({ txHash })=>txHash);
+                        actionKey: 'earn.deposit',
+                        actionParams: {
+                            executeParams: executionParams,
+                            tokenInputs,
+                            signature
+                        },
+                        revertMessage: 'Earn deposit reverted on-chain'
+                    });
+                    reportTransactionSuccess(transactionReportContext, 'Deposit', result);
+                    return result;
+                } catch (error) {
+                    reportTransactionFailure(transactionReportContext, 'Deposit', error);
+                    throw error;
+                }
+            }, ({ txHash })=>txHash);
             return {
                 kind: 'same-chain',
                 txHash,
@@ -34327,7 +35611,13 @@ function finishElapsedWait(lastStatus, lastError) {
             amount: params.amount,
             sourceChain: sourceChain.chain,
             destinationChain: destinationChain.chain,
-            expiresAt: prepared.expiresAt
+            expiresAt: prepared.expiresAt,
+            ...prepared.quoteIssuedAt !== undefined && {
+                quoteIssuedAt: prepared.quoteIssuedAt
+            },
+            ...prepared.quoteExpiry !== undefined && {
+                quoteExpiry: prepared.quoteExpiry
+            }
         };
     }
     /** {@inheritdoc} */ async withdraw(params) {
@@ -34348,7 +35638,7 @@ function finishElapsedWait(lastStatus, lastError) {
             const adapterContractAddress = requireAdapterContract(chain);
             const vaultAddress = assertHexAddress('vaultAddress', params.vaultAddress, 'Vault address must be a 0x-prefixed 20-byte hex address.');
             const { adapter } = params.from;
-            const { executionParams, signature } = await this.runPhase(ctx, 'withdraw', 'fetchParams', async ()=>fetchWithdraw({
+            const { execId, executionParams, signature } = await this.runPhase(ctx, 'withdraw', 'fetchParams', async ()=>fetchWithdraw({
                     vaultAddress,
                     amount: params.amount,
                     address,
@@ -34356,32 +35646,55 @@ function finishElapsedWait(lastStatus, lastError) {
                     config
                 }), ()=>undefined);
             validateExecutionDeadline(executionParams);
+            const transactionReportContext = {
+                execId,
+                chain: apiChain,
+                config
+            };
             const tokenInputs = buildEarnTokenInputs(executionParams, vaultAddress);
             const approvalToken = tokenInputs[0]?.token;
             const requiredAllowance = sumTokenInputAmounts(tokenInputs);
             if (!options.skipApprove && approvalToken !== undefined) {
-                await this.runPhase(ctx, 'approve', 'approve', async ()=>approveAllowanceIfNeeded({
+                await this.runPhase(ctx, 'approve', 'approve', async ()=>{
+                    try {
+                        const approval = await approveAllowanceIfNeeded({
+                            adapter,
+                            chain,
+                            tokenAddress: approvalToken,
+                            delegate: adapterContractAddress,
+                            address,
+                            requiredAllowance,
+                            revertMessage: 'Vault share token approval reverted on-chain'
+                        });
+                        reportTransactionSuccess(transactionReportContext, 'Approve', approval);
+                        return approval;
+                    } catch (error) {
+                        reportTransactionFailure(transactionReportContext, 'Approve', error);
+                        throw error;
+                    }
+                }, (approval)=>approval?.txHash);
+            }
+            const { txHash, explorerUrl } = await this.runPhase(ctx, 'withdraw', 'execute', async ()=>{
+                try {
+                    const result = await executeEarnAction({
                         adapter,
                         chain,
-                        tokenAddress: approvalToken,
-                        delegate: adapterContractAddress,
                         address,
-                        requiredAllowance,
-                        revertMessage: 'Vault share token approval reverted on-chain'
-                    }), (txHash)=>txHash);
-            }
-            const { txHash, explorerUrl } = await this.runPhase(ctx, 'withdraw', 'execute', async ()=>executeEarnAction({
-                    adapter,
-                    chain,
-                    address,
-                    actionKey: 'earn.withdraw',
-                    actionParams: {
-                        executeParams: executionParams,
-                        tokenInputs,
-                        signature
-                    },
-                    revertMessage: 'Earn withdraw reverted on-chain'
-                }), ({ txHash })=>txHash);
+                        actionKey: 'earn.withdraw',
+                        actionParams: {
+                            executeParams: executionParams,
+                            tokenInputs,
+                            signature
+                        },
+                        revertMessage: 'Earn withdraw reverted on-chain'
+                    });
+                    reportTransactionSuccess(transactionReportContext, 'Withdraw', result);
+                    return result;
+                } catch (error) {
+                    reportTransactionFailure(transactionReportContext, 'Withdraw', error);
+                    throw error;
+                }
+            }, ({ txHash })=>txHash);
             return {
                 txHash,
                 explorerUrl,
@@ -34515,141 +35828,6 @@ function finishElapsedWait(lastStatus, lastError) {
                 }
         }
     }
-    gasEstimateFailure(name, chain, error) {
-        return {
-            name,
-            token: chain.nativeCurrency.symbol,
-            blockchain: chain.chain,
-            fees: null,
-            error: getErrorMessage(error)
-        };
-    }
-    async estimateDepositQuoteGasFees(params) {
-        const { adapter, chain, apiChain, address, vaultAddress, amount, config } = params;
-        try {
-            const adapterContractAddress = requireAdapterContract(chain);
-            const normalizedVaultAddress = assertHexAddress('vaultAddress', vaultAddress, 'Vault address must be a 0x-prefixed 20-byte hex address.');
-            const { executionParams, signature } = await fetchDeposit({
-                vaultAddress: normalizedVaultAddress,
-                amount,
-                address,
-                chain: apiChain,
-                config
-            });
-            validateExecutionDeadline(executionParams);
-            const approvalToken = resolveEarnApprovalToken(executionParams);
-            const tokenInputs = approvalToken === undefined ? [] : buildEarnTokenInputs(executionParams, approvalToken);
-            const requiredAllowance = sumTokenInputAmounts(tokenInputs);
-            return await estimateEarnQuoteGasFees({
-                adapter,
-                chain,
-                address,
-                actionName: 'Deposit',
-                actionKey: 'earn.deposit',
-                actionParams: {
-                    executeParams: executionParams,
-                    tokenInputs,
-                    signature
-                },
-                approval: approvalToken !== undefined && requiredAllowance > 0n ? {
-                    token: approvalToken,
-                    delegate: adapterContractAddress,
-                    requiredAllowance
-                } : undefined
-            });
-        } catch (error) {
-            return [
-                this.gasEstimateFailure('Deposit', chain, error)
-            ];
-        }
-    }
-    async estimateWithdrawalQuoteGasFees(params) {
-        const { adapter, chain, apiChain, address, vaultAddress, amount, config } = params;
-        try {
-            const adapterContractAddress = requireAdapterContract(chain);
-            const normalizedVaultAddress = assertHexAddress('vaultAddress', vaultAddress, 'Vault address must be a 0x-prefixed 20-byte hex address.');
-            const { executionParams, signature } = await fetchWithdraw({
-                vaultAddress: normalizedVaultAddress,
-                amount,
-                address,
-                chain: apiChain,
-                config
-            });
-            validateExecutionDeadline(executionParams);
-            const tokenInputs = buildEarnTokenInputs(executionParams, normalizedVaultAddress);
-            const approvalToken = tokenInputs[0]?.token;
-            const requiredAllowance = sumTokenInputAmounts(tokenInputs);
-            return await estimateEarnQuoteGasFees({
-                adapter,
-                chain,
-                address,
-                actionName: 'Withdraw',
-                actionKey: 'earn.withdraw',
-                actionParams: {
-                    executeParams: executionParams,
-                    tokenInputs,
-                    signature
-                },
-                approval: approvalToken !== undefined ? {
-                    token: approvalToken,
-                    delegate: adapterContractAddress,
-                    requiredAllowance
-                } : undefined
-            });
-        } catch (error) {
-            return [
-                this.gasEstimateFailure('Withdraw', chain, error)
-            ];
-        }
-    }
-    async estimateClaimRewardsQuoteGasFees(params) {
-        const { adapter, chain, apiChain, address, vaultAddress, config } = params;
-        try {
-            requireAdapterContract(chain);
-            const { rewards, executionParams, signature } = await fetchClaimRewards({
-                address,
-                chain: apiChain,
-                vaultAddress,
-                config
-            });
-            if (rewards.length === 0) {
-                return [];
-            }
-            const missingExecutionParams = executionParams === undefined;
-            const missingSignature = signature === undefined;
-            if (missingExecutionParams || missingSignature) {
-                throw new KitError({
-                    ...EarnError.INTERNAL_ERROR,
-                    recoverability: 'RETRYABLE',
-                    message: 'Claim rewards response must include executionParams and signature when rewards are claimable',
-                    cause: {
-                        trace: {
-                            rewardsCount: rewards.length,
-                            missingExecutionParams,
-                            missingSignature
-                        }
-                    }
-                });
-            }
-            validateExecutionDeadline(executionParams);
-            return await estimateEarnQuoteGasFees({
-                adapter,
-                chain,
-                address,
-                actionName: 'Claim Rewards',
-                actionKey: 'earn.claimRewards',
-                actionParams: {
-                    executeParams: executionParams,
-                    tokenInputs: [],
-                    signature
-                }
-            });
-        } catch (error) {
-            return [
-                this.gasEstimateFailure('Claim Rewards', chain, error)
-            ];
-        }
-    }
     /** {@inheritdoc} */ async getDepositQuote(params) {
         const config = this.resolveConfig(params.config);
         if (hasQuoteDestinationChain(params)) {
@@ -34672,96 +35850,43 @@ function finishElapsedWait(lastStatus, lastError) {
             throw createValidationFailedError$1('chain', destinationChain.chain, 'chain is only supported for cross-chain Earn deposit quotes; omit chain/address when quoting on the source chain');
         }
         const { address, chain, chainDefinition } = await resolveAdapterContext(params.from);
-        // The quote fetch and the gas estimation share no data, so run them
-        // concurrently. The estimator never rejects (failures fold into
-        // `{ fees: null }` entries), so only a quote failure can throw here.
-        const [quote, gasFees] = await Promise.all([
-            fetchDepositQuote({
-                vaultAddress: params.vaultAddress,
-                amount: params.amount,
-                address,
-                chain,
-                config
-            }),
-            this.estimateDepositQuoteGasFees({
-                adapter: params.from.adapter,
-                chain: chainDefinition,
-                apiChain: chain,
-                address,
-                vaultAddress: params.vaultAddress,
-                amount: params.amount,
-                config
-            })
-        ]);
-        return {
-            ...quote,
-            gasFees
-        };
+        // Gas is estimated server-side by the Earn Service and returned on the quote, so the
+        // SDK no longer simulates it locally. `chainDefinition` lets the fetch fill
+        // the native token symbol / blockchain on each gas entry.
+        return fetchDepositQuote({
+            vaultAddress: params.vaultAddress,
+            amount: params.amount,
+            address,
+            chain,
+            config,
+            chainDefinition
+        });
     }
     /** {@inheritdoc} */ async getWithdrawalQuote(params) {
         const config = this.resolveConfig(params.config);
         const { address, chain, chainDefinition } = await resolveAdapterContext(params.from);
-        // The quote fetch and the gas estimation share no data, so run them
-        // concurrently. The estimator never rejects (failures fold into
-        // `{ fees: null }` entries), so only a quote failure can throw here.
-        const [quote, gasFees] = await Promise.all([
-            fetchWithdrawalQuote({
-                vaultAddress: params.vaultAddress,
-                amount: params.amount,
-                address,
-                chain,
-                config
-            }),
-            this.estimateWithdrawalQuoteGasFees({
-                adapter: params.from.adapter,
-                chain: chainDefinition,
-                apiChain: chain,
-                address,
-                vaultAddress: params.vaultAddress,
-                amount: params.amount,
-                config
-            })
-        ]);
-        return {
-            ...quote,
-            gasFees
-        };
+        // Gas is estimated server-side by the Earn Service and returned on the quote.
+        return fetchWithdrawalQuote({
+            vaultAddress: params.vaultAddress,
+            amount: params.amount,
+            address,
+            chain,
+            config,
+            chainDefinition
+        });
     }
     /** {@inheritdoc} */ async getClaimRewardsQuote(params) {
         const config = this.resolveConfig(params.config);
-        const { address, chain, chainDefinition } = await resolveAdapterContext(params.from);
-        const quote = await fetchClaimRewardsQuote({
+        const { address, chain } = await resolveAdapterContext(params.from);
+        // The claimRewards/quote response carries no gas estimate (unlike
+        // deposit/withdrawal quotes), and the SDK no longer estimates gas locally,
+        // so gasFees is always empty for claim rewards.
+        return fetchClaimRewardsQuote({
             vaultAddress: params.vaultAddress,
             address,
             chain,
             config
         });
-        // No claimable rewards means there is nothing to execute, so there is no
-        // gas to estimate. Short-circuit on the already-fetched quote rather than
-        // calling the (heavier) claim execution endpoint again — this also keeps
-        // `gasFees` empty as documented, instead of risking a `{ fees: null }`
-        // estimation-error entry when the adapter/RPC is unavailable. This
-        // short-circuit is why the claim path stays sequential instead of using
-        // the Promise.all pattern of the deposit/withdrawal quotes: estimating in
-        // parallel would hit the signing endpoint even when nothing is claimable.
-        if (quote.rewards.length === 0) {
-            return {
-                ...quote,
-                gasFees: []
-            };
-        }
-        const gasFees = await this.estimateClaimRewardsQuoteGasFees({
-            adapter: params.from.adapter,
-            chain: chainDefinition,
-            apiChain: chain,
-            address,
-            vaultAddress: params.vaultAddress,
-            config
-        });
-        return {
-            ...quote,
-            gasFees
-        };
     }
 }
 function hasDepositDestination(params) {
@@ -34999,11 +36124,27 @@ function formatPositionPnL(pnl) {
  * @param vault - Provider vault info with raw amount objects
  * @returns Vault info with total deposits and liquidity formatted as strings
  */ function formatVaultInfo(vault) {
-    const { totalDeposits, liquidity, ...rest } = vault;
+    // The flat `totalDeposits`/`liquidity` are deprecated aliases that are
+    // intentionally dual-read through the migration window so existing
+    // consumers keep receiving them until Contract.
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
+    const { totalDeposits, liquidity, liquidityProfile, ...rest } = vault;
+    // `liquidityProfile` is `.optional()` in the response schema during the
+    // expand/contract window (an old backend that predates the nested facets
+    // omits it), so only format and re-attach it when present — matching the
+    // provider-side `toVaultInfo` mapper.
     return {
         ...rest,
         totalDeposits: formatAmount$1(totalDeposits),
-        liquidity: formatAmount$1(liquidity)
+        liquidity: formatAmount$1(liquidity),
+        ...liquidityProfile !== undefined && {
+            liquidityProfile: {
+                ...liquidityProfile,
+                totalDeposits: formatAmount$1(liquidityProfile.totalDeposits),
+                available: formatAmount$1(liquidityProfile.available),
+                totalSupply: formatAmount$1(liquidityProfile.totalSupply)
+            }
+        }
     };
 }
 /**
@@ -36915,25 +38056,6 @@ function formatRetryResult(operation, result) {
 // Auto-register this kit for user agent tracking
 registerKit(`${pkg$2.name}/${pkg$2.version}`);
 
-/**
- * Create an EarnKit instance for AppKit earn operations.
- *
- * @remarks The context parameter is reserved for future EarnKit wiring.
- * EarnKit does not currently support AppKit developer fee hooks, so the
- * factory does not read fee callbacks from the context. Earn custom fees remain
- * reserved until EarnKit fee support ships.
- *
- * When EarnKit supports developer fee hooks, this factory can wire AppKit context through.
- *
- * @param context - AppKit context reserved for future EarnKit wiring
- * @returns A new EarnKit instance
- *
- * @example
- * ```typescript
- * const earnKit = createEarnKit(context)
- * ```
- */ const createEarnKit = ()=>new EarnKit();
-
 /**
  * Register event handlers from a context actions map to a kit instance.
  *
@@ -36998,6 +38120,29 @@ registerKit(`${pkg$2.name}/${pkg$2.version}`);
     }
 };
 
+/**
+ * Create an EarnKit instance for AppKit earn operations.
+ *
+ * Attaches any earn event handlers previously registered on the AppKit
+ * context (via `kit.on('earn.*', …)` or `kit.on('*', …)`) so step events
+ * fire during the returned kit's earn operations.
+ *
+ * @remarks Developer fee hooks from the AppKit context are not applied.
+ * EarnKit does not yet support custom fee policies.
+ *
+ * @param context - AppKit context with earn event handlers and kit options
+ * @returns An EarnKit instance ready for AppKit earn operations
+ *
+ * @example
+ * ```typescript
+ * const earnKit = createEarnKit(context)
+ * ```
+ */ const createEarnKit = (context)=>{
+    const kit = new EarnKit();
+    registerActionHandlers(kit, context.actions.earn, 'earn');
+    return kit;
+};
+
 /**
  * List of all supported token aliases for App Kit send operations.
  *
@@ -37788,7 +38933,8 @@ const tokens = createTokenRegistry();
  * polling loop yourself.
  *
  * @param context - AppKit context.
- * @param params - `txHash`, `chainIn`, optional `chainOut`, and `kitKey`.
+ * @param params - `txHash` and `chainIn`, plus optional `chainOut` and
+ *   `kitKey`.
  * @returns A snapshot of the swap's status at the time of the call.
  *
  * @example
@@ -37877,7 +39023,7 @@ const tokens = createTokenRegistry();
  * addresses before indexing into `result.rates[chain]`.
  *
  * @param context - AppKit context.
- * @param params - `chain`, optional `tokens`, and `kitKey`.
+ * @param params - `chain`, plus optional `tokens` and `kitKey`.
  * @returns A nested map of `[chain][address] → { priceUSD, fetchedAt }`.
  *
  * @example
@@ -37972,7 +39118,7 @@ const tokens = createTokenRegistry();
     }
     // Return earn-specific chains
     if (operationType === 'earn') {
-        const earnKit = createEarnKit();
+        const earnKit = createEarnKit(context);
         return earnKit.getSupportedChains();
     }
     // Return unified balance chains
@@ -37983,7 +39129,7 @@ const tokens = createTokenRegistry();
     // Reuse kit instances here if provider constructors become expensive or stateful.
     const bridgeKit = createBridgeKit(context);
     const swapKit = createSwapKit(context);
-    const earnKit = createEarnKit();
+    const earnKit = createEarnKit(context);
     const bridgeChains = bridgeKit.getSupportedChains();
     const swapChains = swapKit.getSupportedChains();
     const earnChains = earnKit.getSupportedChains();
@@ -38005,7 +39151,7 @@ const tokens = createTokenRegistry();
 };
 
 async function deposit$2(context, params) {
-    return createEarnKit().deposit(params);
+    return createEarnKit(context).deposit(params);
 }
 /**
  * Execute an earn withdrawal operation.
@@ -38029,7 +39175,7 @@ async function deposit$2(context, params) {
  * })
  * ```
  */ async function withdraw(context, params) {
-    return createEarnKit().withdraw(params);
+    return createEarnKit(context).withdraw(params);
 }
 /**
  * Claim earn rewards.
@@ -38052,7 +39198,7 @@ async function deposit$2(context, params) {
  * })
  * ```
  */ async function claimRewards(context, params) {
-    return createEarnKit().claimRewards(params);
+    return createEarnKit(context).claimRewards(params);
 }
 /**
  * Fetch vault information.
@@ -38074,7 +39220,7 @@ async function deposit$2(context, params) {
  * })
  * ```
  */ async function getVaults(context, params) {
-    return createEarnKit().getVaults(params);
+    return createEarnKit(context).getVaults(params);
 }
 /**
  * Discover vaults available on a chain.
@@ -38098,7 +39244,7 @@ async function deposit$2(context, params) {
  * })
  * ```
  */ async function exploreVaults(context, params) {
-    return createEarnKit().exploreVaults(params);
+    return createEarnKit(context).exploreVaults(params);
 }
 /**
  * Lazily iterate every vault available on a chain.
@@ -38122,7 +39268,7 @@ async function deposit$2(context, params) {
  * }
  * ```
  */ function exploreVaultsIterator(context, params) {
-    return createEarnKit().exploreVaultsIterator(params);
+    return createEarnKit(context).exploreVaultsIterator(params);
 }
 /**
  * Fetch a wallet position in a vault.
@@ -38145,7 +39291,7 @@ async function deposit$2(context, params) {
  * })
  * ```
  */ async function getPosition(context, params) {
-    return createEarnKit().getPosition(params);
+    return createEarnKit(context).getPosition(params);
 }
 /**
  * Fetch the current status of a cross-chain Earn deposit.
@@ -38167,7 +39313,7 @@ async function deposit$2(context, params) {
  * console.log(status.status)
  * ```
  */ async function getCrossChainDepositStatus(context, params) {
-    return createEarnKit().getCrossChainDepositStatus(params);
+    return createEarnKit(context).getCrossChainDepositStatus(params);
 }
 /**
  * Poll a cross-chain Earn deposit until it reaches a terminal bridge state.
@@ -38190,7 +39336,7 @@ async function deposit$2(context, params) {
  * console.log(result.outcome)
  * ```
  */ async function waitForCrossChainDeposit(context, params) {
-    return createEarnKit().waitForCrossChainDeposit(params);
+    return createEarnKit(context).waitForCrossChainDeposit(params);
 }
 /**
  * Fetch a deposit quote.
@@ -38214,7 +39360,7 @@ async function deposit$2(context, params) {
  * })
  * ```
  */ async function getDepositQuote(context, params) {
-    return createEarnKit().getDepositQuote(params);
+    return createEarnKit(context).getDepositQuote(params);
 }
 /**
  * Fetch a withdrawal quote.
@@ -38238,7 +39384,7 @@ async function deposit$2(context, params) {
  * })
  * ```
  */ async function getWithdrawalQuote(context, params) {
-    return createEarnKit().getWithdrawalQuote(params);
+    return createEarnKit(context).getWithdrawalQuote(params);
 }
 /**
  * Fetch a claim rewards quote.
@@ -38261,11 +39407,47 @@ async function deposit$2(context, params) {
  * })
  * ```
  */ async function getClaimRewardsQuote(context, params) {
-    return createEarnKit().getClaimRewardsQuote(params);
+    return createEarnKit(context).getClaimRewardsQuote(params);
+}
+/**
+ * Resume a multi-phase earn operation that previously failed.
+ *
+ * Pass the {@link KitError} caught from `deposit`, `withdraw`, or
+ * `claimRewards`. Completed phases can be skipped when the error carries
+ * earn retry context. Call `isRetryableError(error)` first.
+ *
+ * @remarks
+ * Retry re-fetches execution params and may re-submit the execute
+ * transaction. Treat this as best-effort recovery if a prior execute
+ * broadcast may still be in flight.
+ *
+ * @param context - AppKit context
+ * @param error - The error caught from a previous multi-phase earn operation
+ * @returns Promise resolving to the result of the resumed operation
+ * @throws If the error is not retryable or lacks earn retry context
+ *
+ * @example
+ * ```typescript
+ * import { isRetryableError } from '@circle-fin/app-kit'
+ * import { createContext } from '@circle-fin/app-kit/context'
+ * import { retry } from '@circle-fin/app-kit/earn'
+ *
+ * const context = createContext()
+ *
+ * try {
+ *   await deposit(context, params)
+ * } catch (error) {
+ *   if (isRetryableError(error)) {
+ *     const result = await retry(context, error)
+ *   }
+ * }
+ * ```
+ */ async function retry(context, error) {
+    return createEarnKit(context).retry(error);
 }
 
 var name = "@circle-fin/unified-balance-kit";
-var version = "1.2.2";
+var version = "1.3.0";
 var pkg = {
 	name: name,
 	version: version};
@@ -40733,29 +41915,33 @@ const CIRCLE_BPS_DIVISOR = 10_000n;
 const DEFAULT_GAS_FEE = parseUnits('0.1', USDC_DECIMALS);
 /**
  * Return the estimated Gateway gas fee for a chain in USDC atomic units.
- * Falls back to a conservative 0.1 USDC for unlisted chains.
+ * Prefers an entry in `overrides` (the real per-chain fee derived from a
+ * prior estimate), then the static {@link GAS_FEE_BY_CHAIN} constant, and
+ * finally a conservative 0.1 USDC fallback for unlisted chains.
  *
  * @param chain - The source blockchain.
+ * @param overrides - Optional real per-chain gas fees keyed by chain.
  * @returns Gas fee in USDC atomic units.
- */ function getGasFee(chain) {
-    return GAS_FEE_BY_CHAIN.get(chain) ?? DEFAULT_GAS_FEE;
+ */ function getGasFee(chain, overrides) {
+    return overrides?.get(chain) ?? GAS_FEE_BY_CHAIN.get(chain) ?? DEFAULT_GAS_FEE;
 }
 /**
  * Return the estimated forwarder fee for the destination chain
  * (service fee + destination gas fee).
  *
  * @param destinationChain - The mint destination chain.
+ * @param overrides - Optional real per-chain gas fees keyed by chain.
  * @returns Forwarder fee in USDC atomic units.
- */ function getForwarderFee(destinationChain) {
-    const destGas = getGasFee(destinationChain);
+ */ function getForwarderFee(destinationChain, overrides) {
+    const destGas = getGasFee(destinationChain, overrides);
     return FORWARDER_SERVICE_FEE + destGas;
 }
 /**
  * Estimate the fixed fees (gas + forwarder) and compute the maximum
  * amount that can be drawn from this chain for a single intent,
  * accounting for the 0.5 bps transfer fee if cross-chain.
- */ function computeMaxDrawable(slot, forwarderFeeRemaining) {
-    const gasFee = getGasFee(slot.chain);
+ */ function computeMaxDrawable(slot, forwarderFeeRemaining, overrides) {
+    const gasFee = getGasFee(slot.chain, overrides);
     let fixedFees = gasFee;
     let forwarderFeeUsed = 0n;
     if (forwarderFeeRemaining > 0n) {
@@ -40787,14 +41973,14 @@ const DEFAULT_GAS_FEE = parseUnits('0.1', USDC_DECIMALS);
  * buffer), and returns the allocations for this pass.
  *
  * Mutates `slot.remaining` so the next pass sees reduced balances.
- */ function greedyAllocate(slots, amount, destinationChain, useForwarder) {
+ */ function greedyAllocate(slots, amount, destinationChain, useForwarder, overrides) {
     const result = [];
     let remaining = amount;
-    let forwarderFeeRemaining = useForwarder ? getForwarderFee(destinationChain) : 0n;
+    let forwarderFeeRemaining = useForwarder ? getForwarderFee(destinationChain, overrides) : 0n;
     if (remaining <= 0n) return result;
     for (const slot of slots){
         if (remaining <= 0n) break;
-        const { drawable, gasFee, forwarderFeeUsed } = computeMaxDrawable(slot, forwarderFeeRemaining);
+        const { drawable, gasFee, forwarderFeeUsed } = computeMaxDrawable(slot, forwarderFeeRemaining, overrides);
         if (drawable <= 0n) continue;
         // Greedy: take as much as we can from this chain
         const take = remaining < drawable ? remaining : drawable // NOSONAR: This is a false positive — Math.min() only accepts number, not bigint, so the ternary is the correct pattern here.
@@ -40893,7 +42079,7 @@ const DEFAULT_GAS_FEE = parseUnits('0.1', USDC_DECIMALS);
     //    After this pass, slot.remaining reflects consumed capacity.
     // -----------------------------------------------------------------------
     const transferAmount = parseUnits(ctx.amountIn, USDC_DECIMALS);
-    const allocations = greedyAllocate(slots, transferAmount, ctx.destinationChain, ctx.useForwarder);
+    const allocations = greedyAllocate(slots, transferAmount, ctx.destinationChain, ctx.useForwarder, ctx.gasFeeOverrides);
     assertFullyAllocated(allocations, transferAmount, ctx.amountIn);
     // -----------------------------------------------------------------------
     // 4. Phase 2 — Allocate developer fee
@@ -40901,7 +42087,7 @@ const DEFAULT_GAS_FEE = parseUnits('0.1', USDC_DECIMALS);
     //    Same-chain first here too — if the destination chain still has
     //    capacity, use it (same-chain fee intent = cheapest gas).
     // -----------------------------------------------------------------------
-    const developerFeeAllocations = greedyAllocate(slots, devFeeAmount, ctx.destinationChain, false);
+    const developerFeeAllocations = greedyAllocate(slots, devFeeAmount, ctx.destinationChain, false, ctx.gasFeeOverrides);
     if (devFeeAmount > 0n) {
         assertFullyAllocated(developerFeeAllocations, devFeeAmount, formatUnits(devFeeAmount.toString(), USDC_DECIMALS));
     }
@@ -40910,7 +42096,7 @@ const DEFAULT_GAS_FEE = parseUnits('0.1', USDC_DECIMALS);
     //    Again same ordering, same shared reduced balances.
     //    Same-chain first for the same reason.
     // -----------------------------------------------------------------------
-    const circleFeeAllocations = greedyAllocate(slots, circleFeeAmount, ctx.destinationChain, false);
+    const circleFeeAllocations = greedyAllocate(slots, circleFeeAmount, ctx.destinationChain, false, ctx.gasFeeOverrides);
     if (circleFeeAmount > 0n) {
         assertFullyAllocated(circleFeeAllocations, circleFeeAmount, formatUnits(circleFeeAmount.toString(), USDC_DECIMALS));
     }
@@ -41009,10 +42195,12 @@ const BPS_DIVISOR = 100_000n;
  *
  * Unlike `findChainNameByDomain` (which returns the display `name`),
  * this returns `chain.chain` — the enum identifier expected by
- * {@link FeeAllocation}.
+ * {@link FeeAllocation}. Returns `undefined` when no allocation covers the
+ * domain so callers skip the intent rather than bucketing it under a
+ * fabricated sentinel.
  */ function findBlockchainByDomain(domain, allocations) {
     const alloc = allocations.find((a)=>a.chain.gateway.domain === domain);
-    return alloc?.chain.chain ?? 'Unknown';
+    return alloc?.chain.chain;
 }
 /**
  * Normalize any address/salt format to lowercase bytes32 hex.
@@ -41136,6 +42324,33 @@ const BPS_DIVISOR = 100_000n;
         };
     });
 }
+/**
+ * Read an intent's transfer value as a BigInt, tolerating the string form
+ * that can appear on estimate-response specs.
+ */ function intentValue(intent) {
+    const { value } = intent.spec;
+    return typeof value === 'bigint' ? value : safeBigInt(String(value), 'spec.value');
+}
+/**
+ * Split a single intent's `maxFee` into its transfer-fee and gas-fee
+ * components.
+ *
+ *   `transferFee = value * GATEWAY_TRANSFER_FEE_SCALED_BPS / BPS_DIVISOR`
+ *   `gasFee      = maxFee - transferFee`
+ *
+ * Same-chain transfers (withdrawals) do not incur a transfer fee, so the
+ * whole `maxFee` is gas. See {@link aggregateFeesByIntent} for the caveats
+ * on re-deriving the split locally.
+ */ function splitIntentFee(intent) {
+    const { maxFee, spec } = intent;
+    const isSameChain = spec.sourceDomain === spec.destinationDomain;
+    const transferFee = isSameChain ? 0n : intentValue(intent) * GATEWAY_TRANSFER_FEE_SCALED_BPS / BPS_DIVISOR;
+    const gasFee = maxFee > transferFee ? maxFee - transferFee : 0n;
+    return {
+        transferFee,
+        gasFee
+    };
+}
 /**
  * Decompose each intent's `maxFee` into a transfer fee and a gas fee,
  * then aggregate both by source chain.
@@ -41160,7 +42375,6 @@ const BPS_DIVISOR = 100_000n;
  *   names from source domains.
  * @returns Per-chain and total transfer/gas fee breakdowns.
  */ function aggregateFeesByIntent(estimatedIntents, allocations) {
-    const transferFeeBps = GATEWAY_TRANSFER_FEE_SCALED_BPS;
     const transferFeeByChain = new Map();
     const gasFeeByChain = new Map();
     let totalTransferFee = 0n;
@@ -41168,18 +42382,18 @@ const BPS_DIVISOR = 100_000n;
     for (const intent of estimatedIntents){
         const { maxFee, spec } = intent;
         if (maxFee === 0n) continue;
-        const chainName = findBlockchainByDomain(spec.sourceDomain, allocations);
-        const value = typeof spec.value === 'bigint' ? spec.value : safeBigInt(String(spec.value), 'spec.value');
-        const isSameChain = spec.sourceDomain === spec.destinationDomain;
-        const transferFee = isSameChain ? 0n : value * transferFeeBps / BPS_DIVISOR;
-        const gasFee = maxFee > transferFee ? maxFee - transferFee : 0n;
+        const { transferFee, gasFee } = splitIntentFee(intent);
+        totalTransferFee += transferFee;
+        totalGasFee += gasFee;
+        // Totals stay complete even if a domain can't be resolved; only the
+        // per-chain breakdown skips it rather than inventing a placeholder chain.
+        const chain = findBlockchainByDomain(spec.sourceDomain, allocations);
+        if (chain === undefined) continue;
         if (transferFee > 0n) {
-            totalTransferFee += transferFee;
-            transferFeeByChain.set(chainName, (transferFeeByChain.get(chainName) ?? 0n) + transferFee);
+            transferFeeByChain.set(chain, (transferFeeByChain.get(chain) ?? 0n) + transferFee);
         }
         if (gasFee > 0n) {
-            totalGasFee += gasFee;
-            gasFeeByChain.set(chainName, (gasFeeByChain.get(chainName) ?? 0n) + gasFee);
+            gasFeeByChain.set(chain, (gasFeeByChain.get(chain) ?? 0n) + gasFee);
         }
     }
     return {
@@ -41243,6 +42457,91 @@ const BPS_DIVISOR = 100_000n;
     }
     return fees;
 }
+/**
+ * Derive the real per-chain Gateway gas fee from estimated intents, keyed by
+ * source {@link Blockchain}.
+ *
+ * The value is the maximum single-intent gas fee observed on each chain
+ * (`maxFee − transferFee`) — the amount `computeAutoAllocation` must reserve
+ * per burn intent on that chain. Gas is (near) amount-independent, so every
+ * intent on a chain pays roughly the same; taking the max is a conservative
+ * choice for the multi-intent-per-chain case.
+ *
+ * Intended for `AutoAllocationContext.gasFeeOverrides` so the corrective
+ * re-allocation pass reserves the API's real fee instead of the static
+ * {@link GAS_FEE_BY_CHAIN} constant.
+ *
+ * @param estimatedIntents - Intents with `maxFee` from {@link parseEstimateResponse}.
+ * @param allocations - Normalised allocations used to resolve chain from source domain.
+ * @returns Per-chain real gas fees in USDC atomic units.
+ *
+ * @example
+ * ```typescript
+ * import type { BurnIntent } from '../createIntent/types'
+ * import type { NormalizedAllocation } from '../allocations'
+ *
+ * declare const estimatedIntents: BurnIntent[]
+ * declare const allocations: NormalizedAllocation[]
+ *
+ * // Real per-chain gas, ready to pass as AutoAllocationContext.gasFeeOverrides
+ * // to re-run computeAutoAllocation with the corrected reserve.
+ * const overrides = deriveGasFeeOverrides(estimatedIntents, allocations)
+ * ```
+ */ function deriveGasFeeOverrides(estimatedIntents, allocations) {
+    const overrides = new Map();
+    for (const intent of estimatedIntents){
+        if (intent.maxFee === 0n) continue;
+        const chain = findBlockchainByDomain(intent.spec.sourceDomain, allocations);
+        if (chain === undefined) continue;
+        const { gasFee } = splitIntentFee(intent);
+        const prev = overrides.get(chain) ?? 0n;
+        if (gasFee > prev) overrides.set(chain, gasFee);
+    }
+    return overrides;
+}
+/**
+ * Sum the total balance each source chain must cover, keyed by source
+ * {@link Blockchain}.
+ *
+ * Approximates the Gateway API's balance validation, which rejects a transfer
+ * (`BALANCE_INSUFFICIENT_TOKEN`) when a depositor's confirmed balance on a
+ * source chain is below `sum(intent.value + intent.maxFee)` for that
+ * depositor's intents. This aggregates by chain across all sources, so it is
+ * exact for the common single-depositor-per-chain wallet. When several
+ * depositors hold USDC on the same chain, the chain-level sum can mask a
+ * per-depositor shortfall (or a surplus on one depositor can hide it); the
+ * API's own per-depositor `9001` remains the backstop for that case. Scope the
+ * comparison per (depositor, chain) if that multi-depositor case must be caught
+ * pre-submit.
+ *
+ * @param estimatedIntents - Intents with `maxFee` from {@link parseEstimateResponse}.
+ * @param allocations - Normalised allocations used to resolve chain from source domain.
+ * @returns Per-chain required amount (transfer value + fees) in USDC atomic units.
+ *
+ * @example
+ * ```typescript
+ * import { Blockchain } from '@core/chains'
+ * import type { BurnIntent } from '../createIntent/types'
+ * import type { NormalizedAllocation } from '../allocations'
+ *
+ * declare const estimatedIntents: BurnIntent[]
+ * declare const allocations: NormalizedAllocation[]
+ * declare const confirmedBalanceAtomic: bigint
+ *
+ * const required = sumRequiredPerChain(estimatedIntents, allocations)
+ * const overDrawn =
+ *   (required.get(Blockchain.Ethereum) ?? 0n) > confirmedBalanceAtomic
+ * ```
+ */ function sumRequiredPerChain(estimatedIntents, allocations) {
+    const required = new Map();
+    for (const intent of estimatedIntents){
+        const chain = findBlockchainByDomain(intent.spec.sourceDomain, allocations);
+        if (chain === undefined) continue;
+        const amount = intentValue(intent) + intent.maxFee;
+        required.set(chain, (required.get(chain) ?? 0n) + amount);
+    }
+    return required;
+}
 
 /**
  * Sign each adapter group: Solana one intent per signature, EVM batch per adapter.
@@ -41497,69 +42796,127 @@ const FORWARDER_POLL_TIMEOUT_MS = 300_000;
  *   non-forwarder transfer response is missing attestation or signature.
  * @throws KitError Propagated from adapter signing if the user rejects
  *   or the signer is unavailable.
- */ async function resolveAllocationsAndIntents(params, destChain, recipientAddress, useForwarder) {
-    if (params.amountIn) {
-        const rawSources = Array.isArray(params.from) ? params.from : [
-            params.from
-        ];
-        const sourcesArray = rawSources.filter((s)=>s != null);
-        const networkType = destChain.isTestnet ? 'testnet' : 'mainnet';
-        const balanceResults = await Promise.all(sourcesArray.map(async (source)=>{
-            // When sourceAccount is set (delegate flow), scope the balance
-            // query to the Gateway depositor — not the signer. Using the
-            // address-only path bypasses adapter address resolution, which
-            // would otherwise return the signer's balance (developer-
-            // controlled) or reject an explicit address (user-controlled).
-            let querySource;
-            if (source.sourceAccount) {
-                querySource = {
-                    address: source.sourceAccount
-                };
-            } else {
-                querySource = {
-                    adapter: source.adapter
-                };
-                if ('address' in source && source.address) {
-                    querySource['address'] = source.address;
-                }
-            }
-            return getBalances$1({
-                token: params.token,
-                sources: querySource,
-                networkType
-            });
-        }));
-        const chainBalances = [];
-        for(let i = 0; i < balanceResults.length; i++){
-            const breakdowns = balanceResults[i]?.breakdown[0]?.breakdown ?? [];
-            for (const b of breakdowns){
-                chainBalances.push({
-                    chain: b.chain,
-                    confirmedBalance: b.confirmedBalance,
-                    sourceIndex: i
-                });
+ */ /**
+ * Fetch confirmed per-chain USDC balances for every auto-allocation source.
+ *
+ * Used only on the `amountIn` (auto-allocation) path. Returns one
+ * {@link ChainBalance} per (source, chain) pair so the greedy allocator — and
+ * the corrective re-allocation pass — can reason about draw limits without a
+ * second balance round-trip.
+ *
+ * @param params - Spend parameters (source(s) and token).
+ * @param destChain - Resolved destination chain (used for network type).
+ * @returns Confirmed balances tagged with their originating source index.
+ */ async function fetchChainBalances(params, destChain) {
+    const rawSources = Array.isArray(params.from) ? params.from : [
+        params.from
+    ];
+    const sourcesArray = rawSources.filter((s)=>s != null);
+    const networkType = destChain.isTestnet ? 'testnet' : 'mainnet';
+    const balanceResults = await Promise.all(sourcesArray.map(async (source)=>{
+        // When sourceAccount is set (delegate flow), scope the balance
+        // query to the Gateway depositor — not the signer. Using the
+        // address-only path bypasses adapter address resolution, which
+        // would otherwise return the signer's balance (developer-
+        // controlled) or reject an explicit address (user-controlled).
+        let querySource;
+        if (source.sourceAccount) {
+            querySource = {
+                address: source.sourceAccount
+            };
+        } else {
+            querySource = {
+                adapter: source.adapter
+            };
+            if ('address' in source && source.address) {
+                querySource['address'] = source.address;
             }
         }
-        const customFeeConfig = params.config?.customFee;
-        const autoAllocResult = computeAutoAllocation({
-            amountIn: params.amountIn,
-            destinationChain: destChain.chain,
-            chainBalances,
-            useForwarder,
-            ...customFeeConfig ? {
-                customFee: customFeeConfig
-            } : {}
+        return getBalances$1({
+            token: params.token,
+            sources: querySource,
+            networkType
         });
-        const normalizedAutoAllocations = await normalizeAutoAllocations(autoAllocResult, sourcesArray);
-        const intents = buildAutoAllocatedBurnIntents(normalizedAutoAllocations, destChain, recipientAddress, params.token, params.config?.customFee);
-        const allocations = [
-            ...normalizedAutoAllocations.user,
-            ...normalizedAutoAllocations.devFee,
-            ...normalizedAutoAllocations.circleFee
-        ];
+    }));
+    const chainBalances = [];
+    for(let i = 0; i < balanceResults.length; i++){
+        const breakdowns = balanceResults[i]?.breakdown[0]?.breakdown ?? [];
+        for (const b of breakdowns){
+            chainBalances.push({
+                chain: b.chain,
+                confirmedBalance: b.confirmedBalance,
+                sourceIndex: i
+            });
+        }
+    }
+    return chainBalances;
+}
+/**
+ * Build auto-allocated normalised allocations and burn intents from
+ * pre-fetched balances.
+ *
+ * Performs no balance API call, so it can be re-invoked with
+ * `gasFeeOverrides` (the real per-chain gas from a prior estimate) to correct
+ * an over-draw without re-querying balances.
+ *
+ * @param params - Spend parameters (source(s), token, optional custom fee).
+ * @param destChain - Resolved destination chain with Gateway v1 config.
+ * @param recipientAddress - Resolved recipient address on the destination chain.
+ * @param useForwarder - Whether the Forwarding Service path is active.
+ * @param amountIn - Human-readable USDC amount to allocate.
+ * @param chainBalances - Confirmed balances from {@link fetchChainBalances}.
+ * @param gasFeeOverrides - Optional real per-chain gas fees to reserve.
+ * @returns Normalised allocations and burn intents for the estimate/transfer API.
+ */ async function buildAutoAllocatedFromBalances(params, destChain, recipientAddress, useForwarder, amountIn, chainBalances, gasFeeOverrides) {
+    const rawSources = Array.isArray(params.from) ? params.from : [
+        params.from
+    ];
+    const sourcesArray = rawSources.filter((s)=>s != null);
+    const customFeeConfig = params.config?.customFee;
+    const autoAllocResult = computeAutoAllocation({
+        amountIn,
+        destinationChain: destChain.chain,
+        chainBalances,
+        useForwarder,
+        ...customFeeConfig ? {
+            customFee: customFeeConfig
+        } : {},
+        ...gasFeeOverrides ? {
+            gasFeeOverrides
+        } : {}
+    });
+    const normalizedAutoAllocations = await normalizeAutoAllocations(autoAllocResult, sourcesArray);
+    const intents = buildAutoAllocatedBurnIntents(normalizedAutoAllocations, destChain, recipientAddress, params.token, params.config?.customFee);
+    const allocations = [
+        ...normalizedAutoAllocations.user,
+        ...normalizedAutoAllocations.devFee,
+        ...normalizedAutoAllocations.circleFee
+    ];
+    return {
+        allocations,
+        intents
+    };
+}
+/**
+ * Resolve allocations and burn intents for the spend.
+ *
+ * Auto-allocation (`amountIn`) fetches balances once and returns them so the
+ * caller can detect and correct over-draw without re-querying. Explicit
+ * allocations return no balances (they are user-authoritative).
+ *
+ * @param params - Spend parameters.
+ * @param destChain - Resolved destination chain with Gateway v1 config.
+ * @param recipientAddress - Resolved recipient address.
+ * @param useForwarder - Whether the Forwarding Service path is active.
+ * @returns Allocations, intents, and (auto-allocation only) confirmed balances.
+ */ async function resolveAllocationsAndIntents(params, destChain, recipientAddress, useForwarder) {
+    if (params.amountIn) {
+        const chainBalances = await fetchChainBalances(params, destChain);
+        const { allocations, intents } = await buildAutoAllocatedFromBalances(params, destChain, recipientAddress, useForwarder, params.amountIn, chainBalances);
         return {
             allocations,
-            intents
+            intents,
+            chainBalances
         };
     }
     const allocations = await normalizeAllocations(params);
@@ -41601,6 +42958,148 @@ const FORWARDER_POLL_TIMEOUT_MS = 300_000;
         forwardingFee: undefined
     };
 }
+/** Sum confirmed balances (atomic USDC) per source chain. */ function computeAvailablePerChain(chainBalances) {
+    const available = new Map();
+    for (const b of chainBalances){
+        const atomic = parseUnits(b.confirmedBalance, USDC_DECIMALS$1);
+        available.set(b.chain, (available.get(b.chain) ?? 0n) + atomic);
+    }
+    return available;
+}
+/**
+ * Detect source chains whose required draw (value + maxFee across their
+ * intents) exceeds the confirmed balance — the condition the Gateway API
+ * rejects with `BALANCE_INSUFFICIENT_TOKEN` at `/v1/transfer`.
+ *
+ * Both sides are summed per chain (see {@link sumRequiredPerChain} and
+ * {@link computeAvailablePerChain}), so detection is exact for the common
+ * single-depositor-per-chain wallet. When multiple depositors hold USDC on the
+ * same chain, a chain-level surplus can mask a per-depositor shortfall; the
+ * API's own per-depositor `9001` remains the backstop in that case.
+ */ function findOverdrawnChains(estimatedIntents, allocations, chainBalances) {
+    const required = sumRequiredPerChain(estimatedIntents, allocations);
+    const available = computeAvailablePerChain(chainBalances);
+    const overdrawn = [];
+    for (const [chain, req] of required){
+        const avail = available.get(chain) ?? 0n;
+        if (req > avail) {
+            overdrawn.push({
+                chain,
+                required: req,
+                available: avail
+            });
+        }
+    }
+    return overdrawn;
+}
+/**
+ * Build a descriptive KitError for an auto-allocation gas shortfall that
+ * survives the corrective re-allocation, naming the per-chain gap so the
+ * caller sees the real cause instead of the opaque API 9001 rejection.
+ */ function createAutoAllocationGasError(overdrawn, cause) {
+    const detail = overdrawn.map((o)=>`${String(o.chain)} needs ${formatUnits(o.required.toString(), USDC_DECIMALS$1)} USDC ` + `(transfer + gas) but only ${formatUnits(o.available.toString(), USDC_DECIMALS$1)} USDC is available`).join('; ');
+    return new KitError({
+        ...BalanceError.INSUFFICIENT_GAS,
+        recoverability: 'FATAL',
+        message: `Insufficient USDC to cover the transfer amount plus Gateway gas fees: ${detail}. ` + `Reduce the amount or add USDC on the affected chain(s).`,
+        ...cause === undefined ? {} : {
+            cause: {
+                trace: {
+                    cause
+                }
+            }
+        }
+    });
+}
+/**
+ * Validate allocations against the network/forwarder rules, call the estimate
+ * API, and return the estimated intents with any forwarding fee.
+ *
+ * @param allocations - Normalised allocations for the estimate.
+ * @param intents - Burn intents to estimate.
+ * @param destChain - Resolved destination chain with Gateway v1 config.
+ * @param useForwarder - Whether the Forwarding Service path is active.
+ * @returns Estimated intents (with real maxFee) and optional forwarding fee.
+ */ async function validateAndEstimate(allocations, intents, destChain, useForwarder) {
+    assertNetworkCompatibility(allocations, destChain);
+    if (useForwarder) {
+        assertForwarderRouteSupport(destChain, allocations);
+    }
+    const apiBaseUrl = getGatewayApiBaseUrl(destChain.isTestnet);
+    const estimateBody = buildEstimateRequestBody(intents);
+    const { entries, forwardingFee } = await fetchEstimate(apiBaseUrl, estimateBody, useForwarder, allocations);
+    const estimatedIntents = parseEstimateResponse(entries, intents);
+    return {
+        estimatedIntents,
+        forwardingFee
+    };
+}
+/**
+ * Fold newly-observed per-chain gas into the accumulated overrides, keeping the
+ * higher fee per chain so a chain a later pass reveals is never under-reserved.
+ */ function mergeGasFeeOverrides(base, next) {
+    const merged = new Map(base);
+    for (const [chain, fee] of next){
+        const prev = merged.get(chain);
+        if (prev === undefined || fee > prev) {
+            merged.set(chain, fee);
+        }
+    }
+    return merged;
+}
+/**
+ * Maximum corrective re-allocation passes before failing fast. One pass fixes
+ * the common case; a second/third covers a chain that a spill only introduces
+ * after gas is reserved. Bounds the worst case at this many extra estimate
+ * round-trips (only ever reached when the balance genuinely falls short).
+ */ const MAX_CORRECTION_PASSES = 3;
+/**
+ * Correct an auto-allocation over-draw: reserve the estimate's real per-chain
+ * gas, re-allocate from the same balances, and re-estimate — repeating up to
+ * {@link MAX_CORRECTION_PASSES} times, accumulating the real gas each pass
+ * reveals.
+ *
+ * One pass fixes the common case, where the over-drawn chain was already in the
+ * first estimate. A further pass covers a chain that a spill only introduces
+ * once gas is reserved on the destination: that chain isn't in the first
+ * estimate, so its real gas is unknown until it appears, and its first
+ * re-allocation falls back to the static reserve. Each pass folds the newly
+ * revealed gas into the overrides (see {@link mergeGasFeeOverrides}) so the
+ * next pass reserves it too. Per-chain gas is ~amount-independent, so once
+ * every drawn chain's real gas is known the allocation converges.
+ *
+ * When the shortfall is genuine — the re-allocation can't cover the amount, or
+ * the passes are exhausted while still over-drawn — throws a gas-specific
+ * {@link KitError} instead of submitting a doomed transfer.
+ */ async function correctOverdraw(opts) {
+    let overrides = deriveGasFeeOverrides(opts.estimatedIntents, opts.allocations);
+    let overdrawn = opts.overdrawn;
+    for(let pass = 0; pass < MAX_CORRECTION_PASSES; pass++){
+        let corrected;
+        try {
+            corrected = await buildAutoAllocatedFromBalances(opts.params, opts.destChain, opts.recipientAddress, opts.useForwarder, opts.amountIn, opts.chainBalances, overrides);
+        } catch (err) {
+            // Re-allocating with the real gas reserved can't cover the amount →
+            // surface a gas-specific error instead of the opaque API rejection.
+            if (err instanceof KitError && err.code === BalanceError.INSUFFICIENT_TOKEN.code) {
+                throw createAutoAllocationGasError(overdrawn, err);
+            }
+            throw err;
+        }
+        const { estimatedIntents, forwardingFee } = await validateAndEstimate(corrected.allocations, corrected.intents, opts.destChain, opts.useForwarder);
+        const stillOverdrawn = findOverdrawnChains(estimatedIntents, corrected.allocations, opts.chainBalances);
+        if (stillOverdrawn.length === 0) {
+            return {
+                allocations: corrected.allocations,
+                estimatedIntents,
+                forwardingFee
+            };
+        }
+        overdrawn = stillOverdrawn;
+        overrides = mergeGasFeeOverrides(overrides, deriveGasFeeOverrides(estimatedIntents, corrected.allocations));
+    }
+    throw createAutoAllocationGasError(overdrawn);
+}
 /**
  * Validate allocations, call the estimate API, and return estimated intents.
  *
@@ -41608,6 +43107,14 @@ const FORWARDER_POLL_TIMEOUT_MS = 300_000;
  * path. Handles forwarder route validation, network compatibility, and the
  * estimate API call.
  *
+ * For auto-allocation (`amountIn`), the greedy allocator reserves a static
+ * per-chain gas fee that can undershoot the API's real fee, draining a source
+ * (typically the destination chain) below `value + maxFee` and triggering a
+ * `BALANCE_INSUFFICIENT_TOKEN` rejection. When the first estimate reveals such
+ * an over-draw, a bounded corrective re-allocation reserves the real gas and
+ * re-estimates until it converges or fails fast (see {@link correctOverdraw}).
+ * Explicit allocations are user-authoritative and never re-allocated.
+ *
  * @param params - Spend parameters.
  * @param destChain - Resolved destination chain with Gateway v1 config.
  * @param recipientAddress - Resolved recipient address.
@@ -41617,15 +43124,24 @@ const FORWARDER_POLL_TIMEOUT_MS = 300_000;
     if (useForwarder) {
         assertForwarderRouteSupport(destChain);
     }
-    const { allocations, intents } = await resolveAllocationsAndIntents(params, destChain, recipientAddress, useForwarder);
-    assertNetworkCompatibility(allocations, destChain);
-    if (useForwarder) {
-        assertForwarderRouteSupport(destChain, allocations);
+    const { allocations, intents, chainBalances } = await resolveAllocationsAndIntents(params, destChain, recipientAddress, useForwarder);
+    const { estimatedIntents, forwardingFee } = await validateAndEstimate(allocations, intents, destChain, useForwarder);
+    if (params.amountIn && chainBalances) {
+        const overdrawn = findOverdrawnChains(estimatedIntents, allocations, chainBalances);
+        if (overdrawn.length > 0) {
+            return correctOverdraw({
+                params,
+                destChain,
+                recipientAddress,
+                useForwarder,
+                amountIn: params.amountIn,
+                chainBalances,
+                estimatedIntents,
+                allocations,
+                overdrawn
+            });
+        }
     }
-    const apiBaseUrl = getGatewayApiBaseUrl(destChain.isTestnet);
-    const estimateBody = buildEstimateRequestBody(intents);
-    const { entries, forwardingFee } = await fetchEstimate(apiBaseUrl, estimateBody, useForwarder, allocations);
-    const estimatedIntents = parseEstimateResponse(entries, intents);
     return {
         allocations,
         estimatedIntents,
@@ -42533,8 +44049,10 @@ const assertCustomFeePolicySymbol = Symbol('assertCustomFeePolicy');
  *
  * - `computeFee` — required function that receives resolved spend params
  *   and returns a fee as a string (or `Promise<string>`).
- * - `resolveFeeRecipientAddress` — required function that returns a
- *   recipient address as a string (or `Promise<string>`).
+ * - `resolveFeeRecipientAddress` — optional function that returns a
+ *   recipient address as a string (or `Promise<string>`). Omit it when
+ *   using `setFeeRecipients()`'s declarative map instead — a policy
+ *   with neither throws at spend time.
  *
  * @example
  * ```ts
@@ -42547,7 +44065,7 @@ const assertCustomFeePolicySymbol = Symbol('assertCustomFeePolicy');
  * ```
  */ const customFeePolicySchema = z.object({
     computeFee: z.function().returns(z.string().or(z.promise(z.string()))),
-    resolveFeeRecipientAddress: z.function().returns(z.string().or(z.promise(z.string())))
+    resolveFeeRecipientAddress: z.function().returns(z.string().or(z.promise(z.string()))).optional()
 }).strict();
 /**
  * Assert that the provided value conforms to {@link CustomFeePolicy}.
@@ -42569,6 +44087,71 @@ const assertCustomFeePolicySymbol = Symbol('assertCustomFeePolicy');
     validateWithStateTracking(config, customFeePolicySchema, 'UnifiedBalanceKit custom fee policy', assertCustomFeePolicySymbol);
 }
 
+const assertFeeRecipientsConfigSymbol = Symbol('assertFeeRecipientsConfig');
+/**
+ * Schema for validating {@link FeeRecipientsConfig}.
+ *
+ * Requires at least one of `evm`/`solana`, non-empty string values for
+ * whichever keys are present, and — mirroring the `depositAccount`
+ * validation in `deposit/validate/assertions` — an address format that
+ * matches the given chain type (EVM hex vs Solana base58).
+ *
+ * @example
+ * ```ts
+ * const config = {
+ *   evm: '0x1234567890123456789012345678901234567890',
+ *   solana: '9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM',
+ * }
+ * const result = feeRecipientsConfigSchema.safeParse(config)
+ * // result.success === true
+ * ```
+ */ const feeRecipientsConfigSchema = z.object({
+    evm: z.string().min(1, 'Fee recipient address is required.').optional(),
+    solana: z.string().min(1, 'Fee recipient address is required.').optional()
+}).strict().refine((config)=>Object.keys(config).length > 0, {
+    message: 'At least one fee recipient (evm or solana) is required.'
+}).superRefine((config, ctx)=>{
+    for (const type of Object.keys(config)){
+        const address = config[type];
+        if (address == null) continue;
+        // `{ name: type, type }` is a placeholder chain identifier — only
+        // `.type` is checked by these two helpers today, `.name` is unused.
+        // No real ChainDefinition exists here, since validation runs before
+        // a destination chain is resolved.
+        if (!isValidAddressForChain(address, {
+            name: type,
+            type
+        })) {
+            const { expectedAddressFormat } = extractChainInfo({
+                name: type,
+                type
+            });
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: [
+                    type
+                ],
+                message: `Invalid ${type} address "${address}". Expected ${expectedAddressFormat}.`
+            });
+        }
+    }
+});
+/**
+ * Assert that the provided value conforms to {@link FeeRecipientsConfig}.
+ *
+ * Throws a validation error with annotated paths if the configuration is
+ * malformed.
+ *
+ * @param config - The fee recipients map to validate.
+ *
+ * @example
+ * ```ts
+ * assertFeeRecipientsConfig({ evm: '0x1234567890123456789012345678901234567890' })
+ * ```
+ */ function assertFeeRecipientsConfig(config) {
+    validateWithStateTracking(config, feeRecipientsConfigSchema, 'UnifiedBalanceKit fee recipients config', assertFeeRecipientsConfigSymbol);
+}
+
 function sameChain(a, b) {
     return a.chain !== undefined && a.chain === b.chain;
 }
@@ -43549,6 +45132,105 @@ function assertSourceAccountAddresses(from) {
         config: params.config
     };
 }
+/**
+ * Tracks, per {@link CustomFeePolicy} instance, which chain types have
+ * already triggered the "falling back to resolveFeeRecipientAddress"
+ * warning, so repeated `spend()`/`estimateSpend()` calls (e.g. live
+ * quoting) warn once per (policy, chain type) pair rather than on every
+ * call.
+ */ const warnedFeeRecipientFallbacks = new WeakMap();
+/**
+ * Invoke `resolveFeeRecipientAddress` and validate its return value has a
+ * plausible address format for `destChain`, the same check
+ * `setFeeRecipients()` already applies at config time. Unlike the map,
+ * the callback's return value can't be validated ahead of time, so it's
+ * checked here instead — a malformed value throws immediately rather
+ * than silently becoming the fee recipient.
+ *
+ * @internal
+ */ async function resolveFeeRecipientFromCallback(callback, destChain, params) {
+    const address = await callback(destChain, params);
+    if (!isValidAddressForChain(address, destChain)) {
+        throw new KitError({
+            ...InputError.VALIDATION_FAILED,
+            recoverability: 'FATAL',
+            message: `resolveFeeRecipientAddress returned an invalid address ` + `"${address}" for chain type "${destChain.type}" ` + `(resolved destination: ${destChain.name}).`
+        });
+    }
+    return address;
+}
+/**
+ * Resolve the single fee recipient address for a spend.
+ *
+ * Every fee burn intent in a spend mints to the same destination
+ * chain regardless of which source chain(s) funded it, so exactly one
+ * recipient address — valid on `destChain` — is ever needed.
+ *
+ * `feeRecipients` (set via `setFeeRecipients`) takes priority over the
+ * policy's `resolveFeeRecipientAddress` callback for any chain type it
+ * has an entry for, since it's a direct lookup and doesn't require
+ * invoking developer code. For a chain type `feeRecipients` doesn't
+ * cover, it falls back to `resolveFeeRecipientAddress` if one is
+ * configured — a warning is logged once per (policy, chain type) pair
+ * so the fallback isn't a silent surprise, without spamming repeated
+ * `estimateSpend()` calls used for live quoting. Throws if neither
+ * resolves `destChain`'s type, or if `resolveFeeRecipientAddress`
+ * resolves it to a malformed address (see
+ * {@link resolveFeeRecipientFromCallback}).
+ *
+ * @internal
+ */ async function resolveFeeRecipient(destChain, policy, feeRecipients, params) {
+    if (feeRecipients) {
+        // `destChain.type` is `@core/chains`' broader `ChainType` union;
+        // `FeeRecipientChainType` is the narrower subset this map supports
+        // today. A type not present as a key simply has no configured
+        // recipient, which is handled below.
+        const type = destChain.type;
+        const recipientAddress = feeRecipients[type];
+        if (recipientAddress) {
+            return recipientAddress;
+        }
+        if (policy.resolveFeeRecipientAddress) {
+            const warnedTypes = warnedFeeRecipientFallbacks.get(policy);
+            if (!warnedTypes?.has(type)) {
+                warnedFeeRecipientFallbacks.set(policy, (warnedTypes ?? new Set()).add(type));
+                console.warn(`setFeeRecipients() is configured but has no entry for chain ` + `type "${type}" — falling back to customFeePolicy.` + `resolveFeeRecipientAddress for this chain type. Add a ` + `"${type}" entry to setFeeRecipients() to avoid this fallback.`);
+            }
+            return resolveFeeRecipientFromCallback(policy.resolveFeeRecipientAddress, destChain, params);
+        }
+        throw new KitError({
+            ...InputError.VALIDATION_FAILED,
+            recoverability: 'FATAL',
+            message: `No fee recipient configured for chain type "${type}" ` + `(resolved destination: ${destChain.name}). Call setFeeRecipients() ` + `with an entry for "${type}", or provide resolveFeeRecipientAddress ` + `on the custom fee policy.`
+        });
+    }
+    if (!policy.resolveFeeRecipientAddress) {
+        throw new KitError({
+            ...InputError.VALIDATION_FAILED,
+            recoverability: 'FATAL',
+            message: 'No fee recipient configured — call setFeeRecipients() or provide ' + 'resolveFeeRecipientAddress on the custom fee policy.'
+        });
+    }
+    return resolveFeeRecipientFromCallback(policy.resolveFeeRecipientAddress, destChain, params);
+}
+/**
+ * Guard against a common misconfiguration: a developer sets the
+ * declarative `feeRecipients` map expecting it alone to drive fee
+ * collection, but no fee is ever charged without a `computeFee` from
+ * `customFeePolicy` to determine the amount. Without this check that
+ * misconfiguration fails silently — no fee is charged and no error is
+ * raised.
+ *
+ * @internal
+ */ function assertFeeRecipientsHasPolicy(feeRecipients) {
+    if (feeRecipients) {
+        throw new KitError({
+            ...InputError.VALIDATION_FAILED,
+            recoverability: 'FATAL',
+            message: 'setFeeRecipients() is configured but no developer fee will be ' + 'charged: setCustomFeePolicy() must also be set to provide ' + 'computeFee, which determines the fee amount. Call ' + 'setCustomFeePolicy(), or remove setFeeRecipients() if no ' + 'developer fee is intended.'
+        });
+    }
+}
 /**
  * Apply a {@link CustomFeePolicy} to an adapter-only spend.
  *
@@ -43557,15 +45239,20 @@ function assertSourceAccountAddresses(from) {
  * `config.customFee` so the provider sees it.
  *
  * @internal
- */ async function mergeCustomFeePolicyForAdapterOnly(params, policy) {
-    if (params.config?.customFee || !policy) {
+ */ async function mergeCustomFeePolicyForAdapterOnly(params, policy, feeRecipients) {
+    if (params.config?.customFee) {
+        return params;
+    }
+    if (!policy) {
+        assertFeeRecipientsHasPolicy(feeRecipients);
         return params;
     }
     const destChain = resolveChainIdentifier(params.to.chain);
-    const [feeValue, recipientAddress] = await Promise.all([
-        policy.computeFee(params),
-        policy.resolveFeeRecipientAddress(destChain, params)
-    ]);
+    // Resolve the recipient before computing the fee: a KitError here
+    // (missing/unresolvable recipient) shouldn't be preceded by an
+    // otherwise-wasted computeFee call, which may be a network request.
+    const recipientAddress = await resolveFeeRecipient(destChain, policy, feeRecipients, params);
+    const feeValue = await policy.computeFee(params);
     return {
         ...params,
         config: {
@@ -43595,18 +45282,35 @@ function assertSourceAccountAddresses(from) {
         });
     }
 }
-async function mergeCustomFeeConfig(resolved, policy) {
-    if (resolved.config?.customFee || !policy) {
+async function mergeCustomFeeConfig(resolved, policy, feeRecipients) {
+    if (resolved.config?.customFee) {
         return resolved;
     }
-    const firstSourceChain = resolved.from[0]?.allocations[0]?.chain;
-    if (!firstSourceChain) {
+    if (!policy) {
+        assertFeeRecipientsHasPolicy(feeRecipients);
         return resolved;
     }
-    const [feeValue, recipientAddress] = await Promise.all([
-        policy.computeFee(resolved),
-        policy.resolveFeeRecipientAddress(firstSourceChain, resolved)
-    ]);
+    // Skip fee resolution when there's no source chain to spend from at
+    // all. This state can't arise from validated input today — the
+    // caller re-checks and throws "No source chain found" right after
+    // this returns — but skipping here isn't dead code: verified that
+    // removing it lets a degenerate zero-allocation resolved value reach
+    // computeFee/assertDeveloperFeeWithinBounds first, which throws a
+    // misleading "Developer fee must be less than the total spend
+    // amount" (0 >= 0 total allocation) instead of the correct "No
+    // source chain found" error — or, for a real developer computeFee
+    // that assumes a non-empty allocation, an uncaught raw exception
+    // instead of any KitError at all. This guard exists to guarantee the
+    // caller's clear error is what actually surfaces, not for
+    // correctness.
+    if (collectSourceChains(resolved).length === 0) {
+        return resolved;
+    }
+    // Resolve the recipient before computing the fee: a KitError here
+    // (missing/unresolvable recipient) shouldn't be preceded by an
+    // otherwise-wasted computeFee call, which may be a network request.
+    const recipientAddress = await resolveFeeRecipient(resolved.to.chain, policy, feeRecipients, resolved);
+    const feeValue = await policy.computeFee(resolved);
     return {
         ...resolved,
         config: {
@@ -43662,14 +45366,14 @@ async function mergeCustomFeeConfig(resolved, policy) {
     }
     const destChain = resolveChainIdentifier(params.to.chain);
     if (!hasExplicitAllocations(params.from)) {
-        const merged = await mergeCustomFeePolicyForAdapterOnly(params, context.customFeePolicy);
+        const merged = await mergeCustomFeePolicyForAdapterOnly(params, context.customFeePolicy, context.feeRecipients);
         assertDeveloperFeeWithinAmount(merged);
         const provider = findProviderForChain(context, normalizeToken(merged.token), destChain);
         return callSpend(provider, toProviderAdapterOnlyParams(merged));
     }
     const resolved = await resolveSpendParams(params);
     assertSpendNetworkCompatibility(resolved);
-    const withFee = await mergeCustomFeeConfig(resolved, context.customFeePolicy);
+    const withFee = await mergeCustomFeeConfig(resolved, context.customFeePolicy, context.feeRecipients);
     assertDeveloperFeeWithinBounds(withFee);
     const sourceChains = collectSourceChains(withFee);
     if (sourceChains.length === 0) {
@@ -43709,14 +45413,14 @@ async function mergeCustomFeeConfig(resolved, policy) {
     assertSpendParams(params);
     const destChain = resolveChainIdentifier(params.to.chain);
     if (!hasExplicitAllocations(params.from)) {
-        const merged = await mergeCustomFeePolicyForAdapterOnly(params, context.customFeePolicy);
+        const merged = await mergeCustomFeePolicyForAdapterOnly(params, context.customFeePolicy, context.feeRecipients);
         assertDeveloperFeeWithinAmount(merged);
         const provider = findProviderForChain(context, normalizeToken(merged.token), destChain);
         return provider.estimateSpend(toProviderAdapterOnlyParams(merged));
     }
     const resolved = await resolveSpendParams(params);
     assertSpendNetworkCompatibility(resolved);
-    const withFee = await mergeCustomFeeConfig(resolved, context.customFeePolicy);
+    const withFee = await mergeCustomFeeConfig(resolved, context.customFeePolicy, context.feeRecipients);
     assertDeveloperFeeWithinBounds(withFee);
     const sourceChains = collectSourceChains(withFee);
     if (sourceChains.length === 0) {
@@ -44691,6 +46395,46 @@ const removeFundParamsSchema = z.object({
    */ removeCustomFeePolicy() {
         delete this.context.customFeePolicy;
     }
+    /**
+   * Set a declarative fee recipient map, keyed by chain type. Once set,
+   * `spend()`/`estimateSpend()` resolve the fee recipient by looking up
+   * the spend's destination chain type in this map — taking priority
+   * over `customFeePolicy`'s `resolveFeeRecipientAddress` callback.
+   *
+   * @remarks
+   * This only controls which address a fee is sent to — it does not by
+   * itself cause any fee to be charged. You still need
+   * {@link UnifiedBalanceKit.setCustomFeePolicy}'s `computeFee` to
+   * determine the fee amount; calling `setFeeRecipients` without ever
+   * calling `setCustomFeePolicy` throws at spend time (there is no
+   * `computeFee` to determine an amount).
+   *
+   * @param config - Fee recipient addresses keyed by chain type (e.g.
+   *   `{ evm: '0x...', solana: 'Sol...' }`). Provide entries for every
+   *   chain type you expect to spend to; spending to a chain type with
+   *   no matching entry throws before any fee collection is attempted.
+   *
+   * @example
+   * ```typescript
+   * kit.setFeeRecipients({
+   *   evm: '0x1234567890123456789012345678901234567890',
+   *   solana: '9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM',
+   * })
+   * ```
+   */ setFeeRecipients(config) {
+        assertFeeRecipientsConfig(config);
+        this.context.feeRecipients = config;
+    }
+    /**
+   * Remove the declarative fee recipient map for the kit.
+   *
+   * @example
+   * ```typescript
+   * kit.removeFeeRecipients()
+   * ```
+   */ removeFeeRecipients() {
+        delete this.context.feeRecipients;
+    }
 }
 
 // Auto-register this kit for user agent tracking
@@ -45017,6 +46761,45 @@ registerKit(`${pkg.name}/${pkg.version}`);
    */ removeCustomFeePolicy() {
         this.kit.removeCustomFeePolicy();
     }
+    /**
+   * Set a declarative fee recipient map, keyed by chain type.
+   *
+   * Once set, `spend()`/`estimateSpend()` resolve the fee recipient by
+   * looking up the spend's destination chain type in this map — taking
+   * priority over `customFeePolicy`'s `resolveFeeRecipientAddress`
+   * callback.
+   *
+   * @remarks
+   * This only controls which address a fee is sent to — it does not by
+   * itself cause any fee to be charged. You still need
+   * `setCustomFeePolicy`'s `computeFee` to determine the fee amount;
+   * calling `setFeeRecipients` without ever calling `setCustomFeePolicy`
+   * throws at spend time (there is no `computeFee` to determine an
+   * amount).
+   *
+   * @param config - Fee recipient addresses keyed by chain type (e.g.
+   *   `{ evm: '0x...', solana: 'Sol...' }`).
+   *
+   * @example
+   * ```typescript
+   * kit.unifiedBalance.setFeeRecipients({
+   *   evm: '0x1234567890123456789012345678901234567890',
+   *   solana: '9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM',
+   * })
+   * ```
+   */ setFeeRecipients(config) {
+        this.kit.setFeeRecipients(config);
+    }
+    /**
+   * Remove the declarative fee recipient map.
+   *
+   * @example
+   * ```typescript
+   * kit.unifiedBalance.removeFeeRecipients()
+   * ```
+   */ removeFeeRecipients() {
+        this.kit.removeFeeRecipients();
+    }
 }
 
 /**
@@ -45168,7 +46951,8 @@ registerKit(`${pkg.name}/${pkg.version}`);
             waitForCrossChainDeposit: async (params)=>waitForCrossChainDeposit(this.context, params),
             getDepositQuote: async (params)=>getDepositQuote(this.context, params),
             getWithdrawalQuote: async (params)=>getWithdrawalQuote(this.context, params),
-            getClaimRewardsQuote: async (params)=>getClaimRewardsQuote(this.context, params)
+            getClaimRewardsQuote: async (params)=>getClaimRewardsQuote(this.context, params),
+            retry: async (error)=>retry(this.context, error)
         };
     }
     /**
@@ -45427,7 +47211,8 @@ registerKit(`${pkg.name}/${pkg.version}`);
    * or `'NOT_FOUND'`). Use {@link AppKit.waitForSwap} if you'd rather
    * not write the polling loop yourself.
    *
-   * @param params - `txHash`, `chainIn`, optional `chainOut`, and `kitKey`.
+   * @param params - `txHash` and `chainIn`, plus optional `chainOut` and
+   *   `kitKey`.
    * @returns A snapshot of the swap's status at the time of the call.
    * @throws \{KitError\} If `chainIn` or `chainOut` is malformed.
    *
@@ -45541,7 +47326,7 @@ registerKit(`${pkg.name}/${pkg.version}`);
    * translates to the chain's native sentinel address — `0xEee…` for EVM,
    * `1111…` for Solana — before querying the service.
    *
-   * @param params - `chain`, optional `tokens`, and `kitKey`.
+   * @param params - `chain`, plus optional `tokens` and `kitKey`.
    * @returns A nested map of `[chain][address] → { priceUSD, fetchedAt }`.
    * @throws \{KitError\} If `chain` is malformed, `tokens` exceeds 100
    *         entries, or any entry is neither a registered symbol nor a
@@ -45605,6 +47390,10 @@ registerKit(`${pkg.name}/${pkg.version}`);
             this.context.actions.bridge[action] ??= [];
             this.context.actions.bridge[action].push(typedHandler);
         }
+        if (action === '*' || action.startsWith('earn.')) {
+            this.context.actions.earn[action] ??= [];
+            this.context.actions.earn[action].push(typedHandler);
+        }
     }
     off(actionOrWildCard, handler) {
         const action = actionOrWildCard;
@@ -45614,16 +47403,32 @@ registerKit(`${pkg.name}/${pkg.version}`);
             this.unifiedBalance.off(ubAction, typedHandler);
         }
         if (action === '*' || action.startsWith('bridge.')) {
-            const handlers = this.context.actions.bridge[action];
-            if (handlers) {
-                const index = handlers.indexOf(typedHandler);
-                if (index !== -1) {
-                    handlers.splice(index, 1);
-                    if (handlers.length === 0) {
-                        Reflect.deleteProperty(this.context.actions.bridge, action);
-                    }
-                }
-            }
+            this.removeStoredActionHandler(this.context.actions.bridge, action, typedHandler);
+        }
+        if (action === '*' || action.startsWith('earn.')) {
+            this.removeStoredActionHandler(this.context.actions.earn, action, typedHandler);
+        }
+    }
+    /**
+   * Remove one handler from a deferred AppKit action bucket.
+   *
+   * Deletes the action key when its handler list becomes empty.
+   *
+   * @param handlers - Action bucket to update (`bridge` or `earn`)
+   * @param action - Stored action key, including namespace or `*`
+   * @param handler - Handler reference previously passed to {@link on}
+   */ removeStoredActionHandler(handlers, action, handler) {
+        const actionHandlers = handlers[action];
+        if (!actionHandlers) {
+            return;
+        }
+        const index = actionHandlers.indexOf(handler);
+        if (index === -1) {
+            return;
+        }
+        actionHandlers.splice(index, 1);
+        if (actionHandlers.length === 0) {
+            Reflect.deleteProperty(handlers, action);
         }
     }
 }