@bitzy-app/bitzy-sdk 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,800 @@
+import { Address, PublicClient } from 'viem';
+export { Address, zeroAddress } from 'viem';
+import BigNumber from 'bignumber.js';
+export { default as BigNumber } from 'bignumber.js';
+
+interface UseSwapV3RoutesAddressConfig {
+    /**
+     * Address of the Bitzy router contract
+     * Used for executing swap transactions
+     * @example "0xA5E0AE4e5103dc71cA290AA3654830442357A489"
+     */
+    routerAddress: Address;
+    /**
+     * Address of the Bitzy query contract
+     * Used for fetching swap routes and pricing data
+     * @example "0x5b5079587501Bd85d3CDf5bFDf299f4eaAe98c23"
+     */
+    bitzyQueryAddress: Address;
+    /**
+     * Address of the wrapped native token (e.g., pBTC on Botanix)
+     * Used for handling native token swaps
+     * @example "0x0D2437F93Fed6EA64Ef01cCde385FB1263910C56"
+     */
+    wrappedAddress: Address;
+    /**
+     * Address representing the native token (ETH/BTC)
+     * Standard address used across all networks for native tokens
+     * @example "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE"
+     */
+    nativeAddress: Address;
+}
+interface UseSwapV3RoutesConfig {
+    /**
+     * Base URL for the Bitzy API
+     * @default "https://api-public.bitzy.app"
+     * @example "https://api-public.bitzy.app"
+     */
+    apiBaseUrl?: string;
+    /**
+     * API key for authentication (optional)
+     * Used for premium features and rate limiting
+     * @example "your-api-key-here"
+     */
+    apiKey?: string;
+    /**
+     * Contract addresses configuration for the specific network
+     * Contains router, query, wrapped, and native token addresses
+     */
+    config?: UseSwapV3RoutesAddressConfig;
+    /**
+     * Default number of routes to split large swaps into
+     * Higher values provide better execution but increase gas costs
+     * @default 5
+     * @example 5
+     */
+    defaultPartCount?: number;
+    /**
+     * Request timeout in milliseconds
+     * @default 30000 (30 seconds)
+     * @example 30000
+     */
+    timeout?: number;
+    /**
+     * Additional HTTP headers to include with API requests
+     * @example { "authen-key": "token" }
+     */
+    headers?: Record<string, string>;
+    /**
+     * Interval in milliseconds for automatic route refresh
+     * Set to 0 to disable automatic refresh
+     * @default 10000 (10 seconds)
+     * @example 10000
+     */
+    refreshInterval?: number;
+    /**
+     * Viem PublicClient instance for blockchain interactions
+     * Used for contract calls and blockchain state queries
+     * @example publicClient from useAccount() hook
+     */
+    publicClient?: PublicClient;
+    /**
+     * Array of liquidity source types to include
+     * 1 = V2, 2 = V3
+     * @default [1, 2] (both V2 and V3)
+     * @example [2] (V3 only)
+     */
+    types?: number[];
+    /**
+     * Array of enabled liquidity sources
+     * 1 = BITZY, 2 = Other sources
+     * @default [1] (BITZY only)
+     * @example [1, 2] (BITZY and other sources)
+     */
+    enabledSources?: number[];
+    /**
+     * Override partCount calculation logic (offline mode only)
+     * - If provided, this value will be used instead of automatic calculation
+     * - **IGNORED when useOnlinePartCount is true** (best practice)
+     * - If not provided, uses intelligent address-based logic:
+     *   - High-value tokens (BTC, ETH, USDC, USDT): partCount = 5 (better routing)
+     *   - Low-value tokens (meme tokens, small caps): partCount = 1 (simpler routing)
+     *
+     * IMPORTANT EXCEPTIONS & CONCERNS:
+     *
+     * ## Pair Liquidity Impact:
+     * Even high-value tokens can cause issues in low-liquidity pairs:
+     *
+     * ### Problem Examples:
+     * - **BTC-X pair** with only $100 liquidity → Using 5 parts for $1000 swap = 50% impact per part
+     * - **USDC-X pair** with $100,000 liquidity → Using 5 parts for $1000 swap = 1% impact per part
+     *
+     * ### When to Override (offline mode only):
+     * ```typescript
+     * // Low liquidity pair - force single route
+     * const result = useSwapV3Routes(srcToken, dstToken, amountIn, chainId, {
+     *   ...config,
+     *   useOnlinePartCount: false, // Disable online mode
+     *   forcePartCount: 1, // Avoid splitting in low liquidity
+     * });
+     *
+     * // High liquidity pair - allow more routes
+     * const result = useSwapV3Routes(srcToken, dstToken, amountIn, chainId, {
+     *   ...config,
+     *   useOnlinePartCount: false, // Disable online mode
+     *   forcePartCount: 5, // Safe to split in high liquidity
+     * });
+     * ```
+     *
+     * ### Concerns to Consider:
+     * - **Slippage**: Too many parts in low liquidity = higher slippage
+     * - **Gas costs**: More routes = higher transaction costs
+     * - **Execution time**: More routes = longer execution
+     * - **Price impact**: Each part affects price, compounding impact
+     *
+     * ### Recommended Approach:
+     * 1. **Use useOnlinePartCount: true** for automatic pair liquidity detection
+     * 2. **Use forcePartCount** only when online mode is disabled
+     * 3. **Monitor slippage** and adjust accordingly
+     */
+    forcePartCount?: number;
+    /**
+     * Use online API to determine optimal partCount based on real pair liquidity
+     * - If true, calls API to get actual pair liquidity and calculates optimal partCount
+     * - If false or undefined, uses offline address-based logic
+     * - Falls back to offline logic if API call fails
+     * - Uses sensible defaults: 5% max impact, $10,000 min liquidity
+     *
+     * @example
+     * ```typescript
+     * // Use online API for accurate partCount calculation
+     * const result = useSwapV3Routes(srcToken, dstToken, amountIn, chainId, {
+     *   ...config,
+     *   useOnlinePartCount: true, // Get real-time pair liquidity data
+     * });
+     * ```
+     */
+    useOnlinePartCount?: boolean;
+}
+type BN = BigNumber;
+
+declare const ensureBigNumber: (value: any) => BigNumber;
+declare const isBigNumber: (value: any) => value is BigNumber;
+interface SwapV3AddressConfig extends UseSwapV3RoutesAddressConfig {
+    /**
+     * Gas limit for transactions
+     * @default BigInt(50_000_000_000)
+     * @example BigInt(50_000_000_000)
+     */
+    gasLimit?: bigint;
+    /**
+     * Gas price for transactions (optional)
+     * If not provided, uses network default
+     * @example BigInt(20_000_000_000) // 20 gwei
+     */
+    gasPrice?: bigint;
+}
+interface Token {
+    address: Address;
+    symbol: string;
+    name: string;
+    decimals: number;
+    logoURI?: string;
+    chainId?: number;
+}
+interface SwapRoute {
+    routerAddress: Address;
+    lpAddress: Address;
+    fromToken: Address;
+    toToken: Address;
+    from: Address;
+    to: Address;
+    part: string;
+    amountAfterFee: string;
+    dexInterface: number;
+}
+interface SwapResult {
+    routes: SwapRoute[][];
+    distributions: number[];
+    amountOutRoutes: BigNumber[];
+    amountOutBN: BigNumber;
+    amountInParts: BigNumber[];
+    isAmountOutError: boolean;
+    isWrap?: "wrap" | "unwrap";
+}
+interface SwapOptions {
+    amountIn: string;
+    srcToken: Token;
+    dstToken: Token;
+    chainId: number;
+    partCount?: number;
+    liquiditySources?: LiquiditySource[];
+    types?: number[];
+    enabledSources?: number[];
+    /**
+     * Force a specific partCount, overriding intelligent calculation
+     * - If provided, this value will be used instead of automatic calculation
+     * - If not provided, uses intelligent address-based logic:
+     *   - High-value tokens (BTC, ETH, USDC, USDT): partCount = 5 (better routing)
+     *   - Low-value tokens (meme tokens, small caps): partCount = 1 (simpler routing)
+     */
+    forcePartCount?: number;
+}
+interface LiquiditySource {
+    type: "V2" | "V3";
+    source: string;
+    enabled: boolean;
+}
+interface NetworkConfig {
+    routerAddress: Address;
+    bitzyQueryAddress: Address;
+    wrappedAddress: Address;
+    nativeAddress: Address;
+}
+interface PathV3Response {
+    data: {
+        hops: any[];
+        validPath: any[];
+    };
+}
+declare class SwapError extends Error {
+    code: string;
+    details?: any;
+    constructor(options: {
+        message: string;
+        code: string;
+        details?: any;
+    });
+}
+type ChainWrap<T> = {
+    [chainId: number]: T;
+};
+interface LiquiditySourcesConfig {
+    types: number[];
+    enabledSources: number[];
+}
+interface SDKConfig {
+    networks: Record<number, NetworkConfig>;
+    defaultPartCount: number;
+    apiBaseUrl?: string;
+    timeout?: number;
+}
+
+interface FetchSwapRouteConfig {
+    apiBaseUrl?: string;
+    networks?: Record<number, any>;
+    defaultPartCount?: number;
+    timeout?: number;
+    headers?: Record<string, string>;
+    /**
+     * Force a specific partCount, overriding intelligent calculation
+     * - If provided, this value will be used instead of automatic calculation
+     * - If not provided, uses intelligent address-based logic:
+     *   - High-value tokens (BTC, ETH, USDC, USDT): partCount = 5 (better routing)
+     *   - Low-value tokens (meme tokens, small caps): partCount = 1 (simpler routing)
+     */
+    forcePartCount?: number;
+}
+/**
+ * Common function to fetch swap routes
+ * Can be used in any JavaScript/TypeScript environment
+ */
+declare function fetchSwapRoute(options: SwapOptions, config?: FetchSwapRouteConfig): Promise<SwapResult>;
+/**
+ * Batch fetch multiple swap routes
+ */
+declare function fetchBatchSwapRoutes(swaps: Array<{
+    options: SwapOptions;
+    config: FetchSwapRouteConfig;
+}>): Promise<Array<{
+    success: boolean;
+    data?: SwapResult;
+    error?: string;
+}>>;
+/**
+ * Simple quote function
+ */
+declare function getSwapQuote(srcToken: Token, dstToken: Token, amountIn: string, chainId: number, config?: FetchSwapRouteConfig): Promise<{
+    amountOut: string;
+    routes: number;
+}>;
+interface SimplifiedSwapOptions {
+    amountIn: string;
+    srcToken: Token;
+    dstToken: Token;
+    chainId: number;
+    partCount?: number;
+    publicClient?: PublicClient;
+}
+/**
+ * Simplified swap route fetching for 3rd party users
+ * Automatically uses network-specific liquidity sources
+ */
+declare function fetchSwapRouteSimple(options: SimplifiedSwapOptions, config?: FetchSwapRouteConfig): Promise<SwapResult>;
+
+interface UseSwapV3RoutesReturn {
+    routes: any[][];
+    distributions: number[];
+    amountOutRoutes: any[];
+    amountOutBN: BigNumber;
+    amountInParts: any[];
+    fetchRoute: () => Promise<void>;
+    isLoading: boolean;
+    isAmountOutError: boolean;
+    isFirstFetch: boolean;
+    isWrap?: "wrap" | "unwrap";
+    error: string | null;
+    clearError: () => void;
+}
+/**
+ * Hot React Hook for Bitzy Swap V3 Routes
+ *
+ * Provides real-time swap route finding with automatic updates and intelligent routing optimization.
+ *
+ * ## Key Features:
+ *
+ * ### Intelligent partCount Logic:
+ * - **High-value tokens** (BTC, ETH, USDC, USDT): Uses `partCount = 5` for optimal execution
+ * - **Low-value tokens** (meme tokens, small caps): Uses `partCount = 1` for simplicity
+ *
+ * ### Benefits:
+ * - **BTC/ETH swaps**: Use 5 routes for optimal execution and better pricing
+ * - **Meme token swaps**: Use 1 route for simplicity and lower gas costs
+ * - **Stablecoin swaps**: Use 5 routes for better price discovery
+ * - **Easy to extend**: Just add more addresses to the high-value list
+ *
+ * ### Important Exceptions:
+ * **Pair liquidity matters more than token value!**
+ * - BTC-X pair with $100 liquidity → 5 parts for $1000 = 50% impact per part
+ * - USDC-X pair with $100,000 liquidity → 5 parts for $1000 = 1% impact per part
+ *
+ * ### User Control:
+ * - **Online mode**: Use `useOnlinePartCount: true` for automatic pair liquidity detection
+ * - **Offline mode**: Override with `forcePartCount` parameter (ignored when online mode is enabled)
+ * - Customize `defaultPartCount` for high-value tokens
+ * - **Best practice**: Use online mode for accurate results, offline mode for speed
+ *
+ * ## Usage Examples:
+ *
+ * ```typescript
+ * // Minimal usage with defaults
+ * const result = useSwapV3Routes(srcToken, dstToken, amountIn, chainId);
+ * // Uses: apiBaseUrl from DEFAULT_API_BASE_URL, apiKey from NEXT_PUBLIC_BITZY_API_KEY env var or fallback
+ *
+ * // With custom API URL
+ * const result = useSwapV3Routes(srcToken, dstToken, amountIn, chainId, {
+ *   apiBaseUrl: "https://api-public.bitzy.app",
+ * });
+ *
+ * // With custom API key
+ * const result = useSwapV3Routes(srcToken, dstToken, amountIn, chainId, {
+ *   apiKey: "your-custom-api-key",
+ * });
+ *
+ * // With custom liquidity sources
+ * const result = useSwapV3Routes(srcToken, dstToken, amountIn, chainId, {
+ *   apiBaseUrl: "https://api-public.bitzy.app",
+ *   types: [2], // Only V3
+ *   enabledSources: [1], // Only BITZY
+ * });
+ *
+ * // With custom address config
+ * const result = useSwapV3Routes(srcToken, dstToken, amountIn, chainId, {
+ *   apiBaseUrl: "https://api-public.bitzy.app",
+ *   config: addressConfig,
+ * });
+ *
+ * // Force specific partCount
+ * const result = useSwapV3Routes(srcToken, dstToken, amountIn, chainId, {
+ *   apiBaseUrl: "https://api-public.bitzy.app",
+ *   config: addressConfig,
+ *   forcePartCount: 3, // Always use 3 routes
+ * });
+ *
+ * // Custom default for high-value tokens
+ * const result = useSwapV3Routes(srcToken, dstToken, amountIn, chainId, {
+ *   apiBaseUrl: "https://api-public.bitzy.app",
+ *   config: addressConfig,
+ *   defaultPartCount: 7, // High-value tokens use 7 routes instead of 5
+ * });
+ *
+ * // CRITICAL: Check pair liquidity first!
+ * // Low liquidity pair - force single route
+ * const lowLiquidityResult = useSwapV3Routes(srcToken, dstToken, amountIn, chainId, {
+ *   apiBaseUrl: "https://api-public.bitzy.app",
+ *   config: addressConfig,
+ *   forcePartCount: 1, // Avoid splitting in low liquidity pairs
+ * });
+ *
+ * // High liquidity pair - safe to use multiple routes
+ * const highLiquidityResult = useSwapV3Routes(srcToken, dstToken, amountIn, chainId, {
+ *   apiBaseUrl: "https://api-public.bitzy.app",
+ *   config: addressConfig,
+ *   forcePartCount: 5, // Safe to split in high liquidity pairs
+ * });
+ * ```
+ */
+declare const useSwapV3Routes: (srcToken: Token | undefined | null, dstToken: Token | undefined | null, amountIn: string, chainId: number, config?: UseSwapV3RoutesConfig) => UseSwapV3RoutesReturn;
+
+interface APIClientConfig {
+    baseUrl: string;
+    timeout: number;
+    headers?: Record<string, string>;
+}
+declare class APIClient {
+    private static instance;
+    private config;
+    private constructor();
+    /**
+     * Get singleton instance of APIClient
+     * Initializes once with API key and reuses for all requests
+     *
+     * API Key Priority:
+     * 1. Custom headers (if "authen-key" provided in config.headers)
+     * 2. NEXT_PUBLIC_BITZY_API_KEY environment variable
+     * 3. No authentication (if neither provided)
+     */
+    static getInstance(config: APIClientConfig): APIClient;
+    /**
+     * Reset singleton instance (useful for testing or API key changes)
+     */
+    static resetInstance(): void;
+    /**
+     * Make HTTP request with timeout and error handling
+     */
+    private request;
+    /**
+     * Get V3 path for swap routing
+     */
+    getPathV3(srcToken: Token, dstToken: Token, amountIn: string, types: number[], enabledSources: number[]): Promise<PathV3Response>;
+    /**
+     * Get asset minimum partCount from SDK API
+     * Returns minimum amounts for tokens to use multiple routes
+     */
+    getAssetMinimum(): Promise<any>;
+    /**
+     * Build query string from parameters
+     */
+    private buildQueryString;
+}
+
+interface SwapV3ServiceConfig {
+    config: SwapV3AddressConfig;
+    defaultPartCount: number;
+    apiClient: APIClient;
+    publicClient?: PublicClient;
+}
+declare class SwapV3Service {
+    private config;
+    constructor(config: SwapV3ServiceConfig);
+    /**
+     * Fetch swap routes for V3 swaps
+     * This is the core function extracted from the React hook
+     *
+     * ## Intelligent Routing:
+     * - **High-value tokens** (BTC, ETH, USDC, USDT): Uses `partCount = 5` for optimal execution
+     * - **Low-value tokens** (meme tokens, small caps): Uses `partCount = 1` for simplicity
+     *
+     * ## Benefits:
+     * - **BTC/ETH swaps**: Use 5 routes for optimal execution and better pricing
+     * - **Meme token swaps**: Use 1 route for simplicity and lower gas costs
+     * - **Stablecoin swaps**: Use 5 routes for better price discovery
+     * - **Easy to extend**: Just add more addresses to the high-value list
+     *
+     * ## CRITICAL EXCEPTION - Pair Liquidity Impact:
+     * **Pair liquidity matters more than token value!**
+     *
+     * ### Problem Examples:
+     * - **BTC-X pair** with only $100 liquidity → Using 5 parts for $1000 swap = 50% impact per part
+     * - **USDC-X pair** with $100,000 liquidity → Using 5 parts for $1000 swap = 1% impact per part
+     *
+     * ### When to Override:
+     * - Use `forcePartCount: 1` for low liquidity pairs
+     * - Use `forcePartCount: 5` for high liquidity pairs
+     * - Always check pair liquidity before deciding partCount
+     *
+     * ### Concerns:
+     * - **Slippage**: Too many parts in low liquidity = higher slippage
+     * - **Gas costs**: More routes = higher transaction costs
+     * - **Price impact**: Each part affects price, compounding impact
+     */
+    fetchRoute(options: SwapOptions): Promise<SwapResult>;
+    /**
+     * Get supported networks
+     */
+    getSupportedNetworks(): number[];
+    /**
+     * Get network configuration
+     */
+    getNetworkConfig(chainId: number): SwapV3AddressConfig | undefined;
+    /**
+     * Get partCount based on token pair addresses using utility function
+     * @param srcToken - The source token
+     * @param dstToken - The destination token
+     * @param chainId - The chain ID to get network-specific tokens
+     * @param defaultPartCount - Default partCount for high-value pairs
+     * @returns partCount: 5 for high-value pairs, 1 for others
+     */
+    private getPartCount;
+}
+
+declare const DEX_INTERFACE: {
+    readonly V2: 0;
+    readonly V3: 1;
+};
+declare const USER_TARGET: Address;
+declare const ROUTER_TARGET: Address;
+declare const DEFAULT_PART_COUNT = 5;
+declare const DEFAULT_TIMEOUT = 30000;
+declare const DEX_ROUTERS: ChainWrap<Record<string, Address>>;
+declare const CONTRACT_ADDRESSES: ChainWrap<{
+    factoryAddress: Address;
+    v3FactoryAddress: Address;
+    v3PositionManagerAddress: Address;
+    v3WalletHelperAddress: Address;
+    routerAddress: Address;
+    aggregatorAddress: Address;
+    otcAddress: Address;
+    memeTokenGenerator: Address;
+    bitzyQueryAddress: Address;
+    wrappedAddress: Address;
+    nativeAddress: Address;
+    gasLimit: bigint;
+}>;
+declare const LIQUIDITY_SOURCES: ChainWrap<LiquiditySourcesConfig>;
+declare const getLiquiditySources: (chainId: number) => LiquiditySourcesConfig;
+declare const getContractAddresses: (chainId: number) => {
+    factoryAddress: Address;
+    v3FactoryAddress: Address;
+    v3PositionManagerAddress: Address;
+    v3WalletHelperAddress: Address;
+    routerAddress: Address;
+    aggregatorAddress: Address;
+    otcAddress: Address;
+    memeTokenGenerator: Address;
+    bitzyQueryAddress: Address;
+    wrappedAddress: Address;
+    nativeAddress: Address;
+    gasLimit: bigint;
+};
+declare const getDexRouters: (chainId: number) => Record<string, `0x${string}`>;
+declare const DEFAULT_NETWORKS: ChainWrap<{
+    factoryAddress: Address;
+    v3FactoryAddress: Address;
+    v3PositionManagerAddress: Address;
+    v3WalletHelperAddress: Address;
+    routerAddress: Address;
+    aggregatorAddress: Address;
+    otcAddress: Address;
+    memeTokenGenerator: Address;
+    bitzyQueryAddress: Address;
+    wrappedAddress: Address;
+    nativeAddress: Address;
+    gasLimit: bigint;
+}>;
+declare const DEX_ROUTER: Record<string, `0x${string}`>;
+declare const API_ENDPOINTS: {
+    readonly PATH_V3: "/api/sdk/bestpath/split";
+    readonly ASSET_MINIMUM: "/api/sdk/asset/minimum";
+};
+declare const ERROR_CODES: {
+    readonly INVALID_TOKENS: "INVALID_TOKENS";
+    readonly INVALID_AMOUNT: "INVALID_AMOUNT";
+    readonly NETWORK_NOT_SUPPORTED: "NETWORK_NOT_SUPPORTED";
+    readonly API_ERROR: "API_ERROR";
+    readonly QUERY_ERROR: "QUERY_ERROR";
+    readonly INSUFFICIENT_LIQUIDITY: "INSUFFICIENT_LIQUIDITY";
+};
+
+declare const BITZY_QUERY_ABI: readonly [{
+    readonly inputs: readonly [{
+        readonly internalType: "uint256";
+        readonly name: "srcAmount";
+        readonly type: "uint256";
+    }, {
+        readonly internalType: "bytes";
+        readonly name: "encodedRoutes";
+        readonly type: "bytes";
+    }, {
+        readonly internalType: "uint256";
+        readonly name: "parts";
+        readonly type: "uint256";
+    }];
+    readonly name: "splitQuery";
+    readonly outputs: readonly [{
+        readonly components: readonly [{
+            readonly internalType: "uint256";
+            readonly name: "amountOut";
+            readonly type: "uint256";
+        }, {
+            readonly internalType: "uint256";
+            readonly name: "bestIndex";
+            readonly type: "uint256";
+        }];
+        readonly internalType: "struct BitzyQueryV2.OneRoute";
+        readonly name: "";
+        readonly type: "tuple";
+    }, {
+        readonly components: readonly [{
+            readonly internalType: "uint256[]";
+            readonly name: "distribution";
+            readonly type: "uint256[]";
+        }, {
+            readonly internalType: "uint256";
+            readonly name: "amountOut";
+            readonly type: "uint256";
+        }];
+        readonly internalType: "struct BitzyQueryV2.SplitRoute";
+        readonly name: "";
+        readonly type: "tuple";
+    }];
+    readonly stateMutability: "nonpayable";
+    readonly type: "function";
+}];
+
+/**
+ * Convert token amount from human readable format to wei
+ * @param amount - Human readable amount (e.g., "1.5")
+ * @param decimals - Token decimals
+ * @returns BigNumber representation in wei
+ */
+declare function fromTokenAmount(amount: string, decimals: number): BigNumber;
+/**
+ * Convert token amount from wei to human readable format
+ * @param amount - Amount in wei
+ * @param decimals - Token decimals
+ * @returns Human readable amount string
+ */
+declare function toTokenAmount(amount: BigNumber | string, decimals: number): string;
+/**
+ * Check if a token is native (ETH, BNB, etc.)
+ * @param token - Token to check
+ * @param nativeAddress - Native token address for the network
+ * @returns boolean
+ */
+declare function isNativeToken(token: Token, nativeAddress: Address): boolean;
+/**
+ * Check if a token is wrapped (WETH, WBNB, etc.)
+ * @param token - Token to check
+ * @param wrappedAddress - Wrapped token address for the network
+ * @returns boolean
+ */
+declare function isWrappedToken(token: Token, wrappedAddress: Address): boolean;
+/**
+ * Validate token addresses
+ * @param srcToken - Source token
+ * @param dstToken - Destination token
+ * @returns boolean
+ */
+declare function validateTokens(srcToken: Token, dstToken: Token): boolean;
+/**
+ * Validate amount input
+ * @param amount - Amount to validate
+ * @returns boolean
+ */
+declare function validateAmount(amount: string): boolean;
+/**
+ * Calculate optimal part count of a route based on amount and price
+ * @param amount - Input amount
+ * @param price - Token price in USD
+ * @param partCount - Default part count of a route
+ * @returns number
+ */
+declare function calculatePartCount(amount: string, price: number, partCount?: number): number;
+/**
+ * Format error message
+ * @param error - Error object or string
+ * @returns Formatted error string
+ */
+declare function formatError(error: any): string;
+/**
+ * Debounce function
+ * @param func - Function to debounce
+ * @param wait - Wait time in milliseconds
+ * @returns Debounced function with cancel method
+ */
+declare function debounce<T extends (...args: any[]) => any>(func: T, wait: number): ((...args: Parameters<T>) => void) & {
+    cancel: () => void;
+};
+
+/**
+ * Clear the minimum amounts cache
+ * Useful for testing or when you need fresh data immediately
+ */
+declare function clearMinimumAmountsCache(): void;
+/**
+ * High-value tokens that benefit from multi-route optimization
+ * These tokens typically have high liquidity and benefit from route splitting
+ * Network-specific token addresses using ChainWrap pattern
+ */
+declare const HIGH_VALUE_TOKENS: ChainWrap<string[]>;
+/**
+ * Check if a token is considered high-value based on its address and chain
+ * @param token - The token to check
+ * @param chainId - The chain ID to get network-specific tokens
+ * @returns true if the token is high-value, false otherwise
+ */
+declare function isHighValueToken(token: Token | undefined | null, chainId: number): boolean;
+/**
+ * Get partCount based on token pair addresses (offline logic)
+ * This function uses hardcoded address-based logic to determine optimal partCount
+ * Considers both tokens in the pair for better decision making
+ *
+ * IMPORTANT: This is a simplified approach that doesn't consider actual pair liquidity!
+ * For more accurate results, use getPartCountOnline() which checks actual pair liquidity.
+ *
+ * @param srcToken - The source token
+ * @param dstToken - The destination token
+ * @param chainId - The chain ID to get network-specific tokens
+ * @param defaultPartCount - Default partCount for high-value pairs (default: 5)
+ * @returns partCount: 5 for high-value pairs, 1 for others
+ *
+ * @example
+ * ```typescript
+ * // High-value pair (BTC-USDC) → returns 5
+ * const highValuePartCount = getPartCountOffline(btcToken, usdcToken, 3637, 5);
+ *
+ * // Low-value pair (BTC-MEME) → returns 1
+ * const lowValuePartCount = getPartCountOffline(btcToken, memeToken, 3637, 5);
+ * ```
+ */
+declare function getPartCountOffline(srcToken: Token | undefined | null, dstToken: Token | undefined | null, chainId: number, defaultPartCount?: number): number;
+/**
+ * Get partCount using online API data (minimum amount-based)
+ * Checks if the swap amount meets the minimum threshold for multi-route optimization
+ *
+ * @param srcToken - Source token
+ * @param dstToken - Destination token
+ * @param amountIn - Input amount
+ * @param chainId - Chain ID
+ * @param apiBaseUrl - API base URL
+ * @param apiKey - Optional API key
+ * @returns Promise<number> - partCount (5 if amount >= minimum for both tokens, otherwise fallback)
+ */
+declare function getPartCountOnline(srcToken: Token, dstToken: Token, amountIn: string, chainId: number, apiBaseUrl: string, apiKey?: string, fallbackPartCount?: number): Promise<number>;
+/**
+ * Get partCount with fallback strategy
+ * Tries online API first, falls back to offline logic if API fails
+ * Uses sensible defaults: 5% max impact, $10,000 min liquidity
+ *
+ * @param srcToken - The source token
+ * @param dstToken - The destination token
+ * @param amountIn - The swap amount
+ * @param chainId - The chain ID
+ * @param apiBaseUrl - The API base URL
+ * @param fallbackPartCount - PartCount to use if API fails (default: 5)
+ * @returns Promise<number> - Optimal partCount
+ *
+ * @example
+ * ```typescript
+ * // Try online first, fallback to offline
+ * const partCount = await getPartCountWithFallback(
+ *   srcToken,
+ *   dstToken,
+ *   amountIn,
+ *   chainId,
+ *   apiBaseUrl,
+ *   5 // fallback partCount
+ * );
+ * ```
+ */
+declare function getPartCountWithFallback(srcToken: Token, dstToken: Token, amountIn: string, chainId: number, apiBaseUrl: string, fallbackPartCount?: number, apiKey?: string): Promise<number>;
+/**
+ * Calculate price impact for a given swap
+ * @param swapAmount - The swap amount in USD
+ * @param pairLiquidity - The pair liquidity in USD
+ * @param partCount - The number of parts to split the swap
+ * @returns The price impact percentage
+ */
+declare function calculatePriceImpact(swapAmount: number, pairLiquidity: number, partCount: number): number;
+/**
+ * Determine optimal partCount based on price impact thresholds
+ * @param swapAmount - The swap amount in USD
+ * @param pairLiquidity - The pair liquidity in USD
+ * @param maxImpactThreshold - Maximum acceptable impact per part (default: 5%)
+ * @returns Optimal partCount (1 or 5)
+ */
+declare function getOptimalPartCount(swapAmount: number, pairLiquidity: number, maxImpactThreshold?: number): number;
+
+export { APIClient, API_ENDPOINTS, BITZY_QUERY_ABI, CONTRACT_ADDRESSES, DEFAULT_NETWORKS, DEFAULT_PART_COUNT, DEFAULT_TIMEOUT, DEX_INTERFACE, DEX_ROUTER, DEX_ROUTERS, ERROR_CODES, HIGH_VALUE_TOKENS, LIQUIDITY_SOURCES, ROUTER_TARGET, SwapError, SwapV3Service, USER_TARGET, calculatePartCount, calculatePriceImpact, clearMinimumAmountsCache, debounce, ensureBigNumber, fetchBatchSwapRoutes, fetchSwapRoute, fetchSwapRouteSimple, formatError, fromTokenAmount, getContractAddresses, getDexRouters, getLiquiditySources, getOptimalPartCount, getPartCountOffline, getPartCountOnline, getPartCountWithFallback, getSwapQuote, fetchSwapRoute as getSwapRoute, isBigNumber, isHighValueToken, isNativeToken, isWrappedToken, toTokenAmount, useSwapV3Routes as useSwapRoutes, useSwapV3Routes, validateAmount, validateTokens };
+export type { APIClientConfig, BN, ChainWrap, FetchSwapRouteConfig, LiquiditySource, LiquiditySourcesConfig, NetworkConfig, PathV3Response, SDKConfig, SwapOptions, SwapResult, SwapRoute, SwapV3AddressConfig, SwapV3ServiceConfig, Token, UseSwapV3RoutesAddressConfig, UseSwapV3RoutesConfig, UseSwapV3RoutesReturn };