@circle-fin/app-kit 1.12.1 → 1.13.0

package/index.mjs

@@ -30,9 +30,9 @@ if (typeof window !== 'undefined' && typeof window.Buffer === 'undefined') {
 import { z } from 'zod';
 import pino from 'pino';
 import { parseUnits as parseUnits$1, formatUnits as formatUnits$1 } from '@ethersproject/units';
-import { hexlify, hexZeroPad } from '@ethersproject/bytes';
+import { hexlify, hexZeroPad, concat } from '@ethersproject/bytes';
 import '@ethersproject/abi';
-import { getAddress } from '@ethersproject/address';
+import { getAddress, isAddress } from '@ethersproject/address';
 import bs58 from 'bs58';
 import { PublicKey } from '@solana/web3.js';
 import 'bn.js';
@@ -4064,6 +4064,8 @@ function getOptionalString(value) {
     Blockchain["Optimism_Sepolia"] = "Optimism_Sepolia";
     Blockchain["Pharos"] = "Pharos";
     Blockchain["Pharos_Testnet"] = "Pharos_Testnet";
+    Blockchain["Plasma"] = "Plasma";
+    Blockchain["Plasma_Testnet"] = "Plasma_Testnet";
     Blockchain["Polkadot_Asset_Hub"] = "Polkadot_Asset_Hub";
     Blockchain["Polkadot_Westmint"] = "Polkadot_Westmint";
     Blockchain["Plume"] = "Plume";
@@ -4133,6 +4135,7 @@ var BridgeChain;
     BridgeChain["Morph"] = "Morph";
     BridgeChain["Optimism"] = "Optimism";
     BridgeChain["Pharos"] = "Pharos";
+    BridgeChain["Plasma"] = "Plasma";
     BridgeChain["Plume"] = "Plume";
     BridgeChain["Polygon"] = "Polygon";
     BridgeChain["Sei"] = "Sei";
@@ -4159,6 +4162,7 @@ var BridgeChain;
     BridgeChain["Morph_Testnet"] = "Morph_Testnet";
     BridgeChain["Optimism_Sepolia"] = "Optimism_Sepolia";
     BridgeChain["Pharos_Testnet"] = "Pharos_Testnet";
+    BridgeChain["Plasma_Testnet"] = "Plasma_Testnet";
     BridgeChain["Plume_Testnet"] = "Plume_Testnet";
     BridgeChain["Polygon_Amoy_Testnet"] = "Polygon_Amoy_Testnet";
     BridgeChain["Sei_Testnet"] = "Sei_Testnet";
@@ -4616,6 +4620,8 @@ var EarnChain;
  * This program handles minting operations for Gateway transactions
  * on Solana devnet.
  */ const GATEWAY_MINTER_SOLANA_DEVNET = 'GATEmKK2ECL1brEngQZWCgMWPbvrEYqsV6u29dAaHavr';
+/** TokenMessengerWithFees address shared by enabled EVM mainnet sources. */ const TOKEN_MESSENGER_WITH_FEES_EVM_MAINNET = '0x71f54F818671cD0D7ea140Da213e5C8b5C92a408';
+/** TokenMessengerWithFees address shared by enabled EVM testnet sources. */ const TOKEN_MESSENGER_WITH_FEES_EVM_TESTNET = '0x8745D906D67C346E5eb1aEEED38Eb87F34DF0C0A';
 /**
  * Circle's fee recipient address for EVM chains.
  *
@@ -4663,6 +4669,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_TESTNET,
                 messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
                 confirmations: 1,
                 fastConfirmations: 1
@@ -4730,6 +4737,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_MAINNET,
                 messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
                 confirmations: 65,
                 fastConfirmations: 1
@@ -4794,6 +4802,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_TESTNET,
                 messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
                 confirmations: 65,
                 fastConfirmations: 1
@@ -4858,6 +4867,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_MAINNET,
                 messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
                 confirmations: 1,
                 fastConfirmations: 1
@@ -4919,6 +4929,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x8fe6b999dc680ccfdd5bf7eb0974218be2542daa',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_TESTNET,
                 messageTransmitter: '0xe737e5cebeeba77efe34d4aa090756590b1ce275',
                 confirmations: 1,
                 fastConfirmations: 1
@@ -4986,6 +4997,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_MAINNET,
                 messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
                 confirmations: 65,
                 fastConfirmations: 1
@@ -5050,6 +5062,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x8fe6b999dc680ccfdd5bf7eb0974218be2542daa',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_TESTNET,
                 messageTransmitter: '0xe737e5cebeeba77efe34d4aa090756590b1ce275',
                 confirmations: 65,
                 fastConfirmations: 1
@@ -5160,6 +5173,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_MAINNET,
                 messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
                 confirmations: 65,
                 fastConfirmations: 1
@@ -5204,6 +5218,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x8fe6b999dc680ccfdd5bf7eb0974218be2542daa',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_TESTNET,
                 messageTransmitter: '0xe737e5cebeeba77efe34d4aa090756590b1ce275',
                 confirmations: 65,
                 fastConfirmations: 1
@@ -5435,6 +5450,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_MAINNET,
                 messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
                 confirmations: 65,
                 fastConfirmations: 2
@@ -5499,6 +5515,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x8fe6b999dc680ccfdd5bf7eb0974218be2542daa',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_TESTNET,
                 messageTransmitter: '0xe737e5cebeeba77efe34d4aa090756590b1ce275',
                 confirmations: 65,
                 fastConfirmations: 2
@@ -5609,6 +5626,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_MAINNET,
                 messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
                 confirmations: 1,
                 fastConfirmations: 1
@@ -5668,6 +5686,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_TESTNET,
                 messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
                 confirmations: 1,
                 fastConfirmations: 1
@@ -5822,6 +5841,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_MAINNET,
                 messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
                 confirmations: 65,
                 fastConfirmations: 1
@@ -5869,6 +5889,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_TESTNET,
                 messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
                 confirmations: 65,
                 fastConfirmations: 1
@@ -5913,6 +5934,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_MAINNET,
                 messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
                 confirmations: 1,
                 fastConfirmations: 1
@@ -5958,6 +5980,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x8fe6b999dc680ccfdd5bf7eb0974218be2542daa',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_TESTNET,
                 messageTransmitter: '0xe737e5cebeeba77efe34d4aa090756590b1ce275',
                 confirmations: 1,
                 fastConfirmations: 1
@@ -6004,6 +6027,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_MAINNET,
                 messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
                 confirmations: 1,
                 fastConfirmations: 1
@@ -6317,6 +6341,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_MAINNET,
                 messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
                 confirmations: 65,
                 fastConfirmations: 1
@@ -6381,6 +6406,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x8fe6b999dc680ccfdd5bf7eb0974218be2542daa',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_TESTNET,
                 messageTransmitter: '0xe737e5cebeeba77efe34d4aa090756590b1ce275',
                 confirmations: 65,
                 fastConfirmations: 1
@@ -6501,6 +6527,98 @@ var EarnChain;
     }
 });
 
+/**
+ * Plasma Mainnet chain definition
+ * @remarks
+ * This represents the official production network for the Plasma blockchain.
+ * Plasma is an EVM-equivalent Layer 1 blockchain purpose-built for global
+ * stablecoin payments, with deterministic BFT finality (PlasmaBFT/Fast-HotStuff).
+ */ const Plasma = defineChain({
+    type: 'evm',
+    chain: Blockchain.Plasma,
+    name: 'Plasma',
+    title: 'Plasma Mainnet',
+    nativeCurrency: {
+        name: 'Plasma',
+        symbol: 'XPL',
+        decimals: 18
+    },
+    chainId: 9745,
+    isTestnet: false,
+    explorerUrl: 'https://plasmascan.to/tx/{hash}',
+    rpcEndpoints: [
+        'https://rpc.plasma.to'
+    ],
+    eurcAddress: '0x3EE196E78d4d4248b849B8E1C7F44C5457FAFD2C',
+    usdcAddress: '0x2d661C89D812261039AF9764eceaAee884f5F67F',
+    usdtAddress: null,
+    cctp: {
+        domain: 33,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
+                confirmations: 3,
+                fastConfirmations: 1
+            }
+        },
+        forwarderSupported: {
+            source: false,
+            destination: false
+        }
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_MAINNET
+    }
+});
+
+/**
+ * Plasma Testnet chain definition
+ * @remarks
+ * This represents the official test network for the Plasma blockchain.
+ * Plasma is an EVM-equivalent Layer 1 blockchain purpose-built for global
+ * stablecoin payments, with deterministic BFT finality (PlasmaBFT/Fast-HotStuff).
+ */ const PlasmaTestnet = defineChain({
+    type: 'evm',
+    chain: Blockchain.Plasma_Testnet,
+    name: 'Plasma Testnet',
+    title: 'Plasma Testnet',
+    nativeCurrency: {
+        name: 'Plasma',
+        symbol: 'XPL',
+        decimals: 18
+    },
+    chainId: 9746,
+    isTestnet: true,
+    explorerUrl: 'https://testnet.plasmascan.to/tx/{hash}',
+    rpcEndpoints: [
+        'https://testnet-rpc.plasma.to'
+    ],
+    eurcAddress: '0x98AfA0F93Dd993B736399f9074eDcEBD1985A330',
+    usdcAddress: '0xE67Fb267022cBA8064Dd388CC2FED724F3120D9D',
+    usdtAddress: null,
+    cctp: {
+        domain: 33,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
+                confirmations: 3,
+                fastConfirmations: 1
+            }
+        },
+        forwarderSupported: {
+            source: false,
+            destination: false
+        }
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_TESTNET
+    }
+});
+
 /**
  * Plume Mainnet chain definition
  * @remarks
@@ -6532,6 +6650,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_MAINNET,
                 messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
                 confirmations: 65,
                 fastConfirmations: 1
@@ -6578,6 +6697,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_TESTNET,
                 messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
                 confirmations: 65,
                 fastConfirmations: 1
@@ -6679,6 +6799,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_MAINNET,
                 messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
                 confirmations: 33,
                 fastConfirmations: 13
@@ -6744,6 +6865,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_TESTNET,
                 messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
                 confirmations: 33,
                 fastConfirmations: 13
@@ -6803,6 +6925,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_MAINNET,
                 messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
                 confirmations: 1,
                 fastConfirmations: 1
@@ -6862,6 +6985,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_TESTNET,
                 messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
                 confirmations: 1,
                 fastConfirmations: 1
@@ -6919,6 +7043,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_MAINNET,
                 messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
                 confirmations: 1,
                 fastConfirmations: 1
@@ -6977,6 +7102,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_TESTNET,
                 messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
                 confirmations: 1,
                 fastConfirmations: 1
@@ -7292,6 +7418,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_MAINNET,
                 messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
                 confirmations: 65,
                 fastConfirmations: 1
@@ -7356,6 +7483,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_TESTNET,
                 messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
                 confirmations: 65,
                 fastConfirmations: 1
@@ -7413,6 +7541,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cF5d',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_MAINNET,
                 messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
                 confirmations: 65,
                 fastConfirmations: 1
@@ -7472,6 +7601,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x8fe6b999dc680ccfdd5bf7eb0974218be2542daa',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_TESTNET,
                 messageTransmitter: '0xe737e5cebeeba77efe34d4aa090756590b1ce275',
                 confirmations: 65,
                 fastConfirmations: 1
@@ -7532,6 +7662,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_MAINNET,
                 messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
                 confirmations: 3,
                 fastConfirmations: 3
@@ -7577,6 +7708,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_TESTNET,
                 messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
                 confirmations: 3,
                 fastConfirmations: 1
@@ -7787,6 +7919,8 @@ var Chains = /*#__PURE__*/Object.freeze({
   OptimismSepolia: OptimismSepolia,
   Pharos: Pharos,
   PharosTestnet: PharosTestnet,
+  Plasma: Plasma,
+  PlasmaTestnet: PlasmaTestnet,
   Plume: Plume,
   PlumeTestnet: PlumeTestnet,
   PolkadotAssetHub: PolkadotAssetHub,
@@ -7836,6 +7970,34 @@ var Chains = /*#__PURE__*/Object.freeze({
     return chain.cctp?.contracts.v2 !== undefined;
 }
 
+/**
+ * Check whether a chain supports source-paid ("receive-exact") CCTP v2 fees.
+ *
+ * A chain supports source-paid fees when its CCTP v2 configuration carries a
+ * deployed `TokenMessengerWithFees` wrapper address. Bridge Kit routes
+ * `feePayment: 'source'` transfers through this wrapper via
+ * `depositForBurnWithHookAndFees`, so a chain without the wrapper cannot be a
+ * source for receive-exact bridging.
+ *
+ * @param chain - The chain definition to check.
+ * @returns `true` when the chain has a `tokenMessengerWithFees` wrapper
+ *   configured, `false` otherwise.
+ *
+ * @example
+ * ```typescript
+ * import { Chains, hasSourceFeeSupport } from '@core/chains'
+ *
+ * hasSourceFeeSupport(Chains.Optimism) // true
+ * hasSourceFeeSupport(Chains.Solana) // false
+ * ```
+ */ function hasSourceFeeSupport(chain) {
+    if (!isCCTPV2Supported(chain)) {
+        return false;
+    }
+    const wrapper = chain.cctp.contracts.v2.tokenMessengerWithFees;
+    return typeof wrapper === 'string' && wrapper.length > 0;
+}
+
 /**
  * Check if a chain supports a specific type of custom smart contract logic.
  *
@@ -10163,6 +10325,7 @@ function parseOrThrow(value, schema, context) {
         [Blockchain.Noble]: 'uusdc',
         [Blockchain.Optimism]: '0x0b2c639c533813f4aa9d7837caf62653d097ff85',
         [Blockchain.Pharos]: '0xC879C018dB60520F4355C26eD1a6D572cdAC1815',
+        [Blockchain.Plasma]: '0x2d661C89D812261039AF9764eceaAee884f5F67F',
         [Blockchain.Plume]: '0x222365EF19F7947e5484218551B56bb3965Aa7aF',
         [Blockchain.Polkadot_Asset_Hub]: '1337',
         [Blockchain.Polygon]: '0x3c499c542cef5e3811e1192ce70d8cc03d5c3359',
@@ -10199,6 +10362,7 @@ function parseOrThrow(value, schema, context) {
         [Blockchain.Noble_Testnet]: 'uusdc',
         [Blockchain.Optimism_Sepolia]: '0x5fd84259d66Cd46123540766Be93DFE6D43130D7',
         [Blockchain.Pharos_Testnet]: '0xcfC8330f4BCAB529c625D12781b1C19466A9Fc8B',
+        [Blockchain.Plasma_Testnet]: '0xE67Fb267022cBA8064Dd388CC2FED724F3120D9D',
         [Blockchain.Plume_Testnet]: '0xcB5f30e335672893c7eb944B374c196392C19D18',
         [Blockchain.Polkadot_Westmint]: '31337',
         [Blockchain.Polygon_Amoy_Testnet]: '0x41e94eb019c0762f9bfcf9fb1e58725bfb0e7582',
@@ -10261,6 +10425,7 @@ function parseOrThrow(value, schema, context) {
         [Blockchain.Base]: '0x60a3E35Cc302bFA44Cb288Bc5a4F316Fdb1adb42',
         [Blockchain.Cronos]: '0xA6dE01a2d62C6B5f3525d768f34d276652C554c8',
         [Blockchain.Ethereum]: '0x1aBaEA1f7C830bD89Acc67eC4af516284b1bC33c',
+        [Blockchain.Plasma]: '0x3EE196E78d4d4248b849B8E1C7F44C5457FAFD2C',
         [Blockchain.Solana]: 'HzwqbKZw8HxMN6bF2yFZNrht3c2iXXzpKcFu7uBEDKtr',
         [Blockchain.World_Chain]: '0x1C60ba0A0eD1019e8Eb035E6daF4155A5cE2380B',
         // =========================================================================
@@ -10269,7 +10434,8 @@ function parseOrThrow(value, schema, context) {
         [Blockchain.Arc_Testnet]: '0x89B50855Aa3bE2F677cD6303Cec089B5F319D72a',
         [Blockchain.Base_Sepolia]: '0x808456652fdb597867f38412077A9182bf77359F',
         [Blockchain.Cronos_Testnet]: '0x31f7538adb53cF16350e6B0c89d03D91b7D12c46',
-        [Blockchain.Ethereum_Sepolia]: '0x08210F9170F89Ab7658F0B5E3fF39b0E03C594D4'
+        [Blockchain.Ethereum_Sepolia]: '0x08210F9170F89Ab7658F0B5E3fF39b0E03C594D4',
+        [Blockchain.Plasma_Testnet]: '0x98AfA0F93Dd993B736399f9074eDcEBD1985A330'
     }
 };
 
@@ -11222,6 +11388,16 @@ function parseOrThrow(value, schema, context) {
  *
  * Set to 0 when no additional Circle-reserved data is needed.
  */ const CCTP_FORWARD_PAYLOAD_LENGTH = 0;
+/**
+ * Length in bytes of a Solana owner (ed25519 / PDA) public key.
+ */ const SOLANA_PUBKEY_LENGTH = 32;
+/**
+ * Byte length of the Solana ATA-creation forwarding payload appended after the
+ * `cctp-forward` frame: `createAta` (1 byte) + `ataOwner` (32 bytes).
+ *
+ * Circle's Orbit relayer decodes exactly this many bytes; see
+ * {@link buildSolanaAtaForwardingHookData}.
+ */ const SOLANA_ATA_FORWARD_PAYLOAD_LENGTH = 1 + SOLANA_PUBKEY_LENGTH;
 /**
  * Build the hookData bytes for CCTP forwarding.
  *
@@ -11278,6 +11454,108 @@ function buildForwardingHookData() {
     cachedHookDataHex = '0x' + Array.from(buffer).map((b)=>b.toString(16).padStart(2, '0')).join('');
     return cachedHookDataHex;
 }
+/**
+ * Build a `cctp-forward` hookData frame that instructs Circle's Orbit relayer to
+ * create the recipient's Associated Token Account (ATA) before minting on Solana.
+ *
+ * When an EVM→Solana bridge is forwarded, the destination mint targets the
+ * recipient's USDC ATA — which does not exist for a fresh wallet. This frame
+ * tells the relayer to prepend an idempotent `createAssociatedTokenAccount`
+ * instruction (the relayer pays the rent) so the mint always succeeds.
+ *
+ * Unlike {@link buildForwardingHookData} (an empty version-0 frame), this emits
+ * a version-0 frame whose 32-bit `dataLength` is set to
+ * {@link SOLANA_ATA_FORWARD_PAYLOAD_LENGTH} (33), followed by the payload the
+ * relayer decodes:
+ * - Byte 0: `createAta` flag, always `1`
+ * - Bytes 1-32: the recipient's 32-byte Solana owner public key (`ataOwner`)
+ *
+ * @remarks
+ * `ataOwner` is the recipient's *wallet* public key, not the derived ATA. The
+ * relayer re-derives the ATA from `ataOwner` and the USDC mint and requires it
+ * to equal the burn's `mintRecipient`, so callers must pass the same owner used
+ * to derive `mintRecipient`. The all-zero key is reserved as "absent owner" and
+ * is rejected.
+ *
+ * @param ataOwner - The recipient's 32-byte Solana owner public key.
+ * @returns A 0x-prefixed hex string: the 32-byte frame followed by the 33-byte
+ *   Solana ATA payload.
+ * @throws {KitError} If `ataOwner` is not exactly 32 bytes, or is the all-zero
+ *   key (INPUT_VALIDATION_FAILED).
+ *
+ * @example
+ * ```typescript
+ * import { PublicKey } from '@solana/web3.js'
+ * import { buildSolanaAtaForwardingHookData } from '@core/utils'
+ *
+ * const owner = new PublicKey('9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM')
+ * const hookData = buildSolanaAtaForwardingHookData(owner.toBytes())
+ *
+ * // Use with the forwarded depositForBurnWithHook action so the relayer
+ * // creates the recipient ATA before minting.
+ * await adapter.prepareAction('cctp.v2.depositForBurnWithHook', {
+ *   amount: BigInt('1000000'),
+ *   mintRecipient: '0x...',
+ *   maxFee: BigInt('50000'),
+ *   minFinalityThreshold: 1000,
+ *   fromChain: ethereum,
+ *   toChain: solana,
+ *   hookData,
+ * })
+ * ```
+ */ function buildSolanaAtaForwardingHookData(ataOwner) {
+    if (!(ataOwner instanceof Uint8Array) || ataOwner.length !== SOLANA_PUBKEY_LENGTH) {
+        throw createValidationFailedError$1('ataOwner', ataOwner, `Expected a ${String(SOLANA_PUBKEY_LENGTH)}-byte Solana owner public key`);
+    }
+    if (ataOwner.every((byte)=>byte === 0)) {
+        throw createValidationFailedError$1('ataOwner', ataOwner, 'Expected a non-zero Solana owner public key; the all-zero key is reserved as "absent owner"');
+    }
+    // Inner payload: createAta(1) + ataOwner(32).
+    const payload = new Uint8Array(SOLANA_ATA_FORWARD_PAYLOAD_LENGTH);
+    payload[0] = 1 // createAta = true
+    ;
+    payload.set(ataOwner, 1);
+    // 32-byte header: 24-byte magic + uint32 version(0) + uint32 dataLength(33).
+    // The relayer reads dataLength from the v0 frame to slice the inner payload,
+    // so it MUST reflect the appended byte count (unlike the GenericExecutor path).
+    const frame = new Uint8Array(32);
+    frame.set(new TextEncoder().encode(CCTP_FORWARD_MAGIC_PREFIX), 0);
+    const view = new DataView(frame.buffer);
+    view.setUint32(24, CCTP_FORWARD_VERSION, false) // big-endian, 0
+    ;
+    view.setUint32(28, SOLANA_ATA_FORWARD_PAYLOAD_LENGTH, false) // big-endian, 33
+    ;
+    return hexlify(concat([
+        frame,
+        payload
+    ]));
+}
+
+/**
+ * Left-pad a 20-byte EVM address to a 32-byte (`bytes32`) hex string.
+ *
+ * Mirrors viem's `pad(address, size 32)` and CCTP's `mintRecipient`
+ * convention. Solana addresses are already 32 bytes and need no padding.
+ *
+ * @param address - A 0x-prefixed 20-byte EVM address.
+ * @returns The address left-zero-padded to a 0x-prefixed 32-byte hex string.
+ * @throws {KitError} If `address` is not a valid EVM address (INPUT_VALIDATION_FAILED).
+ *
+ * @example
+ * ```typescript
+ * import { padAddressToBytes32 } from '@core/utils'
+ *
+ * padAddressToBytes32('0x75275Aff2D01699D922f045b69ed291311209738')
+ * // '0x00000000000000000000000075275aff2d01699d922f045b69ed291311209738'
+ * ```
+ */ function padAddressToBytes32(address) {
+    if (!isAddress(address)) {
+        throw createValidationFailedError$1('address', address, 'Expected a valid 20-byte EVM address');
+    }
+    // bytes32 is raw bytes, not a checksummed address — emit lowercase so it
+    // matches ABI-decoded output.
+    return hexZeroPad(getAddress(address), 32).toLowerCase();
+}
 
 /**
  * Configuration for {@link retryAsync}.
@@ -11866,7 +12144,7 @@ function resolveOptions(options) {
 }
 
 var name$4 = "@circle-fin/bridge-kit";
-var version$5 = "1.13.0";
+var version$5 = "1.14.0";
 var pkg$5 = {
 	name: name$4,
 	version: version$5};
@@ -12316,7 +12594,7 @@ const READ_ACTION_KEY_SET = new Set(READ_ACTION_KEYS);
  * const result = evmAddressSchema.safeParse(validAddress)
  * console.log(result.success) // true
  * ```
- */ const evmAddressSchema = hexStringSchema.refine((value)=>value.length === 42, 'EVM address must be exactly 42 characters long (0x + 40 hex characters)').transform((value)=>value);
+ */ const evmAddressSchema$1 = hexStringSchema.refine((value)=>value.length === 42, 'EVM address must be exactly 42 characters long (0x + 40 hex characters)').transform((value)=>value);
 /**
  * Schema for validating transaction hashes.
  *
@@ -13005,6 +13283,10 @@ var TransferSpeed;
     token: z.literal('USDC').optional(),
     config: z.object({
         transferSpeed: z.nativeEnum(TransferSpeed).optional(),
+        feePayment: z.enum([
+            'source',
+            'destination'
+        ]).optional(),
         maxFee: z.string().min(1, 'Required').pipe(createDecimalStringValidator({
             allowZero: true,
             regexMessage: MAX_FEE_FORMAT_ERROR_MESSAGE,
@@ -13012,7 +13294,8 @@ var TransferSpeed;
             maxDecimals: 6
         })(z.string())).optional(),
         customFee: customFeeSchema.optional()
-    }).optional()
+    }).optional(),
+    quote: z.string().regex(/^0x([a-fA-F0-9]{2})+$/, 'must be non-empty 0x hex').optional()
 });
 
 /**
@@ -14226,16 +14509,73 @@ var TransferSpeed;
     };
 }
 
+/**
+ * Dispatch a bridge step event through the provider's action dispatcher.
+ *
+ * Constructs the appropriate action payload and dispatches it to any registered
+ * event listeners. Handles type-safe dispatching for different step types.
+ * When provided, traceId from the invocation context is included for end-to-end correlation.
+ *
+ * @param name - The step name (approve, burn, fetchAttestation, or mint).
+ * @param step - The completed bridge step containing transaction details and explorerUrl.
+ * @param provider - The CCTP v2 provider with action dispatcher.
+ * @param invocation - Optional invocation context containing traceId for correlation.
+ *
+ * @example
+ * ```typescript
+ * const step: BridgeStep = {
+ *   name: 'burn',
+ *   state: 'success',
+ *   txHash: '0xabc...',
+ *   explorerUrl: 'https://sepolia.etherscan.io/tx/0xabc...',
+ *   data: { ... }
+ * }
+ * dispatchStepEvent('burn', step, provider, invocationContext)
+ * ```
+ */ function dispatchStepEvent(name, step, provider, invocation) {
+    if (!provider.actionDispatcher) {
+        return;
+    }
+    // Extract traceId from invocation context if provided
+    const traceId = invocation?.traceId;
+    const actionValues = {
+        protocol: 'cctp',
+        version: 'v2',
+        ...traceId !== undefined && {
+            traceId
+        },
+        values: step
+    };
+    switch(name){
+        case 'approve':
+        case 'burn':
+        case 'mint':
+            provider.actionDispatcher.dispatch(name, {
+                ...actionValues,
+                method: name
+            });
+            break;
+        case 'fetchAttestation':
+        case 'reAttest':
+            provider.actionDispatcher.dispatch(name, {
+                ...actionValues,
+                method: name,
+                values: step
+            });
+            break;
+    }
+}
+
 /**
  * Base URL for Circle's IRIS API (mainnet/production).
  *
  * The IRIS API provides attestation services for CCTP cross-chain transfers.
- */ const IRIS_API_BASE_URL = 'https://iris-api.circle.com';
+ */ const IRIS_API_BASE_URL$1 = 'https://iris-api.circle.com';
 /**
  * Base URL for Circle's IRIS API (testnet/sandbox).
  *
  * Used for development and testing on testnet chains.
- */ const IRIS_API_SANDBOX_BASE_URL = 'https://iris-api-sandbox.circle.com';
+ */ const IRIS_API_SANDBOX_BASE_URL$1 = 'https://iris-api-sandbox.circle.com';
 
 /**
  * Type guard to validate the API response structure.
@@ -14278,7 +14618,7 @@ const isFastBurnFeeResponse = (data)=>{
  * @param isTestnet - Whether the request is for a testnet chain
  * @returns The complete API URL
  */ function buildFastBurnFeeUrl(sourceDomain, destinationDomain, isTestnet) {
-    const baseUrl = isTestnet ? IRIS_API_SANDBOX_BASE_URL : IRIS_API_BASE_URL;
+    const baseUrl = isTestnet ? IRIS_API_SANDBOX_BASE_URL$1 : IRIS_API_BASE_URL$1;
     return `${baseUrl}/v2/burn/USDC/fees/${sourceDomain.toString()}/${destinationDomain.toString()}`;
 }
 const FAST_TIER_FINALITY_THRESHOLD = 1000;
@@ -14489,6 +14829,77 @@ const FAST_TIER_FINALITY_THRESHOLD = 1000;
     }
 };
 
+/**
+ * Build the forwarding `hookData` for a forwarded (Orbit-relayed) CCTP v2 burn,
+ * tailored to the destination chain.
+ *
+ * For EVM destinations the recipient already holds ERC-20 USDC directly, so the
+ * empty version-0 `cctp-forward` frame is sufficient. For Solana destinations
+ * USDC is held in an Associated Token Account (ATA) that may not exist for a
+ * fresh wallet, so this emits a frame carrying `createAta` + `ataOwner` that
+ * instructs the relayer to create the recipient ATA (idempotently, at the
+ * relayer's expense) before minting.
+ *
+ * `@solana/web3.js` is imported lazily so EVM-only consumers never load Solana
+ * code, mirroring {@link getMintRecipientAccount}.
+ *
+ * @param chainType - The destination blockchain type ('evm' or 'solana').
+ * @param ownerAddress - The recipient's wallet address on the destination chain
+ *   (base58 for Solana). Must be the same owner used to derive `mintRecipient`.
+ * @returns A 0x-prefixed hookData hex string for the forwarded burn.
+ * @throws {KitError} If `chainType` is neither 'evm' nor 'solana', if
+ *   `@solana/web3.js` cannot be loaded, or if `ownerAddress` is not a valid
+ *   Solana public key (all FATAL).
+ *
+ * @example
+ * ```typescript
+ * import { getForwarderHookData } from './getForwarderHookData'
+ *
+ * // EVM: empty forwarding frame
+ * const evmHook = await getForwarderHookData('evm', '0x742d35Cc...')
+ *
+ * // Solana: frame instructing the relayer to create the recipient ATA
+ * const solanaHook = await getForwarderHookData(
+ *   'solana',
+ *   '9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM',
+ * )
+ * ```
+ */ const getForwarderHookData = async (/** The destination blockchain type - determines the hookData shape */ chainType, /** The recipient's wallet address (hex for EVM, base58 for Solana) */ ownerAddress)=>{
+    if (chainType === 'evm') {
+        // EVM: the recipient holds USDC directly; no ATA setup is needed.
+        return buildForwardingHookData();
+    }
+    // Fail closed: only EVM and Solana forwarding destinations are supported.
+    // Without this guard any future non-EVM chain type would silently fall
+    // through to the Solana path and mis-encode hookData on a money-movement path.
+    if (chainType !== 'solana') {
+        throw new KitError({
+            ...InputError.VALIDATION_FAILED,
+            recoverability: 'FATAL',
+            message: `Forwarded burns are not supported for destination chain type "${chainType}"`
+        });
+    }
+    // Solana: encode the owner so the relayer creates the recipient ATA.
+    // Resolve @solana/web3.js lazily so EVM-only consumers never load Solana code.
+    const { PublicKey } = await import('@solana/web3.js').catch(()=>{
+        throw new KitError({
+            ...InputError.VALIDATION_FAILED,
+            recoverability: 'FATAL',
+            message: 'Failed to load @solana/web3.js. Please ensure it is installed: npm install @solana/web3.js'
+        });
+    });
+    try {
+        const owner = new PublicKey(ownerAddress);
+        return buildSolanaAtaForwardingHookData(owner.toBytes());
+    } catch (error) {
+        throw new KitError({
+            ...InputError.INVALID_ADDRESS,
+            recoverability: 'FATAL',
+            message: `Failed to build Solana forwarder hookData for recipient "${ownerAddress}": ${error instanceof Error ? error.message : String(error)}`
+        });
+    }
+};
+
 /**
  * Validates and converts a fee value to bigint.
  *
@@ -14591,7 +15002,7 @@ const FAST_TIER_FINALITY_THRESHOLD = 1000;
 
 /**
  * The zero address, denoting a native-currency fee in a signed quote.
- */ const ZERO_ADDRESS$1 = '0x0000000000000000000000000000000000000000';
+ */ const ZERO_ADDRESS$2 = '0x0000000000000000000000000000000000000000';
 /**
  * Resolve the fee payment channel for a prepaid-FORWARD burn via `TokenMessengerWithFees`.
  *
@@ -14632,7 +15043,7 @@ const FAST_TIER_FINALITY_THRESHOLD = 1000;
     if (typeof feeTotalAmount !== 'bigint' || feeTotalAmount < 0n) {
         throw createValidationFailedError$1('feeTotalAmount', feeTotalAmount, 'Must be a non-negative bigint');
     }
-    const isNativeFee = feeToken.toLowerCase() === ZERO_ADDRESS$1;
+    const isNativeFee = feeToken.toLowerCase() === ZERO_ADDRESS$2;
     const isBurnTokenFee = !isNativeFee && feeToken.toLowerCase() === burnToken.toLowerCase();
     if (isNativeFee) {
         return {
@@ -14770,7 +15181,7 @@ const FAST_TIER_FINALITY_THRESHOLD = 1000;
  * @param isTestnet - Whether the request is for a testnet chain
  * @returns The complete API URL with forward=true query parameter
  */ function buildForwardingFeeUrl(sourceDomain, destinationDomain, isTestnet) {
-    const baseUrl = isTestnet ? IRIS_API_SANDBOX_BASE_URL : IRIS_API_BASE_URL;
+    const baseUrl = isTestnet ? IRIS_API_SANDBOX_BASE_URL$1 : IRIS_API_BASE_URL$1;
     return `${baseUrl}/v2/burn/USDC/fees/${sourceDomain.toString()}/${destinationDomain.toString()}?forward=true`;
 }
 /**
@@ -15831,7 +16242,7 @@ function hasPendingState(analysis, result) {
  * // => 'https://iris-api-sandbox.circle.com/v2/messages/1?transactionHash=0xdef...'
  * ```
  */ const buildIrisUrl = (sourceDomainId, transactionHash, isTestnet)=>{
-    const baseUrl = isTestnet ? IRIS_API_SANDBOX_BASE_URL : IRIS_API_BASE_URL;
+    const baseUrl = isTestnet ? IRIS_API_SANDBOX_BASE_URL$1 : IRIS_API_BASE_URL$1;
     const url = new URL(`${baseUrl}/v2/messages/${String(sourceDomainId)}`);
     url.searchParams.set('transactionHash', transactionHash);
     return url.toString();
@@ -15999,7 +16410,7 @@ function hasPendingState(analysis, result) {
  * // => 'https://iris-api-sandbox.circle.com/v2/reattest/0xabc'
  * ```
  */ const buildReAttestUrl = (nonce, isTestnet)=>{
-    const baseUrl = isTestnet ? IRIS_API_SANDBOX_BASE_URL : IRIS_API_BASE_URL;
+    const baseUrl = isTestnet ? IRIS_API_SANDBOX_BASE_URL$1 : IRIS_API_BASE_URL$1;
     const url = new URL(`${baseUrl}/v2/reattest/${nonce}`);
     return url.toString();
 };
@@ -16454,7 +16865,8 @@ const assertCCTPv2BridgeParamsSymbol = Symbol('assertCCTPv2BridgeParams');
  * - `destinationChain` — present and supports CCTP v2
  * - source and destination chains must both be testnet or both mainnet
  * - source and destination chains must differ
- * - `executor` — non-empty string
+ * - destination — either `executor`, or both `mintRecipient` and
+ *   `destinationCaller`; not both
  * - `amount` — bigint or non-empty string coercible to bigint
  * - `feeTotalAmount` — bigint or non-empty string coercible to bigint
  * - `feeToken` — valid EVM address (`0x` + 40 hex chars)
@@ -16496,10 +16908,17 @@ const assertCCTPv2BridgeParamsSymbol = Symbol('assertCCTPv2BridgeParams');
     if (source.chain.name === dest.name) {
         throw createUnsupportedRouteError(source.chain.name, dest.name);
     }
-    // executor
+    // Destination: GenericExecutor shorthand or explicit recipient + caller.
     const executor = p['executor'];
-    if (typeof executor !== 'string' || executor === '') {
-        throw createValidationFailedError$1('executor', executor, 'A GenericExecutor address is required (used for both mintRecipient and destinationCaller)');
+    const mintRecipient = p['mintRecipient'];
+    const destinationCaller = p['destinationCaller'];
+    const hasExecutor = typeof executor === 'string' && executor !== '';
+    const hasDirectDestination = typeof mintRecipient === 'string' && mintRecipient !== '' && typeof destinationCaller === 'string' && destinationCaller !== '';
+    if (!hasExecutor && !hasDirectDestination) {
+        throw createValidationFailedError$1('destination', undefined, 'Provide executor, or both mintRecipient and destinationCaller');
+    }
+    if (hasExecutor && hasDirectDestination) {
+        throw createValidationFailedError$1('destination', undefined, 'Provide executor or direct destination fields, not both');
     }
     // amount
     const rawAmount = p['amount'];
@@ -16522,7 +16941,7 @@ const assertCCTPv2BridgeParamsSymbol = Symbol('assertCCTPv2BridgeParams');
         throw createValidationFailedError$1('feeTotalAmount', rawFee, 'Must be a valid integer value coercible to bigint');
     }
     // feeToken
-    if (!evmAddressSchema.safeParse(p['feeToken']).success) {
+    if (!evmAddressSchema$1.safeParse(p['feeToken']).success) {
         throw createValidationFailedError$1('feeToken', p['feeToken'], 'Must be a valid EVM address (use the zero address for a native fee)');
     }
     // claim
@@ -16534,7 +16953,7 @@ const assertCCTPv2BridgeParamsSymbol = Symbol('assertCCTPv2BridgeParams');
     if (!hexStringSchema.safeParse(claim['signedQuote']).success) {
         throw createValidationFailedError$1('claim.signedQuote', claim['signedQuote'], 'Must be a valid hex string starting with 0x');
     }
-    if (!evmAddressSchema.safeParse(claim['refundAddress']).success) {
+    if (!evmAddressSchema$1.safeParse(claim['refundAddress']).success) {
         throw createValidationFailedError$1('claim.refundAddress', claim['refundAddress'], 'Must be a valid EVM address');
     }
     // hookData (optional)
@@ -16916,63 +17335,6 @@ const mockAttestationMessage = {
     });
 }
 
-/**
- * Dispatch a bridge step event through the provider's action dispatcher.
- *
- * Constructs the appropriate action payload and dispatches it to any registered
- * event listeners. Handles type-safe dispatching for different step types.
- * When provided, traceId from the invocation context is included for end-to-end correlation.
- *
- * @param name - The step name (approve, burn, fetchAttestation, or mint).
- * @param step - The completed bridge step containing transaction details and explorerUrl.
- * @param provider - The CCTP v2 provider with action dispatcher.
- * @param invocation - Optional invocation context containing traceId for correlation.
- *
- * @example
- * ```typescript
- * const step: BridgeStep = {
- *   name: 'burn',
- *   state: 'success',
- *   txHash: '0xabc...',
- *   explorerUrl: 'https://sepolia.etherscan.io/tx/0xabc...',
- *   data: { ... }
- * }
- * dispatchStepEvent('burn', step, provider, invocationContext)
- * ```
- */ function dispatchStepEvent(name, step, provider, invocation) {
-    if (!provider.actionDispatcher) {
-        return;
-    }
-    // Extract traceId from invocation context if provided
-    const traceId = invocation?.traceId;
-    const actionValues = {
-        protocol: 'cctp',
-        version: 'v2',
-        ...traceId !== undefined && {
-            traceId
-        },
-        values: step
-    };
-    switch(name){
-        case 'approve':
-        case 'burn':
-        case 'mint':
-            provider.actionDispatcher.dispatch(name, {
-                ...actionValues,
-                method: name
-            });
-            break;
-        case 'fetchAttestation':
-        case 'reAttest':
-            provider.actionDispatcher.dispatch(name, {
-                ...actionValues,
-                method: name,
-                values: step
-            });
-            break;
-    }
-}
-
 /**
  * Check whether the source adapter supports EIP-5792 atomic batching and
  * the consumer has not explicitly opted out via `config.batchTransactions`.
@@ -17219,7 +17581,7 @@ const mockAttestationMessage = {
     return step;
 }
 
-var version$4 = "1.11.0";
+var version$4 = "1.12.0";
 var pkg$4 = {
 	version: version$4};
 
@@ -17925,18 +18287,18 @@ var pkg$4 = {
     }
 }
 
-function isPlainObject(value) {
+function isPlainObject$1(value) {
     if (typeof value !== 'object' || value === null || Array.isArray(value)) {
         return false;
     }
     const prototype = Object.getPrototypeOf(value);
     return prototype === Object.prototype || prototype === null;
 }
-function assertHeadersConfig(headers, field) {
+function assertHeadersConfig$1(headers, field) {
     if (headers === undefined) {
         return;
     }
-    if (!isPlainObject(headers)) {
+    if (!isPlainObject$1(headers)) {
         throw createValidationFailedError$1(field, headers, `${field} must be a plain object with string header values when provided`);
     }
     for (const [name, value] of Object.entries(headers)){
@@ -17946,16 +18308,16 @@ function assertHeadersConfig(headers, field) {
     }
 }
 function assertCCTPV2Config(config) {
-    if (!isPlainObject(config)) {
+    if (!isPlainObject$1(config)) {
         throw createValidationFailedError$1('config', config, 'config must be a plain object when provided');
     }
-    assertHeadersConfig(config['headers'], 'config.headers');
+    assertHeadersConfig$1(config['headers'], 'config.headers');
     const attestation = config['attestation'];
     if (attestation !== undefined) {
-        if (!isPlainObject(attestation)) {
+        if (!isPlainObject$1(attestation)) {
             throw createValidationFailedError$1('config.attestation', attestation, 'config.attestation must be a plain object when provided');
         }
-        assertHeadersConfig(attestation['headers'], 'config.attestation.headers');
+        assertHeadersConfig$1(attestation['headers'], 'config.attestation.headers');
     }
 }
 /**
@@ -18030,6 +18392,34 @@ function assertCCTPV2Config(config) {
         this.config = config;
     }
     /**
+   * Emit a bridge step event through the provider's registered action
+   * dispatcher.
+   *
+   * Kit-level orchestration that drives the burn primitives directly instead
+   * of {@link CCTPV2BridgingProvider.bridge} (for example the receive-exact
+   * source-fee flow) uses this to surface the same `approve`/`burn`/`mint`
+   * events as the standard bridge path. It is a no-op when no dispatcher is
+   * registered.
+   *
+   * @param name - The step name (`approve`, `burn`, `mint`, ...).
+   * @param step - The completed bridge step to broadcast.
+   * @param invocation - Optional invocation context carrying a `traceId` for
+   *   end-to-end correlation.
+   * @returns Nothing.
+   *
+   * @example
+   * ```typescript
+   * const provider = new CCTPV2BridgingProvider()
+   * provider.emitBridgeStep('burn', {
+   *   name: 'burn',
+   *   state: 'success',
+   *   txHash: '0xabc...',
+   * })
+   * ```
+   */ emitBridgeStep(name, step, invocation) {
+        dispatchStepEvent(name, step, this, invocation);
+    }
+    /**
    * Resolves the effective polling configuration for an attestation request.
    *
    * Precedence (lowest to highest): provider `config.attestation`, then the
@@ -18855,8 +19245,11 @@ function assertCCTPV2Config(config) {
         // 2. Forwarder: Does the user want Circle's relayer to handle attestation/mint?
         const useCustomBurn = hasCustomContractSupport(source.chain, 'bridge');
         const useForwarder = destination.useForwarder === true;
-        // Build hookData once if forwarder is enabled (memoized internally)
-        const hookData = useForwarder ? buildForwardingHookData() : undefined;
+        // Build hookData once if forwarder is enabled. EVM destinations get the
+        // empty forwarding frame; Solana destinations get a frame instructing the
+        // relayer to create the recipient's ATA (using the same owner that derived
+        // `mintRecipient`) so the mint succeeds even for a fresh wallet.
+        const hookData = useForwarder ? await getForwarderHookData(destination.chain.type, destinationAddressForMint) : undefined;
         if (useCustomBurn) {
             // Custom burn path: use bridge contract (with or without hook)
             const customBurnParams = {
@@ -18884,13 +19277,14 @@ function assertCCTPV2Config(config) {
     /**
    * Prepare a prepaid-FORWARD burn through the `TokenMessengerWithFees` wrapper.
    *
-   * Builds the source-chain `depositForBurnWithHookAndFees` call for the
-   * GenericExecutor FORWARD path: fees are collected up front on the source chain
-   * against a signed quote, `mintRecipient` and `destinationCaller` are both set to
-   * the GenericExecutor, and the GE `hookData` is passed through unchanged.
+   * Build the source-chain `depositForBurnWithHookAndFees` call. Fees are
+   * collected up front on the source chain against a signed quote. The
+   * destination may use the GenericExecutor shorthand, or an explicit mint
+   * recipient and destination caller for direct forwarding.
    *
-   * This is the low-level on-chain primitive behind the UBK `fastCrossChainDeposit`
-   * and Bridge Kit `bridge({ deposit })` flows. The `hookData` and signed-quote
+   * This is the low-level on-chain primitive behind the Unified Balance Kit
+   * `fastCrossChainDeposit` and the Bridge Kit source-fee
+   * (`feePayment: 'source'`) flow. The `hookData` and signed-quote
    * `claim` are produced elsewhere and passed in here:
    * - `hookData`: `buildForwardingHookDataWithPayload(version,
    *   buildDepositForGenericExecutorPayload(...).hookData)` from `@core/utils`.
@@ -18907,32 +19301,48 @@ function assertCCTPV2Config(config) {
    *   approval covers both; the redundant second approval is skipped.
    *
    * @typeParam TFromAdapterCapabilities - The source adapter's capabilities.
-   * @param params - The burn amount, executor, hookData, signed-quote claim, and fee.
+   * @param params - The burn amount, destination, hook data, signed quote, and fee.
    * @returns The prepared approvals, the prepared burn, and the resolved fee plan.
    * @throws {KitError} If the wallet context is invalid, `destinationChain` does not
-   *   support CCTP v2, the executor is missing, `amount` or `feeTotalAmount` is not
-   *   a bigint or a numeric string coercible to bigint, the hookData lacks a
-   *   `cctp-forward` frame (guaranteed `ForwardFeeWithoutHook`), or the operation
-   *   context cannot be resolved.
+   *   support CCTP v2, the destination fields are missing, `amount` or
+   *   `feeTotalAmount` is not a bigint or a numeric string coercible to bigint,
+   *   the hook data lacks a `cctp-forward` frame (guaranteed
+   *   `ForwardFeeWithoutHook`), or the operation context cannot be resolved.
    *
    * @example
    * ```typescript
+   * import {
+   *   CCTPV2BridgingProvider,
+   *   type BurnWithFeesParams,
+   * } from '@circle-fin/provider-cctp-v2'
+   *
+   * declare const source: BurnWithFeesParams['source']
+   * declare const destinationChain: BurnWithFeesParams['destinationChain']
+   * declare const recipient: string
+   * declare const hookData: string
+   * declare const claim: BurnWithFeesParams['claim']
+   *
+   * const provider = new CCTPV2BridgingProvider()
    * const { approvals, burn } = await provider.burnWithFees({
    *   source,
-   *   destinationChain: Arc,
+   *   destinationChain,
    *   amount: 1_000_000n,
-   *   executor: genericExecutorAddress,
-   *   hookData: geForwardHookData,
-   *   claim: { signedQuote: '0x01...', refundAddress: userAddress },
-   *   feeToken: '0x0000000000000000000000000000000000000000', // native
-   *   feeTotalAmount: 3_500_000n,
+   *   mintRecipient: recipient,
+   *   destinationCaller: '0x0000000000000000000000000000000000000000',
+   *   hookData,
+   *   claim,
+   *   feeToken: source.chain.usdcAddress,
+   *   feeTotalAmount: 10_000n,
    * })
    * for (const approval of approvals) await approval.execute()
    * const txHash = await burn.execute()
    * ```
    */ async burnWithFees(params) {
         assertBurnWithFeesParams(params);
-        const { source, destinationChain, executor, hookData, claim, feeToken } = params;
+        const { source, destinationChain, hookData, claim, feeToken } = params;
+        const hasExecutor = 'executor' in params && params.executor !== undefined;
+        const mintRecipient = hasExecutor ? params.executor : params.mintRecipient;
+        const destinationCaller = hasExecutor ? params.executor : params.destinationCaller;
         const amount = BigInt(params.amount);
         const feeTotalAmount = BigInt(params.feeTotalAmount);
         // Coupling guard: the prepaid FORWARD path always requests a FORWARD fee item,
@@ -18963,13 +19373,14 @@ function assertCCTPV2Config(config) {
                 delegate: wrapperAddress,
                 amount: approval.amount
             }, context)));
-        // Build the burn: mintRecipient AND destinationCaller are both the executor.
+        // Build the burn with either the GenericExecutor shorthand or the explicit
+        // direct-forwarding recipient and caller.
         const burn = await source.adapter.prepareAction('cctp.v2.depositForBurnWithFees', {
             fromChain: source.chain,
             toChain: destinationChain,
             amount,
-            mintRecipient: executor,
-            destinationCaller: executor,
+            mintRecipient,
+            destinationCaller,
             hookData,
             claim,
             feeToken,
@@ -19126,6 +19537,948 @@ function assertCCTPV2Config(config) {
     ]
 ];
 
+/**
+ * Base URL for Circle's Quote API (hosted in Iris) on mainnet/production.
+ */ const IRIS_API_BASE_URL = 'https://iris-api.circle.com';
+/**
+ * Base URL for Circle's Quote API (hosted in Iris) on testnet/sandbox.
+ */ const IRIS_API_SANDBOX_BASE_URL = 'https://iris-api-sandbox.circle.com';
+/**
+ * Native fee-token sentinel (the zero address).
+ *
+ * When `feeToken` is the zero address the quote prices fees in the source
+ * chain's native gas token (paid as `msg.value` on-chain). Pass a USDC token
+ * address instead to denominate fees in USDC.
+ */ const NATIVE_FEE_TOKEN = '0x0000000000000000000000000000000000000000';
+/**
+ * API path prefix for the CCTP v2 USDC burn quote endpoint.
+ *
+ * The full path is `${QUOTE_BURN_USDC_PATH}/{sourceDomain}/{destinationDomain}`;
+ * `usdc` is a fixed literal, not a token parameter.
+ */ const QUOTE_BURN_USDC_PATH = '/v2/quote/burn/usdc';
+/**
+ * API path prefix for the CCTP v2 USDC quote validate endpoint.
+ *
+ * The full path is `${QUOTE_VALIDATE_USDC_PATH}/{sourceDomain}`; accepts a
+ * `POST { abiSignature, args }` body and returns whether the signed quote is
+ * currently claimable together with its authoritative expiry status.
+ */ const QUOTE_VALIDATE_USDC_PATH = '/v2/quote/validate/usdc';
+/**
+ * Default polling configuration for Quote API calls.
+ *
+ * A signed quote is short-lived (typically ~2 minutes, varying per chain) and
+ * a feature-flag-disabled source chain returns a
+ * permanent `503 SERVICE_NOT_ENABLED`, so retrying buys little and risks
+ * outliving the quote. The client therefore makes a single attempt
+ * (`maxRetries: 1`) with a 15s timeout, mirroring the reference
+ * implementation; callers refresh by requesting a new quote rather than
+ * relying on transport retries.
+ *
+ * No `headers` are set here: `pollApiWithValidation` always injects
+ * `Content-Type: application/json` and adds `User-Agent` in Node. Browser
+ * requests omit a user-agent header to avoid a CORS preflight, so duplicating
+ * either header here would be dead configuration.
+ */ const FEE_QUOTE_DEFAULT_CONFIG = {
+    timeout: 15_000,
+    maxRetries: 1,
+    retryDelay: 200
+};
+
+/** Decimal string in token minor units, constrained to be strictly positive. */ const positiveAmountSchema = z.string().regex(/^\d+$/, 'must be a non-negative integer string')// Re-check the digit shape here: zod still runs this refinement when the
+// regex check above fails ("dirty"), so guard BigInt() against throwing on a
+// non-numeric value before comparing.
+.refine((value)=>/^\d+$/.test(value) && BigInt(value) > 0n, 'must be greater than zero');
+/**
+ * A 20-byte EVM address in `0x` hex.
+ *
+ * The MVP prepaid-`FORWARD` `burn/usdc` path targets EVM contracts
+ * (`TokenMessengerWithFees` / `GenericExecutor`), so `feeToken` and
+ * `destinationCaller` are constrained to EVM addresses by design. This is an
+ * intentional scope limit, not a permanent one: it can be widened to other
+ * address formats as the fee service expands to more chains.
+ */ const evmAddressSchema = z.string().regex(/^0x[a-fA-F0-9]{40}$/, 'must be a 20-byte 0x address');
+/** Even-length `0x` hex (the empty `0x` is allowed). */ const hexSchema = z.string().regex(/^0x([a-fA-F0-9]{2})*$/, 'must be even-length 0x hex');
+/** Non-empty, even-length `0x` hex. */ const nonEmptyHexSchema = z.string().regex(/^0x([a-fA-F0-9]{2})+$/, 'must be non-empty 0x hex');
+/** A 32-byte `0x` hex hash. */ const bytes32Schema = z.string().regex(/^0x[a-fA-F0-9]{64}$/, 'must be a 32-byte 0x hash');
+/** Decimal string in minor units, allowing zero. */ const numericStringSchema$1 = z.string().regex(/^\d+$/, 'must be a non-negative integer string');
+/** An `https:` URL, used for the optional base-URL override. */ const httpsUrlSchema = z.string().refine((value)=>{
+    try {
+        return new URL(value).protocol === 'https:';
+    } catch  {
+        return false;
+    }
+}, 'must be an https URL');
+const forwardParamsSchema = z.object({
+    hookData: hexSchema.optional(),
+    destinationCaller: evmAddressSchema.optional()
+}).strict();
+const forwardRequestSchema = z.object({
+    type: z.literal('FORWARD'),
+    params: forwardParamsSchema.optional()
+}).strict();
+const preFinalityRequestSchema = z.object({
+    type: z.literal('PRE_FINALITY')
+}).strict();
+/** A single quote request item (`FORWARD` or `PRE_FINALITY`). */ const feeQuoteRequestSchema = z.discriminatedUnion('type', [
+    forwardRequestSchema,
+    preFinalityRequestSchema
+]);
+/** A non-empty list of quote request items with unique types. */ const feeQuoteRequestsSchema = z.array(feeQuoteRequestSchema).min(1, 'at least one request item is required').refine((items)=>new Set(items.map((item)=>item.type)).size === items.length, 'request item types must be unique');
+/**
+ * A structured `Partial<ApiPollingConfig>` polling override.
+ *
+ * Validates the field types callers actually set, so a plain-JS caller passing
+ * `{ timeout: 'soon' }` is rejected at the boundary rather than failing opaquely
+ * inside the transport. Unknown keys pass through so a future `ApiPollingConfig`
+ * field is forwarded rather than silently dropped.
+ */ const apiPollingConfigSchema = z.object({
+    timeout: z.number().int().positive().optional(),
+    maxRetries: z.number().int().nonnegative().optional(),
+    retryDelay: z.number().int().nonnegative().optional(),
+    backoff: z.enum([
+        'fixed',
+        'exponential'
+    ]).optional(),
+    maxRetryDelayMs: z.number().int().positive().optional(),
+    headers: z.record(z.string()).optional()
+}).passthrough();
+/**
+ * The validatable input for {@link fetchFeeQuote}.
+ *
+ * This is the single source of truth for input validation, including the CCTP
+ * domains and the `isTestnet` environment flag. Validating `isTestnet` at
+ * runtime matters because a plain-JS caller who omits it would otherwise leave
+ * it `undefined`, which is falsy and silently selects the production base URL.
+ * (`buildFeeQuoteUrl` independently re-validates the domains for standalone
+ * callers.)
+ */ const fetchFeeQuoteInputSchema = z.object({
+    sourceDomain: z.number().int().nonnegative(),
+    destinationDomain: z.number().int().nonnegative(),
+    amount: positiveAmountSchema,
+    feeToken: evmAddressSchema.optional(),
+    requests: feeQuoteRequestsSchema,
+    isTestnet: z.boolean(),
+    baseUrl: httpsUrlSchema.optional(),
+    config: apiPollingConfigSchema.optional()
+}).strict();
+const feeQuoteItemSchema = z.object({
+    type: z.string().min(1),
+    amount: numericStringSchema$1,
+    args: z.array(z.string()),
+    argsHash: bytes32Schema
+}).passthrough();
+const exchangeRatesSchema = z.object({
+    feeTokenUsd: z.string(),
+    destinationTokenUsd: z.string()
+}).passthrough();
+const metadataSchema = z.object({
+    destinationGasPrice: z.string().optional(),
+    exchangeRates: exchangeRatesSchema.optional()
+}).passthrough();
+/** The `expiry` object the Quote API nests the quote TTL under. */ const expirySchema = z.discriminatedUnion('mode', [
+    z.object({
+        mode: z.literal('TIMESTAMP'),
+        expiresAt: z.number().int().nonnegative()
+    }).passthrough(),
+    z.object({
+        mode: z.literal('BLOCK_NUMBER'),
+        expiresAtBlock: z.number().int().nonnegative(),
+        blockEstimatedAt: z.number().int().nonnegative().optional()
+    }).passthrough()
+]);
+/** Schema for a signed fee quote returned by the Quote API. */ const signedFeeQuoteSchema = z.object({
+    // The runtime YAML spec maps signedQuote to a looser `hex` (which allows
+    // an empty `0x`); we keep the stricter non-empty form. Do not relax
+    // without a reason.
+    signedQuote: nonEmptyHexSchema,
+    issuedAt: z.number().int().nonnegative(),
+    // The API returns a mode-specific timestamp or source-block deadline.
+    expiry: expirySchema,
+    feeTotalAmount: numericStringSchema$1,
+    feeToken: evmAddressSchema,
+    nonce: numericStringSchema$1,
+    items: z.array(feeQuoteItemSchema),
+    metadata: metadataSchema.optional()
+}).passthrough();
+/**
+ * Validate that an unknown value is a signed fee quote.
+ *
+ * @param value - The unknown value to validate.
+ * @returns `true` when the value matches the signed-quote response shape.
+ *
+ * @example
+ * ```typescript
+ * import { isSignedFeeQuote } from '@circle-fin/provider-fee-v1'
+ *
+ * declare const payload: unknown
+ * if (isSignedFeeQuote(payload)) {
+ *   console.log(payload.feeTotalAmount)
+ * }
+ * ```
+ */ function isSignedFeeQuote(value) {
+    return signedFeeQuoteSchema.safeParse(value).success;
+}
+/** Validate input to {@link validateQuote}. */ const validateQuoteInputSchema = z.object({
+    sourceDomain: z.number().int().nonnegative(),
+    abiSignature: z.string().min(1),
+    args: z.array(z.union([
+        z.string(),
+        z.array(z.string())
+    ])),
+    isTestnet: z.boolean(),
+    baseUrl: httpsUrlSchema.optional(),
+    config: apiPollingConfigSchema.optional()
+}).strict();
+const quoteExpiryStatusSchema = z.discriminatedUnion('mode', [
+    z.object({
+        mode: z.literal('TIMESTAMP'),
+        expired: z.boolean(),
+        secondsRemaining: z.number().int().nonnegative(),
+        expiresAt: z.number().int().nonnegative()
+    }).passthrough(),
+    z.object({
+        mode: z.literal('BLOCK_NUMBER'),
+        expired: z.boolean(),
+        secondsRemaining: z.number().int().nonnegative(),
+        expiresAtBlock: z.number().int().nonnegative(),
+        blockEstimatedAt: z.number().int().nonnegative().optional()
+    }).passthrough()
+]);
+const validateQuoteItemSchema = z.object({
+    type: z.string().min(1),
+    argsMatch: z.boolean(),
+    amount: numericStringSchema$1.optional(),
+    args: z.array(z.string()).optional(),
+    argsHash: bytes32Schema.optional(),
+    computedArgsHash: bytes32Schema.optional()
+}).passthrough();
+/**
+ * Schema for a response from the Quote API validation endpoint.
+ *
+ * The endpoint takes the source domain as a URL path parameter and does not
+ * return it in the response body, so `sourceDomain` is intentionally not part
+ * of this schema.
+ */ const validateQuoteResultSchema = z.object({
+    signedQuote: nonEmptyHexSchema,
+    expiry: quoteExpiryStatusSchema,
+    feeTotalAmount: numericStringSchema$1,
+    feeToken: evmAddressSchema,
+    nonce: numericStringSchema$1,
+    claimable: z.boolean(),
+    // Preserve newly introduced server-side reasons as opaque strings rather
+    // than rejecting the entire safety response before the SDK is updated.
+    failedChecks: z.array(z.string().min(1)),
+    items: z.array(validateQuoteItemSchema)
+}).passthrough();
+/**
+ * Validate a Quote API validation response.
+ *
+ * @param value - The unknown response value.
+ * @returns `true` when the value has the expected validation response shape.
+ *
+ * @example
+ * ```typescript
+ * import { isValidateQuoteResult } from '@circle-fin/provider-fee-v1'
+ *
+ * declare const response: unknown
+ * if (isValidateQuoteResult(response)) {
+ *   console.log(response.claimable)
+ * }
+ * ```
+ */ function isValidateQuoteResult(value) {
+    return validateQuoteResultSchema.safeParse(value).success;
+}
+
+/**
+ * Validate that a CCTP domain id is a non-negative integer.
+ *
+ * @param value - The domain id to validate.
+ * @param label - The parameter name, used in the error message.
+ * @returns Nothing.
+ * @throws {@link KitError} When the value is not a non-negative integer.
+ * @internal
+ */ function assertDomain(value, label) {
+    if (!Number.isInteger(value) || value < 0) {
+        throw new KitError({
+            ...InputError.VALIDATION_FAILED,
+            recoverability: 'FATAL',
+            message: `Quote API getFeeQuote failed: ${label} must be a ` + `non-negative integer, received ${String(value)}`,
+            cause: {
+                trace: {
+                    [label]: value
+                }
+            }
+        });
+    }
+}
+/**
+ * Build the Quote API URL for a CCTP v2 USDC burn quote.
+ *
+ * Resolves the environment base URL (or an explicit `baseUrl` override) and
+ * appends the burn/usdc path with the source and destination CCTP domains.
+ * `usdc` is a fixed path literal, not a token parameter.
+ *
+ * @param params - The domains and environment selector.
+ * @returns The fully-qualified Quote API URL.
+ * @throws {@link KitError} When either domain is not a non-negative integer.
+ *
+ * @example
+ * ```typescript
+ * import { buildFeeQuoteUrl } from '@circle-fin/provider-fee-v1'
+ *
+ * const url = buildFeeQuoteUrl({
+ *   sourceDomain: 3,
+ *   destinationDomain: 26,
+ *   isTestnet: false,
+ * })
+ * // => 'https://iris-api.circle.com/v2/quote/burn/usdc/3/26'
+ * ```
+ */ function buildFeeQuoteUrl(params) {
+    const { sourceDomain, destinationDomain, isTestnet, baseUrl } = params;
+    assertDomain(sourceDomain, 'sourceDomain');
+    assertDomain(destinationDomain, 'destinationDomain');
+    const resolvedBaseUrl = baseUrl ?? (isTestnet ? IRIS_API_SANDBOX_BASE_URL : IRIS_API_BASE_URL);
+    return new URL(`${QUOTE_BURN_USDC_PATH}/${String(sourceDomain)}/${String(destinationDomain)}`, resolvedBaseUrl).toString();
+}
+
+/**
+ * Assert that a quote's per-item fee amounts sum to its `feeTotalAmount`.
+ *
+ * A defensive integrity check on the Quote API response, enforced internally
+ * by `fetchFeeQuote`. It does not compare against the destination-side
+ * `feeExecuted`, which is expected to be zero for prepaid forward-only burns.
+ *
+ * @param quote - The signed fee quote to check.
+ * @returns Nothing.
+ * @throws {@link KitError} When the item amounts do not sum to `feeTotalAmount`.
+ * @internal
+ */ function assertFeeItemsSumToTotal(quote) {
+    const itemsTotal = quote.items.reduce((sum, item)=>sum + BigInt(item.amount), 0n);
+    const declaredTotal = BigInt(quote.feeTotalAmount);
+    if (itemsTotal !== declaredTotal) {
+        throw new KitError({
+            ...InputError.VALIDATION_FAILED,
+            recoverability: 'FATAL',
+            message: `Quote API getFeeQuote failed: fee items sum ` + `(${itemsTotal.toString()}) does not equal feeTotalAmount ` + `(${declaredTotal.toString()})`,
+            cause: {
+                trace: {
+                    itemsTotal: itemsTotal.toString(),
+                    feeTotalAmount: quote.feeTotalAmount
+                }
+            }
+        });
+    }
+}
+
+/**
+ * Determine whether a Quote API error represents a disabled source chain.
+ *
+ * @param error - The error thrown by the HTTP layer.
+ * @returns `true` when the error contains the `SERVICE_NOT_ENABLED` marker.
+ * @internal
+ */ function isServiceNotEnabled(error) {
+    const body = typeof error === 'object' && error !== null && 'responseBody' in error ? error.responseBody : undefined;
+    if (typeof body === 'object' && body !== null) {
+        const fields = body;
+        const candidates = [
+            fields['errorCode'],
+            fields['code'],
+            fields['message'],
+            fields['externalMessage'],
+            fields['error']
+        ];
+        if (candidates.some((value)=>typeof value === 'string' && value.toUpperCase().includes('SERVICE_NOT_ENABLED'))) {
+            return true;
+        }
+    }
+    return getErrorMessage(error).toUpperCase().includes('SERVICE_NOT_ENABLED');
+}
+
+const SERVICE$1 = 'Quote API';
+const OPERATION$1 = 'getFeeQuote';
+/**
+ * Serialize request items for the wire body.
+ *
+ * `PRE_FINALITY` is emitted with no `params` key, and a `FORWARD` item only
+ * carries the binding fields that are present.
+ *
+ * @param requests - The request items to serialize.
+ * @returns The serialized request items.
+ * @internal
+ */ function serializeRequests(requests) {
+    return requests.map((request)=>{
+        if (request.type === 'PRE_FINALITY') {
+            return {
+                type: 'PRE_FINALITY'
+            };
+        }
+        const params = request.params;
+        if (params === undefined) {
+            return {
+                type: 'FORWARD'
+            };
+        }
+        const forwardParams = {};
+        if (params.hookData !== undefined) {
+            forwardParams.hookData = params.hookData;
+        }
+        if (params.destinationCaller !== undefined) {
+            forwardParams.destinationCaller = params.destinationCaller;
+        }
+        return {
+            type: 'FORWARD',
+            params: forwardParams
+        };
+    });
+}
+/**
+ * Fetch a signed fee quote from Circle's Quote API for a CCTP v2 USDC burn.
+ *
+ * Validates inputs, POSTs to
+ * `/v2/quote/burn/usdc/{sourceDomain}/{destinationDomain}` with a single
+ * attempt (the signed quote is short-lived), and returns the typed quote. A
+ * disabled source chain (`503 SERVICE_NOT_ENABLED`) surfaces as a fatal,
+ * non-retryable error; other failures are mapped to a {@link KitError} via the
+ * shared API error parser.
+ *
+ * @param params - The domains, amount, request items, and environment.
+ * @returns The signed fee quote.
+ * @throws {@link KitError} On invalid input, a disabled source chain, an HTTP
+ *   error, or an invalid response shape.
+ *
+ * @example
+ * ```typescript
+ * import { fetchFeeQuote } from '@circle-fin/provider-fee-v1'
+ *
+ * const quote = await fetchFeeQuote({
+ *   sourceDomain: 3,
+ *   destinationDomain: 26,
+ *   amount: '1000000',
+ *   requests: [{ type: 'FORWARD' }, { type: 'PRE_FINALITY' }],
+ *   isTestnet: false,
+ * })
+ * console.log(quote.feeTotalAmount, quote.expiry)
+ * ```
+ */ async function fetchFeeQuote(params) {
+    const { sourceDomain, destinationDomain, amount, requests, feeToken, isTestnet, baseUrl, config } = params;
+    const parsed = fetchFeeQuoteInputSchema.safeParse({
+        sourceDomain,
+        destinationDomain,
+        amount,
+        feeToken,
+        requests,
+        isTestnet,
+        baseUrl,
+        config
+    });
+    if (!parsed.success) {
+        const detail = parsed.error.issues.map((issue)=>`${issue.path.join('.')}: ${issue.message}`).join('; ');
+        throw new KitError({
+            ...InputError.VALIDATION_FAILED,
+            recoverability: 'FATAL',
+            message: `${SERVICE$1} ${OPERATION$1} failed: ${detail}`,
+            cause: {
+                trace: parsed.error.issues
+            }
+        });
+    }
+    const url = baseUrl === undefined ? buildFeeQuoteUrl({
+        sourceDomain,
+        destinationDomain,
+        isTestnet
+    }) : buildFeeQuoteUrl({
+        sourceDomain,
+        destinationDomain,
+        isTestnet,
+        baseUrl
+    });
+    const body = {
+        amount,
+        feeToken: feeToken ?? NATIVE_FEE_TOKEN,
+        requests: serializeRequests(requests)
+    };
+    const pollingConfig = {
+        ...FEE_QUOTE_DEFAULT_CONFIG,
+        ...config
+    };
+    let quote;
+    try {
+        quote = await pollApiPost(url, body, isSignedFeeQuote, pollingConfig);
+    } catch (error) {
+        // Only one service-specific code (SERVICE_NOT_ENABLED) needs bespoke
+        // mapping, so it is detected inline rather than via a dedicated
+        // `parseFeeQuoteApiError` parser; everything else flows through the shared
+        // `parseApiError`. Promote to a parser if more coded errors appear.
+        if (isServiceNotEnabled(error)) {
+            throw new KitError({
+                ...InputError.UNSUPPORTED_ROUTE,
+                recoverability: 'FATAL',
+                message: `${SERVICE$1} ${OPERATION$1} failed: source chain not enabled for fee ` + `quotes (SERVICE_NOT_ENABLED)`,
+                cause: {
+                    trace: error
+                }
+            });
+        }
+        throw parseApiError(error, {
+            service: SERVICE$1,
+            operation: OPERATION$1
+        });
+    }
+    // Defense-in-depth: a self-consistent quote's per-item fees sum to the
+    // declared total. Enforced here so callers cannot forget the check.
+    assertFeeItemsSumToTotal(quote);
+    return quote;
+}
+
+const SERVICE = 'Quote API';
+const OPERATION = 'validateQuote';
+/**
+ * Validate a signed quote against a complete source-chain contract call.
+ *
+ * @param params - The source domain, ABI signature, call arguments, and environment.
+ * @returns The claimability, binding checks, and authoritative expiry status.
+ * @throws {@link KitError} When input, transport, or response validation fails.
+ *
+ * @example
+ * ```typescript
+ * import { validateQuote } from '@circle-fin/provider-fee-v1'
+ *
+ * const result = await validateQuote({
+ *   sourceDomain: 3,
+ *   // The exact function + arguments, in ABI order, that will be burned on-chain.
+ *   abiSignature:
+ *     'depositForBurnWithHookAndFees(uint256,uint32,bytes32,address,bytes32,bytes,(bytes,address))',
+ *   args: [
+ *     '1000000',
+ *     '26',
+ *     '0x0000000000000000000000001111111111111111111111111111111111111111',
+ *     '0x2222222222222222222222222222222222222222',
+ *     '0x0000000000000000000000000000000000000000000000000000000000000000',
+ *     '0x636374702d666f72776172640000000000000000000000000000000000000000',
+ *     ['0x01abcd', '0x3333333333333333333333333333333333333333'],
+ *   ],
+ *   isTestnet: false,
+ * })
+ * console.log(result.claimable, result.expiry.secondsRemaining)
+ * ```
+ */ async function validateQuote(params) {
+    const parsed = validateQuoteInputSchema.safeParse(params);
+    if (!parsed.success) {
+        const detail = parsed.error.issues.map((issue)=>`${issue.path.join('.')}: ${issue.message}`).join('; ');
+        throw new KitError({
+            ...InputError.VALIDATION_FAILED,
+            recoverability: 'FATAL',
+            message: `${SERVICE} ${OPERATION} failed: ${detail}`,
+            cause: {
+                trace: parsed.error.issues
+            }
+        });
+    }
+    const { sourceDomain, abiSignature, args, isTestnet, baseUrl } = parsed.data;
+    // `config` was validated by the schema above; spread the caller's original,
+    // precisely typed `Partial<ApiPollingConfig>` so the merged polling config
+    // stays assignable under `exactOptionalPropertyTypes`.
+    const pollingConfig = {
+        ...FEE_QUOTE_DEFAULT_CONFIG,
+        ...params.config
+    };
+    const resolvedBaseUrl = baseUrl ?? (isTestnet ? IRIS_API_SANDBOX_BASE_URL : IRIS_API_BASE_URL);
+    const url = new URL(`${QUOTE_VALIDATE_USDC_PATH}/${String(sourceDomain)}`, resolvedBaseUrl).toString();
+    try {
+        return await pollApiPost(url, {
+            abiSignature,
+            args
+        }, isValidateQuoteResult, pollingConfig);
+    } catch (error) {
+        if (isServiceNotEnabled(error)) {
+            throw new KitError({
+                ...InputError.UNSUPPORTED_ROUTE,
+                recoverability: 'FATAL',
+                message: `${SERVICE} ${OPERATION} failed: source chain not enabled for ` + `quote validation (SERVICE_NOT_ENABLED)`,
+                cause: {
+                    trace: error
+                }
+            });
+        }
+        throw parseApiError(error, {
+            service: SERVICE,
+            operation: OPERATION
+        });
+    }
+}
+
+/** Refresh timestamp quotes this many seconds before submission. */ const QUOTE_EXPIRY_SAFETY_SECONDS = 30;
+/** ABI signature validated by the Quote API before source-chain submission. */ const BURN_WITH_FEES_ABI_SIGNATURE = 'depositForBurnWithHookAndFees(uint256,uint32,bytes32,address,bytes32,bytes,(bytes,address))';
+/** Unrestricted CCTP destination caller used by the forwarding relayer. */ const ZERO_ADDRESS$1 = '0x0000000000000000000000000000000000000000';
+function isQuoteNearEstimatedExpiry(quote) {
+    const currentSeconds = Math.floor(Date.now() / 1_000);
+    const expiresAt = quote.expiry.mode === 'TIMESTAMP' ? quote.expiry.expiresAt : quote.expiry.blockEstimatedAt;
+    // A BLOCK_NUMBER quote may omit the advisory `blockEstimatedAt` estimate; when
+    // it is absent, skip this wall-clock pre-check and defer to the authoritative
+    // source-chain-tip validation performed downstream.
+    if (expiresAt === undefined) {
+        return false;
+    }
+    return expiresAt <= currentSeconds + QUOTE_EXPIRY_SAFETY_SECONDS;
+}
+function assertSourceFeeRoute(params) {
+    const { source, destination, config } = params;
+    if (source.chain.type !== 'evm' || destination.chain.type !== 'evm' || !isCCTPV2Supported(source.chain) || !isCCTPV2Supported(destination.chain)) {
+        throw createUnsupportedRouteError(source.chain.name, destination.chain.name);
+    }
+    const useForwarder = destination.useForwarder;
+    if (useForwarder !== true) {
+        throw createValidationFailedError$1('to.useForwarder', useForwarder, "feePayment: 'source' requires useForwarder: true");
+    }
+    if (config.customFee !== undefined) {
+        throw createValidationFailedError$1('config.customFee', config.customFee, "Custom fees are not supported with feePayment: 'source'. Remove the " + 'per-call customFee or the kit-level custom fee policy for this route.');
+    }
+}
+function buildQuoteBinding(params) {
+    assertSourceFeeRoute(params);
+    const mintRecipient = params.destination.recipientAddress ?? params.destination.address;
+    const hookData = buildForwardingHookData();
+    const requests = [
+        {
+            type: 'FORWARD',
+            params: {
+                hookData,
+                destinationCaller: ZERO_ADDRESS$1
+            }
+        }
+    ];
+    if ((params.config.transferSpeed ?? TransferSpeed.FAST) === TransferSpeed.FAST) {
+        requests.push({
+            type: 'PRE_FINALITY'
+        });
+    }
+    return {
+        sourceDomain: params.source.chain.cctp.domain,
+        destinationDomain: params.destination.chain.cctp.domain,
+        isTestnet: params.source.chain.isTestnet,
+        amount: params.amount,
+        mintRecipient,
+        hookData,
+        destinationCaller: ZERO_ADDRESS$1,
+        feeToken: params.source.chain.usdcAddress,
+        requests
+    };
+}
+async function fetchBoundQuote(binding) {
+    try {
+        const quote = await fetchFeeQuote({
+            sourceDomain: binding.sourceDomain,
+            destinationDomain: binding.destinationDomain,
+            amount: binding.amount,
+            feeToken: binding.feeToken,
+            requests: binding.requests,
+            isTestnet: binding.isTestnet
+        });
+        if (quote.feeToken.toLowerCase() !== binding.feeToken.toLowerCase()) {
+            throw createValidationFailedError$1('feeToken', quote.feeToken, 'Fee Service must return source-chain USDC for source-fee bridging');
+        }
+        return quote;
+    } catch (error) {
+        if (isRateLimitError(error)) {
+            throw new KitError({
+                ...RateLimitError.RATE_LIMIT_EXCEEDED,
+                recoverability: 'RETRYABLE',
+                message: 'Fee Service rate limit exceeded. Retry with caller-managed exponential backoff; Bridge Kit does not retry signed quote requests automatically.',
+                cause: {
+                    trace: error
+                }
+            });
+        }
+        throw error;
+    }
+}
+async function fetchSubmissionQuote(binding) {
+    let quote = await fetchBoundQuote(binding);
+    if (isQuoteNearEstimatedExpiry(quote)) {
+        quote = await fetchBoundQuote(binding);
+    }
+    if (isQuoteNearEstimatedExpiry(quote)) {
+        throw createValidationFailedError$1('quote', undefined, 'Fee Service returned a quote too close to expiry for safe submission');
+    }
+    return quote;
+}
+async function validateBoundQuote(binding, signedQuote, refundAddress) {
+    return validateQuote({
+        sourceDomain: binding.sourceDomain,
+        abiSignature: BURN_WITH_FEES_ABI_SIGNATURE,
+        args: [
+            binding.amount,
+            String(binding.destinationDomain),
+            padAddressToBytes32(binding.mintRecipient),
+            binding.feeToken,
+            padAddressToBytes32(binding.destinationCaller),
+            binding.hookData,
+            [
+                signedQuote,
+                refundAddress
+            ]
+        ],
+        isTestnet: binding.isTestnet
+    });
+}
+function isValidationSafe(binding, signedQuote, validation, expectedQuote) {
+    return validation.claimable && !validation.expiry.expired && validation.expiry.secondsRemaining > QUOTE_EXPIRY_SAFETY_SECONDS && validation.signedQuote.toLowerCase() === signedQuote.toLowerCase() && validation.feeToken.toLowerCase() === binding.feeToken.toLowerCase() && (expectedQuote === undefined || validation.feeTotalAmount === expectedQuote.feeTotalAmount && validation.nonce === expectedQuote.nonce);
+}
+function unsafeQuoteError(validation) {
+    const detail = validation.failedChecks.length > 0 ? ` (${validation.failedChecks.join(', ')})` : '';
+    return createValidationFailedError$1('quote', undefined, `The fee quote is not safe for submission${detail}; ` + 'call estimate again to obtain a valid quote');
+}
+function toExecutionFeeQuote(quote) {
+    return {
+        signedQuote: quote.signedQuote,
+        feeToken: quote.feeToken,
+        feeTotalAmount: quote.feeTotalAmount
+    };
+}
+function toFeeItems(quote) {
+    return quote.items.map((item)=>({
+            type: item.type,
+            amount: formatUnits(item.amount, 6),
+            args: item.args,
+            argsHash: item.argsHash
+        }));
+}
+/**
+ * Estimate a source-fee bridge using a source-denominated signed fee quote.
+ *
+ * @internal
+ */ async function estimateSourceFeeBridge(params) {
+    const binding = buildQuoteBinding(params);
+    const quote = await fetchSubmissionQuote(binding);
+    const feeTotal = formatUnits(quote.feeTotalAmount, 6);
+    return {
+        token: 'USDC',
+        amount: formatUnits(params.amount, 6),
+        source: {
+            address: params.source.address,
+            chain: params.source.chain.chain
+        },
+        destination: {
+            address: params.destination.address,
+            chain: params.destination.chain.chain,
+            ...params.destination.recipientAddress !== undefined && {
+                recipientAddress: params.destination.recipientAddress
+            }
+        },
+        gasFees: [],
+        fees: quote.items.map((item)=>({
+                type: item.type === 'FORWARD' ? 'forwarder' : 'provider',
+                token: 'USDC',
+                amount: formatUnits(item.amount, 6)
+            })),
+        amountReceived: formatUnits(params.amount, 6),
+        feeTotal,
+        feeItems: toFeeItems(quote),
+        totalDebit: formatUnits((BigInt(params.amount) + BigInt(quote.feeTotalAmount)).toString(), 6),
+        quoteExpiry: quote.expiry,
+        quote: quote.signedQuote
+    };
+}
+async function readAllowance(params, delegate) {
+    const operationContext = {
+        chain: params.source.chain,
+        address: params.source.address
+    };
+    const prepared = await params.source.adapter.prepareAction('usdc.allowance', {
+        walletAddress: params.source.address,
+        delegate
+    }, operationContext);
+    return BigInt(String(await prepared.execute()));
+}
+async function executeAndConfirm(request, params, provider) {
+    const txHash = await request.execute();
+    const data = await provider.waitForTransaction(params.source.adapter, txHash, params.source.chain);
+    return {
+        txHash,
+        data
+    };
+}
+async function prepareAndPreflight(params, binding, quote, provider) {
+    assertSourceFeeRoute(params);
+    const totalDebit = (BigInt(params.amount) + BigInt(quote.feeTotalAmount)).toString();
+    const operationContext = {
+        chain: params.source.chain,
+        address: params.source.address
+    };
+    await validateBalanceForTransaction({
+        adapter: params.source.adapter,
+        amount: totalDebit,
+        token: 'USDC',
+        tokenAddress: params.source.chain.usdcAddress,
+        operationContext
+    });
+    const prepared = await provider.burnWithFees({
+        source: params.source,
+        destinationChain: params.destination.chain,
+        amount: params.amount,
+        mintRecipient: binding.mintRecipient,
+        destinationCaller: binding.destinationCaller,
+        hookData: binding.hookData,
+        claim: {
+            signedQuote: quote.signedQuote,
+            refundAddress: params.source.address
+        },
+        feeToken: quote.feeToken,
+        feeTotalAmount: quote.feeTotalAmount
+    });
+    const wrapper = resolveCCTPV2ContractAddress(params.source.chain, 'tokenMessengerWithFees');
+    const allowance = await readAllowance(params, wrapper);
+    if (allowance >= BigInt(totalDebit)) {
+        return {
+            prepared,
+            approveStep: {
+                name: 'approve',
+                state: 'noop'
+            }
+        };
+    }
+    let lastApproval;
+    for (const approval of prepared.approvals){
+        lastApproval = await executeAndConfirm(approval, params, provider);
+    }
+    return {
+        prepared,
+        approveStep: {
+            name: 'approve',
+            state: 'success',
+            data: lastApproval?.data,
+            ...lastApproval?.txHash !== undefined && {
+                txHash: lastApproval.txHash,
+                explorerUrl: buildExplorerUrl(params.source.chain, lastApproval.txHash)
+            }
+        }
+    };
+}
+async function resolveExecutionQuote(binding, suppliedQuote, refundAddress) {
+    if (suppliedQuote === undefined) {
+        const fetchedQuote = await fetchSubmissionQuote(binding);
+        return {
+            quote: toExecutionFeeQuote(fetchedQuote),
+            fetchedQuote
+        };
+    }
+    const validation = await validateBoundQuote(binding, suppliedQuote, refundAddress);
+    if (!isValidationSafe(binding, suppliedQuote, validation)) {
+        throw unsafeQuoteError(validation);
+    }
+    return {
+        quote: toExecutionFeeQuote(validation),
+        fetchedQuote: undefined
+    };
+}
+/**
+ * Execute a source-fee bridge while preserving receive-exact semantics.
+ *
+ * @internal
+ */ async function executeSourceFeeBridge(rawParams, params, provider) {
+    // Narrows `params` to the CCTP v2 route type for the rest of this function.
+    // buildQuoteBinding asserts too, but that narrows its own scope, not this one.
+    assertSourceFeeRoute(params);
+    const binding = buildQuoteBinding(params);
+    const suppliedQuote = rawParams.quote;
+    let { quote, fetchedQuote } = await resolveExecutionQuote(binding, suppliedQuote, params.source.address);
+    let { prepared, approveStep } = await prepareAndPreflight(params, binding, quote, provider);
+    // Validate against the current source-chain tip after approval confirmation.
+    // BLOCK_NUMBER expiries cannot be checked safely with wall-clock time alone.
+    let validation = await validateBoundQuote(binding, quote.signedQuote, params.source.address);
+    if (!isValidationSafe(binding, quote.signedQuote, validation, fetchedQuote)) {
+        if (suppliedQuote === undefined) {
+            fetchedQuote = await fetchSubmissionQuote(binding);
+            quote = toExecutionFeeQuote(fetchedQuote);
+            const refreshedPreparation = await prepareAndPreflight(params, binding, quote, provider);
+            prepared = refreshedPreparation.prepared;
+            if (refreshedPreparation.approveStep.state !== 'noop') {
+                approveStep = refreshedPreparation.approveStep;
+            }
+            validation = await validateBoundQuote(binding, quote.signedQuote, params.source.address);
+            if (!isValidationSafe(binding, quote.signedQuote, validation, fetchedQuote)) {
+                throw unsafeQuoteError(validation);
+            }
+        } else {
+            throw unsafeQuoteError(validation);
+        }
+    }
+    // Surface the same step events as the standard bridge() path so
+    // kit.on('approve'|'burn'|'mint', ...) handlers fire for source-fee bridges.
+    if (approveStep.state !== 'noop') {
+        provider.emitBridgeStep('approve', approveStep);
+    }
+    const burn = await executeAndConfirm(prepared.burn, params, provider);
+    const burnStep = {
+        name: 'burn',
+        state: 'success',
+        txHash: burn.txHash,
+        data: burn.data,
+        explorerUrl: buildExplorerUrl(params.source.chain, burn.txHash)
+    };
+    provider.emitBridgeStep('burn', burnStep);
+    const resultBase = {
+        amount: params.amount,
+        token: 'USDC',
+        config: params.config,
+        provider: provider.name,
+        source: {
+            address: params.source.address,
+            chain: params.source.chain
+        },
+        destination: {
+            address: params.destination.address,
+            chain: params.destination.chain,
+            ...params.destination.recipientAddress !== undefined && {
+                recipientAddress: params.destination.recipientAddress
+            },
+            useForwarder: true
+        }
+    };
+    const attestation = await provider.fetchRelayerMint(params.source, burn.txHash);
+    const forwardTxHash = attestation.forwardTxHash;
+    // The burn already moved funds. If the relayer confirms without a
+    // destination hash, surface an error-state result that preserves the burn
+    // step (so `retry()` can resume the mint) instead of throwing and discarding
+    // the completed burn.
+    if (typeof forwardTxHash !== 'string' || forwardTxHash.trim() === '') {
+        const mintStep = {
+            name: 'mint',
+            state: 'error',
+            forwarded: true,
+            errorCategory: 'failed_offchain',
+            errorMessage: 'Relayer confirmation did not include a destination transaction hash'
+        };
+        provider.emitBridgeStep('mint', mintStep);
+        return {
+            ...resultBase,
+            state: 'error',
+            steps: [
+                approveStep,
+                burnStep,
+                mintStep
+            ]
+        };
+    }
+    const mintStep = {
+        name: 'mint',
+        state: 'success',
+        forwarded: true,
+        txHash: forwardTxHash,
+        explorerUrl: buildExplorerUrl(params.destination.chain, forwardTxHash)
+    };
+    provider.emitBridgeStep('mint', mintStep);
+    return {
+        ...resultBase,
+        state: 'success',
+        steps: [
+            approveStep,
+            burnStep,
+            mintStep
+        ]
+    };
+}
+
 /** SDK name used in telemetry payloads. */ const SDK_NAME$3 = resolveKitSdkName(pkg$5.name);
 /**
  * Pick the most-relevant `txHash` to attach to an error telemetry payload.
@@ -19353,11 +20706,18 @@ function assertCCTPV2Config(config) {
             this.validateNetworkCompatibility(resolvedParams);
             // Merge the custom fee config into the resolved params
             const finalResolvedParams = await this.mergeCustomFeeConfig(resolvedParams);
-            // Find a provider that supports this route
-            const provider = this.findProviderForRoute(finalResolvedParams);
-            // Execute the transfer using the provider
-            // Format the bridge result into human-readable string values for the user
-            const result = formatBridgeResult(await provider.bridge(finalResolvedParams), 'to-human-readable');
+            let result;
+            // Execute the explicit source-fee path without changing legacy
+            // useForwarder behavior for callers that did not opt in.
+            if (params.config?.feePayment === 'source') {
+                const sourceFeeProvider = this.findSourceFeeProvider(finalResolvedParams);
+                result = formatBridgeResult(await executeSourceFeeBridge(params, finalResolvedParams, sourceFeeProvider), 'to-human-readable');
+            } else {
+                // Find a provider that supports this route
+                const provider = this.findProviderForRoute(finalResolvedParams);
+                // Execute the transfer using the provider and format the result.
+                result = formatBridgeResult(await provider.bridge(finalResolvedParams), 'to-human-readable');
+            }
             // Emit error telemetry when the provider returns an error state
             // (provider records step failures in the result instead of throwing).
             if (result.state === 'error') {
@@ -19480,42 +20840,7 @@ function assertCCTPV2Config(config) {
             tokenIn: result.token
         });
     }
-    /**
-   * Estimate the cost and fees for a cross-chain USDC bridge operation.
-   *
-   * This method calculates the expected gas fees and protocol costs for bridging
-   * without actually executing the transaction. It performs the same validation
-   * as the bridge method but stops before execution.
-   *
-   * @param params - The bridge parameters for cost estimation, including optional invocation metadata
-   * @returns Promise resolving to detailed cost breakdown including gas estimates
-   * @throws {KitError} When the parameters are invalid.
-   * @throws {UnsupportedRouteError} When the route is not supported.
-   *
-   * @example
-   * ```typescript
-   * // Basic usage
-   * const estimate = await kit.estimate({
-   *   from: { adapter: adapter, chain: 'Ethereum' },
-   *   to: { adapter: adapter, chain: 'Base' },
-   *   amount: '10.50',
-   *   token: 'USDC'
-   * })
-   * console.log('Estimated cost:', estimate.totalCost)
-   *
-   * // With custom invocation metadata
-   * const estimate = await kit.estimate({
-   *   from: { adapter: adapter, chain: 'Ethereum' },
-   *   to: { adapter: adapter, chain: 'Base' },
-   *   amount: '10.50',
-   *   token: 'USDC',
-   *   invocationMeta: {
-   *     traceId: 'custom-trace-id',
-   *     callers: [{ type: 'app', name: 'MyDApp', version: '1.0.0' }],
-   *   },
-   * })
-   * ```
-   */ async estimate(params) {
+    async estimate(params) {
         return withErrorTelemetry(async ()=>{
             // First validate the parameters
             assertBridgeParams(params, bridgeParamsWithChainIdentifierSchema);
@@ -19525,6 +20850,10 @@ function assertCCTPV2Config(config) {
             this.validateNetworkCompatibility(resolvedParams);
             // Merge the custom fee config into the resolved params
             const finalResolvedParams = await this.mergeCustomFeeConfig(resolvedParams);
+            if (params.config?.feePayment === 'source') {
+                this.findSourceFeeProvider(finalResolvedParams);
+                return estimateSourceFeeBridge(finalResolvedParams);
+            }
             // Find a provider that supports this route
             const provider = this.findProviderForRoute(finalResolvedParams);
             // Estimate the transfer using the provider and format amounts to human-readable strings
@@ -19573,6 +20902,9 @@ function assertCCTPV2Config(config) {
    * // Get only chains that support forwarding
    * const forwarderChains = kit.getSupportedChains({ forwarderSupported: true })
    *
+   * // Get only chains that can pay fees on the source chain (receive-exact)
+   * const sourceFeeChains = kit.getSupportedChains({ sourceFeeSupported: true })
+   *
    * console.log('Supported chains:')
    * allChains.forEach(chain => {
    *   console.log(`- ${chain.name} (${chain.type})`)
@@ -19621,6 +20953,10 @@ function assertCCTPV2Config(config) {
                 return options.forwarderSupported ? fs.source || fs.destination : !fs.source && !fs.destination;
             });
         }
+        // Apply source-paid ("receive-exact") fee support filter if provided
+        if (options?.sourceFeeSupported !== undefined) {
+            chains = chains.filter((chain)=>hasSourceFeeSupport(chain) === options.sourceFeeSupported);
+        }
         return chains;
     }
     /**
@@ -19655,6 +20991,20 @@ function assertCCTPV2Config(config) {
         return provider;
     }
     /**
+   * Find the default CCTP v2 provider for a source-fee forwarding route.
+   *
+   * @param params - The resolved provider parameters.
+   * @returns The CCTP v2 provider that supports the forwarded route.
+   * @throws {UnsupportedRouteError} When no source-fee provider supports the route.
+   * @internal
+   */ findSourceFeeProvider(params) {
+        const provider = this.providers.find((candidate)=>candidate instanceof CCTPV2BridgingProvider && candidate.supportsRoute(params.source.chain, params.destination.chain, params.token, true));
+        if (!(provider instanceof CCTPV2BridgingProvider)) {
+            throw createUnsupportedRouteError(params.source.chain.name, params.destination.chain.name);
+        }
+        return provider;
+    }
+    /**
    * Merge custom fee configuration into provider parameters.
    *
    * Prioritizes any custom fee configuration already present on the
@@ -19794,7 +21144,7 @@ function assertCCTPV2Config(config) {
 registerKit(`${pkg$5.name}/${pkg$5.version}`);
 
 var name$3 = "@circle-fin/swap-kit";
-var version$3 = "1.5.2";
+var version$3 = "1.6.0";
 var pkg$3 = {
 	name: name$3,
 	version: version$3};
@@ -19808,7 +21158,7 @@ const optionalChainIdentifierField = chainIdentifierField.optional();
  * Catches obviously malformed addresses at parse time; chain-specific validation
  * is performed in buildServiceParams.
  */ const destinationAddressSchema = z.union([
-    evmAddressSchema,
+    evmAddressSchema$1,
     solanaAddressSchema
 ]);
 /**
@@ -19854,9 +21204,16 @@ const optionalChainIdentifierField = chainIdentifierField.optional();
         message: 'stopLimit must be greater than 0'
     }).optional(),
     customFee: serviceSwapCustomFeeSchema.optional(),
+    apiKey: z.string({
+        invalid_type_error: 'apiKey must be a string'
+    })// Tolerate '' so the `process.env.CIRCLE_API_KEY ?? ''` idiom falls back to
+    // kitKey via resolveApiKey instead of being rejected here.
+    .optional(),
     kitKey: z.string({
         invalid_type_error: 'kitKey must be a string'
-    }).min(1, 'kitKey must be a non-empty string').optional(),
+    })// Tolerate '' so an unset kit-key env var yields the permissionless path,
+    // matching buildServiceParams (which already omits an empty credential).
+    .optional(),
     provider: z.string({
         invalid_type_error: 'provider must be a string'
     }).min(1, 'provider must be a non-empty string').optional(),
@@ -20021,23 +21378,49 @@ const optionalChainIdentifierField = chainIdentifierField.optional();
     fees: z.array(serviceSwapFeeSchema).optional()
 }).passthrough();
 
-/** Placeholder used wherever a kit key is scrubbed from logs, traces, or errors. */ const REDACTED_KIT_KEY = '[redacted]';
+/** Placeholder used wherever a credential is scrubbed from logs, traces, or errors. */ const REDACTED_CREDENTIAL = '[redacted]';
+/**
+ * Config fields that carry a Stablecoin Service credential.
+ *
+ * `apiKey` is the supported field; `kitKey` is the deprecated alias. Redaction
+ * and credential resolution both read this list so a newly added field is
+ * scrubbed everywhere it needs to be.
+ */ const CREDENTIAL_CONFIG_FIELDS = [
+    'apiKey',
+    'kitKey'
+];
 
+/**
+ * Replaces any credential field present on a config with a redaction marker.
+ *
+ * Covers `apiKey` and the deprecated `kitKey`, so adding a credential field
+ * without extending this list cannot silently leak it into a trace. Returns the
+ * config unchanged when it carries no credential.
+ */ const redactCredentialFields = (config)=>{
+    const present = CREDENTIAL_CONFIG_FIELDS.filter((field)=>field in config);
+    if (present.length === 0) {
+        return config;
+    }
+    return present.reduce((acc, field)=>({
+            ...acc,
+            [field]: REDACTED_CREDENTIAL
+        }), {
+        ...config
+    });
+};
 /**
  * Builds a redacted projection of swap params that is safe to embed in error
  * traces (which may be logged downstream). Allow-lists only non-sensitive
  * fields and drops `from` entirely — `from.adapter` can carry signer/private-key
- * material for signer-backed (viem/ethers) flows — and redacts `config.kitKey`.
+ * material for signer-backed (viem/ethers) flows — and redacts every credential
+ * field on `config`.
  */ const redactSwapParamsForTrace = (params)=>{
     if (typeof params !== 'object' || params === null) {
         return params;
     }
     const record = params;
     const config = record['config'];
-    const redactedConfig = typeof config === 'object' && config !== null && 'kitKey' in config ? {
-        ...config,
-        kitKey: REDACTED_KIT_KEY
-    } : config;
+    const redactedConfig = typeof config === 'object' && config !== null ? redactCredentialFields(config) : config;
     return {
         tokenIn: record['tokenIn'],
         tokenOut: record['tokenOut'],
@@ -20121,6 +21504,41 @@ const optionalChainIdentifierField = chainIdentifierField.optional();
  *
  * @internal
  */ const MAX_RATE_ADDRESSES_PER_REQUEST = 100;
+/**
+ * Environment prefixes carried by Circle platform API keys.
+ *
+ * A Circle API key is `<ENV>_API_KEY:<keyId>:<keySecret>`, where `<ENV>` is one
+ * of these prefixes.
+ *
+ * @internal
+ */ const API_KEY_ENV_PREFIXES = [
+    'TEST',
+    'LIVE',
+    'SAND',
+    'SANDBOX',
+    'SMOK',
+    'PROD',
+    'STAG',
+    'DEV'
+];
+/**
+ * Accepted credential formats for Stablecoin Service authentication.
+ *
+ * Matches a Circle platform API key (`<ENV>_API_KEY:<keyId>:<keySecret>`) and
+ * the legacy kit key (`KIT_KEY:<keyId>:<keySecret>`). API keys are the
+ * recommended credential; kit keys remain accepted as the legacy path.
+ *
+ * @remarks
+ * This is a local pre-flight check, not the authority — the Stablecoin Service
+ * validates the credential and answers 401 when it rejects one. The prefix list
+ * is therefore deliberately permissive: a valid key carrying a prefix this SDK
+ * has not been taught about should reach the service and be judged there rather
+ * than be refused locally, since refusing locally is indistinguishable from an
+ * outage to the caller. Kept as the single source of truth so the pattern is
+ * not restated per call site.
+ *
+ * @internal
+ */ const API_KEY_PATTERN = new RegExp(`^(?:KIT_KEY|(?:${API_KEY_ENV_PREFIXES.join('|')})_API_KEY)` + ':[a-zA-Z0-9._-]+:[a-zA-Z0-9._-]+$');
 
 /**
  * Zod schema for validating stop limits.
@@ -20189,13 +21607,14 @@ const optionalChainIdentifierField = chainIdentifierField.optional();
 /**
  * Zod schema for validating API keys.
  *
- * Validates that the API key is a valid API key format.
+ * Accepts a Circle platform API key (`<ENV>_API_KEY:<keyId>:<keySecret>`) and
+ * the legacy kit key (`KIT_KEY:<keyId>:<keySecret>`).
  *
  * @example
  * ```typescript
  * import { apiKeySchema } from '@core/service-client'
  *
- * const result = apiKeySchema.safeParse('KIT_KEY:e84d2546d4e321b2ff427dc988c89503:f84d2548d4e322b2ff427fc989c87503')
+ * const result = apiKeySchema.safeParse('TEST_API_KEY:e84d2546d4e321b2ff427dc988c89503:f84d2548d4e322b2ff427fc989c87503')
  * if (!result.success) {
  *   console.error('Invalid API key format:', result.error.issues)
  * }
@@ -20203,7 +21622,7 @@ const optionalChainIdentifierField = chainIdentifierField.optional();
  */ const apiKeySchema = z.string({
     required_error: 'API key is required',
     invalid_type_error: 'Invalid API key format'
-}).regex(/^KIT_KEY:[a-zA-Z0-9._-]+:[a-zA-Z0-9._-]+$/, 'Invalid API key format');
+}).regex(API_KEY_PATTERN, 'Invalid API key format');
 /**
  * Zod schema for platform fees configuration.
  *
@@ -20727,8 +22146,8 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
  * Validates that an API key is properly formatted for Circle Stablecoin Service.
  *
  * This function performs validation on API keys to ensure they conform to the
- * expected format before making API requests. The key must follow the structure:
- * `KIT_KEY:keyId:keySecret`
+ * expected format before making API requests. The key must follow the structure
+ * `<ENV>_API_KEY:keyId:keySecret`, or the legacy `KIT_KEY:keyId:keySecret`.
  *
  * @param apiKey - The API key to validate (can be any type for graceful handling).
  * @returns True if the API key is valid, false otherwise.
@@ -20736,7 +22155,8 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
  * @remarks
  * This function handles invalid inputs gracefully by returning false rather than
  * throwing errors. It validates:
- * - The key starts with the `KIT_KEY:` prefix
+ * - The key carries a recognized prefix — `<ENV>_API_KEY:` for a Circle platform
+ *   API key, or `KIT_KEY:` for the legacy kit key
  * - Contains exactly three colon-separated parts
  * - keyId and keySecret contain only valid characters (alphanumeric, `-`, `_`, `.`)
  * - keyId and keySecret are non-empty
@@ -20744,40 +22164,80 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
  *
  * Valid characters in keyId and keySecret: `a-z`, `A-Z`, `0-9`, `-`, `_`, `.`
  *
+ * Format is checked locally only so an obviously malformed credential fails
+ * before a request is made. The Stablecoin Service remains the authority on
+ * whether a well-formed key is actually accepted.
+ *
  * @example
  * ```typescript
  * import { isValidApiKey } from '@core/service-client'
  *
  * // Valid API key
- * const isValid = isValidApiKey('KIT_KEY:e84d2546d4e321b2ff427dc988c89503:f84d2548d4e322b2ff427fc989c87503')
+ * const isValid = isValidApiKey('TEST_API_KEY:e84d2546d4e321b2ff427dc988c89503:f84d2548d4e322b2ff427fc989c87503')
  * console.log(isValid) // true
  *
+ * // Legacy kit keys remain valid
+ * console.log(isValidApiKey('KIT_KEY:my-key-id:my-key-secret')) // true
+ *
  * ```
  */ const isValidApiKey = (apiKey)=>{
     // Handle invalid input types
     if (typeof apiKey !== 'string') {
         return false;
     }
-    const apiKeyPattern = /^KIT_KEY:[a-zA-Z0-9._-]+:[a-zA-Z0-9._-]+$/;
     // Validate without trimming - any whitespace will cause validation to fail
-    return apiKeyPattern.test(apiKey);
+    return API_KEY_PATTERN.test(apiKey);
 };
 /**
- * Assert that a Stablecoin Service kit key is not being supplied from a browser.
+ * Resolve the credential to authenticate a Stablecoin Service request with.
+ *
+ * `apiKey` is the supported field; `kitKey` is the deprecated alias kept for
+ * existing integrations. When both are supplied `apiKey` wins, so a caller
+ * migrating field-by-field cannot be silently pinned to a stale credential.
  *
- * The kit key (`KIT_KEY:<id>:<secret>`) is a server-only secret. Every
- * Stablecoin Service request that attaches an `Authorization: Bearer` header
- * funnels through this package, so calling this guard before that header is
- * built prevents the secret from being sent from — and thus bundled into — a
- * client application. In Node.js the check is a no-op, preserving the
- * legitimate "hold the kit key on the server, forward the prepared transaction
- * to the client" flow. When no kit key is supplied the permissionless (keyless)
- * client path remains fully allowed.
+ * An empty-string value is treated as absent on either field. Without this, the
+ * common `process.env.CIRCLE_API_KEY ?? ''` idiom (which yields `''` when the
+ * variable is unset) would either shadow a working `kitKey` or, on a bare
+ * `kitKey: ''`, reach downstream validation as an invalid credential instead of
+ * falling through to the permissionless path.
+ *
+ * @param source - Object carrying either credential field, or neither.
+ * @returns The credential to use, or `undefined` for the permissionless
+ *   (keyless) path.
+ *
+ * @example
+ * ```typescript
+ * import { resolveApiKey } from '@core/service-client'
  *
- * @param apiKey - The inline kit key for the request, or `undefined` when none
- *   was supplied (permissionless mode).
+ * resolveApiKey({ apiKey: 'TEST_API_KEY:id:secret' }) // 'TEST_API_KEY:id:secret'
+ * resolveApiKey({ kitKey: 'KIT_KEY:id:secret' }) // 'KIT_KEY:id:secret'
+ * resolveApiKey({ apiKey: '', kitKey: 'KIT_KEY:id:secret' }) // 'KIT_KEY:id:secret'
+ * resolveApiKey({ kitKey: '' }) // undefined
+ * resolveApiKey({}) // undefined
+ * ```
+ */ const resolveApiKey = (source)=>{
+    // Treat an empty-string value as absent on either field so the
+    // `env ?? ''` idiom falls through to the next credential (or permissionless).
+    const normalize = (value)=>value !== undefined && value !== '' ? value : undefined;
+    return normalize(source.apiKey) ?? normalize(source.kitKey);
+};
+/**
+ * Assert that a Stablecoin Service credential is not supplied from a browser.
+ *
+ * An API key (`<ENV>_API_KEY:<id>:<secret>`) and a legacy kit key
+ * (`KIT_KEY:<id>:<secret>`) are both server-only secrets. Every Stablecoin
+ * Service request that attaches an `Authorization: Bearer` header funnels
+ * through this package, so calling this guard before that header is built
+ * prevents the secret from being sent from — and thus bundled into — a client
+ * application. In Node.js the check is a no-op, preserving the legitimate "hold
+ * the credential on the server, forward the prepared transaction to the client"
+ * flow. When no credential is supplied the permissionless (keyless) client path
+ * remains fully allowed.
+ *
+ * @param apiKey - The inline credential for the request, or `undefined` when
+ *   none was supplied (permissionless mode).
  * @returns Nothing.
- * @throws KitError with VALIDATION_FAILED when a kit key is supplied while
+ * @throws KitError with VALIDATION_FAILED when a credential is supplied while
  *   running in a browser environment. The secret value is never echoed.
  *
  * @example
@@ -20785,10 +22245,10 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
  * import { assertBrowserSafeApiKey } from '@core/service-client'
  *
  * // Server (Node.js): no-op, request proceeds with the Authorization header.
- * assertBrowserSafeApiKey('KIT_KEY:my-id:my-secret')
+ * assertBrowserSafeApiKey('TEST_API_KEY:my-id:my-secret')
  *
  * // Browser: throws to stop the secret from leaking into the client bundle.
- * assertBrowserSafeApiKey('KIT_KEY:my-id:my-secret')
+ * assertBrowserSafeApiKey('TEST_API_KEY:my-id:my-secret')
  *
  * // Browser, permissionless: allowed.
  * assertBrowserSafeApiKey(undefined)
@@ -20798,7 +22258,7 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
         return;
     }
     if (isBrowserEnvironment()) {
-        throw createValidationFailedError$1('kitKey', '[redacted]', 'kitKey must not be provided in a browser environment — it is a server-only secret. Run kit operations that use a kit key on your server, or omit kitKey to use the permissionless (keyless) client path');
+        throw createValidationFailedError$1('apiKey', '[redacted]', 'apiKey must not be provided in a browser environment — it is a server-only secret. Run kit operations that use an API key on your server, or omit apiKey (and the legacy kitKey) to use the permissionless (keyless) client path');
     }
 };
 
@@ -20810,7 +22270,8 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
  *
  * @remarks
  * - Input validation leverages Zod schemas to surface actionable KitErrors.
- * - API key format must match `KIT_KEY:<keyId>:<keySecret>`
+ * - API key format must match `<ENV>_API_KEY:<keyId>:<keySecret>`, or the
+ *   legacy `KIT_KEY:<keyId>:<keySecret>`
  *
  * @param params - The create transaction request parameters with API key.
  * @returns A promise that resolves to a typed {@link CreateSwapResponse}.
@@ -20839,7 +22300,7 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
  *       recipientAddress: '0x050928e1f9086b20539c767c96909663ff7fbdf2',
  *     },
  *   },
- *   apiKey: 'KIT_KEY:example-key:example-secret',
+ *   apiKey: 'TEST_API_KEY:example-key:example-secret',
  * })
  *
  * console.log(`Transaction target: ${transaction.transaction.target}`)
@@ -20858,13 +22319,13 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
     const url = new URL('/v1/stablecoinKits/swap', STABLECOIN_SERVICE_BASE_URL).toString();
     // Remove the API key from the request body
     const { apiKey, ...requestBody } = validatedParams;
-    // Never let a server-only kit key leave a browser (no-op in Node.js).
+    // Never let a server-only credential leave a browser (no-op in Node.js).
     assertBrowserSafeApiKey(apiKey);
     const effectiveConfig = {
         ...DEFAULT_CONFIG$1,
         headers: {
             ...DEFAULT_CONFIG$1.headers,
-            // Permissionless mode: no Authorization header when the kit key is absent.
+            // Permissionless mode: no Authorization header when the credential is absent.
             ...apiKey !== undefined && {
                 Authorization: `Bearer ${apiKey}`
             }
@@ -21014,7 +22475,7 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
     }
     // Use validated data
     const validatedParams = result.data;
-    // Never let a server-only kit key leave a browser (no-op in Node.js).
+    // Never let a server-only credential leave a browser (no-op in Node.js).
     assertBrowserSafeApiKey(validatedParams.apiKey);
     // Build the API URL
     const url = buildQuoteUrl(validatedParams);
@@ -21023,7 +22484,7 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
         ...DEFAULT_CONFIG$1,
         headers: {
             ...DEFAULT_CONFIG$1.headers,
-            // Permissionless mode: no Authorization header when the kit key is absent.
+            // Permissionless mode: no Authorization header when the credential is absent.
             ...validatedParams.apiKey !== undefined && {
                 Authorization: `Bearer ${validatedParams.apiKey}`
             }
@@ -21088,14 +22549,14 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
             toChain: result.data.toChain
         }
     };
-    // Never let a server-only kit key leave a browser (no-op in Node.js).
+    // Never let a server-only credential leave a browser (no-op in Node.js).
     assertBrowserSafeApiKey(validatedParams.apiKey);
     const url = buildSwapStatusUrl(validatedParams);
     const effectiveConfig = {
         ...DEFAULT_CONFIG$1,
         headers: {
             ...DEFAULT_CONFIG$1.headers,
-            // Permissionless mode: no Authorization header when the kit key is absent.
+            // Permissionless mode: no Authorization header when the credential is absent.
             ...validatedParams.apiKey !== undefined && {
                 Authorization: `Bearer ${validatedParams.apiKey}`
             }
@@ -21121,7 +22582,7 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
  * const url = buildTokenRatesUrl({
  *   chain: 'Ethereum',
  *   addresses: ['0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48'],
- *   apiKey: 'KIT_KEY:key:secret',
+ *   apiKey: 'TEST_API_KEY:key:secret',
  * })
  * // => 'https://api.circle.com/v1/stablecoinKits/rates?chain=Ethereum&addresses=...'
  * ```
@@ -21194,14 +22655,14 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
             addresses: result.data.addresses
         }
     };
-    // Never let a server-only kit key leave a browser (no-op in Node.js).
+    // Never let a server-only credential leave a browser (no-op in Node.js).
     assertBrowserSafeApiKey(validatedParams.apiKey);
     const url = buildTokenRatesUrl(validatedParams);
     const effectiveConfig = {
         ...DEFAULT_CONFIG$1,
         headers: {
             ...DEFAULT_CONFIG$1.headers,
-            // Permissionless mode: no Authorization header when the kit key is absent.
+            // Permissionless mode: no Authorization header when the credential is absent.
             ...validatedParams.apiKey !== undefined && {
                 Authorization: `Bearer ${validatedParams.apiKey}`
             }
@@ -23179,7 +24640,7 @@ const abiParameterSchema = z.object({
  */ z.object({
     type: z.literal('evm'),
     abi: abiSchema,
-    address: evmAddressSchema,
+    address: evmAddressSchema$1,
     functionName: z.string({
         required_error: 'Function name is required',
         invalid_type_error: 'Function name must be a string'
@@ -23216,7 +24677,7 @@ const abiParameterSchema = z.object({
  * }
  * ```
  */ z.object({
-    address: evmAddressSchema,
+    address: evmAddressSchema$1,
     value: z.bigint({
         required_error: 'Value is required for native transfers',
         invalid_type_error: 'Value must be a bigint'
@@ -24450,6 +25911,23 @@ async function signUnits(group, signingUnits) {
     }
     return signedSets;
 }
+/**
+ * Fail loudly if a signing group carries an intent it does not own.
+ *
+ * Every intent in a group is signed by `group.address`, so that signer must own
+ * each intent's `spec.sourceSigner`. If distinct spend sources ever collapse
+ * into one group again (DEVX-3638), this throws before signing instead of
+ * silently producing a wrong-signer signature. specs are bytes32 and
+ * `group.address` is a native address, so normalize both before comparing.
+ */ function assertGroupSignerOwnsIntents(group) {
+    if (group.address == null || group.address === '') return;
+    const groupSigner = convertAddress(group.address, 'bytes32').toLowerCase();
+    for (const intent of group.intents){
+        if (intent.spec.sourceSigner.toLowerCase() !== groupSigner) {
+            throw createValidationFailedError$1('group.address', group.address, `Signing group for ${group.address} carries an intent whose ` + `sourceSigner is ${intent.spec.sourceSigner}; a group must be signed ` + 'by the wallet that owns every intent it carries. This indicates ' + 'distinct spend sources collapsed into a single signing group.');
+        }
+    }
+}
 /**
  * Sign an EVM adapter group.
  *
@@ -24492,22 +25970,42 @@ async function signUnits(group, signingUnits) {
     // Validate the collection before doing bytecode reads or asking a wallet
     // to sign. evmSigningData owns the canonical BurnIntent validation.
     validateGroupIntents(group.intents);
+    // Guard against a wrong-signer collapse: the group's signer must own every
+    // intent it carries.
+    assertGroupSignerOwnsIntents(group);
     const chainsByDomain = collectChainsByDomain(group);
     const signerTypeByDomain = await classifySignerTypes(group, chainsByDomain);
     const signingUnits = createSigningUnits(group, signerTypeByDomain);
     return await signUnits(group, signingUnits);
 }
 
+// One adapter instance can serve several signer addresses (e.g. a single
+// dev-controlled adapter used for multiple wallets), so the group map must be
+// keyed on `(adapter, sourceSigner)` rather than the adapter reference alone.
+// Keying on the adapter alone collapsed two same-chain sources into one group,
+// signing the second wallet's intent with the first wallet (DEVX-3638 /
+// DEVX-3194). A Map needs a primitive key, so give each adapter instance a
+// stable token and combine it with the (case-normalized) signer address.
+const adapterTokens = new WeakMap();
+let nextAdapterToken = 0;
+function groupKey(alloc) {
+    let token = adapterTokens.get(alloc.adapter);
+    if (token === undefined) {
+        token = nextAdapterToken++;
+        adapterTokens.set(alloc.adapter, token);
+    }
+    return `${String(token)}:${alloc.sourceSigner.toLowerCase()}`;
+}
 /**
  * Add an EVM intent into the batched EVM group map.
  *
- * On EVM, all intents for the same adapter are batched into a single
- * group. The signing step uses `chainsByDomain` to preserve EOA batching
+ * On EVM, all intents for the same adapter **and signer** are batched into a
+ * single group. The signing step uses `chainsByDomain` to preserve EOA batching
  * while signing ERC-1271 intents separately on their source chains.
  *
  * @param intent - The burn intent to group.
  * @param alloc - The allocation that resolved to this intent.
- * @param evmGroups - Mutable map of adapter → EVM group.
+ * @param evmGroups - Mutable map of `(adapter, sourceSigner)` key → EVM group.
  *
  * @example
  * ```typescript
@@ -24517,12 +26015,13 @@ async function signUnits(group, signingUnits) {
  * groupEvmIntents(intent, alloc, groups)
  * ```
  */ function groupEvmIntents(intent, alloc, evmGroups) {
-    const existing = evmGroups.get(alloc.adapter);
+    const key = groupKey(alloc);
+    const existing = evmGroups.get(key);
     if (existing) {
         existing.intents.push(intent);
         existing.chainsByDomain.set(alloc.chain.gateway.domain, alloc.chain);
     } else {
-        evmGroups.set(alloc.adapter, {
+        evmGroups.set(key, {
             adapter: alloc.adapter,
             chain: alloc.chain,
             intents: [
@@ -24615,7 +26114,7 @@ z.object({
     signature: evmSignatureSchema,
     tokenInputs: z.array(z.object({
         permitType: z.nativeEnum(PermitType),
-        token: evmAddressSchema,
+        token: evmAddressSchema$1,
         amount: z.bigint().refine((value)=>value >= 0n, {
             message: 'amount must be a non-negative bigint'
         }),
@@ -25208,7 +26707,7 @@ function writeBytes32(buffer, hex, offset) {
 });
 
 /**
- * Assert that the kit key is valid for swap operations.
+ * Assert that the credential is valid for swap operations.
  *
  * @remarks
  * This validation is called when swap operations are executed, not at construction time.
@@ -25216,34 +26715,35 @@ function writeBytes32(buffer, hex, offset) {
  * at usage time rather than construction time.
  *
  * Validates:
- * - Kit key matches the required format (KIT_KEY:id:secret) when provided.
- *   An absent or empty kit key is permitted (permissionless mode) — the swap
- *   service now treats the key as optional.
+ * - The credential matches an accepted format when provided — a Circle API key
+ *   (`<ENV>_API_KEY:id:secret`) or a legacy kit key (`KIT_KEY:id:secret`).
+ *   An absent or empty credential is permitted (permissionless mode) — the swap
+ *   service treats the credential as optional.
  *
- * @param kitKey - The inline kit key from the swap operation config (optional)
- * @throws KitError with VALIDATION_FAILED if a kit key is provided but does not
- *   match the KIT_KEY:<keyId>:<keySecret> format
+ * @param apiKey - The inline credential from the swap operation config (optional)
+ * @throws KitError with VALIDATION_FAILED if a credential is provided but does
+ *   not match an accepted format
  *
  * @example
  * ```typescript
- * import { assertKitKey } from './assertKitKey'
+ * import { assertApiKey } from './assertApiKey'
  *
- * const kitKey = 'KIT_KEY:9d1bd085-bad2-4a2b-ae67-5814b85167c9:secretvalue'
+ * const apiKey = 'TEST_API_KEY:9d1bd085-bad2-4a2b-ae67-5814b85167c9:secretvalue'
  *
- * // Validate kit key before use
- * assertKitKey(kitKey)
+ * // Validate the credential before use
+ * assertApiKey(apiKey)
  * ```
- */ function assertKitKey(kitKey) {
-    // Permissionless mode: the swap service treats the kit key as optional, so an
-    // absent (or empty) key is valid. Only validate the format when a key is
+ */ function assertApiKey(apiKey) {
+    // Permissionless mode: the swap service treats the credential as optional, so
+    // an absent (or empty) value is valid. Only validate the format when one is
     // actually provided.
-    if (!kitKey) {
+    if (!apiKey) {
         return;
     }
-    const apiKeyResult = apiKeySchema.safeParse(kitKey);
+    const apiKeyResult = apiKeySchema.safeParse(apiKey);
     if (!apiKeyResult.success) {
         const errors = apiKeyResult.error.issues.map((issue)=>issue.message).join(', ');
-        throw createValidationFailedError$1('kitKey', REDACTED_KIT_KEY, `Invalid API key format. ${errors}. Expected format: KIT_KEY:<keyId>:<keySecret>. Get your free Kit Key at: https://developers.circle.com/w3s/keys#kit-keys`);
+        throw createValidationFailedError$1('apiKey', REDACTED_CREDENTIAL, `Invalid API key format. ${errors}. Expected format: <ENV>_API_KEY:<keyId>:<keySecret> (for example TEST_API_KEY:... or LIVE_API_KEY:...). Legacy KIT_KEY:<keyId>:<keySecret> values are still accepted. Get your key at: https://developers.circle.com/w3s/keys`);
     }
 }
 
@@ -25435,7 +26935,7 @@ const TOKEN_REGISTRY$4 = createTokenRegistry();
     }
     // Validate recipient address format matches the chain type
     if (chain.type === 'evm') {
-        const result = evmAddressSchema.safeParse(recipientAddress);
+        const result = evmAddressSchema$1.safeParse(recipientAddress);
         if (!result.success) {
             throw createInvalidAddressError(recipientAddress, chain.name, '0x-prefixed 42-character hex string (0x + 40 hex characters)');
         }
@@ -25497,7 +26997,7 @@ function resolveFeePayoutChain(tokenIn, tokenOut, sourceChain, destinationChain)
  *   to: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
  *   config: {
  *     slippageBps: 300,
- *     kitKey: 'KIT_KEY:...:...'  // Required inline kit key
+ *     apiKey: 'TEST_API_KEY:...:...'  // Inline credential (optional)
  *   }
  * }
  *
@@ -25535,18 +27035,17 @@ function resolveFeePayoutChain(tokenIn, tokenOut, sourceChain, destinationChain)
     validateResolvedAddress(resolvedTokenInAddress, chain);
     validateResolvedAddress(resolvedTokenOutAddress, destinationChain);
     validateResolvedAddress(to, destinationChain);
-    const kitKey = config?.kitKey;
-    // Validate the kit key format when one is provided (permissionless otherwise).
-    assertKitKey(kitKey);
+    const apiKey = resolveApiKey(config ?? {});
+    // Validate the credential format when one is provided (permissionless
+    // otherwise).
+    assertApiKey(apiKey);
     // Validate custom fee configuration if present
     const customFee = config?.customFee;
     if (customFee !== undefined) {
         const feePayoutChain = resolveFeePayoutChain(tokenIn, tokenOut, chain, destinationChain);
         validateCustomFeeConfig(customFee, feePayoutChain);
     }
-    // Build CreateSwapParams for service client
-    // Use object spread to conditionally include optional properties
-    // Note: Service client expects 'apiKey' field, so we map kitKey → apiKey
+    // Build CreateSwapParams for service client, spreading optional properties.
     const chainName = chain.chain // The API expects the Blockchain enum value format like "World_Chain"
     ;
     const destinationChainName = destinationChain.chain;
@@ -25581,9 +27080,9 @@ function resolveFeePayoutChain(tokenIn, tokenOut, sourceChain, destinationChain)
                 }
             }
         },
-        // Map kitKey → apiKey for the service client; omitted in permissionless mode.
-        ...kitKey ? {
-            apiKey: kitKey
+        // Omitted in permissionless mode.
+        ...apiKey ? {
+            apiKey
         } : {}
     };
 }
@@ -27487,9 +28986,9 @@ async function fetchSameChainStatusSnapshot({ isCrossChainSwap, txHash, chain, a
  * ```typescript
  * import { StablecoinServiceSwapProvider } from '@circle-fin/provider-stablecoin-service-swap'
  *
- * // Create provider with developer fee (1 USDC)
+ * // Create provider with developer fee (1 USDC).
+ * // Credentials are supplied per operation via `config.apiKey`, not here.
  * const provider = new StablecoinServiceSwapProvider({
- *   kitKey: process.env.STABLECOIN_KIT_API_KEY,
  *   customFee: {
  *     amount: '1000000', // 1 USDC in base units (6 decimals)
  *     recipientAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0'
@@ -28151,9 +29650,7 @@ async function fetchSameChainStatusSnapshot({ isCrossChainSwap, txHash, chain, a
    * import { createAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
    * import { Ethereum } from '@core/chains'
    *
-   * const provider = new StablecoinServiceSwapProvider({
-   *   kitKey: process.env.STABLECOIN_KIT_API_KEY
-   * })
+   * const provider = new StablecoinServiceSwapProvider()
    *
    * const adapter = createAdapterFromPrivateKey({
    *   privateKey: process.env.PRIVATE_KEY
@@ -28647,7 +30144,7 @@ const optionalSwapChainIdentifierField = swapChainIdentifierField.optional();
     /**
      * Fee recipient address (required).
      * Must be a valid EVM address or Solana address.
-     */ recipientAddress: z.string().refine((value)=>evmAddressSchema.safeParse(value).success || solanaAddressSchema.safeParse(value).success, {
+     */ recipientAddress: z.string().refine((value)=>evmAddressSchema$1.safeParse(value).success || solanaAddressSchema.safeParse(value).success, {
         message: 'recipientAddress must be a valid blockchain address: EVM (0x + 40 hex chars) or Solana (base58, 32-44 chars)'
     })
 }).strict();
@@ -28659,7 +30156,8 @@ const optionalSwapChainIdentifierField = swapChainIdentifierField.optional();
  * - slippageBps: Optional positive number for slippage tolerance
  * - stopLimit: Optional decimal string for minimum output
  * - customFee: Optional fee configuration
- * - kitKey: Optional string identifier
+ * - apiKey: Optional credential string
+ * - kitKey: Optional credential string (deprecated alias for apiKey)
  */ const swapConfigSchema = z.object({
     allowanceStrategy: allowanceStrategySchema$1.optional(),
     slippageBps: z.number().int().min(0).optional(),
@@ -28669,11 +30167,12 @@ const optionalSwapChainIdentifierField = swapChainIdentifierField.optional();
         attributeName: 'stopLimit'
     })(z.string())).optional(),
     customFee: swapCustomFeeSchema.optional(),
+    apiKey: z.string().optional(),
     kitKey: z.string().optional()
 });
 const swapDestinationSchema = z.object({
     chain: optionalSwapChainIdentifierField,
-    recipientAddress: z.string().refine((value)=>evmAddressSchema.safeParse(value).success || solanaAddressSchema.safeParse(value).success, {
+    recipientAddress: z.string().refine((value)=>evmAddressSchema$1.safeParse(value).success || solanaAddressSchema.safeParse(value).success, {
         message: 'recipientAddress must be a valid blockchain address: EVM (0x + 40 hex chars) or Solana (base58, 32-44 chars)'
     }).optional()
 }).strict();
@@ -30780,7 +32279,8 @@ const transformAmount = (value, direction, decimals)=>formatUnits(value, decimal
 /**
  * Helper to format the config section of a swap result, transforming fee amounts.
  *
- * Strips sensitive fields like kitKey from the config before returning.
+ * Strips the credential fields (`apiKey` and the deprecated `kitKey`) from the
+ * config before returning, so a result is safe to log or serialize.
  *
  * @param config - The swap config from the provider.
  * @param outputTokenTransform - The amount transformer for output-token-denominated values (fees and amountOut).
@@ -30789,11 +32289,11 @@ const transformAmount = (value, direction, decimals)=>formatUnits(value, decimal
     if (!config) {
         return undefined;
     }
-    // Remove kitKey from the config
-    const cloneConfig = {
-        ...config
-    };
-    delete cloneConfig.kitKey;
+    // Rebuild the config without any credential field. Filtering entries rather
+    // than deleting them avoids reading the deprecated `kitKey` property
+    // directly, and keeps the credential list in one place.
+    const credentialFields = CREDENTIAL_CONFIG_FIELDS;
+    const cloneConfig = Object.fromEntries(Object.entries(config).filter(([key])=>!credentialFields.includes(key)));
     if (Object.keys(cloneConfig).length === 0) {
         return undefined;
     }
@@ -30994,9 +32494,9 @@ const transformAmount = (value, direction, decimals)=>formatUnits(value, decimal
     try {
         // Step 1: Build quote params directly (no need for buildServiceParams)
         // Use chain.chain (Blockchain enum value like "World_Chain") not chain.name
-        // The kit key is optional (permissionless mode); when absent the quote is
-        // fetched without an Authorization header.
-        const kitKey = params.config?.kitKey;
+        // The credential is optional (permissionless mode); when absent the quote
+        // is fetched without an Authorization header.
+        const apiKey = resolveApiKey(params.config ?? {});
         // Resolve token aliases to addresses for the quote API
         // The quote endpoint requires resolved addresses, not aliases like 'USDC'
         const chain = params.from.chain;
@@ -31021,8 +32521,8 @@ const transformAmount = (value, direction, decimals)=>formatUnits(value, decimal
             ...params.config?.slippageBps !== undefined && {
                 slippageBps: params.config.slippageBps
             },
-            ...kitKey ? {
-                apiKey: kitKey
+            ...apiKey ? {
+                apiKey
             } : {}
         };
         // Step 2: Get quote from service
@@ -31426,7 +32926,7 @@ const sleep$2 = async (ms)=>new Promise((resolve)=>setTimeout(resolve, ms));
  * the service returns `receivingTokenDecimals`. When decimals are missing
  * the field is omitted entirely (never raw base units).
  *
- * @param params - `txHash`, `chainIn`, optional `chainOut`, and `kitKey`.
+ * @param params - `txHash`, `chainIn`, optional `chainOut`, and `apiKey`.
  * @returns A single snapshot of the swap's status.
  * @throws \{KitError\} If `chainIn` or `chainOut` is malformed.
  *
@@ -31442,7 +32942,7 @@ const sleep$2 = async (ms)=>new Promise((resolve)=>setTimeout(resolve, ms));
  *   txHash: result.txHash,
  *   chainIn: result.chainIn,
  *   chainOut: result.chainOut,
- *   kitKey: process.env.KIT_KEY ?? '',
+ *   apiKey: process.env.CIRCLE_API_KEY,
  * })
  * while (status.progress.status === 'PENDING') {
  *   await new Promise((r) => setTimeout(r, 3_000))
@@ -31450,7 +32950,7 @@ const sleep$2 = async (ms)=>new Promise((resolve)=>setTimeout(resolve, ms));
  *     txHash: result.txHash,
  *     chainIn: result.chainIn,
  *     chainOut: result.chainOut,
- *     kitKey: process.env.KIT_KEY ?? '',
+ *     apiKey: process.env.CIRCLE_API_KEY,
  *   })
  * }
  *
@@ -31468,14 +32968,15 @@ const sleep$2 = async (ms)=>new Promise((resolve)=>setTimeout(resolve, ms));
     const chainIn = normalizeChain(params.chainIn, 'chainIn');
     const chainOut = params.chainOut === undefined ? undefined : normalizeChain(params.chainOut, 'chainOut');
     const isCrossChain = chainOut !== undefined && chainOut !== chainIn;
+    const apiKey = resolveApiKey(params);
     const request = {
         txHash: params.txHash,
         chain: chainIn,
         ...isCrossChain && {
             toChain: chainOut
         },
-        ...params.kitKey ? {
-            apiKey: params.kitKey
+        ...apiKey ? {
+            apiKey
         } : {}
     };
     let raw = await getSwapStatus$2(request);
@@ -31554,9 +33055,9 @@ const isResultShape = (params)=>'result' in params;
  *
  * Two parameter shapes are accepted:
  *
- * - Pass the {@link SwapResult} directly: `{ result, kitKey, ... }`.
+ * - Pass the {@link SwapResult} directly: `{ result, apiKey, ... }`.
  *   Cleanest when chaining off `kit.swap()`.
- * - Pass discrete fields: `{ txHash, chainIn, chainOut?, kitKey, ... }`.
+ * - Pass discrete fields: `{ txHash, chainIn, chainOut?, apiKey, ... }`.
  *   Useful for resuming an in-flight swap from a persisted record.
  *
  * @param params - Wait configuration. See {@link WaitForSwapParams}.
@@ -31576,7 +33077,7 @@ const isResultShape = (params)=>'result' in params;
  *
  * const final = await waitForSwap({
  *   result,
- *   kitKey: process.env.KIT_KEY ?? '',
+ *   apiKey: process.env.CIRCLE_API_KEY,
  *   onProgress: (snapshot) => {
  *     console.log(snapshot.progress.substatus ?? snapshot.progress.status)
  *   },
@@ -31594,7 +33095,7 @@ const isResultShape = (params)=>'result' in params;
  *   txHash: '0x…',
  *   chainIn: 'Ethereum',
  *   chainOut: 'Base',
- *   kitKey: process.env.KIT_KEY ?? '',
+ *   apiKey: process.env.CIRCLE_API_KEY,
  * })
  * ```
  */ async function waitForSwap$1(params) {
@@ -31610,14 +33111,15 @@ const isResultShape = (params)=>'result' in params;
     const chainOut = isResultShape(params) ? params.result.chainOut : params.chainOut;
     // Delegate parameter validation (txHash, chainIn, chainOut) to
     // getSwapStatus so the same rules apply to both helpers.
+    const apiKey = resolveApiKey(params);
     const statusParams = {
         txHash,
         chainIn,
         ...chainOut !== undefined && {
             chainOut
         },
-        ...params.kitKey ? {
-            kitKey: params.kitKey
+        ...apiKey ? {
+            apiKey
         } : {}
     };
     const deadline = Date.now() + timeoutMs;
@@ -31741,7 +33243,7 @@ function resolveTokenEntry(entry, index, chain, chainDef, context) {
  *
  * @param context - SwapKit context (provides the `TokenRegistry` used for
  *                  symbol resolution).
- * @param params - `chain`, optional `tokens`, and `kitKey`.
+ * @param params - `chain`, optional `tokens`, and `apiKey`.
  * @returns A nested map of `[chain][address] → { priceUSD, fetchedAt }`.
  * @throws \{KitError\} If `chain` cannot be resolved, `tokens` exceeds 100
  *         entries, or any entry is neither a registered symbol nor a
@@ -31756,7 +33258,7 @@ function resolveTokenEntry(entry, index, chain, chainDef, context) {
  * const { rates } = await getTokenRates(context, {
  *   chain: Blockchain.Ethereum,
  *   tokens: ['USDC', 'EURC', 'NATIVE'],
- *   kitKey: process.env.KIT_KEY ?? '',
+ *   apiKey: process.env.CIRCLE_API_KEY,
  * })
  *
  * const usdc = rates['Ethereum']?.['0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48']
@@ -31777,10 +33279,11 @@ function resolveTokenEntry(entry, index, chain, chainDef, context) {
     // valid Blockchain enum string, so `getChainByEnum` is guaranteed to resolve.
     const chainDef = getChainByEnum(chain);
     const resolvedAddresses = params.tokens?.map((entry, index)=>resolveTokenEntry(entry, index, chain, chainDef, context));
+    const apiKey = resolveApiKey(params);
     return getTokenRates$2({
         chain,
-        ...params.kitKey ? {
-            apiKey: params.kitKey
+        ...apiKey ? {
+            apiKey
         } : {},
         ...resolvedAddresses !== undefined && {
             addresses: resolvedAddresses
@@ -32411,7 +33914,7 @@ function resolveTokenEntry(entry, index, chain, chainDef, context) {
    * is formatted as a human-readable decimal string; when decimals are
    * missing the field is omitted entirely (never raw base units).
    *
-   * @param params - `txHash`, `chainIn`, optional `chainOut`, and `kitKey`.
+   * @param params - `txHash`, `chainIn`, optional `chainOut`, and `apiKey`.
    * @returns A snapshot of the swap's status at the time of the call.
    * @throws \{KitError\} If `chainIn` or `chainOut` is malformed.
    *
@@ -32424,7 +33927,7 @@ function resolveTokenEntry(entry, index, chain, chainDef, context) {
    *   txHash: result.txHash,
    *   chainIn: result.chainIn,
    *   chainOut: result.chainOut,
-   *   kitKey: process.env.KIT_KEY ?? '',
+   *   apiKey: process.env.CIRCLE_API_KEY,
    * })
    * console.log(status.progress.status, status.progress.substatus)
    * ```
@@ -32436,7 +33939,7 @@ function resolveTokenEntry(entry, index, chain, chainDef, context) {
    *   txHash: result.txHash,
    *   chainIn: result.chainIn,
    *   chainOut: result.chainOut,
-   *   kitKey: process.env.KIT_KEY ?? '',
+   *   apiKey: process.env.CIRCLE_API_KEY,
    * })
    * while (status.progress.status === 'PENDING') {
    *   await new Promise((r) => setTimeout(r, 3_000))
@@ -32444,7 +33947,7 @@ function resolveTokenEntry(entry, index, chain, chainDef, context) {
    *     txHash: result.txHash,
    *     chainIn: result.chainIn,
    *     chainOut: result.chainOut,
-   *     kitKey: process.env.KIT_KEY ?? '',
+   *     apiKey: process.env.CIRCLE_API_KEY,
    *   })
    * }
    *
@@ -32475,7 +33978,7 @@ function resolveTokenEntry(entry, index, chain, chainDef, context) {
    * 5xx, etc.) surface unchanged so the caller can decide whether to
    * retry the whole wait. The wait itself only emits a timeout error.
    *
-   * @param params - Wait configuration including identifiers, kit key,
+   * @param params - Wait configuration including identifiers, API key,
    *                 optional `timeoutMs`, and an optional `onProgress`
    *                 callback fired on every successful poll.
    * @returns The first terminal {@link SwapStatusResult} observed.
@@ -32494,7 +33997,7 @@ function resolveTokenEntry(entry, index, chain, chainDef, context) {
    *
    * const final = await kit.waitForSwap({
    *   result,
-   *   kitKey: process.env.KIT_KEY ?? '',
+   *   apiKey: process.env.CIRCLE_API_KEY,
    *   onProgress: (snap) => console.log(snap.progress.substatus ?? snap.progress.status),
    * })
    *
@@ -32512,7 +34015,7 @@ function resolveTokenEntry(entry, index, chain, chainDef, context) {
    *   txHash: persisted.txHash,
    *   chainIn: persisted.chainIn,
    *   chainOut: persisted.chainOut,
-   *   kitKey: process.env.KIT_KEY ?? '',
+   *   apiKey: process.env.CIRCLE_API_KEY,
    * })
    * ```
    */ async waitForSwap(params) {
@@ -32546,7 +34049,7 @@ function resolveTokenEntry(entry, index, chain, chainDef, context) {
    * not cache a rate for the native asset on that chain, the response simply
    * omits the address.
    *
-   * @param params - `chain`, optional `tokens`, and `kitKey`.
+   * @param params - `chain`, optional `tokens`, and `apiKey`.
    * @returns A nested map of `[chain][address] → { priceUSD, fetchedAt }`.
    * @throws \{KitError\} If `chain` is malformed, `tokens` exceeds 100
    *         entries, or any entry is neither a registered symbol nor a
@@ -32558,7 +34061,7 @@ function resolveTokenEntry(entry, index, chain, chainDef, context) {
    * const { rates } = await kit.getTokenRates({
    *   chain: 'Ethereum',
    *   tokens: ['USDC', 'EURC', 'NATIVE'],
-   *   kitKey: process.env.KIT_KEY ?? '',
+   *   apiKey: process.env.CIRCLE_API_KEY,
    * })
    *
    * const usdc = rates['Ethereum']?.['0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48']
@@ -32572,7 +34075,7 @@ function resolveTokenEntry(entry, index, chain, chainDef, context) {
    *   chain: 'Ethereum',
    *   // 'USDC' (registry symbol) + raw USDT address
    *   tokens: ['USDC', '0xdAC17F958D2ee523a2206206994597C13D831ec7'],
-   *   kitKey: process.env.KIT_KEY ?? '',
+   *   apiKey: process.env.CIRCLE_API_KEY,
    * })
    * ```
    *
@@ -32581,7 +34084,7 @@ function resolveTokenEntry(entry, index, chain, chainDef, context) {
    * ```typescript
    * const { rates } = await kit.getTokenRates({
    *   chain: 'Base',
-   *   kitKey: process.env.KIT_KEY ?? '',
+   *   apiKey: process.env.CIRCLE_API_KEY,
    * })
    * ```
    */ async getTokenRates(params) {
@@ -32943,7 +34446,7 @@ registerKit(`${pkg$3.name}/${pkg$3.version}`);
 };
 
 var name$2 = "@circle-fin/earn-kit";
-var version$2 = "1.5.1";
+var version$2 = "1.6.0";
 var pkg$2 = {
 	name: name$2,
 	version: version$2};
@@ -33159,7 +34662,7 @@ function toSdkChain(chain) {
  *
  * @internal
  */ function assertHexAddress(field, value, message = `${field} must be a 0x-prefixed 20-byte hex address`) {
-    const result = evmAddressSchema.safeParse(value);
+    const result = evmAddressSchema$1.safeParse(value);
     if (!result.success) {
         throw createValidationFailedError$1(field, value, message);
     }
@@ -34845,7 +36348,7 @@ const EARN_OPERATIONS = new Set([
     // Store the original service params non-enumerably. `retry()` reads them by
     // direct property access (`trace.params`), but JSON.stringify, console.log,
     // and telemetry serializers skip non-enumerable properties — so a
-    // permissioned call's `config.kitKey` (a `KIT_KEY:<id>:<secret>` value) and
+    // permissioned call's `config.apiKey` (a credential value) and
     // the in-memory adapter never leak through a logged error. defineProperty
     // also redefines any enumerable `params` an upstream trace may have carried.
     Object.defineProperty(trace, 'params', {
@@ -34916,7 +36419,7 @@ function isNonNegativeBigIntLike(value) {
     }
 }
 const hexSignatureSchema = evmSignatureSchema;
-const hexAddressSchema = evmAddressSchema;
+const hexAddressSchema = evmAddressSchema$1;
 // '0x' prefix + 32 bytes * 2 hex chars.
 const BYTES32_HEX_LENGTH = 66;
 const bridgeFeeTokenSchema = hexAddressSchema;
@@ -35885,7 +37388,7 @@ const bridgeDepositPrepareReviewSchema = z.object({
 }
 
 var name$1 = "@circle-fin/provider-earn-service";
-var version$1 = "1.4.1";
+var version$1 = "1.5.0";
 var pkg$1 = {
 	name: name$1,
 	version: version$1};
@@ -35947,10 +37450,12 @@ var pkg$1 = {
  *
  * @internal
  */ function buildConfig(serviceConfig) {
-    // The kit key is a server-only secret. Reject it in the browser so it cannot
-    // leak into a client bundle (no-op in Node.js). Keyless usage stays allowed.
-    if (serviceConfig?.kitKey !== undefined && isBrowserEnvironment()) {
-        throw createValidationFailedError$1('kitKey', '[redacted]', 'kitKey must not be provided in a browser environment — it is a server-only secret. Run EarnKit operations that use a kit key on your server, or omit kitKey to use the permissionless (keyless) client path');
+    const apiKey = resolveApiKey(serviceConfig ?? {});
+    // The credential is a server-only secret. Reject it in the browser so it
+    // cannot leak into a client bundle (no-op in Node.js). Keyless usage stays
+    // allowed.
+    if (apiKey !== undefined && isBrowserEnvironment()) {
+        throw createValidationFailedError$1('apiKey', '[redacted]', 'apiKey must not be provided in a browser environment — it is a server-only secret. Run EarnKit operations that use an API key on your server, or omit apiKey (and the legacy kitKey) to use the permissionless (keyless) client path');
     }
     const baseUrl = serviceConfig?.baseUrl ?? EARN_SERVICE_BASE_URL;
     // The API CORS policy does not allow this custom header. Keep the existing
@@ -35959,7 +37464,7 @@ var pkg$1 = {
     const sdkVersionHeader = isNodeEnvironment() ? {
         [SDK_VERSION_HEADER]: resolveSdkVersionHeader()
     } : {};
-    if (serviceConfig?.kitKey === undefined) {
+    if (apiKey === undefined) {
         return {
             pollingConfig: {
                 ...DEFAULT_CONFIG,
@@ -35971,11 +37476,11 @@ var pkg$1 = {
             baseUrl
         };
     }
-    if (!isValidApiKey(serviceConfig.kitKey)) {
+    if (!isValidApiKey(apiKey)) {
         throw new KitError({
             ...InputError.VALIDATION_FAILED,
             recoverability: 'FATAL',
-            message: 'Invalid kitKey format. Expected KIT_KEY:<keyId>:<keySecret>.'
+            message: 'Invalid apiKey format. Expected <ENV>_API_KEY:<keyId>:<keySecret> (for example TEST_API_KEY:...), or a legacy KIT_KEY:<keyId>:<keySecret>.'
         });
     }
     return {
@@ -35984,7 +37489,7 @@ var pkg$1 = {
             headers: {
                 ...DEFAULT_CONFIG.headers,
                 ...sdkVersionHeader,
-                Authorization: `Bearer ${serviceConfig.kitKey}`
+                Authorization: `Bearer ${apiKey}`
             }
         },
         baseUrl
@@ -37301,9 +38806,9 @@ function finishElapsedWait(lastStatus, lastError) {
  * // Permissionless mode
  * const provider = new EarnServiceProvider()
  *
- * // Permissioned mode with Kit Key
+ * // Permissioned mode with an API key
  * const provider = new EarnServiceProvider({
- *   kitKey: 'KIT_KEY:keyId:keySecret',
+ *   apiKey: 'TEST_API_KEY:keyId:keySecret',
  * })
  *
  * // Custom base URL for testing
@@ -38530,7 +40035,7 @@ function findProvider(context, chain, operation = 'earn') {
  * fast instead of round-tripping to the service.
  *
  * @internal
- */ const recipientEvmAddressSchema = evmAddressSchema.refine((address)=>!ZERO_EVM_ADDRESS_REGEX.test(address), 'address must not be the zero address').refine(isValidEip55Checksum, 'address has an invalid EIP-55 checksum');
+ */ const recipientEvmAddressSchema = evmAddressSchema$1.refine((address)=>!ZERO_EVM_ADDRESS_REGEX.test(address), 'address must not be the zero address').refine(isValidEip55Checksum, 'address has an invalid EIP-55 checksum');
 /**
  * Schema for the adapter context within earn operations.
  *
@@ -38562,19 +40067,39 @@ const sourceAdapterContextSchema = z.object({
 /**
  * Schema for the EarnConfig options.
  *
- * Validate the optional Kit Key field using the standard `apiKeySchema`
- * format (`KIT_KEY:<keyId>:<keySecret>`). When omitted, the SDK
- * operates in permissionless mode. `baseUrl` overrides the Earn Service
- * endpoint (e.g. staging); `batchTransactions: false` opts out of atomic
- * batched execution. Both are forwarded to the provider, so this `.strict()`
- * schema must accept them or a valid config object is rejected.
+ * Validate the *resolved* credential using the standard `apiKeySchema` format
+ * (`<ENV>_API_KEY:<keyId>:<keySecret>`, or a legacy
+ * `KIT_KEY:<keyId>:<keySecret>`). `apiKey` takes precedence over the deprecated
+ * `kitKey`, so a malformed `kitKey` that is being ignored must not fail a config
+ * that supplies a valid `apiKey` (and vice versa) — only the credential that
+ * would actually be sent is format-checked. When neither is supplied the SDK
+ * operates in permissionless mode. `baseUrl` overrides the Earn Service endpoint
+ * (e.g. staging); `batchTransactions: false` opts out of atomic batched
+ * execution. All are forwarded to the provider, so this `.strict()` schema must
+ * accept them or a valid config object is rejected.
  *
  * @internal
  */ const earnConfigSchema = z.object({
-    kitKey: apiKeySchema.optional(),
+    apiKey: z.string().optional(),
+    kitKey: z.string().optional(),
     baseUrl: z.string().optional(),
     batchTransactions: z.boolean().optional()
-}).strict();
+}).strict().superRefine((config, ctx)=>{
+    const credential = resolveApiKey(config);
+    if (credential === undefined) {
+        return;
+    }
+    const result = apiKeySchema.safeParse(credential);
+    if (!result.success) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: [
+                credential === config.apiKey ? 'apiKey' : 'kitKey'
+            ],
+            message: result.error.issues[0]?.message ?? 'Invalid API key format'
+        });
+    }
+});
 /**
  * Canonical decimal form: a leading digit with no leading zeros (a single
  * '0' is only allowed immediately before the decimal point). Rejects the
@@ -38646,7 +40171,7 @@ const sourceAdapterContextSchema = z.object({
  * currently supports EVM vault addresses on Arc Testnet.
  *
  * @internal
- */ const vaultAddressSchema = evmAddressSchema.refine(isValidEip55Checksum, 'address has an invalid EIP-55 checksum');
+ */ const vaultAddressSchema = evmAddressSchema$1.refine(isValidEip55Checksum, 'address has an invalid EIP-55 checksum');
 /**
  * Validation schema for VaultQuery.
  *
@@ -38921,7 +40446,7 @@ const sameChainGetDepositQuoteParamsSchema = z.object({
 const crossChainGetDepositQuoteParamsSchema = z.object({
     from: sourceAdapterContextSchema,
     chain: earnBridgeDestinationChainIdentifierSchema,
-    address: evmAddressSchema,
+    address: evmAddressSchema$1,
     vaultAddress: vaultAddressSchema,
     amount: amountSchema$1,
     transferSpeed: z.enum([
@@ -41237,7 +42762,7 @@ const tokens = createTokenRegistry();
  *
  * @param context - AppKit context.
  * @param params - `txHash` and `chainIn`, plus optional `chainOut` and
- *   `kitKey`.
+ *   `apiKey`.
  * @returns A snapshot of the swap's status at the time of the call.
  *
  * @example
@@ -41251,7 +42776,7 @@ const tokens = createTokenRegistry();
  *   txHash: result.txHash,
  *   chainIn: result.chainIn,
  *   chainOut: result.chainOut,
- *   kitKey: process.env.KIT_KEY ?? '',
+ *   apiKey: process.env.CIRCLE_API_KEY,
  * })
  *
  * console.log(status.progress.status, status.progress.substatus)
@@ -41274,7 +42799,7 @@ const tokens = createTokenRegistry();
  * `timeoutMs` elapses.
  *
  * @param context - AppKit context.
- * @param params - Wait configuration, including identifiers, kit key,
+ * @param params - Wait configuration, including identifiers, API key,
  *                 optional `timeoutMs`, and an optional `onProgress`
  *                 callback.
  * @returns The first terminal {@link SwapStatusResult} observed.
@@ -41290,7 +42815,7 @@ const tokens = createTokenRegistry();
  *   txHash: result.txHash,
  *   chainIn: result.chainIn,
  *   chainOut: result.chainOut,
- *   kitKey: process.env.KIT_KEY ?? '',
+ *   apiKey: process.env.CIRCLE_API_KEY,
  *   onProgress: (snap) => console.log(snap.progress.status),
  * })
  *
@@ -41326,7 +42851,7 @@ const tokens = createTokenRegistry();
  * addresses before indexing into `result.rates[chain]`.
  *
  * @param context - AppKit context.
- * @param params - `chain`, plus optional `tokens` and `kitKey`.
+ * @param params - `chain`, plus optional `tokens` and `apiKey`.
  * @returns A nested map of `[chain][address] → { priceUSD, fetchedAt }`.
  *
  * @example
@@ -41337,7 +42862,7 @@ const tokens = createTokenRegistry();
  * const { rates } = await kit.getTokenRates({
  *   chain: 'Ethereum',
  *   tokens: ['USDC'],
- *   kitKey: process.env.KIT_KEY ?? '',
+ *   apiKey: process.env.CIRCLE_API_KEY,
  * })
  *
  * const usdc = rates['Ethereum']?.['0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48']
@@ -41348,6 +42873,43 @@ const tokens = createTokenRegistry();
     return kit.getTokenRates(params);
 };
 
+const BRIDGE_FILTER_KEYS = new Set([
+    'chainType',
+    'isTestnet',
+    'forwarderSupported',
+    'sourceFeeSupported'
+]);
+function assertBridgeSupportedChainsOptions(options) {
+    if (options === undefined) {
+        return;
+    }
+    if (options === null || typeof options !== 'object' || Array.isArray(options)) {
+        throw createValidationFailedError$1('options', options, 'Bridge chain filters must be an object');
+    }
+    const entries = Object.entries(options);
+    if (entries.length === 0 || entries.some(([key])=>!BRIDGE_FILTER_KEYS.has(key))) {
+        throw createValidationFailedError$1('options', options, 'Bridge chain filters must contain only supported filter properties');
+    }
+    const record = options;
+    for (const key of [
+        'isTestnet',
+        'forwarderSupported',
+        'sourceFeeSupported'
+    ]){
+        if (record[key] !== undefined && typeof record[key] !== 'boolean') {
+            throw createValidationFailedError$1(`options.${key}`, record[key], 'Bridge chain boolean filters must be true or false');
+        }
+    }
+    const chainType = record['chainType'];
+    if (chainType !== undefined) {
+        const chainTypes = Array.isArray(chainType) ? chainType : [
+            chainType
+        ];
+        if (chainTypes.length === 0 || chainTypes.some((value)=>value !== 'evm' && value !== 'solana')) {
+            throw createValidationFailedError$1('options.chainType', chainType, "Bridge chain type must be 'evm', 'solana', or an array of those values");
+        }
+    }
+}
 /**
  * Get chains supported by AppKit operations.
  *
@@ -41362,6 +42924,7 @@ const tokens = createTokenRegistry();
  * @param context - AppKit context containing fee configuration.
  * @param operationType - Optional operation type to filter chains ('bridge' | 'swap' | 'earn' | 'unifiedBalance').
  * @param unifiedBalance - Persistent AppKitUnifiedBalance namespace instance.
+ * @param bridgeOptions - Optional Bridge Kit chain filters. Requires `operationType: 'bridge'`.
  * @returns Array of unique chain definitions supporting the specified operation(s)
  *
  * @example Get all supported chains via AppKit
@@ -41380,6 +42943,13 @@ const tokens = createTokenRegistry();
  * console.log('Chains supporting bridge:', bridgeChains.map(c => c.name))
  * ```
  *
+ * @example Get chains that support source-paid bridge fees
+ * ```typescript
+ * const sourceFeeChains = kit.getSupportedChains('bridge', {
+ *   sourceFeeSupported: true,
+ * })
+ * ```
+ *
  * @example Get swap-specific chains
  * ```typescript
  * const swapChains = kit.getSupportedChains('swap')
@@ -41400,7 +42970,8 @@ const tokens = createTokenRegistry();
  * const supportsEthBridge = bridgeChains.some(c => c.chain === Ethereum.chain)
  * console.log(`Ethereum supports bridge: ${supportsEthBridge}`)
  * ```
- */ const getSupportedChains$2 = (context, operationType, unifiedBalance)=>{
+ */ const getSupportedChains$2 = (context, operationType, unifiedBalance, bridgeOptions)=>{
+    assertBridgeSupportedChainsOptions(bridgeOptions);
     // Runtime validation when operationType is provided
     if (operationType !== undefined && operationType !== 'bridge' && operationType !== 'swap' && operationType !== 'earn' && operationType !== 'unifiedBalance') {
         throw new KitError({
@@ -41409,10 +42980,13 @@ const tokens = createTokenRegistry();
             message: `Invalid operationType: "${String(operationType)}". Expected 'bridge', 'swap', 'earn', or 'unifiedBalance'.`
         });
     }
+    if (bridgeOptions !== undefined && operationType !== 'bridge') {
+        throw createValidationFailedError$1('options', bridgeOptions, "Bridge chain filters require operationType 'bridge'");
+    }
     // Return bridge-specific chains
     if (operationType === 'bridge') {
         const bridgeKit = createBridgeKit(context);
-        return bridgeKit.getSupportedChains();
+        return bridgeKit.getSupportedChains(bridgeOptions);
     }
     // Return swap-specific chains
     if (operationType === 'swap') {
@@ -41750,7 +43324,7 @@ async function deposit$2(context, params) {
 }
 
 var name = "@circle-fin/unified-balance-kit";
-var version = "1.4.1";
+var version = "1.5.0";
 var pkg = {
 	name: name,
 	version: version};
@@ -42583,6 +44157,8 @@ const gatewayInfoSchema = z.object({
  * Fetch Gateway info from the `/v1/info` endpoint.
  *
  * @param isTestnet - Whether to query the testnet or mainnet API.
+ * @param config - Optional polling config overrides, including custom
+ *   `headers` forwarded with the request.
  * @returns Parsed Gateway info including per-domain processed heights.
  * @throws KitError on HTTP failure or invalid response.
  *
@@ -42591,11 +44167,11 @@ const gatewayInfoSchema = z.object({
  * const info = await fetchGatewayInfo(true)
  * console.log(info.domains.map(d => `${d.chain}: ${d.processedHeight}`))
  * ```
- */ async function fetchGatewayInfo(isTestnet) {
+ */ async function fetchGatewayInfo(isTestnet, config) {
     const apiBaseUrl = getGatewayApiBaseUrl(isTestnet);
     const url = `${apiBaseUrl}/v1/info`;
     try {
-        return await pollApiGet(url, assertGatewayInfoResponse);
+        return await pollApiGet(url, assertGatewayInfoResponse, config);
     } catch (error) {
         if (error instanceof KitError) {
             throw error;
@@ -42621,6 +44197,8 @@ const gatewayInfoSchema = z.object({
  *
  * @param isTestnet - Whether to query the testnet or mainnet API.
  * @param domain - The Gateway domain number (e.g. 0 = Ethereum, 6 = Base).
+ * @param config - Optional polling config overrides, including custom
+ *   `headers` forwarded with the `/v1/info` request.
  * @returns The processed height as a bigint.
  * @throws KitError when the domain is not found in the response.
  *
@@ -42629,10 +44207,10 @@ const gatewayInfoSchema = z.object({
  * const height = await getProcessedHeight(true, 6) // Base Sepolia
  * console.log(`Gateway processed up to block ${height}`)
  * ```
- */ async function getProcessedHeight(isTestnet, domain) {
+ */ async function getProcessedHeight(isTestnet, domain, config) {
     // No caching in v1 — /v1/info is cheap and delegate status checks
     // are infrequent. Revisit if rate-limit or latency issues appear.
-    const info = await fetchGatewayInfo(isTestnet);
+    const info = await fetchGatewayInfo(isTestnet, config);
     const entry = info.domains.find((d)=>d.domain === domain);
     if (!entry) {
         throw new KitError({
@@ -43098,12 +44676,22 @@ function throwNetworkMismatch(expected, actual) {
  * @param allocations - Normalized allocations used to map domain → adapter/chain.
  * @returns Array of groups, each with adapter, chain, and intents to sign.
  */ function groupIntentsByAdapter(intents, allocations) {
+    // Keyed by `(adapter, sourceSigner)` (see groupEvmIntents), not by adapter
+    // alone: two spend sources on the same chain — including two addresses behind
+    // one shared adapter — must stay in separate signing groups.
     const evmGroups = new Map();
     const solanaGroups = [];
     for (const intent of intents){
-        const alloc = allocations.find((a)=>a.chain.gateway.domain === intent.spec.sourceDomain);
+        // Match each intent back to its source allocation by BOTH Gateway domain
+        // and signer. Two spend sources on the same chain share a domain, so
+        // matching on domain alone always returned the FIRST allocation — folding
+        // the second wallet's intent into the first wallet's signing group so it
+        // was signed by the wrong wallet (DEVX-3638). specs carry sourceSigner as
+        // bytes32 and allocations carry native addresses, so normalize both.
+        const intentSigner = intent.spec.sourceSigner.toLowerCase();
+        const alloc = allocations.find((a)=>a.chain.gateway.domain === intent.spec.sourceDomain && convertAddress(a.sourceSigner, 'bytes32').toLowerCase() === intentSigner);
         if (!alloc) {
-            throw createValidationFailedError$1('intent.spec.sourceDomain', intent.spec.sourceDomain, `No allocation found for sourceDomain ${String(intent.spec.sourceDomain)}; ` + 'estimate response contains an intent that does not match any allocation');
+            throw createValidationFailedError$1('intent.spec.sourceDomain', intent.spec.sourceDomain, `No allocation found for sourceDomain ${String(intent.spec.sourceDomain)} and sourceSigner ${String(intent.spec.sourceSigner)}; ` + 'estimate response contains an intent that does not match any allocation');
         }
         if (alloc.chain.type === 'solana') {
             solanaGroups.push(groupSolanaIntents(intent, alloc));
@@ -45004,12 +46592,12 @@ const FORWARDER_POLL_TIMEOUT_MS = 300_000;
  *   exceeds the 5-minute timeout without reaching a terminal status.
  * @throws KitError Propagated from {@link pollApiGet} if the HTTP
  *   request itself fails or returns a non-OK response.
- */ async function pollForwarderCompletion(apiBaseUrl, transferId) {
+ */ async function pollForwarderCompletion(apiBaseUrl, transferId, requestConfig) {
     const startTime = Date.now();
     while(Date.now() - startTime < FORWARDER_POLL_TIMEOUT_MS){
         let status;
         try {
-            status = await pollApiGet(`${apiBaseUrl}/v1/transfer/${transferId}`, assertGatewayTransferDetails);
+            status = await pollApiGet(`${apiBaseUrl}/v1/transfer/${transferId}`, assertGatewayTransferDetails, requestConfig);
         } catch (error) {
             throwGatewayApiError(error);
         }
@@ -45127,7 +46715,7 @@ const FORWARDER_POLL_TIMEOUT_MS = 300_000;
  * @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) {
+ */ async function fetchChainBalances(params, destChain, requestConfig) {
     const rawSources = Array.isArray(params.from) ? params.from : [
         params.from
     ];
@@ -45156,7 +46744,7 @@ const FORWARDER_POLL_TIMEOUT_MS = 300_000;
             token: params.token,
             sources: querySource,
             networkType
-        });
+        }, requestConfig);
     }));
     const chainBalances = [];
     for(let i = 0; i < balanceResults.length; i++){
@@ -45229,9 +46817,9 @@ const FORWARDER_POLL_TIMEOUT_MS = 300_000;
  * @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) {
+ */ async function resolveAllocationsAndIntents(params, destChain, recipientAddress, useForwarder, requestConfig) {
     if (params.amountIn) {
-        const chainBalances = await fetchChainBalances(params, destChain);
+        const chainBalances = await fetchChainBalances(params, destChain, requestConfig);
         const { allocations, intents } = await buildAutoAllocatedFromBalances(params, destChain, recipientAddress, useForwarder, params.amountIn, chainBalances);
         return {
             allocations,
@@ -45254,11 +46842,11 @@ const FORWARDER_POLL_TIMEOUT_MS = 300_000;
  * @param useForwarder - Whether the Forwarding Service path is active.
  * @param allocations - Normalised allocations (forwarded to error handler).
  * @returns Estimate entries and optional forwarding fee.
- */ async function fetchEstimate(apiBaseUrl, estimateBody, useForwarder, allocations) {
+ */ async function fetchEstimate(apiBaseUrl, estimateBody, useForwarder, allocations, requestConfig) {
     if (useForwarder) {
         let fwdResponse;
         try {
-            fwdResponse = await pollApiPost(`${apiBaseUrl}/v1/estimate?enableForwarder=true`, estimateBody, assertGatewayForwarderEstimateResponse);
+            fwdResponse = await pollApiPost(`${apiBaseUrl}/v1/estimate?enableForwarder=true`, estimateBody, assertGatewayForwarderEstimateResponse, requestConfig);
         } catch (error) {
             throwGatewayApiError(error, allocations);
         }
@@ -45269,7 +46857,7 @@ const FORWARDER_POLL_TIMEOUT_MS = 300_000;
     }
     let entries;
     try {
-        entries = await pollApiPost(`${apiBaseUrl}/v1/estimate`, estimateBody, assertGatewayEstimateResponse);
+        entries = await pollApiPost(`${apiBaseUrl}/v1/estimate`, estimateBody, assertGatewayEstimateResponse, requestConfig);
     } catch (error) {
         throwGatewayApiError(error, allocations);
     }
@@ -45340,14 +46928,14 @@ const FORWARDER_POLL_TIMEOUT_MS = 300_000;
  * @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) {
+ */ async function validateAndEstimate(allocations, intents, destChain, useForwarder, requestConfig) {
     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 { entries, forwardingFee } = await fetchEstimate(apiBaseUrl, estimateBody, useForwarder, allocations, requestConfig);
     const estimatedIntents = parseEstimateResponse(entries, intents);
     return {
         estimatedIntents,
@@ -45406,7 +46994,7 @@ const FORWARDER_POLL_TIMEOUT_MS = 300_000;
             }
             throw err;
         }
-        const { estimatedIntents, forwardingFee } = await validateAndEstimate(corrected.allocations, corrected.intents, opts.destChain, opts.useForwarder);
+        const { estimatedIntents, forwardingFee } = await validateAndEstimate(corrected.allocations, corrected.intents, opts.destChain, opts.useForwarder, opts.requestConfig);
         const stillOverdrawn = findOverdrawnChains(estimatedIntents, corrected.allocations, opts.chainBalances);
         if (stillOverdrawn.length === 0) {
             return {
@@ -45440,12 +47028,12 @@ const FORWARDER_POLL_TIMEOUT_MS = 300_000;
  * @param recipientAddress - Resolved recipient address.
  * @param useForwarder - Whether the Forwarding Service path is active.
  * @returns Allocations, estimated intents, and optional forwarding fee.
- */ async function resolveValidatedIntents(params, destChain, recipientAddress, useForwarder) {
+ */ async function resolveValidatedIntents(params, destChain, recipientAddress, useForwarder, requestConfig) {
     if (useForwarder) {
         assertForwarderRouteSupport(destChain);
     }
-    const { allocations, intents, chainBalances } = await resolveAllocationsAndIntents(params, destChain, recipientAddress, useForwarder);
-    const { estimatedIntents, forwardingFee } = await validateAndEstimate(allocations, intents, destChain, useForwarder);
+    const { allocations, intents, chainBalances } = await resolveAllocationsAndIntents(params, destChain, recipientAddress, useForwarder, requestConfig);
+    const { estimatedIntents, forwardingFee } = await validateAndEstimate(allocations, intents, destChain, useForwarder, requestConfig);
     if (params.amountIn && chainBalances) {
         const overdrawn = findOverdrawnChains(estimatedIntents, allocations, chainBalances);
         if (overdrawn.length > 0) {
@@ -45458,7 +47046,10 @@ const FORWARDER_POLL_TIMEOUT_MS = 300_000;
                 chainBalances,
                 estimatedIntents,
                 allocations,
-                overdrawn
+                overdrawn,
+                ...requestConfig ? {
+                    requestConfig
+                } : {}
             });
         }
     }
@@ -45502,10 +47093,10 @@ const FORWARDER_POLL_TIMEOUT_MS = 300_000;
         attestationSignature: transferResponse.signature
     };
 }
-async function runSpendNormalPath(params, destChain, useForwarder, dispatcher, steps) {
+async function runSpendNormalPath(params, destChain, useForwarder, dispatcher, steps, requestConfig) {
     const chainName = destChain.name;
     const recipientAddress = await resolveRecipientAddress(params.to);
-    const { allocations, estimatedIntents, forwardingFee: estimateFwdFee } = await resolveValidatedIntents(params, destChain, recipientAddress, useForwarder);
+    const { allocations, estimatedIntents, forwardingFee: estimateFwdFee } = await resolveValidatedIntents(params, destChain, recipientAddress, useForwarder, requestConfig);
     pushStep(steps, dispatcher, 'gateway.spend.step.buildBurnIntents', chainName, {
         name: 'buildBurnIntents',
         state: 'success',
@@ -45542,7 +47133,7 @@ async function runSpendNormalPath(params, destChain, useForwarder, dispatcher, s
     const forwarderParam = useForwarder ? '?enableForwarder=true' : '';
     let transferResponse;
     try {
-        transferResponse = await pollApiPost(`${transferApiBaseUrl}/v1/transfer${forwarderParam}`, transferBody, assertGatewayTransferResponse);
+        transferResponse = await pollApiPost(`${transferApiBaseUrl}/v1/transfer${forwarderParam}`, transferBody, assertGatewayTransferResponse, requestConfig);
     } catch (error) {
         throwGatewayApiError(error, allocations);
     }
@@ -45622,10 +47213,11 @@ function updateFeesWithActual(fees, completionStatus) {
             amount: actual
         } : f);
 }
-async function resolveDestinationTxHash(params, destChain, forwarder, transferId, attestation, attestationSignature, fees) {
+async function resolveDestinationTxHash(opts) {
+    const { params, destChain, forwarder, transferId, attestation, attestationSignature, fees, requestConfig } = opts;
     if (forwarder && transferId) {
         const apiBaseUrl = getGatewayApiBaseUrl(destChain.isTestnet);
-        const completionStatus = await pollForwarderCompletion(apiBaseUrl, transferId);
+        const completionStatus = await pollForwarderCompletion(apiBaseUrl, transferId, requestConfig);
         if (!completionStatus.transactionHash) {
             throw new KitError({
                 ...OnchainError.TRANSACTION_REVERTED,
@@ -45708,9 +47300,20 @@ function buildSpendResult(recipientAddress, destChain, txHash, allocationResults
 /**
  * Execute the mint step, recording success/error as a spend step.
  */ async function executeMintStep(opts) {
-    const { params, destChain, forwarder, transferId, attestation, attestationSignature, fees, steps, dispatcher } = opts;
+    const { params, destChain, forwarder, transferId, attestation, attestationSignature, fees, steps, dispatcher, requestConfig } = opts;
     try {
-        const mintResult = await resolveDestinationTxHash(params, destChain, forwarder, transferId, attestation, attestationSignature, fees);
+        const mintResult = await resolveDestinationTxHash({
+            params,
+            destChain,
+            forwarder,
+            transferId,
+            attestation,
+            attestationSignature,
+            fees,
+            ...requestConfig ? {
+                requestConfig
+            } : {}
+        });
         pushStep(steps, dispatcher, 'gateway.spend.step.mint', destChain.name, {
             name: 'mint',
             state: 'success',
@@ -45765,7 +47368,8 @@ function buildSpendResult(recipientAddress, destChain, txHash, allocationResults
     assertSpendAddresses(params, destChain);
     const forwarder = isForwarderEnabled(params.to);
     const steps = [];
-    const context = params.config?.retry ? await resolveRetryContext(params) : await resolveNormalContext(params, destChain, forwarder, dispatcher, steps);
+    const requestConfig = options?.requestConfig;
+    const context = params.config?.retry ? await resolveRetryContext(params) : await resolveNormalContext(params, destChain, forwarder, dispatcher, steps, requestConfig);
     const fees = appendForwarderFee(context.fees, context.forwardingFee);
     const mintResult = await executeMintStep({
         params,
@@ -45776,7 +47380,10 @@ function buildSpendResult(recipientAddress, destChain, txHash, allocationResults
         attestationSignature: context.attestationSignature,
         fees,
         steps,
-        dispatcher
+        dispatcher,
+        ...requestConfig ? {
+            requestConfig
+        } : {}
     });
     // A throwing `onBroadcast` must never strand the caller after a
     // successful mint — the chain has moved. `safeInvokeCallback` swallows
@@ -45793,14 +47400,14 @@ function buildSpendResult(recipientAddress, destChain, txHash, allocationResults
 /**
  * Resolve the spend context via the normal (non-retry) path.
  * Validates `from`, then delegates to `runSpendNormalPath`.
- */ async function resolveNormalContext(params, destChain, forwarder, dispatcher, steps) {
+ */ async function resolveNormalContext(params, destChain, forwarder, dispatcher, steps, requestConfig) {
     if (!params.from) {
         throw createValidationFailedError$1('from', params.from, 'Source (from) is required when config.retry is not provided.');
     }
     return runSpendNormalPath({
         ...params,
         from: params.from
-    }, destChain, forwarder, dispatcher, steps);
+    }, destChain, forwarder, dispatcher, steps, requestConfig);
 }
 /**
  * Estimate fees for a Gateway spend without executing it.
@@ -45823,13 +47430,13 @@ function buildSpendResult(recipientAddress, destChain, txHash, allocationResults
  * })
  * fees.forEach((f) => console.log(f.type, f.amount, f.allocations))
  * ```
- */ async function estimateSpend$1(params) {
+ */ async function estimateSpend$1(params, requestConfig) {
     const destChain = resolveChainIdentifier(params.to.chain);
     assertGatewayV1(destChain);
     assertSpendAddresses(params, destChain);
     const forwarder = isForwarderEnabled(params.to);
     const recipientAddress = await resolveRecipientAddress(params.to);
-    const { allocations, estimatedIntents, forwardingFee } = await resolveValidatedIntents(params, destChain, recipientAddress, forwarder);
+    const { allocations, estimatedIntents, forwardingFee } = await resolveValidatedIntents(params, destChain, recipientAddress, forwarder, requestConfig);
     const fees = computeEstimateFees(estimatedIntents, allocations, params.config?.customFee);
     if (forwardingFee) {
         fees.push({
@@ -45953,6 +47560,9 @@ function assertNotSelfDelegation(chain, signerAddress, delegateAddress, action)
  *    the delegate is `'ready'` (finalized); otherwise it is `'pending'`.
  *
  * @param params - The adapter context (`from`), delegate address, and token.
+ * @param requestConfig - Optional polling config overrides, including custom
+ *   `headers` forwarded with the `/v1/info` request used on the EVM finality
+ *   check.
  * @returns Promise resolving to `'none'`, `'pending'`, or `'ready'`.
  * @throws KitError if the chain is unsupported or `/v1/info` fails.
  *
@@ -45972,7 +47582,7 @@ function assertNotSelfDelegation(chain, signerAddress, delegateAddress, action)
  * const status = await getDelegateStatus(params)
  * if (status === 'ready') { // safe to spend }
  * ```
- */ async function getDelegateStatus$1(params) {
+ */ async function getDelegateStatus$1(params, requestConfig) {
     const { from, delegateAddress } = params;
     const { adapter } = from;
     const chain = resolveChainIdentifier(from.chain);
@@ -46012,7 +47622,7 @@ function assertNotSelfDelegation(chain, signerAddress, delegateAddress, action)
         return String(finalizedResult).toLowerCase() === 'true' ? 'ready' : 'pending';
     }
     // EVM: use processedHeight from /v1/info
-    const processedHeight = await getProcessedHeight(chain.isTestnet, chain.gateway.domain);
+    const processedHeight = await getProcessedHeight(chain.isTestnet, chain.gateway.domain, requestConfig);
     // If the RPC node lags Gateway's indexer view, the historical read at
     // processedHeight may throw a block-range error. This is safe to treat
     // as 'pending' because processedHeight comes from Gateway's /v1/info
@@ -46230,6 +47840,35 @@ function dispatchEvent(dispatcher, opName, stage, chain, data) {
     dispatchEvent(dispatcher, opName, 'failed', chain, extractErrorInfo(error));
 }
 
+// ---------------------------------------------------------------------------
+// Config validation
+// ---------------------------------------------------------------------------
+function isPlainObject(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function assertHeadersConfig(headers) {
+    if (headers === undefined) {
+        return;
+    }
+    if (!isPlainObject(headers)) {
+        throw createValidationFailedError$1('config.headers', headers, 'config.headers must be a plain object with string header values when provided');
+    }
+    for (const [name, value] of Object.entries(headers)){
+        if (typeof value !== 'string') {
+            throw createValidationFailedError$1(`config.headers.${name}`, value, 'header values must be strings');
+        }
+    }
+}
+function assertGatewayV1Config(config) {
+    if (!isPlainObject(config)) {
+        throw createValidationFailedError$1('config', config, 'config must be a plain object when provided');
+    }
+    assertHeadersConfig(config['headers']);
+}
 // ---------------------------------------------------------------------------
 // Factory
 // ---------------------------------------------------------------------------
@@ -46239,7 +47878,12 @@ function dispatchEvent(dispatcher, opName, stage, chain, data) {
  * Returns a plain object that implements {@link IGatewayProvider} by
  * delegating to the standalone functions in `operations/`.
  *
+ * @param config - Optional provider configuration. Supply `headers` to
+ *   forward custom HTTP headers with every Gateway API request. See
+ *   {@link GatewayV1Config}.
  * @returns An {@link IGatewayProvider} instance.
+ * @throws Throws when `config` or `config.headers` is not a plain object, or a
+ *   header value is not a string.
  *
  * @example
  * ```typescript
@@ -46248,7 +47892,23 @@ function dispatchEvent(dispatcher, opName, stage, chain, data) {
  * const provider = createGatewayV1Provider()
  * const chains = provider.getSupportedChains()
  * ```
- */ function createGatewayV1Provider() {
+ *
+ * @example
+ * ```typescript
+ * // Forward a custom header on every Gateway API request.
+ * const provider = createGatewayV1Provider({
+ *   headers: { 'X-Access-Key': process.env.GATEWAY_ACCESS_KEY! },
+ * })
+ * ```
+ */ function createGatewayV1Provider(config = {}) {
+    assertGatewayV1Config(config);
+    // Captured once and threaded to every Gateway API call the operations make,
+    // so a configured header reaches balances, estimate, transfer, forwarder
+    // status, and /v1/info alike. Left undefined when no headers are configured
+    // so the operations keep their existing defaults untouched.
+    const requestConfig = config.headers ? {
+        headers: config.headers
+    } : undefined;
     /**
    * Execute an operation with started/succeeded/failed event dispatch.
    */ async function withEvents(opName, chain, startedData, params, fn) {
@@ -46279,21 +47939,25 @@ function dispatchEvent(dispatcher, opName, stage, chain, data) {
             }, params, depositFor$1),
         spend: async (params, options)=>{
             const destChainName = extractChainInfo(params.to.chain).name;
+            const mergedOptions = requestConfig ? {
+                ...options,
+                requestConfig
+            } : options;
             return withEvents('spend', destChainName, {
                 destinationChain: destChainName,
                 token: params.token ?? 'USDC'
-            }, params, async (p)=>spend$1(p, provider.actionDispatcher, options));
+            }, params, async (p)=>spend$1(p, provider.actionDispatcher, mergedOptions));
         },
         estimateSpend: async (params)=>{
             const destChainName = extractChainInfo(params.to.chain).name;
             return withEvents('estimateSpend', destChainName, {
                 destinationChain: destChainName,
                 token: params.token ?? 'USDC'
-            }, params, estimateSpend$1);
+            }, params, async (p)=>estimateSpend$1(p, requestConfig));
         },
         getBalances: async (params)=>withEvents('getBalances', 'aggregate', {
                 token: params.token ?? 'USDC'
-            }, params, getBalances$1),
+            }, params, async (p)=>getBalances$1(p, requestConfig)),
         addDelegate: async (params)=>withEvents('addDelegate', extractChainInfo(params.from.chain).name, {
                 delegateAddress: params.delegateAddress
             }, params, addDelegate$1),
@@ -46311,7 +47975,9 @@ function dispatchEvent(dispatcher, opName, stage, chain, data) {
         // in withEvents. getSupportedChains is synchronous. getDelegateStatus is a
         // lightweight read that consumers treat as a utility check, unlike
         // getBalances which involves API polling and benefits from lifecycle events.
-        getDelegateStatus: getDelegateStatus$1,
+        // getDelegateStatus is wrapped to forward the provider's request config to
+        // its /v1/info call; getSupportedChains makes no API call.
+        getDelegateStatus: async (params)=>getDelegateStatus$1(params, requestConfig),
         getSupportedChains: getSupportedChains$1
     };
     return provider;
@@ -46321,6 +47987,7 @@ function dispatchEvent(dispatcher, opName, stage, chain, data) {
  * The default providers that will be used in addition to the providers
  * provided to the createUnifiedBalanceKitContext factory function.
  *
+ * @param config - Optional configuration forwarded to the default provider.
  * @returns A readonly tuple with one element: the default Gateway v1 provider
  *   instance created via {@link createGatewayV1Provider}.
  * @internal
@@ -46332,8 +47999,10 @@ function dispatchEvent(dispatcher, opName, stage, chain, data) {
  * const { providers } = createUnifiedBalanceKitContext()
  * // providers[0] is the default Gateway v1 instance from getDefaultProviders()
  * ```
- */ const getDefaultProviders = ()=>[
-        createGatewayV1Provider()
+ */ const getDefaultProviders = (config = {})=>[
+        createGatewayV1Provider(config.headers ? {
+            headers: config.headers
+        } : {})
     ];
 function createUnifiedBalanceKitContext(config = {}) {
     // Runtime guard: `excludeDefaultProviders: true` with no `providers` is
@@ -46347,7 +48016,10 @@ function createUnifiedBalanceKitContext(config = {}) {
     // Initialize default providers — either the canonical singleton tuple or
     // an empty list when the caller has opted out. Typed loosely here; each
     // public overload narrows the return type for callers.
-    const defaultProviders = config.excludeDefaultProviders === true ? [] : getDefaultProviders();
+    const defaultProvidersConfig = config.headers ? {
+        headers: config.headers
+    } : {};
+    const defaultProviders = config.excludeDefaultProviders === true ? [] : getDefaultProviders(defaultProvidersConfig);
     const providers = [
         ...defaultProviders,
         ...config.providers ?? []
@@ -47038,29 +48710,65 @@ function sumAllocationsFromSources(sources) {
     }
 });
 
+function normalizeAddressIdentity(value) {
+    if (typeof value !== 'string') return undefined;
+    try {
+        return convertAddress(value, 'bytes32').toLowerCase();
+    } catch  {
+        // Address validation below owns the structured error for invalid input.
+        return value;
+    }
+}
 /**
- * Reject `from` arrays containing the same adapter reference more than once.
- * Must run on the raw input (before Zod parsing) because `z.object()` creates
- * new wrapper objects and identity (`===`) is lost.
+ * Reject `from` arrays that describe the same spend source more than once.
+ *
+ * One adapter instance may legitimately be reused across distinct Gateway
+ * source accounts. When `sourceAccount` is omitted, the signer address
+ * identifies the source. Must run on the raw input (before Zod parsing)
+ * because `z.object()` creates new wrapper objects and adapter identity
+ * (`===`) is lost.
  *
  * @internal
- */ function assertNoDuplicateAdapters(params) {
+ */ function assertNoDuplicateSpendSources(params) {
     if (params == null || typeof params !== 'object') return;
     const from = params['from'];
     if (!Array.isArray(from) || from.length < 2) return;
-    const seen = new Set();
+    const seen = new Map();
     for (const source of from){
         if (source == null || typeof source !== 'object') continue;
-        const adapter = source['adapter'];
+        const record = source;
+        const adapter = record['adapter'];
         if (adapter == null) continue;
-        if (seen.has(adapter)) {
+        const sourceAccount = normalizeAddressIdentity(record['sourceAccount']) ?? normalizeAddressIdentity(record['address']);
+        let sourceAccounts = seen.get(adapter);
+        if (sourceAccounts == null) {
+            sourceAccounts = new Set();
+            seen.set(adapter, sourceAccounts);
+        }
+        if (sourceAccounts.has(sourceAccount)) {
             throw new KitError({
                 ...InputError.VALIDATION_FAILED,
                 recoverability: 'FATAL',
-                message: 'Duplicate adapter instance detected in from array. ' + 'Each source must use a distinct adapter object.'
+                message: 'Duplicate spend source detected in from array. The same adapter ' + 'and Gateway source account are reused more than once.'
             });
         }
-        seen.add(adapter);
+        sourceAccounts.add(sourceAccount);
+    }
+}
+function assertSourceAddressContexts(from) {
+    const sources = Array.isArray(from) ? from : [
+        from
+    ];
+    for (const raw of sources){
+        if (raw == null || typeof raw !== 'object') continue;
+        const source = raw;
+        const addressContext = source.adapter?.capabilities?.addressContext;
+        if (addressContext === 'developer-controlled' && (typeof source.address !== 'string' || source.address === '')) {
+            throw createValidationFailedError$1('address', source.address, 'Address is required for developer-controlled adapters.');
+        }
+        if (addressContext === 'user-controlled' && source.address !== undefined) {
+            throw createValidationFailedError$1('address', source.address, 'Address should not be provided for user-controlled adapters. ' + 'The address is automatically resolved from the connected wallet.');
+        }
     }
 }
 /**
@@ -47074,14 +48782,17 @@ function sumAllocationsFromSources(sources) {
  * @throws \{KitError\} When validation fails; error code is
  *   {@link InputError.VALIDATION_FAILED}.
  */ function assertSpendParams(params) {
-    assertNoDuplicateAdapters(params);
+    assertNoDuplicateSpendSources(params);
+    if (params != null && typeof params === 'object' && 'from' in params) {
+        assertSourceAddressContexts(params['from']);
+    }
     const result = spendParamsSchema.safeParse(params);
     if (!result.success) {
         throw convertZodErrorToStructured(result.error, params);
     }
     const data = result.data;
     // Validate recipientAddress against the destination chain
-    if (data.to.recipientAddress) {
+    if (data.to.recipientAddress !== undefined && data.to.recipientAddress !== '') {
         const toChain = data.to.chain;
         if (!isValidAddressForChain(data.to.recipientAddress, toChain)) {
             const chainInfo = extractChainInfo(toChain);
@@ -47089,7 +48800,7 @@ function sumAllocationsFromSources(sources) {
         }
     }
     // Validate sourceAccount against each source's allocation chain
-    if (data.from) {
+    if (data.from !== undefined) {
         assertSourceAccountAddresses(data.from);
     }
 }
@@ -47104,11 +48815,15 @@ function assertSourceAccountAddresses(from) {
         from
     ];
     for (const raw of sources){
-        if (!raw || typeof raw !== 'object' || !('sourceAccount' in raw)) continue;
+        if (raw === null || typeof raw !== 'object' || !('sourceAccount' in raw)) {
+            continue;
+        }
         const source = raw;
-        if (!source.sourceAccount) continue;
+        if (source.sourceAccount === undefined || source.sourceAccount === '') {
+            continue;
+        }
         const sourceChain = getSourceChainFromAllocations(source.allocations);
-        if (!sourceChain) continue;
+        if (sourceChain === undefined) continue;
         if (!isValidAddressForChain(source.sourceAccount, sourceChain)) {
             const chainInfo = extractChainInfo(sourceChain);
             throw createInvalidAddressError(source.sourceAccount, String(chainInfo.name), chainInfo.expectedAddressFormat);
@@ -49308,6 +51023,11 @@ function assertAppKitCustomFeePolicyScope(operation) {
             assertAppKitCustomFeePolicy(config.customFeePolicy);
         }
         const unifiedBalance = new AppKitUnifiedBalance({
+            // Top-level headers act as the shared default; an explicit
+            // `unifiedBalance.headers` overrides them by coming later in the spread.
+            ...config.headers != null && {
+                headers: config.headers
+            },
             ...config.unifiedBalance,
             ...config.disableErrorReporting != null && {
                 disableErrorReporting: config.disableErrorReporting
@@ -49410,30 +51130,7 @@ function assertAppKitCustomFeePolicyScope(operation) {
    */ async retryBridge(result, retryContext) {
         return retryBridge(this.context, result, retryContext);
     }
-    /**
-   * Estimate the bridge operation.
-   *
-   * Calculates gas costs, protocol fees, and optional custom fees for a
-   * cross-chain bridge transfer without executing the transaction. Useful
-   * for displaying cost estimates to users before they confirm a transfer.
-   *
-   * @param params - Bridge parameters containing source, destination, amount, and token
-   * @returns Promise resolving to the estimate result with fee information
-   * @throws If bridge parameters are invalid
-   * @throws If the bridge route is not supported
-   *
-   * @example
-   * ```typescript
-   * const estimate = await kit.estimateBridge({
-   *   from: { adapter: sourceAdapter, chain: 'Ethereum' },
-   *   to: { adapter: destAdapter, chain: 'Polygon' },
-   *   amount: '100.50',
-   *   token: 'USDC'
-   * })
-   *
-   * console.log('Estimated fees:', estimate.fees)
-   * ```
-   */ async estimateBridge(params) {
+    async estimateBridge(params) {
         return estimateBridge(this.context, params);
     }
     /**
@@ -49549,7 +51246,7 @@ function assertAppKitCustomFeePolicyScope(operation) {
    *   config: {
    *     slippageBps: 300,  // 3% slippage
    *     allowanceStrategy: 'permit',
-   *     kitKey: 'KIT_KEY:id:secret'
+   *     apiKey: 'TEST_API_KEY:id:secret'
    *   }
    * })
    *
@@ -49578,7 +51275,7 @@ function assertAppKitCustomFeePolicyScope(operation) {
    *   amountIn: '100.50',
    *   config: {
    *     slippageBps: 300,
-   *     kitKey: 'KIT_KEY:id:secret'
+   *     apiKey: 'TEST_API_KEY:id:secret'
    *   }
    * })
    *
@@ -49602,7 +51299,7 @@ function assertAppKitCustomFeePolicyScope(operation) {
    * not write the polling loop yourself.
    *
    * @param params - `txHash` and `chainIn`, plus optional `chainOut` and
-   *   `kitKey`.
+   *   `apiKey`.
    * @returns A snapshot of the swap's status at the time of the call.
    * @throws \{KitError\} If `chainIn` or `chainOut` is malformed.
    *
@@ -49615,7 +51312,7 @@ function assertAppKitCustomFeePolicyScope(operation) {
    *   txHash: result.txHash,
    *   chainIn: result.chainIn,
    *   chainOut: result.chainOut,
-   *   kitKey: process.env.KIT_KEY ?? '',
+   *   apiKey: process.env.CIRCLE_API_KEY,
    * })
    *
    * console.log(status.progress.status, status.progress.substatus)
@@ -49628,7 +51325,7 @@ function assertAppKitCustomFeePolicyScope(operation) {
    *   txHash: result.txHash,
    *   chainIn: result.chainIn,
    *   chainOut: result.chainOut,
-   *   kitKey: process.env.KIT_KEY ?? '',
+   *   apiKey: process.env.CIRCLE_API_KEY,
    * })
    * while (status.progress.status === 'PENDING') {
    *   await new Promise((r) => setTimeout(r, 3_000))
@@ -49636,7 +51333,7 @@ function assertAppKitCustomFeePolicyScope(operation) {
    *     txHash: result.txHash,
    *     chainIn: result.chainIn,
    *     chainOut: result.chainOut,
-   *     kitKey: process.env.KIT_KEY ?? '',
+   *     apiKey: process.env.CIRCLE_API_KEY,
    *   })
    * }
    * ```
@@ -49655,7 +51352,7 @@ function assertAppKitCustomFeePolicyScope(operation) {
    * expires. Timeouts surface as a RETRYABLE `KitError` so callers can
    * re-invoke with the same `txHash`.
    *
-   * @param params - Wait configuration: identifiers, kit key, and optional
+   * @param params - Wait configuration: identifiers, API key, and optional
    *                 `timeoutMs` / `onProgress`.
    * @returns The first terminal {@link SwapStatusResult} observed.
    * @throws \{KitError\} (`NETWORK.TIMEOUT`, RETRYABLE) when the wait
@@ -49668,7 +51365,7 @@ function assertAppKitCustomFeePolicyScope(operation) {
    *
    * const final = await kit.waitForSwap({
    *   result,
-   *   kitKey: process.env.KIT_KEY ?? '',
+   *   apiKey: process.env.CIRCLE_API_KEY,
    *   onProgress: (snap) => console.log(snap.progress.status),
    * })
    *
@@ -49684,7 +51381,7 @@ function assertAppKitCustomFeePolicyScope(operation) {
    *   txHash: persisted.txHash,
    *   chainIn: persisted.chainIn,
    *   chainOut: persisted.chainOut,
-   *   kitKey: process.env.KIT_KEY ?? '',
+   *   apiKey: process.env.CIRCLE_API_KEY,
    * })
    * ```
    */ async waitForSwap(params) {
@@ -49716,7 +51413,7 @@ function assertAppKitCustomFeePolicyScope(operation) {
    * translates to the chain's native sentinel address — `0xEee…` for EVM,
    * `1111…` for Solana — before querying the service.
    *
-   * @param params - `chain`, plus optional `tokens` and `kitKey`.
+   * @param params - `chain`, plus optional `tokens` and `apiKey`.
    * @returns A nested map of `[chain][address] → { priceUSD, fetchedAt }`.
    * @throws \{KitError\} If `chain` is malformed, `tokens` exceeds 100
    *         entries, or any entry is neither a registered symbol nor a
@@ -49727,7 +51424,7 @@ function assertAppKitCustomFeePolicyScope(operation) {
    * const { rates } = await kit.getTokenRates({
    *   chain: 'Ethereum',
    *   tokens: ['USDC', 'EURC'],
-   *   kitKey: process.env.KIT_KEY ?? '',
+   *   apiKey: process.env.CIRCLE_API_KEY,
    * })
    *
    * const usdc = rates['Ethereum']?.['0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48']
@@ -49736,38 +51433,8 @@ function assertAppKitCustomFeePolicyScope(operation) {
    */ async getTokenRates(params) {
         return getTokenRates(this.context, params);
     }
-    /**
-   * Get chains supported by AppKit operations.
-   *
-   * Returns blockchain networks that support specific stablecoin operations.
-   * When no operation type is specified, returns all chains supporting any
-   * operation (bridge, swap, earn, or unified balance).
-   *
-   * @param operationType - Optional operation type to filter chains ('bridge' | 'swap' | 'earn' | 'unifiedBalance')
-   * @returns Array of unique chain definitions supporting the specified operation(s)
-   *
-   * @example Get all supported chains
-   * ```typescript
-   * import { AppKit } from '@circle-fin/app-kit'
-   *
-   * const kit = new AppKit()
-   * const allChains = kit.getSupportedChains()
-   *
-   * console.log(`Total supported chains: ${allChains.length}`)
-   * allChains.forEach(chain => {
-   *   console.log(`- ${chain.name} (${chain.type})`)
-   * })
-   * ```
-   *
-   * @example Get bridge-specific chains
-   * ```typescript
-   * const kit = new AppKit()
-   * const bridgeChains = kit.getSupportedChains('bridge')
-   *
-   * console.log('Chains supporting bridge:', bridgeChains.map(c => c.name))
-   * ```
-   */ getSupportedChains(operationType) {
-        return getSupportedChains$2(this.context, operationType, this.unifiedBalance);
+    getSupportedChains(operationType, options) {
+        return getSupportedChains$2(this.context, operationType, this.unifiedBalance, options);
     }
     /**
    * Set operation-scoped custom fee policies.