@circle-fin/app-kit 1.11.0 → 1.12.1

package/context.d.mts

@@ -740,6 +740,8 @@ declare enum Blockchain {
     World_Chain_Sepolia = "World_Chain_Sepolia",
     XDC = "XDC",
     XDC_Apothem = "XDC_Apothem",
+    X_Layer = "X_Layer",
+    X_Layer_Testnet = "X_Layer_Testnet",
     ZKSync_Era = "ZKSync_Era",
     ZKSync_Sepolia = "ZKSync_Sepolia"
 }
@@ -952,6 +954,7 @@ declare enum BridgeChain {
     Unichain = "Unichain",
     World_Chain = "World_Chain",
     XDC = "XDC",
+    X_Layer = "X_Layer",
     Arc_Testnet = "Arc_Testnet",
     Arbitrum_Sepolia = "Arbitrum_Sepolia",
     Avalanche_Fuji = "Avalanche_Fuji",
@@ -975,7 +978,8 @@ declare enum BridgeChain {
     Sonic_Testnet = "Sonic_Testnet",
     Unichain_Sepolia = "Unichain_Sepolia",
     World_Chain_Sepolia = "World_Chain_Sepolia",
-    XDC_Apothem = "XDC_Apothem"
+    XDC_Apothem = "XDC_Apothem",
+    X_Layer_Testnet = "X_Layer_Testnet"
 }
 /**
  * Type representing valid bridge chain identifiers.
@@ -2953,6 +2957,18 @@ interface TokenActionMap {
          */
         walletAddress?: string | undefined;
     };
+    /**
+     * Get the on-chain name of the token contract.
+     *
+     * This is a read-only operation. For USDC the value is also the EIP-712
+     * domain name, which permit and authorize signing flows need.
+     */
+    name: ActionParameters & {
+        /**
+         * The contract address of the token.
+         */
+        tokenAddress: string;
+    };
 }
 
 /**
@@ -3782,6 +3798,30 @@ declare class ActionRegistry {
     executeAction<TActionKey extends ActionKeys>(action: TActionKey, params: ActionPayload<TActionKey>, context: ResolvedOperationContext): Promise<PreparedChainRequest>;
 }
 
+/**
+ * Canonical list of actions that do not prepare or submit transactions.
+ *
+ * @internal
+ */
+declare const READ_ACTION_KEYS: readonly ["token.allowance", "token.balanceOf", "token.name", "native.balanceOf", "usdc.allowance", "usdc.balanceOf", "usdc.name", "gateway.v1.isDelegate", "gateway.v1.withdrawingBalance", "gateway.v1.withdrawalBlock", "gateway.v1.signBurnIntents"];
+/**
+ * Action keys that execute without preparing or submitting a transaction.
+ *
+ * @remarks
+ * Derive this type from the canonical runtime list so compile-time and runtime
+ * classification cannot drift. `gateway.v1.signBurnIntents` is included
+ * because the action system models off-chain signing as a read action: it does
+ * not prepare a chain request.
+ *
+ * @example
+ * ```typescript
+ * import type { ReadActionKey } from '@core/adapter'
+ *
+ * const action: ReadActionKey = 'token.allowance'
+ * ```
+ */
+type ReadActionKey = (typeof READ_ACTION_KEYS)[number];
+
 /**
  * Defines the capabilities of an adapter, including address handling patterns and supported chains.
  *
@@ -3950,6 +3990,69 @@ declare abstract class Adapter<TAdapterCapabilities extends AdapterCapabilities
      * ```
      */
     prepareAction<TActionKey extends ActionKeys>(action: TActionKey, params: ActionPayload<TActionKey>, ctx: OperationContext<TAdapterCapabilities>): Promise<PreparedChainRequest>;
+    /**
+     * Execute a non-transaction action without routing through transaction preparation.
+     *
+     * @remarks
+     * Use this seam for balance, allowance, contract-state, and other actions
+     * classified as reads. It never calls {@link Adapter.prepareAction}, so
+     * transaction authorization wrappers only observe actions that can produce a
+     * signable chain request.
+     *
+     * @typeParam TActionKey - The read action key.
+     * @param action - The read action to execute.
+     * @param params - The parameters for the read action.
+     * @param ctx - The operation context.
+     * @returns The raw action response.
+     * @throws {KitError} When the key is not a read action or no handler is registered.
+     * @throws Error When the operation context or action handler fails.
+     *
+     * @example
+     * ```typescript
+     * import { Ethereum } from '@core/chains'
+     *
+     * const balance = await adapter.readAction(
+     *   'token.balanceOf',
+     *   { tokenAddress, walletAddress },
+     *   { chain: Ethereum },
+     * )
+     * ```
+     *
+     * @internal
+     */
+    readAction<TActionKey extends ReadActionKey>(action: TActionKey, params: ActionPayload<TActionKey>, ctx: OperationContext<TAdapterCapabilities>): Promise<unknown>;
+    /**
+     * Read the current token allowance a delegate holds over an owner's tokens.
+     *
+     * @remarks
+     * Perform a network read through {@link Adapter.readAction}. This method
+     * never routes through {@link Adapter.prepareAction}. On chains without an
+     * allowance model, such as Solana, return the maximum uint256 value.
+     *
+     * @param params - The token to query and the delegate whose allowance is being read.
+     * @param ctx - Operation context with compile-time validated address requirements.
+     * @returns A promise resolving to the current allowance in the token's base units.
+     * @throws {KitError} When the adapter does not register a `token.allowance` handler.
+     * @throws Error When the operation context or action handler fails.
+     *
+     * @example
+     * ```typescript
+     * import type { Adapter } from '@core/adapter'
+     * import { Ethereum } from '@core/chains'
+     *
+     * declare const adapter: Adapter
+     *
+     * const allowance = await adapter.getTokenAllowance(
+     *   {
+     *     tokenAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+     *     delegate: '0x1111111111111111111111111111111111111111',
+     *   },
+     *   { chain: Ethereum },
+     * )
+     * console.log(allowance) // 1000000n
+     * ```
+     */
+    getTokenAllowance(params: ActionPayload<'token.allowance'>, ctx: OperationContext<TAdapterCapabilities>): Promise<bigint>;
     /**
      * Prepares a transaction for future gas estimation and execution.
      *
@@ -5260,6 +5363,132 @@ declare enum TransferSpeed {
     /** Standard burn mode - normal transfer time with standard fees */
     SLOW = "SLOW"
 }
+/**
+ * Context object representing a wallet and signing authority on a specific blockchain network.
+ *
+ * Combines a wallet or contract address, the blockchain it resides on, and the adapter (signer)
+ * responsible for authorizing transactions. Used to specify the source or destination in cross-chain
+ * transfer operations.
+ *
+ * @remarks
+ * The `adapter` (signer) and `address` do not always have to belong to the same entity. For example,
+ * in minting or withdrawal scenarios, the signing adapter may authorize a transaction that credits
+ * funds to a different recipient address. This context is essential for cross-chain operations,
+ * ensuring that both the address and the associated adapter are correctly paired with the intended
+ * blockchain, but not necessarily with each other.
+ *
+ * @example
+ * ```typescript
+ * import type { WalletContext } from '@core/provider'
+ * import { adapter, blockchain } from './setup'
+ *
+ * const wallet: WalletContext = {
+ *   adapter,
+ *   address: '0x1234...abcd',
+ *   chain: blockchain,
+ * }
+ * ```
+ */
+interface WalletContext<TAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities, 
+/**
+ * The chain definition type to use for the wallet context.
+ *
+ * @defaultValue ChainDefinition
+ */
+TChainDefinition extends ChainDefinition = ChainDefinition> {
+    /**
+     * The adapter (signer) for the wallet on the specified chain.
+     *
+     * Responsible for authorizing transactions and signing messages on behalf of the wallet or
+     * for a different recipient, depending on the use case.
+     */
+    adapter: Adapter<TAdapterCapabilities>;
+    /**
+     * The wallet or contract address.
+     *
+     * Must be a valid address format for the specified blockchain. May differ from the adapter's
+     * own address in scenarios such as relayed transactions or third-party minting.
+     */
+    address: string;
+    /**
+     * The blockchain network where the wallet or contract address resides.
+     *
+     * Determines the context and format for the address and adapter.
+     */
+    chain: TChainDefinition;
+}
+/**
+ * Wallet context for bridge destinations with optional custom recipient.
+ *
+ * Extends WalletContext to support scenarios where the recipient address
+ * differs from the signer address (e.g., bridging to a third-party wallet).
+ * The signer address is used for transaction authorization, while the
+ * recipient address specifies where the minted funds should be sent.
+ *
+ * @typeParam TAdapterCapabilities - The adapter capabilities type to use for the wallet context.
+ * @typeParam TChainDefinition - The chain definition type to use for the wallet context.
+ *
+ * @example
+ * ```typescript
+ * import type { DestinationWalletContext } from '@core/provider'
+ * import { adapter, blockchain } from './setup'
+ *
+ * // Bridge to a custom recipient address
+ * const destination: DestinationWalletContext = {
+ *   adapter,
+ *   address: '0x1234...abcd', // Signer address
+ *   chain: blockchain,
+ *   recipientAddress: '0x9876...fedc' // Custom recipient
+ * }
+ * ```
+ */
+interface DestinationWalletContext<TAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities, 
+/**
+ * The chain definition type to use for the wallet context.
+ *
+ * @defaultValue ChainDefinition
+ */
+TChainDefinition extends ChainDefinition = ChainDefinition> extends WalletContext<TAdapterCapabilities, TChainDefinition> {
+    /**
+     * Optional custom recipient address for minted funds.
+     *
+     * When provided, minted tokens will be sent to this address instead of
+     * the address specified in the wallet context. The wallet context address
+     * is still used for transaction signing and authorization.
+     *
+     * Must be a valid address format for the specified blockchain.
+     */
+    recipientAddress?: string;
+}
+/**
+ * Parameters for executing a cross-chain bridge operation.
+ */
+interface BridgeParams$1<TFromCapabilities extends AdapterCapabilities = AdapterCapabilities, TToCapabilities extends AdapterCapabilities = AdapterCapabilities, 
+/**
+ * The chain definition type to use for the wallet context.
+ *
+ * @defaultValue ChainDefinition
+ */
+TChainDefinition extends ChainDefinition = ChainDefinition> {
+    /** The source adapter containing wallet and chain information */
+    source: WalletContext<TFromCapabilities, TChainDefinition>;
+    /** The destination adapter containing wallet and chain information */
+    destination: DestinationWalletContext<TToCapabilities, TChainDefinition>;
+    /** The amount to transfer (as a string to avoid precision issues) */
+    amount: string;
+    /** The token to transfer (currently only USDC is supported) */
+    token: 'USDC';
+    /** Bridge configuration (e.g., fast burn settings) */
+    config: BridgeConfig;
+    /**
+     * Optional invocation metadata for tracing and correlation.
+     *
+     * When provided, the `traceId` is used to correlate all events emitted during
+     * the bridge operation. If not provided, an OpenTelemetry-compatible traceId
+     * will be auto-generated.
+     */
+    invocationMeta?: InvocationMeta;
+}
 /**
  * Configuration options for customizing bridge behavior.
  *
@@ -5567,6 +5796,91 @@ type BridgeDestination<TAdapterCapabilities extends AdapterCapabilities = Adapte
     useForwarder?: boolean;
 }) | ForwarderDestination<TChainIdentifier>;
 
+type FeeFunction<TFromAdapterCapabilities extends AdapterCapabilities, TToAdapterCapabilities extends AdapterCapabilities> = (params: BridgeParams$1<TFromAdapterCapabilities, TToAdapterCapabilities>) => Promise<string> | string;
+type FeeRecipientFunction<TFromAdapterCapabilities extends AdapterCapabilities, TToAdapterCapabilities extends AdapterCapabilities> = (feePayoutChain: ChainDefinition, params: BridgeParams$1<TFromAdapterCapabilities, TToAdapterCapabilities>) => Promise<string> | string;
+/**
+ * Custom fee policy for BridgeKit.
+ *
+ * Provides hooks to calculate an absolute custom fee and resolve the fee recipient address
+ * on the source chain. The returned fee is **added on top of the transfer amount** (the wallet signs for
+ * `amount + customFee`). Once collected, the custom fee is split:
+ *
+ * - **10%** automatically routes to Circle.
+ * - **90%** routes to your supplied `recipientAddress`.
+ *
+ * The entire transfer amount still flows through CCTPv2, which then charges its own protocol fee.
+ *
+ * Use `computeFee` (recommended) for human-readable amounts, or `calculateFee` (deprecated)
+ * for smallest-unit amounts. Only one should be provided.
+ *
+ * @example
+ * ```typescript
+ * import type { CustomFeePolicy, BridgeParams } from '@circle-fin/bridge-kit'
+ *
+ * const policy: CustomFeePolicy = {
+ *   // computeFee receives human-readable amounts (e.g., '100' for 100 USDC)
+ *   computeFee: (params: BridgeParams) => {
+ *     const amount = parseFloat(params.amount)
+ *
+ *     // 1% fee, capped between 5-50 USDC
+ *     const fee = Math.min(Math.max(amount * 0.01, 5), 50)
+ *     return fee.toFixed(6)
+ *   },
+ *   resolveFeeRecipientAddress: (feePayoutChain) =>
+ *     feePayoutChain.type === 'solana'
+ *       ? 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v'
+ *       : '0x1234567890123456789012345678901234567890',
+ * }
+ * ```
+ */
+type CustomFeePolicy$2 = {
+    /**
+     * A function that returns the fee to charge for the bridge transfer.
+     * The value returned from the function represents an absolute fee.
+     * The returned fee is **added on top of the transfer amount**. For example, returning
+     * `'5'` (5 USDC) for a 100 USDC transfer causes the wallet to debit 105 USDC total.
+     * CCTPv2 still processes the full 100 USDC transfer amount, while the custom fee is split
+     * 10%/90% between Circle and your fee recipient.
+     *
+     * @example
+     * ```typescript
+     * computeFee: (params) => {
+     *   const amount = parseFloat(params.amount)
+     *   return (amount * 0.01).toString() // 1% fee
+     * }
+     * ```
+     */
+    computeFee: FeeFunction<AdapterCapabilities, AdapterCapabilities>;
+    calculateFee?: never;
+    /**
+     * A function that returns the fee recipient for a bridge transfer.
+     * The value returned from the function represents the address that will receive the fee on the source chain of the bridge transfer.
+     * The fee recipient address **must be a valid address for the source chain** of the bridge transfer.
+     *
+     * For example: if you are bridging from Ethereum to Solana you would return `'0x1234567890123456789012345678901234567890'`,
+     * because the source chain of the bridge transfer is Ethereum.
+     */
+    resolveFeeRecipientAddress: FeeRecipientFunction<AdapterCapabilities, AdapterCapabilities>;
+} | {
+    computeFee?: never;
+    /**
+     * Calculate the fee to charge for the bridge transfer using smallest-unit amounts.
+     *
+     * @deprecated Use `computeFee` instead, which receives human-readable amounts.
+     *
+     * The `params.amount` is in smallest units (e.g., `'100000000'` for 100 USDC).
+     */
+    calculateFee: FeeFunction<AdapterCapabilities, AdapterCapabilities>;
+    /**
+     * A function that returns the fee recipient for a bridge transfer.
+     * The value returned from the function represents the address that will receive the fee on the source chain of the bridge transfer.
+     * The fee recipient address **must be a valid address for the source chain** of the bridge transfer.
+     *
+     * For example: if you are bridging from Ethereum to Solana you would return `'0x1234567890123456789012345678901234567890'`,
+     * because the source chain of the bridge transfer is Ethereum.
+     */
+    resolveFeeRecipientAddress: FeeRecipientFunction<AdapterCapabilities, AdapterCapabilities>;
+};
 /**
  * Parameters for initiating a cross-chain USDC bridge transfer.
  *
@@ -5671,6 +5985,463 @@ interface BridgeParams<TFromAdapterCapabilities extends AdapterCapabilities = Ad
     invocationMeta?: InvocationMeta;
 }
 
+/**
+ * Allowance strategy for token approvals during swap operations.
+ *
+ * Defines how token allowances should be granted to the swap contract:
+ * - `permit`: Use EIP-2612 permit signature (gas-efficient, no approval transaction)
+ * - `approve`: Traditional approval transaction
+ *
+ * The default strategy is `permit` with fallback to `approve` if permit is not supported.
+ */
+type AllowanceStrategy$1 = 'permit' | 'approve';
+/**
+ * Configuration options for swap operations.
+ *
+ * Controls swap behavior including allowance strategy, slippage tolerance,
+ * minimum output amounts, custom fees, and kit identification.
+ *
+ * @example
+ * ```typescript
+ * import type { ServiceSwapConfig } from '@circle-fin/provider-stablecoin-service-swap'
+ *
+ * // Percentage-based fee
+ * const config: ServiceSwapConfig = {
+ *   allowanceStrategy: 'permit',
+ *   slippageBps: 300, // 3%
+ *   stopLimit: '950000', // Minimum 0.95 USDC output
+ *   customFee: {
+ *     percentageBps: 1000,  // 10% fee
+ *     recipientAddress: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Absolute amount fee (from callback)
+ * const config: ServiceSwapConfig = {
+ *   allowanceStrategy: 'permit',
+ *   customFee: {
+ *     amount: '10000', // 0.01 USDC fee (absolute)
+ *     recipientAddress: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
+ *   }
+ * }
+ * ```
+ */
+interface ServiceSwapConfig {
+    /**
+     * Strategy for granting token allowances to the swap contract.
+     *
+     * Defaults to 'permit' with fallback to 'approve'.
+     */
+    allowanceStrategy?: AllowanceStrategy$1;
+    /**
+     * Maximum acceptable slippage in basis points (BPS).
+     *
+     * 1 BPS = 0.01%, so 300 BPS = 3% slippage.
+     * Defaults to 300 BPS (3%).
+     */
+    slippageBps?: number;
+    /**
+     * Minimum acceptable output amount in smallest units (stop-limit).
+     *
+     * If the estimated output falls below this value, the swap will fail.
+     * Expressed as a string to avoid precision issues.
+     */
+    stopLimit?: string;
+    /**
+     * Custom fee configuration for this swap.
+     *
+     * Supports two mutually exclusive approaches:
+     * 1. Percentage-based: Use `percentageBps` field (simple)
+     * 2. Absolute amount: Use `amount` field (from callback)
+     *
+     * If both are set, validation will fail. Transaction-level percentage
+     * takes precedence over kit-level callback policy.
+     */
+    customFee?: {
+        /**
+         * Fee percentage in basis points (NEW).
+         *
+         * 100 bps = 1%, 1000 bps = 10%, 10000 bps = 100%
+         *
+         * Service calculates fee using `estimatedAmount` for same-chain output fees
+         * and the input amount for cross-chain swaps.
+         * Must be greater than 0 and less than or equal to 10000 (maximum 100%).
+         * Mutually exclusive with `amount`.
+         *
+         * @example 1000 // 10% fee
+         */
+        percentageBps?: number;
+        /**
+         * Fee amount in smallest units (for callback results).
+         *
+         * Absolute fee amount calculated by callback function.
+         * Mutually exclusive with `percentageBps`.
+         *
+         * @example '10000' // 0.01 USDC (6 decimals)
+         */
+        amount?: string;
+        /**
+         * Address that will receive the developer's 90% fee share.
+         *
+         * Required whenever a custom fee is submitted to the provider. Optional at
+         * the type level so SDK callback flows can represent partial fee state
+         * before final validation.
+         *
+         * Must be valid on the fee payout chain: source chain for input-side fees
+         * and cross-chain swaps, destination chain for same-chain output-side fees.
+         *
+         * @example '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
+         */
+        recipientAddress?: string;
+    };
+    /**
+     * Stablecoin Service Kit Key used to authenticate service-backed swap
+     * requests.
+     *
+     * Treat this value as a credential. Do not log it, embed it in client-side
+     * source, or expose it in telemetry.
+     */
+    kitKey?: string;
+    /**
+     * DEX aggregator identifier used to source the swap route.
+     *
+     * @example 'lifi', 'paraswap'
+     */
+    provider?: string;
+    /**
+     * Whether to fuse the ERC-20 approval and the swap into a single atomic
+     * batch when the adapter supports it (EIP-5792, or a signing strategy that
+     * declares atomic batching).
+     *
+     * @remarks
+     * Defaults to `true`. When batching is available this collapses the two
+     * sequential transactions of the on-chain approval path into one atomic
+     * submission — a single signing challenge for a smart-contract wallet. Set
+     * to `false` to force the sequential approve-then-swap path. Has no effect on
+     * the gasless permit path (already a single transaction) or on native-token
+     * swaps (no approval needed).
+     *
+     * The batch path relies on the wallet's own gas estimation for the swap call:
+     * the service-provided gas floor and pre-flight simulation that the sequential
+     * path applies are not conveyed through the batch. For a complex/multi-hop
+     * swap whose wallet-side estimate under-shoots, this can out-of-gas-revert the
+     * atomic batch where the sequential path would succeed — set `false` to fall
+     * back to the service-floored sequential path if you hit this.
+     *
+     * @defaultValue true
+     */
+    batchTransactions?: boolean;
+}
+/**
+ * Parameters for initiating a swap operation through the Stablecoin Service.
+ *
+ * This type is used as the primary input to provider swap operations, allowing users to specify
+ * the source context, input/output tokens, swap amount, destination address, and optional configuration.
+ *
+ * @typeParam TFromAdapterCapabilities - The adapter capabilities type for the source adapter.
+ *
+ * @example
+ * ```typescript
+ * import type { ServiceSwapParams } from '@circle-fin/provider-stablecoin-service-swap'
+ * import { createAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
+ * import { Ethereum } from '@core/chains'
+ *
+ * const adapter = createAdapterFromPrivateKey({
+ *   privateKey: process.env.PRIVATE_KEY,
+ * })
+ *
+ * const params: ServiceSwapParams = {
+ *   from: { adapter, chain: Ethereum },
+ *   tokenIn: 'USDC', // Alias resolves to chain-specific address
+ *   tokenOut: 'USDT', // Alias resolves to chain-specific address
+ *   amountIn: '100500000', // 100.50 USDC in base units
+ *   to: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
+ *   config: {
+ *     slippageBps: 300, // 3% slippage
+ *     allowanceStrategy: 'permit'
+ *   }
+ * }
+ * ```
+ */
+interface ServiceSwapParams<TFromAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities, 
+/**
+ * The chain definition type to use for the wallet context.
+ *
+ * @defaultValue ChainDefinition
+ */
+TChainDefinition extends ChainDefinition = ChainDefinition> {
+    /**
+     * The source adapter context (wallet and chain) for the swap.
+     */
+    from: WalletContext<TFromAdapterCapabilities, TChainDefinition>;
+    /**
+     * The input token address or alias to swap from.
+     *
+     * **Supported formats:**
+     * - Token alias: `"USDC"`, `"USDT"`, `"NATIVE"` (case-insensitive)
+     * - EVM address: `'0x'` prefixed hex (e.g., `'0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'`)
+     * - Solana address: Base58-encoded (e.g., `'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v'`)
+     *
+     * Token aliases are automatically resolved to the chain-specific contract address.
+     *
+     * @example 'USDC' // Recommended: use alias
+     * @example '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48' // Or full address
+     */
+    tokenIn: string;
+    /**
+     * The output token address or alias to swap to.
+     *
+     * **Supported formats:**
+     * - Token alias: `"USDC"`, `"USDT"`, `"NATIVE"` (case-insensitive)
+     * - EVM address: `'0x'` prefixed hex (e.g., `'0xdAC17F958D2ee523a2206206994597C13D831ec7'`)
+     * - Solana address: Base58-encoded (e.g., `'Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB'`)
+     *
+     * Token aliases are automatically resolved to the chain-specific contract address.
+     *
+     * @example 'USDT' // Recommended: use alias
+     * @example '0xdAC17F958D2ee523a2206206994597C13D831ec7' // Or full address
+     */
+    tokenOut: string;
+    /**
+     * The amount of input token to swap in base units.
+     *
+     * SwapKit converts human-readable amounts to base units before passing to the provider.
+     *
+     * @example '100500000' for 100.50 USDC (6 decimals)
+     */
+    amountIn: string;
+    /**
+     * The destination address where the swapped tokens will be sent.
+     *
+     * @example '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
+     */
+    to: string;
+    /**
+     * Optional destination chain for cross-chain swaps.
+     *
+     * Defaults to `from.chain` for same-chain swaps.
+     */
+    toChain?: TChainDefinition;
+    /**
+     * Optional configuration for swap behavior.
+     *
+     * If omitted, defaults will be used:
+     * - allowanceStrategy: 'permit' (fallback to 'approve')
+     * - slippageBps: 300 (3%)
+     */
+    config?: ServiceSwapConfig;
+}
+
+/**
+ * Fee context when fee is taken from INPUT token.
+ *
+ * Used for swaps where the fee is collected from the input token, including
+ * all cross-chain swaps.
+ * Extends the resolved swap parameters with a discriminator to indicate input fee scenario.
+ *
+ * @typeParam TFromAdapterCapabilities - The adapter capabilities type for the source adapter
+ *
+ * @example
+ * ```typescript
+ * // USDC → RandomToken swap (fee from input)
+ * const context: SwapInputFeeContext = {
+ *   type: 'input',
+ *   from: {
+ *     adapter: viemAdapter,
+ *     chain: Ethereum,
+ *     address: '0x...'
+ *   },
+ *   tokenIn: 'USDC',
+ *   tokenOut: 'RandomToken',
+ *   amountIn: '100000000',  // 100 USDC in base units
+ *   to: '0x...'
+ * }
+ * ```
+ */
+interface SwapInputFeeContext<TFromAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities> extends ResolvedSwapParams<TFromAdapterCapabilities> {
+    /**
+     * Fee source discriminator - input token.
+     */
+    type: 'input';
+}
+/**
+ * Fee context when fee is taken from OUTPUT token.
+ *
+ * Used for swaps where the output token is supported for fee collection.
+ * Extends the resolved swap parameters with output amounts and discriminator.
+ *
+ * @typeParam TFromAdapterCapabilities - The adapter capabilities type for the source adapter
+ *
+ * @remarks
+ * If using `estimatedAmount` in callback and quote cache expires,
+ * calculated fee may not match fresh quote. Use `minAmount` for
+ * predictability at the cost of potentially lower fees.
+ *
+ * @example
+ * ```typescript
+ * // RandomToken → USDC swap (fee from output)
+ * const context: SwapOutputFeeContext = {
+ *   type: 'output',
+ *   from: {
+ *     adapter: viemAdapter,
+ *     chain: Ethereum,
+ *     address: '0x...'
+ *   },
+ *   tokenIn: 'RandomToken',
+ *   tokenOut: 'USDC',
+ *   amountIn: '100000000',
+ *   to: '0x...',
+ *   minAmount: '50000000',      // 50 USDC guaranteed minimum
+ *   estimatedAmount: '55000000'  // 55 USDC expected output
+ * }
+ * ```
+ */
+interface SwapOutputFeeContext<TFromAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities> extends ResolvedSwapParams<TFromAdapterCapabilities> {
+    /**
+     * Fee source discriminator - output token.
+     */
+    type: 'output';
+    /**
+     * Guaranteed minimum output amount in base units.
+     *
+     * More stable but lower than estimatedAmount. Use this for
+     * predictable fee calculations.
+     */
+    minAmount: string;
+    /**
+     * Estimated output amount in base units.
+     *
+     * Expected output based on current market conditions. May be
+     * higher than minAmount. Subject to change if quote expires.
+     */
+    estimatedAmount: string;
+}
+/**
+ * Discriminated union for swap fee contexts.
+ *
+ * Provides different context based on whether fee is from input or output token.
+ * Discriminated by the `type` field: 'input' for fees from input token, 'output' for output token.
+ *
+ * Includes full swap parameters (adapter, chain, tokens, amounts) for maximum flexibility
+ * in fee calculation logic.
+ *
+ * @typeParam TFromAdapterCapabilities - The adapter capabilities type for the source adapter
+ */
+type SwapFeeContext<TFromAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities> = SwapInputFeeContext<TFromAdapterCapabilities> | SwapOutputFeeContext<TFromAdapterCapabilities>;
+/**
+ * Custom fee policy for SwapKit (callback-based approach).
+ *
+ * Provides hooks to calculate an absolute fee amount and resolve the fee
+ * recipient address. The callback receives a discriminated context with
+ * different fields based on operation type (bridge vs swap) and fee source
+ * (input vs output).
+ *
+ * @remarks
+ * This is mutually exclusive with transaction-level percentage fees.
+ * If both are set, the transaction-level percentage takes precedence.
+ *
+ * The callback approach makes two API calls for same-chain output fees:
+ * 1. GET /quote - retrieve fee context and quote
+ * 2. POST /swap - execute with calculated fee
+ *
+ * Cross-chain swaps always use input fees on the source chain, so callbacks
+ * receive `type: 'input'` for those routes.
+ *
+ * @example
+ * ```typescript
+ * import type { CustomFeePolicy } from '@circle-fin/swap-kit'
+ *
+ * const policy: CustomFeePolicy = {
+ *   computeFee: async (ctx) => {
+ *     // Discriminate by fee source (input vs output)
+ *     if (ctx.type === 'input') {
+ *       // Simple percentage for input fees
+ *       return (parseFloat(ctx.amountIn) * 0.1).toString()
+ *     } else {
+ *       // Complex logic for output fees (VIP tiers, etc.)
+ *       const user = await database.getUser(...)
+ *       if (user.isVIP) {
+ *         return (parseFloat(ctx.minAmount) * 0.05).toString()
+ *       }
+ *       return (parseFloat(ctx.estimatedAmount) * 0.1).toString()
+ *     }
+ *   },
+ *   resolveFeeRecipientAddress: (chain) => {
+ *     return chain.type === 'solana'
+ *       ? 'SolanaAddress...'
+ *       : '0xEVMAddress...'
+ *   },
+ * }
+ * ```
+ */
+interface CustomFeePolicy$1 {
+    /**
+     * Calculate custom fee amount based on swap context.
+     *
+     * Receives full swap parameters including adapter, chain, tokens, and amounts.
+     * Context is discriminated by `type` field:
+     * - 'input': Fee from input token (OK → Any swaps and all cross-chain swaps)
+     * - 'output': Fee from output token (same-chain Any → OK swaps), includes minAmount and estimatedAmount
+     *
+     * The wrapper automatically converts amounts to/from base units, so your
+     * callback works with human-readable numbers (e.g., '0.1' for 0.1 USDC).
+     *
+     * @typeParam TFromAdapterCapabilities - The adapter capabilities type for the source adapter
+     * @param context - Discriminated swap fee context with full swap parameters
+     * @returns Absolute fee amount as string in human-readable format
+     *
+     * @example
+     * ```typescript
+     * computeFee: async (ctx) => {
+     *   if (ctx.type === 'output') {
+     *     // Output fee scenario
+     *     // Use estimatedAmount or minAmount for calculation
+     *     return (parseFloat(ctx.estimatedAmount) * 0.01).toString()
+     *   }
+     *   // Input fee scenario
+     *   return (parseFloat(ctx.amountIn) * 0.01).toString()
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * computeFee: async (ctx) => {
+     *   if (ctx.type === 'output') {
+     *     // Use minAmount for predictable fees
+     *     return (parseFloat(ctx.minAmount) * 0.01).toString()
+     *   }
+     *   return (parseFloat(ctx.amountIn) * 0.01).toString()
+     * }
+     * ```
+     */
+    computeFee: <TFromAdapterCapabilities extends AdapterCapabilities>(context: SwapFeeContext<TFromAdapterCapabilities>) => Promise<string> | string;
+    /**
+     * Resolve fee recipient address for the chain where fee is collected.
+     *
+     * Called with the chain where fee will be paid. For cross-chain swaps this
+     * is always the source chain. Must return a valid address format for that
+     * chain type (EVM or Solana).
+     *
+     * @param feePayoutChain - Chain definition where fee is collected
+     * @param context - The swap fee context with full parameters
+     * @returns Fee recipient address for the chain
+     *
+     * @example
+     * ```typescript
+     * resolveFeeRecipientAddress: (chain, ctx) => {
+     *   // Chain-based routing
+     *   if (chain.type === 'solana') {
+     *     return 'SolanaAddress...'
+     *   }
+     *   return '0xEVMAddress...'
+     * }
+     * ```
+     */
+    resolveFeeRecipientAddress: <TFromAdapterCapabilities extends AdapterCapabilities>(feePayoutChain: ChainDefinition, context: SwapFeeContext<TFromAdapterCapabilities>) => Promise<string> | string;
+}
 /**
  * Adapter context constrained to swap-supported chains.
  */
@@ -5818,6 +6589,45 @@ interface SwapConfig {
      */
     kitKey?: string;
 }
+/**
+ * Resolved parameters for swap operations after validation and normalization.
+ *
+ * Internal type used by SwapKit operations after `resolveSwapParams()` has:
+ * - Validated the input parameters
+ * - Resolved chain identifiers to full ChainDefinition objects
+ * - Extracted and validated wallet addresses
+ *
+ * Note: Raw user input is validated first, then `tokenIn` and `tokenOut` may
+ * be canonicalized for downstream routing (for example, Arc Testnet
+ * `NATIVE` → `USDC`). Address resolution is handled by the provider layer.
+ *
+ * This type is consumed by swap providers and internal operations but is not
+ * exposed to end users. It extends ServiceSwapParams which is the format expected
+ * by the StablecoinServiceSwapProvider.
+ *
+ * @typeParam TFromAdapterCapabilities - The adapter capabilities type for the source adapter.
+ *
+ * @example
+ * ```typescript
+ * // After resolution, SwapParams becomes ResolvedSwapParams:
+ * const resolved: ResolvedSwapParams = {
+ *   from: {
+ *     adapter: viemAdapter,
+ *     chain: Ethereum, // Full chain definition
+ *     address: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
+ *   },
+ *   tokenIn: 'USDC',  // Canonicalized for provider routing
+ *   tokenOut: 'USDT', // Canonicalized for provider routing
+ *   amountIn: '100500000', // Converted to base units (100.5 USDC with 6 decimals)
+ *   to: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
+ *   config: {
+ *     slippageBps: 300,
+ *     allowanceStrategy: 'permit'
+ *   }
+ * }
+ * ```
+ */
+type ResolvedSwapParams<TFromAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities> = ServiceSwapParams<TFromAdapterCapabilities>;
 interface SwapParams<TFromAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities> {
     /**
      * The source adapter context (wallet and chain) for the swap.
@@ -5930,6 +6740,24 @@ interface EarnConfig {
      * Format: `KIT_KEY:<keyId>:<keySecret>`
      */
     readonly kitKey?: string | undefined;
+    /**
+     * Optional base URL override for the Earn Service API.
+     *
+     * Defaults to `https://api.circle.com` when omitted. Override for testing
+     * against staging or local environments.
+     */
+    readonly baseUrl?: string | undefined;
+    /**
+     * Enable or disable atomic batched transaction execution.
+     *
+     * When `true` (or `undefined` / omitted), same-chain deposit and withdraw
+     * bundle the approve and execute calls into one adapter-native atomic batch
+     * when the connected wallet supports it. Set to `false` to force the
+     * sequential approve → execute flow.
+     *
+     * @defaultValue `undefined` (batching attempted when the wallet supports it)
+     */
+    readonly batchTransactions?: boolean | undefined;
 }
 /**
  * Parameters for fetching vault information.
@@ -6362,6 +7190,122 @@ interface GetClaimRewardsQuoteParams<TFromAdapterCapabilities extends AdapterCap
  */
 type EarnOperationParams = AnyDepositParams | WithdrawParams | ClaimRewardsParams | GetVaultsParams | ExploreVaultsParams | ExploreVaultsIteratorParams | GetPositionParams | GetDepositQuoteParams | GetWithdrawalQuoteParams | GetClaimRewardsQuoteParams;
 
+interface CustomFeeConfig {
+    recipientAddress: string;
+    value: string;
+}
+/**
+ * Data needed to retry a mint that failed after the transfer was
+ * already committed (funds locked).
+ *
+ * Obtain these values from the KitError (TRANSACTION_REVERTED) thrown when
+ * the on-chain mint step fails. The attestation and signature are available
+ * in `error.cause.trace`.
+ */
+interface RetryMintConfig {
+    /** The attestation hex string returned by the Gateway `/v1/transfer` API. */
+    attestation: string;
+    /** The attestation signature hex string returned by `/v1/transfer`. */
+    signature: string;
+}
+interface SpendConfig {
+    customFee?: CustomFeeConfig;
+    /**
+     * When provided, skips the estimate/sign/transfer steps and proceeds
+     * directly to the on-chain mint using a previously obtained attestation.
+     *
+     * Use this to retry a mint that failed due to an RPC or network issue
+     * after the transfer was already committed.
+     *
+     * @remarks
+     * The `useForwarder` flag on the destination is ignored during retry
+     * because the attestation was already issued — the Forwarding Service
+     * is only involved in the initial transfer, not re-mints.
+     */
+    retry?: RetryMintConfig;
+}
+interface ResolvedAllocation {
+    amount: string;
+    chain: ChainDefinition;
+}
+interface ResolvedSpendSource<TAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities> {
+    adapter: Adapter<TAdapterCapabilities>;
+    allocations: ResolvedAllocation[];
+    address?: string;
+    sourceAccount?: string;
+}
+interface ResolvedSpendDestination<TAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities> {
+    adapter?: Adapter<TAdapterCapabilities>;
+    chain: ChainDefinition;
+    recipientAddress?: string;
+    address?: string;
+    useForwarder?: boolean;
+}
+interface ResolvedSpendParams<TFromAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities, TToAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities> {
+    from: ResolvedSpendSource<TFromAdapterCapabilities>[];
+    to: ResolvedSpendDestination<TToAdapterCapabilities>;
+    token: SupportedToken;
+    config?: SpendConfig;
+}
+/**
+ * Function that computes the fee amount (in human-readable units, e.g. "10.5")
+ * given the resolved spend parameters.
+ */
+type SpendFeeFunction = (params: ResolvedSpendParams) => Promise<string> | string;
+/**
+ * Function that resolves the fee recipient address for a spend.
+ * Called once per spend, against the resolved **destination** chain —
+ * every fee burn intent in a spend mints to that single chain
+ * regardless of which source chain(s) funded it, so only one
+ * recipient address (valid on the destination chain) is ever needed.
+ */
+type SpendFeeRecipientFunction = (destinationChain: ChainDefinition, params: ResolvedSpendParams) => Promise<string> | string;
+/**
+ * Policy for computing and routing custom developer fees.
+ *
+ * **Important:** When the kit invokes `computeFee` and
+ * `resolveFeeRecipientAddress`, the `params` argument may be the
+ * **raw, unresolved** `SpendParams` (cast to `ResolvedSpendParams`).
+ * Fields that only exist after resolution (e.g. per-source allocations)
+ * may be `undefined`.  Implementations should only rely on top-level
+ * fields such as `to`, `token`, and `amount`.
+ *
+ * @remarks
+ * `resolveFeeRecipientAddress` is optional when you configure
+ * {@link UnifiedBalanceKit.setFeeRecipients} instead — the declarative
+ * map takes priority over this callback when both are present. Provide
+ * exactly one of the two; a policy with neither throws at spend time.
+ */
+interface CustomFeePolicy {
+    computeFee: SpendFeeFunction;
+    resolveFeeRecipientAddress?: SpendFeeRecipientFunction;
+}
+
+/**
+ * Runtime array of token identifiers supported by the unified-balance-kit.
+ *
+ * @example
+ * ```typescript
+ * import { SUPPORTED_TOKENS } from '@circle-fin/unified-balance-kit'
+ *
+ * if (SUPPORTED_TOKENS.includes('USDC')) {
+ *   console.log('USDC is supported')
+ * }
+ * ```
+ */
+declare const SUPPORTED_TOKENS: readonly ["USDC"];
+/**
+ * Token identifiers supported by the unified-balance-kit.
+ *
+ * @example
+ * ```typescript
+ * import type { SupportedToken } from '@circle-fin/unified-balance-kit'
+ *
+ * const token: SupportedToken = 'USDC'
+ * ```
+ */
+type SupportedToken = (typeof SUPPORTED_TOKENS)[number];
+
 /**
  * Operation types that support the `getFee`/`getFeeRecipient` hooks.
  */
@@ -6392,6 +7336,31 @@ interface OperationParamsMap {
     swap: SwapParams;
     earn: EarnOperationParams;
 }
+/**
+ * Operation-scoped custom fee policies configured at the AppKit level.
+ *
+ * Each property is optional so consumers can enable custom fees only for the
+ * operation they use. AppKit forwards the supplied policy to the matching
+ * underlying kit when that operation runs.
+ *
+ * @example
+ * ```typescript
+ * const policy: AppKitCustomFeePolicy = {
+ *   bridge: {
+ *     computeFee: () => '1.00',
+ *     resolveFeeRecipientAddress: () => '0x1234567890123456789012345678901234567890',
+ *   },
+ * }
+ * ```
+ */
+interface AppKitCustomFeePolicy {
+    /** Custom fee policy forwarded to BridgeKit bridge operations. */
+    bridge?: CustomFeePolicy$2;
+    /** Custom fee policy forwarded to SwapKit swap operations. */
+    swap?: CustomFeePolicy$1;
+    /** Custom fee policy forwarded to UnifiedBalanceKit spend operations. */
+    unifiedBalance?: CustomFeePolicy;
+}
 /**
  * Context interface for the AppKit with strongly typed getFee method.
  *
@@ -6479,6 +7448,14 @@ interface AppKitContext {
         chain: ChainDefinition;
         params: OperationParamsMap[T];
     }): Promise<string>;
+    /**
+     * Operation-scoped custom fee policies.
+     *
+     * Prefer {@link AppKit.setCustomFeePolicy} for runtime configuration. This
+     * context property is read by the internal kit factories when AppKit creates
+     * BridgeKit and SwapKit instances for each operation.
+     */
+    customFeePolicy?: AppKitCustomFeePolicy;
     /**
      * Event handlers registered for AppKit operations.
      *