@circle-fin/app-kit 1.8.1 → 1.10.0

package/unifiedBalance.mjs

@@ -2237,6 +2237,8 @@ class KitError extends Error {
     Blockchain["Celo_Alfajores_Testnet"] = "Celo_Alfajores_Testnet";
     Blockchain["Codex"] = "Codex";
     Blockchain["Codex_Testnet"] = "Codex_Testnet";
+    Blockchain["Cronos"] = "Cronos";
+    Blockchain["Cronos_Testnet"] = "Cronos_Testnet";
     Blockchain["Edge"] = "Edge";
     Blockchain["Edge_Testnet"] = "Edge_Testnet";
     Blockchain["Ethereum"] = "Ethereum";
@@ -2319,6 +2321,7 @@ var BridgeChain;
     BridgeChain["Avalanche"] = "Avalanche";
     BridgeChain["Base"] = "Base";
     BridgeChain["Codex"] = "Codex";
+    BridgeChain["Cronos"] = "Cronos";
     BridgeChain["Edge"] = "Edge";
     BridgeChain["Ethereum"] = "Ethereum";
     BridgeChain["HyperEVM"] = "HyperEVM";
@@ -2343,6 +2346,7 @@ var BridgeChain;
     BridgeChain["Avalanche_Fuji"] = "Avalanche_Fuji";
     BridgeChain["Base_Sepolia"] = "Base_Sepolia";
     BridgeChain["Codex_Testnet"] = "Codex_Testnet";
+    BridgeChain["Cronos_Testnet"] = "Cronos_Testnet";
     BridgeChain["Edge_Testnet"] = "Edge_Testnet";
     BridgeChain["Ethereum_Sepolia"] = "Ethereum_Sepolia";
     BridgeChain["HyperEVM_Testnet"] = "HyperEVM_Testnet";
@@ -2864,7 +2868,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: {
@@ -3398,6 +3405,96 @@ var EarnChain;
     }
 });
 
+/**
+ * Cronos Mainnet chain definition
+ * @remarks
+ * This represents the official production network for the Cronos blockchain.
+ * Cronos is an EVM-compatible blockchain.
+ */ const Cronos = defineChain({
+    type: 'evm',
+    chain: Blockchain.Cronos,
+    name: 'Cronos',
+    title: 'Cronos Mainnet',
+    nativeCurrency: {
+        name: 'Cronos',
+        symbol: 'CRO',
+        decimals: 18
+    },
+    chainId: 25,
+    isTestnet: false,
+    explorerUrl: 'https://cronoscan.com/tx/{hash}',
+    rpcEndpoints: [
+        'https://evm.cronos.org'
+    ],
+    eurcAddress: '0xA6dE01a2d62C6B5f3525d768f34d276652C554c8',
+    usdcAddress: '0x3D7F2C478aAfdB65542BCB44bCeeC05849999d2D',
+    usdtAddress: null,
+    cctp: {
+        domain: 32,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
+                confirmations: 1,
+                fastConfirmations: 1
+            }
+        },
+        forwarderSupported: {
+            source: false,
+            destination: false
+        }
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_MAINNET
+    }
+});
+
+/**
+ * Cronos Testnet chain definition
+ * @remarks
+ * This represents the official test network for the Cronos blockchain.
+ * Cronos is an EVM-compatible blockchain.
+ */ const CronosTestnet = defineChain({
+    type: 'evm',
+    chain: Blockchain.Cronos_Testnet,
+    name: 'Cronos Testnet',
+    title: 'Cronos Testnet',
+    nativeCurrency: {
+        name: 'CRO',
+        symbol: 'tCRO',
+        decimals: 18
+    },
+    chainId: 338,
+    isTestnet: true,
+    explorerUrl: 'https://explorer.cronos.org/testnet/tx/{hash}',
+    rpcEndpoints: [
+        'https://evm-t3.cronos.org'
+    ],
+    eurcAddress: '0x31f7538adb53cF16350e6B0c89d03D91b7D12c46',
+    usdcAddress: '0xEb33dc5fac03833e132593659e1dE7256aB59794',
+    usdtAddress: null,
+    cctp: {
+        domain: 32,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
+                confirmations: 1,
+                fastConfirmations: 1
+            }
+        },
+        forwarderSupported: {
+            source: false,
+            destination: false
+        }
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_TESTNET
+    }
+});
+
 /**
  * Edge Mainnet chain definition
  * @remarks
@@ -5749,6 +5846,8 @@ var Chains = /*#__PURE__*/Object.freeze({
   CeloAlfajoresTestnet: CeloAlfajoresTestnet,
   Codex: Codex,
   CodexTestnet: CodexTestnet,
+  Cronos: Cronos,
+  CronosTestnet: CronosTestnet,
   Edge: Edge,
   EdgeTestnet: EdgeTestnet,
   Ethereum: Ethereum,
@@ -5856,7 +5955,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
 ;
 /**
@@ -7722,6 +7824,7 @@ function parseOrThrow(value, schema, context) {
         [Blockchain.Base]: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
         [Blockchain.Celo]: '0xcebA9300f2b948710d2653dD7B07f33A8B32118C',
         [Blockchain.Codex]: '0xd996633a415985DBd7D6D12f4A4343E31f5037cf',
+        [Blockchain.Cronos]: '0x3D7F2C478aAfdB65542BCB44bCeeC05849999d2D',
         [Blockchain.Edge]: '0x98d2919b9A214E6Fa5384AC81E6864bA686Ad74c',
         [Blockchain.Ethereum]: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
         [Blockchain.Hedera]: '0.0.456858',
@@ -7755,6 +7858,7 @@ function parseOrThrow(value, schema, context) {
         [Blockchain.Avalanche_Fuji]: '0x5425890298aed601595a70AB815c96711a31Bc65',
         [Blockchain.Base_Sepolia]: '0x036CbD53842c5426634e7929541eC2318f3dCF7e',
         [Blockchain.Codex_Testnet]: '0x6d7f141b6819C2c9CC2f818e6ad549E7Ca090F8f',
+        [Blockchain.Cronos_Testnet]: '0xEb33dc5fac03833e132593659e1dE7256aB59794',
         [Blockchain.Edge_Testnet]: '0x2d9F7CAD728051AA35Ecdc472a14cf8cDF5CFD6B',
         [Blockchain.Ethereum_Sepolia]: '0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238',
         [Blockchain.Hedera_Testnet]: '0.0.429274',
@@ -7827,6 +7931,7 @@ function parseOrThrow(value, schema, context) {
         // =========================================================================
         [Blockchain.Avalanche]: '0xc891EB4cbdEFf6e073e859e987815Ed1505c2ACD',
         [Blockchain.Base]: '0x60a3E35Cc302bFA44Cb288Bc5a4F316Fdb1adb42',
+        [Blockchain.Cronos]: '0xA6dE01a2d62C6B5f3525d768f34d276652C554c8',
         [Blockchain.Ethereum]: '0x1aBaEA1f7C830bD89Acc67eC4af516284b1bC33c',
         [Blockchain.Solana]: 'HzwqbKZw8HxMN6bF2yFZNrht3c2iXXzpKcFu7uBEDKtr',
         [Blockchain.World_Chain]: '0x1C60ba0A0eD1019e8Eb035E6daF4155A5cE2380B',
@@ -7835,6 +7940,7 @@ function parseOrThrow(value, schema, context) {
         // =========================================================================
         [Blockchain.Arc_Testnet]: '0x89B50855Aa3bE2F677cD6303Cec089B5F319D72a',
         [Blockchain.Base_Sepolia]: '0x808456652fdb597867f38412077A9182bf77359F',
+        [Blockchain.Cronos_Testnet]: '0x31f7538adb53cF16350e6B0c89d03D91b7D12c46',
         [Blockchain.Ethereum_Sepolia]: '0x08210F9170F89Ab7658F0B5E3fF39b0E03C594D4'
     }
 };
@@ -8639,7 +8745,7 @@ function parseOrThrow(value, schema, context) {
 }
 
 var name = "@circle-fin/unified-balance-kit";
-var version = "1.2.1";
+var version = "1.3.0";
 var pkg = {
 	name: name,
 	version: version};
@@ -16275,29 +16381,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) {
@@ -16329,14 +16439,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.
@@ -16435,7 +16545,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
@@ -16443,7 +16553,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));
     }
@@ -16452,7 +16562,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));
     }
@@ -16551,10 +16661,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.
@@ -16678,6 +16790,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.
@@ -16702,7 +16841,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;
@@ -16710,18 +16848,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 {
@@ -16785,6 +16923,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.
@@ -17039,69 +17262,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);
@@ -17143,6 +17424,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.
  *
@@ -17150,6 +17573,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.
@@ -17159,15 +17590,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,
@@ -18075,8 +18515,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
@@ -18089,7 +18531,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}.
@@ -18111,6 +18553,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;
 }
@@ -19091,6 +19598,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.
  *
@@ -19099,15 +19705,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: {
@@ -19137,18 +19748,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: {
@@ -19204,14 +19832,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) {
@@ -19251,14 +19879,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) {
@@ -20233,6 +20861,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
@@ -20559,6 +21227,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 };