@circle-fin/app-kit 1.9.0 → 1.11.0

package/unifiedBalance.mjs

@@ -16,6 +16,17 @@
  * limitations under the License.
  */
 
+// Buffer polyfill setup - executes before any other code
+// Ensures globalThis.Buffer is available for Solana libraries
+import { Buffer } from 'buffer';
+if (typeof globalThis !== 'undefined' && typeof globalThis.Buffer === 'undefined') {
+    globalThis.Buffer = Buffer;
+}
+if (typeof window !== 'undefined' && typeof window.Buffer === 'undefined') {
+    window.Buffer = Buffer;
+}
+
+
 import { z } from 'zod';
 import { PublicKey } from '@solana/web3.js';
 import 'bn.js';
@@ -41,6 +52,27 @@ import { getAddress } from '@ethersproject/address';
  * }
  * ```
  */ const isNodeEnvironment = ()=>typeof process !== 'undefined' && typeof process.versions === 'object' && typeof process.versions.node === 'string';
+/**
+ * Return the SDK User-Agent request header only when running in Node.js.
+ *
+ * Browsers forbid manually setting `User-Agent`, and a custom fallback header
+ * can trigger CORS preflight. Non-Node server runtimes also omit this optional
+ * attribution header because they cannot set it reliably.
+ *
+ * @returns A User-Agent header in Node.js, or an empty object otherwise.
+ *
+ * @example
+ * ```typescript
+ * import { getNodeUserAgentHeader } from '@core/utils'
+ *
+ * const headers = {
+ *   'Content-Type': 'application/json',
+ *   ...getNodeUserAgentHeader(),
+ * }
+ * ```
+ */ const getNodeUserAgentHeader = ()=>isNodeEnvironment() ? {
+        'User-Agent': getUserAgent()
+    } : {};
 /**
  * Detect the runtime environment and return a shortened identifier.
  *
@@ -2868,7 +2900,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: {
@@ -5952,7 +5987,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
 ;
 /**
@@ -7074,13 +7112,12 @@ const swapTokenEnumSchema = z.enum([
         headers: {
             ...DEFAULT_CONFIG.headers,
             ...config.headers ?? {},
-            // In browser environments, directly setting the 'User-Agent' or similar headers is restricted and may be ignored or cause errors.
-            // This is why we use the 'X-User-Agent' header instead.
-            ...typeof window === 'undefined' ? {
-                'User-Agent': getUserAgent()
-            } : {
-                'X-User-Agent': getUserAgent()
-            }
+            // Browsers forbid setting a user-agent request header, and the custom
+            // fallback header the SDK used instead trips CORS preflight against the
+            // Circle APIs (it isn't in their `Access-Control-Allow-Headers`),
+            // blocking the request. So send the SDK user agent only in Node;
+            // browsers omit it entirely.
+            ...getNodeUserAgentHeader()
         }
     };
     let lastError;
@@ -8352,6 +8389,7 @@ function parseOrThrow(value, schema, context) {
     if (payload.tokenIn !== undefined) safe['tokenIn'] = payload.tokenIn;
     if (payload.tokenOut !== undefined) safe['tokenOut'] = payload.tokenOut;
     if (payload.txHash !== undefined) safe['txHash'] = payload.txHash;
+    if (payload.correlationId !== undefined) safe['correlationId'] = payload.correlationId;
     if (payload.errorDetails !== undefined) {
         const errorDetails = {
             ...payload.errorDetails.errorCode !== undefined && {
@@ -8422,18 +8460,15 @@ function parseOrThrow(value, schema, context) {
         timeoutHandle.unref();
     }
     try {
-        const isNode = isNodeEnvironment();
-        const userAgent = getUserAgent();
         await fetch(getLogsUrl(), {
             method: 'POST',
             headers: {
                 'Content-Type': 'application/json',
-                // Browser restricts setting User-Agent; use X-User-Agent instead.
-                ...isNode ? {
-                    'User-Agent': userAgent
-                } : {
-                    'X-User-Agent': userAgent
-                }
+                // Browsers forbid setting a user-agent request header, and the custom
+                // fallback header the SDK used instead trips CORS preflight (it isn't
+                // in the telemetry endpoint's `Access-Control-Allow-Headers`), so send
+                // it only in Node; browsers omit it entirely.
+                ...getNodeUserAgentHeader()
             },
             body: JSON.stringify(toSafePayload(payload)),
             signal: controller.signal
@@ -8646,7 +8681,7 @@ function parseOrThrow(value, schema, context) {
         // discards the stack trace, nested `cause`, and any custom Error
         // properties — exactly the context an on-call needs when a
         // resolver-closure regression triggers this path.
-        console.warn(`[stablecoin-kits telemetry] dropped error event '${eventType}':`, cause);
+        console.warn(`[stablecoin-kits telemetry] dropped event '${eventType}':`, cause);
     } catch  {
     // console.warn itself throwing is the user's environment; nothing more we
     // can do without risking the original operation error.
@@ -8662,7 +8697,9 @@ function parseOrThrow(value, schema, context) {
         sdkVersion: config.sdkVersion,
         eventType,
         timestamp: new Date().toISOString(),
-        errorDetails,
+        ...errorDetails !== undefined && {
+            errorDetails
+        },
         clientContext: buildClientContext(),
         ...context?.sourceChain != null && {
             sourceChain: context.sourceChain
@@ -8678,6 +8715,9 @@ function parseOrThrow(value, schema, context) {
         },
         ...context?.txHash != null && {
             txHash: context.txHash
+        },
+        ...context?.correlationId != null && {
+            correlationId: context.correlationId
         }
     };
 }
@@ -8739,7 +8779,7 @@ function parseOrThrow(value, schema, context) {
 }
 
 var name = "@circle-fin/unified-balance-kit";
-var version = "1.2.2";
+var version = "1.3.1";
 var pkg = {
 	name: name,
 	version: version};
@@ -16375,29 +16415,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) {
@@ -16429,14 +16473,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.
@@ -16535,7 +16579,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
@@ -16543,7 +16587,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));
     }
@@ -16552,7 +16596,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));
     }
@@ -16651,10 +16695,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.
@@ -16778,6 +16824,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.
@@ -16802,7 +16875,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;
@@ -16810,18 +16882,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 {
@@ -16885,6 +16957,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.
@@ -17139,69 +17296,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);
@@ -17243,6 +17458,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.
  *
@@ -17250,6 +17607,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.
@@ -17259,15 +17624,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,
@@ -18175,8 +18549,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
@@ -18189,7 +18565,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}.
@@ -18211,6 +18587,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;
 }
@@ -19191,6 +19632,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.
  *
@@ -19199,15 +19739,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: {
@@ -19237,18 +19782,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: {
@@ -19304,14 +19866,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) {
@@ -19351,14 +19913,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) {
@@ -19895,7 +20457,11 @@ const removeFundParamsSchema = z.object({
 // Remove Fund Operations
 // ---------------------------------------------------------------------------
 /**
- * Kick off a delayed fund removal from an account.
+ * Kick off a delayed recovery fund removal from an account.
+ *
+ * Use `initiateRemoveFund` only as a trustless fallback when the normal spend
+ * flow is unavailable. For day-to-day movement out of a Unified Balance, use
+ * `spend`.
  *
  * Validates `from` and `amount`, resolves the chain and token via
  * {@link resolveRemoveFundParams}, selects the matching provider, then calls
@@ -19932,7 +20498,10 @@ const removeFundParamsSchema = z.object({
     return provider.initiateRemoveFund(resolved);
 }
 /**
- * Complete a fund removal once the 7-day activation period has passed.
+ * Complete a recovery fund removal once the 7-day withdrawal delay has passed.
+ *
+ * Use `removeFund` only as a trustless fallback when the normal spend flow is
+ * unavailable. For day-to-day movement out of a Unified Balance, use `spend`.
  *
  * Validates `from`, resolves the chain and token via
  * {@link resolveRemoveFundParams}, selects the matching provider, then calls
@@ -20021,13 +20590,18 @@ const removeFundParamsSchema = z.object({
 /** SDK name used in telemetry payloads. */ const SDK_NAME = resolveKitSdkName(pkg.name);
 /**
  * A high-level class-based interface for cross-chain USDC deposits,
- * spending, balance queries, delegation management, and withdrawals.
+ * spending, balance queries, delegation management, and recovery fund removals.
  *
  * UnifiedBalanceKit provides a familiar class-based API for developers who
  * prefer traditional object-oriented patterns. The class maintains an
  * internal context and provides methods that delegate to the standalone
  * operation functions exported by this package.
  *
+ * Use `spend` for normal movement out of a Unified Balance. `removeFund` is a
+ * trustless recovery path for situations where the normal spend flow is
+ * unavailable, and it requires a 7-day withdrawal delay before funds can be
+ * removed.
+ *
  * @remarks
  * For functional usage, import and use the operations directly:
  * ```typescript
@@ -20248,7 +20822,11 @@ const removeFundParamsSchema = z.object({
         });
     }
     /**
-   * Kick off a delayed fund removal from an account.
+   * Kick off a delayed recovery fund removal from an account.
+   *
+   * Use this only as a trustless fallback when the normal spend flow is
+   * unavailable. For day-to-day movement out of a Unified Balance, use
+   * `spend`.
    *
    * @param params - The account owner's adapter context, amount, and
    *   optional token type.
@@ -20262,7 +20840,12 @@ const removeFundParamsSchema = z.object({
         });
     }
     /**
-   * Complete a fund removal once the activation period has passed.
+   * Complete a recovery fund removal once the 7-day withdrawal delay has
+   * passed.
+   *
+   * Use this only as a trustless fallback when the normal spend flow is
+   * unavailable. For day-to-day movement out of a Unified Balance, use
+   * `spend`.
    *
    * @param params - The account owner context matching the original
    *   fund removal initiation.
@@ -20333,6 +20916,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
@@ -20349,6 +20972,11 @@ registerKit(`${pkg.name}/${pkg.version}`);
  * Internally holds a persistent {@link UnifiedBalanceKit} instance so that
  * event dispatchers and custom fee policies are preserved across calls.
  *
+ * Use {@link AppKitUnifiedBalance.spend} for normal movement out of a Unified
+ * Balance. {@link AppKitUnifiedBalance.removeFund} is a trustless recovery path
+ * for situations where the normal spend flow is unavailable, and it requires a
+ * 7-day withdrawal delay after {@link AppKitUnifiedBalance.initiateRemoveFund}.
+ *
  * @example
  * ```typescript
  * import { AppKit } from '@circle-fin/app-kit'
@@ -20560,7 +21188,12 @@ registerKit(`${pkg.name}/${pkg.version}`);
         return this.kit.removeDelegate(params);
     }
     /**
-   * Kick off a delayed fund removal from an account.
+   * Initiate a trustless recovery removal from an account.
+   *
+   * Use `spend` for normal movement out of a Unified Balance. `removeFund` is a
+   * recovery path for situations where the normal spend flow is unavailable.
+   * Calling this method starts the 7-day withdrawal delay before the removal can
+   * be completed.
    *
    * @param params - The account owner's adapter context, amount, and token.
    * @returns Promise resolving to the initiation details.
@@ -20579,11 +21212,16 @@ registerKit(`${pkg.name}/${pkg.version}`);
         return this.kit.initiateRemoveFund(params);
     }
     /**
-   * Complete a fund removal once the activation period has passed.
+   * Complete a trustless recovery removal after the withdrawal delay.
+   *
+   * Use `spend` for normal movement out of a Unified Balance. `removeFund` is a
+   * recovery path for situations where the normal spend flow is unavailable.
+   * Both EVM and Solana removals require a 7-day withdrawal delay after
+   * `initiateRemoveFund` before funds can be removed.
    *
    * @param params - The account owner context matching the original initiation.
    * @returns Promise resolving to the fund removal details.
-   * @throws {KitError} If the activation period has not elapsed or the
+   * @throws {KitError} If the withdrawal delay has not elapsed or the
    *   on-chain transaction fails.
    *
    * @example
@@ -20659,6 +21297,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();
+    }
 }
 
 export { AppKitUnifiedBalance };