@provable-games/ekubo-sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,927 @@
+/**
+ * Ekubo pool key identifying a unique liquidity pool
+ */
+interface PoolKey {
+    token0: string;
+    token1: string;
+    fee: string;
+    tick_spacing: number;
+    extension: string;
+}
+/**
+ * A single hop in a swap route through one pool
+ */
+interface RouteNode {
+    pool_key: PoolKey;
+    sqrt_ratio_limit: string;
+    skip_ahead: number;
+}
+/**
+ * A split in a multi-route swap, representing one path through liquidity pools
+ */
+interface SwapSplit {
+    amount_specified: string;
+    route: RouteNode[];
+}
+/**
+ * A complete swap quote from the Ekubo API
+ */
+interface SwapQuote {
+    /** Price impact as a decimal (e.g., 0.01 = 1%) */
+    impact: number;
+    /** Total amount to send or receive (always positive) */
+    total: bigint;
+    /** Individual route splits for multi-path swaps */
+    splits: SwapSplit[];
+}
+/**
+ * Raw API response format (before transformation)
+ */
+interface SwapQuoteApiResponse {
+    price_impact: number;
+    total_calculated: string | number;
+    splits: SwapSplit[];
+}
+/**
+ * Error response from the Ekubo API
+ */
+interface SwapQuoteErrorResponse {
+    error: string;
+}
+
+/**
+ * Token information for registry and resolution
+ */
+interface TokenInfo {
+    /** Token symbol (e.g., "ETH", "STRK") */
+    symbol: string;
+    /** Contract address (hex string) */
+    address: string;
+    /** Token decimals (default: 18) */
+    decimals?: number;
+    /** Human-readable name */
+    name?: string;
+}
+
+/**
+ * Configuration for fetch operations with retry logic
+ */
+interface FetchConfig {
+    /** Request timeout in milliseconds (default: 10000) */
+    timeout?: number;
+    /** Maximum number of retry attempts (default: 3) */
+    maxRetries?: number;
+    /** Base backoff delay in milliseconds (default: 1000) */
+    baseBackoff?: number;
+    /** Maximum backoff delay in milliseconds (default: 5000) */
+    maxBackoff?: number;
+    /** Custom fetch function (for SSR or custom implementations) */
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * Configuration for quote polling
+ */
+interface PollingConfig {
+    /** Polling interval in milliseconds (default: 5000) */
+    interval?: number;
+    /** Maximum consecutive errors before auto-stopping (default: 3) */
+    maxConsecutiveErrors?: number;
+}
+/**
+ * Main configuration for EkuboClient
+ */
+interface EkuboClientConfig {
+    /** Chain shorthand: 'mainnet' or 'sepolia' */
+    chain?: "mainnet" | "sepolia";
+    /** Custom chain ID (overrides chain setting) */
+    chainId?: string;
+    /** Custom quoter API URL (for swap quotes) */
+    quoterApiUrl?: string;
+    /** Custom API URL (for tokens, prices, stats, etc.) */
+    apiUrl?: string;
+    /** Custom router contract address */
+    routerAddress?: string;
+    /** Default slippage percentage as bigint (default: 5n = 5%) */
+    defaultSlippagePercent?: bigint;
+    /** Fetch configuration */
+    fetch?: FetchConfig;
+    /** Polling configuration */
+    polling?: PollingConfig;
+    /** Additional custom tokens to register */
+    customTokens?: TokenInfo[];
+}
+/**
+ * Resolved configuration with all defaults applied
+ */
+interface ResolvedConfig {
+    chainId: string;
+    quoterApiUrl: string;
+    apiUrl: string;
+    routerAddress: string;
+    defaultSlippagePercent: bigint;
+    fetch: Required<FetchConfig>;
+    polling: Required<PollingConfig>;
+}
+
+/**
+ * A single Starknet call (compatible with starknet.js Call type)
+ */
+interface SwapCall {
+    contractAddress: string;
+    entrypoint: string;
+    calldata: string[];
+}
+/**
+ * Result of swap call generation
+ */
+interface SwapCallsResult {
+    /** Transfer call to send tokens to router */
+    transferCall: SwapCall;
+    /** Swap execution calls */
+    swapCalls: SwapCall[];
+    /** Clear remaining tokens call */
+    clearCall: SwapCall;
+    /** All calls in execution order */
+    allCalls: SwapCall[];
+}
+/**
+ * Parameters for fetching a swap quote
+ */
+interface FetchQuoteParams {
+    /** Amount to swap (in smallest unit) */
+    amount: bigint;
+    /** Token to sell (address or symbol) */
+    tokenFrom: string;
+    /** Token to buy (address or symbol) */
+    tokenTo: string;
+    /** Optional abort signal for cancellation */
+    signal?: AbortSignal;
+}
+
+/**
+ * Price history data point
+ */
+interface PriceDataPoint {
+    timestamp: number;
+    price: number;
+}
+/**
+ * Price history response
+ */
+interface PriceHistoryResponse {
+    data: PriceDataPoint[];
+}
+/**
+ * Parameters for getPriceHistory
+ */
+interface GetPriceHistoryParams {
+    /** Token to get price for */
+    token: string;
+    /** Quote token (e.g., USDC) */
+    otherToken: string;
+    /** Chain ID (Ekubo format) */
+    chainId?: string;
+    /** Time interval in seconds */
+    interval?: number;
+    /** API base URL */
+    apiUrl?: string;
+    /** Fetch configuration */
+    fetchConfig?: FetchConfig;
+}
+/**
+ * Fetch price history from Ekubo API
+ */
+declare function getPriceHistory(params: GetPriceHistoryParams): Promise<PriceHistoryResponse>;
+
+/**
+ * Token metadata from Ekubo API
+ */
+interface ApiTokenInfo {
+    /** Token contract address */
+    address: string;
+    /** Token name */
+    name: string;
+    /** Token symbol */
+    symbol: string;
+    /** Token decimals */
+    decimals: number;
+    /** Logo URI (optional) */
+    logo_uri?: string;
+    /** Whether token is verified/trusted */
+    verified?: boolean;
+}
+/**
+ * Parameters for fetching tokens
+ */
+interface FetchTokensParams {
+    /** Chain ID (Ekubo format) */
+    chainId?: string;
+    /** API base URL */
+    apiUrl?: string;
+    /** Fetch configuration */
+    fetchConfig?: FetchConfig;
+}
+/**
+ * Parameters for fetching a single token
+ */
+interface FetchTokenParams extends FetchTokensParams {
+    /** Token contract address */
+    tokenAddress: string;
+}
+/**
+ * Parameters for batch fetching tokens
+ */
+interface FetchTokensBatchParams extends FetchTokensParams {
+    /** Token contract addresses */
+    tokenAddresses: string[];
+}
+/**
+ * Fetch list of all tokens for a chain
+ */
+declare function fetchTokens(params?: FetchTokensParams): Promise<ApiTokenInfo[]>;
+/**
+ * Fetch metadata for a single token
+ */
+declare function fetchToken(params: FetchTokenParams): Promise<ApiTokenInfo | null>;
+/**
+ * Fetch metadata for multiple tokens at once
+ */
+declare function fetchTokensBatch(params: FetchTokensBatchParams): Promise<ApiTokenInfo[]>;
+
+/**
+ * Trading pair statistics
+ */
+interface PairStats {
+    token0: string;
+    token1: string;
+    tvl_usd: number;
+    volume_24h_usd: number;
+    fees_24h_usd: number;
+    price: number;
+    price_change_24h: number;
+}
+/**
+ * Overview statistics response
+ */
+interface OverviewStats {
+    tvl_usd: number;
+    volume_24h_usd: number;
+    fees_24h_usd: number;
+}
+/**
+ * Pool information
+ */
+interface PoolInfo {
+    key_hash: string;
+    token0: string;
+    token1: string;
+    fee: string;
+    tick_spacing: number;
+    extension: string;
+    tvl_usd: number;
+    volume_24h_usd: number;
+}
+/**
+ * TVL data point
+ */
+interface TvlDataPoint {
+    timestamp: number;
+    tvl_usd: number;
+}
+/**
+ * Volume data point
+ */
+interface VolumeDataPoint {
+    timestamp: number;
+    volume_usd: number;
+}
+/**
+ * Base parameters for stats API calls
+ */
+interface StatsBaseParams {
+    /** Chain ID (Ekubo format) */
+    chainId?: string;
+    /** API base URL */
+    apiUrl?: string;
+    /** Fetch configuration */
+    fetchConfig?: FetchConfig;
+}
+/**
+ * Parameters for pair-specific queries
+ */
+interface PairStatsParams extends StatsBaseParams {
+    /** First token address */
+    tokenA: string;
+    /** Second token address */
+    tokenB: string;
+}
+/**
+ * Fetch overview of top trading pairs
+ */
+declare function fetchTopPairs(params?: StatsBaseParams): Promise<PairStats[]>;
+/**
+ * Fetch protocol TVL overview
+ */
+declare function fetchTvl(params?: StatsBaseParams): Promise<OverviewStats>;
+/**
+ * Fetch protocol volume overview
+ */
+declare function fetchVolume(params?: StatsBaseParams): Promise<OverviewStats>;
+/**
+ * Fetch TVL for a specific trading pair
+ */
+declare function fetchPairTvl(params: PairStatsParams): Promise<TvlDataPoint[]>;
+/**
+ * Fetch volume for a specific trading pair
+ */
+declare function fetchPairVolume(params: PairStatsParams): Promise<VolumeDataPoint[]>;
+/**
+ * Fetch pools for a specific trading pair
+ */
+declare function fetchPairPools(params: PairStatsParams): Promise<PoolInfo[]>;
+
+/**
+ * Parameters for generating swap calls
+ */
+interface GenerateSwapCallsParams {
+    /** Token being sold (address) */
+    sellToken: string;
+    /** Token being bought (address) */
+    buyToken: string;
+    /** Minimum amount of buyToken to receive */
+    minimumReceived: bigint;
+    /** Quote from Ekubo API */
+    quote: SwapQuote;
+    /** Chain ID (Ekubo format) */
+    chainId?: string;
+    /** Router contract address (overrides chainId lookup) */
+    routerAddress?: string;
+    /** Slippage percentage for transfer amount (default: 5n = 5%) */
+    slippagePercent?: bigint;
+}
+/**
+ * Generate swap calls for Ekubo router
+ *
+ * This generates the calls needed to execute a swap:
+ * 1. Transfer tokens to router
+ * 2. Execute multihop_swap or multi_multihop_swap
+ * 3. Clear minimum profits
+ * 4. Clear remaining tokens
+ */
+declare function generateSwapCalls(params: GenerateSwapCallsParams): SwapCallsResult;
+/**
+ * Prepare swap calls with approval included
+ * This is a convenience wrapper that adds the ERC20 approve call
+ */
+declare function prepareSwapCalls(params: GenerateSwapCallsParams): SwapCallsResult & {
+    approveCall: SwapCall;
+};
+
+/**
+ * Token registry for managing token information and symbol-to-address resolution
+ */
+declare class TokenRegistry {
+    private symbolMap;
+    private addressMap;
+    constructor(tokens?: TokenInfo[]);
+    /**
+     * Register a token
+     */
+    register(token: TokenInfo): void;
+    /**
+     * Get token by symbol (case-insensitive)
+     */
+    getBySymbol(symbol: string): TokenInfo | undefined;
+    /**
+     * Get token by address (normalized)
+     */
+    getByAddress(address: string): TokenInfo | undefined;
+    /**
+     * Check if a token exists by symbol
+     */
+    hasSymbol(symbol: string): boolean;
+    /**
+     * Check if a token exists by address
+     */
+    hasAddress(address: string): boolean;
+    /**
+     * Get all registered tokens
+     */
+    getAll(): TokenInfo[];
+    /**
+     * Get all registered symbols
+     */
+    getSymbols(): string[];
+}
+/**
+ * Get the default token registry (singleton)
+ */
+declare function getDefaultRegistry(): TokenRegistry;
+/**
+ * Create a new token registry with custom tokens
+ */
+declare function createTokenRegistry(customTokens?: TokenInfo[]): TokenRegistry;
+
+/**
+ * Resolve a token identifier (symbol or address) to a normalized address
+ *
+ * @param tokenIdentifier - Token symbol (e.g., "ETH") or address
+ * @param registry - Optional token registry (defaults to mainnet tokens)
+ * @returns Normalized address
+ * @throws TokenNotFoundError if symbol is not found in registry
+ */
+declare function resolveToken(tokenIdentifier: string, registry?: TokenRegistry): string;
+/**
+ * Resolve a token identifier to full token info
+ *
+ * @param tokenIdentifier - Token symbol or address
+ * @param registry - Optional token registry
+ * @returns TokenInfo or undefined if not found
+ */
+declare function resolveTokenInfo(tokenIdentifier: string, registry?: TokenRegistry): TokenInfo | undefined;
+/**
+ * Check if a token identifier can be resolved
+ */
+declare function canResolveToken(tokenIdentifier: string, registry?: TokenRegistry): boolean;
+
+/**
+ * Well-known mainnet tokens
+ */
+declare const MAINNET_TOKENS: TokenInfo[];
+/**
+ * Get mainnet tokens as a map by symbol (uppercase)
+ */
+declare function getMainnetTokensMap(): Map<string, TokenInfo>;
+
+/**
+ * Default polling configuration
+ */
+declare const DEFAULT_POLLING_CONFIG: Required<PollingConfig>;
+/**
+ * Quote poller callbacks
+ */
+interface QuotePollerCallbacks {
+    /** Called when a new quote is received */
+    onQuote: (quote: SwapQuote) => void;
+    /** Called when an error occurs */
+    onError?: (error: Error) => void;
+    /** Called when polling stops (due to errors or manually) */
+    onStop?: (reason: "manual" | "errors") => void;
+}
+/**
+ * Parameters for quote polling
+ */
+interface QuotePollerParams {
+    /** Amount to swap */
+    amount: bigint;
+    /** Token to sell (address) */
+    tokenFrom: string;
+    /** Token to buy (address) */
+    tokenTo: string;
+    /** Chain ID (Ekubo format) */
+    chainId?: string;
+}
+/**
+ * QuotePoller class for real-time quote updates
+ */
+declare class QuotePoller {
+    private intervalId;
+    private abortController;
+    private consecutiveErrors;
+    private isRunning;
+    private readonly params;
+    private readonly callbacks;
+    private readonly config;
+    private readonly fetchConfig?;
+    constructor(params: QuotePollerParams, callbacks: QuotePollerCallbacks, config?: PollingConfig, fetchConfig?: FetchConfig);
+    /**
+     * Start polling for quotes
+     */
+    start(): void;
+    /**
+     * Stop polling
+     */
+    stop(): void;
+    /**
+     * Check if currently polling
+     */
+    get running(): boolean;
+    /**
+     * Update polling parameters (requires restart)
+     */
+    updateParams(params: Partial<QuotePollerParams>): void;
+    /**
+     * Fetch a quote
+     */
+    private fetchQuote;
+    /**
+     * Stop due to consecutive errors
+     */
+    private stopDueToErrors;
+}
+/**
+ * Create a quote poller instance
+ */
+declare function createQuotePoller(params: QuotePollerParams, callbacks: QuotePollerCallbacks, config?: PollingConfig, fetchConfig?: FetchConfig): QuotePoller;
+
+/**
+ * Main Ekubo SDK client
+ *
+ * Provides a high-level interface for:
+ * - Fetching swap quotes
+ * - Generating swap calls
+ * - Token symbol resolution
+ * - Quote polling
+ * - Protocol statistics (TVL, volume, pairs)
+ * - Dynamic token list fetching
+ */
+declare class EkuboClient {
+    private readonly config;
+    private readonly tokenRegistry;
+    constructor(config?: EkuboClientConfig);
+    /**
+     * Resolve configuration with defaults
+     */
+    private resolveConfig;
+    /**
+     * Get the current chain ID
+     */
+    get chainId(): string;
+    /**
+     * Get the router contract address
+     */
+    get routerAddress(): string;
+    /**
+     * Get the token registry
+     */
+    get tokens(): TokenRegistry;
+    /**
+     * Resolve a token identifier (symbol or address) to an address
+     */
+    resolveToken(tokenIdentifier: string): string;
+    /**
+     * Fetch a swap quote
+     *
+     * @param params - Quote parameters (supports symbols or addresses)
+     * @returns Swap quote
+     */
+    getQuote(params: FetchQuoteParams): Promise<SwapQuote>;
+    /**
+     * Fetch a token price in USDC
+     *
+     * @param tokenIdentifier - Token symbol or address
+     * @param amount - Amount of token
+     * @param signal - Optional abort signal
+     * @returns Price in USDC (as bigint)
+     */
+    getUsdcPrice(tokenIdentifier: string, amount: bigint, signal?: AbortSignal): Promise<bigint>;
+    /**
+     * Fetch price history
+     *
+     * @param token - Token symbol or address
+     * @param otherToken - Quote token symbol or address
+     * @param interval - Time interval in seconds (default: 7000)
+     * @returns Price history data
+     */
+    getPriceHistory(token: string, otherToken: string, interval?: number): Promise<PriceHistoryResponse>;
+    /**
+     * Generate swap calls from a quote
+     *
+     * @param params - Call generation parameters (supports symbols or addresses)
+     * @returns Swap calls result
+     */
+    generateSwapCalls(params: Omit<GenerateSwapCallsParams, "chainId" | "routerAddress">): SwapCallsResult;
+    /**
+     * Prepare swap calls with approval included
+     *
+     * @param params - Call generation parameters (supports symbols or addresses)
+     * @returns Swap calls result with approve call
+     */
+    prepareSwapCalls(params: Omit<GenerateSwapCallsParams, "chainId" | "routerAddress">): SwapCallsResult & {
+        approveCall: SwapCall;
+    };
+    /**
+     * Create a quote poller for real-time updates
+     *
+     * @param params - Quote parameters (supports symbols or addresses)
+     * @param callbacks - Poller callbacks
+     * @param config - Optional polling configuration
+     * @returns QuotePoller instance
+     */
+    createQuotePoller(params: Omit<FetchQuoteParams, "signal">, callbacks: QuotePollerCallbacks, config?: PollingConfig): QuotePoller;
+    /**
+     * Register a custom token in the local registry
+     */
+    registerToken(token: TokenInfo): void;
+    /**
+     * Fetch all tokens from the Ekubo API
+     *
+     * @returns Array of token metadata from the API
+     */
+    fetchTokens(): Promise<ApiTokenInfo[]>;
+    /**
+     * Fetch metadata for a single token from the API
+     *
+     * @param tokenAddress - Token contract address
+     * @returns Token metadata or null if not found
+     */
+    fetchToken(tokenAddress: string): Promise<ApiTokenInfo | null>;
+    /**
+     * Fetch metadata for multiple tokens at once
+     *
+     * @param tokenAddresses - Array of token addresses
+     * @returns Array of token metadata
+     */
+    fetchTokensBatch(tokenAddresses: string[]): Promise<ApiTokenInfo[]>;
+    /**
+     * Fetch tokens from API and register them in the local registry
+     *
+     * @returns Number of tokens registered
+     */
+    syncTokensFromApi(): Promise<number>;
+    /**
+     * Fetch top trading pairs by volume
+     *
+     * @returns Array of pair statistics
+     */
+    getTopPairs(): Promise<PairStats[]>;
+    /**
+     * Fetch protocol TVL overview
+     *
+     * @returns TVL statistics
+     */
+    getTvl(): Promise<OverviewStats>;
+    /**
+     * Fetch protocol volume overview
+     *
+     * @returns Volume statistics
+     */
+    getVolume(): Promise<OverviewStats>;
+    /**
+     * Fetch TVL history for a trading pair
+     *
+     * @param tokenA - First token (symbol or address)
+     * @param tokenB - Second token (symbol or address)
+     * @returns TVL data points
+     */
+    getPairTvl(tokenA: string, tokenB: string): Promise<TvlDataPoint[]>;
+    /**
+     * Fetch volume history for a trading pair
+     *
+     * @param tokenA - First token (symbol or address)
+     * @param tokenB - Second token (symbol or address)
+     * @returns Volume data points
+     */
+    getPairVolume(tokenA: string, tokenB: string): Promise<VolumeDataPoint[]>;
+    /**
+     * Fetch pools for a trading pair
+     *
+     * @param tokenA - First token (symbol or address)
+     * @param tokenB - Second token (symbol or address)
+     * @returns Pool information
+     */
+    getPairPools(tokenA: string, tokenB: string): Promise<PoolInfo[]>;
+}
+/**
+ * Create an EkuboClient instance
+ */
+declare function createEkuboClient(config?: EkuboClientConfig): EkuboClient;
+
+/**
+ * Parameters for fetchSwapQuote
+ */
+interface FetchSwapQuoteParams {
+    /** Amount to receive (will be negated internally) */
+    amount: bigint;
+    /** Token to sell (address) */
+    tokenFrom: string;
+    /** Token to buy (address) */
+    tokenTo: string;
+    /** Chain ID (Ekubo format) */
+    chainId?: string;
+    /** Abort signal for cancellation */
+    signal?: AbortSignal;
+    /** Fetch configuration */
+    fetchConfig?: FetchConfig;
+}
+/**
+ * Fetch a swap quote from Ekubo API with retry logic
+ */
+declare function fetchSwapQuote(params: FetchSwapQuoteParams): Promise<SwapQuote>;
+/**
+ * Fetch token price in USDC
+ */
+declare function fetchSwapQuoteInUsdc(params: Omit<FetchSwapQuoteParams, "tokenTo">): Promise<bigint>;
+
+/**
+ * Result of encoding a route
+ */
+interface EncodedRoute {
+    token: string;
+    encoded: string[];
+}
+/**
+ * Encode a single route node into calldata format
+ */
+declare function encodeRouteNode(routeNode: RouteNode, currentToken: string): {
+    nextToken: string;
+    calldata: string[];
+};
+/**
+ * Encode a full route (array of route nodes) into calldata format
+ */
+declare function encodeRoute(route: RouteNode[], targetToken: string): EncodedRoute;
+
+/**
+ * Ekubo chain IDs (decimal string format used by API)
+ */
+declare const CHAIN_IDS: {
+    readonly MAINNET: "23448594291968334";
+    readonly SEPOLIA: "393402133025997798000961";
+};
+/**
+ * Starknet.js chain ID constants (hex format)
+ */
+declare const STARKNET_CHAIN_IDS: {
+    readonly SN_MAIN: "0x534e5f4d41494e";
+    readonly SN_SEPOLIA: "0x534e5f5345504f4c4941";
+};
+/**
+ * Ekubo Router contract addresses by chain
+ */
+declare const ROUTER_ADDRESSES: {
+    readonly "23448594291968334": "0x0199741822c2dc722f6f605204f35e56dbc23bceed54818168c4c49e4fb8737e";
+    readonly "393402133025997798000961": "0x0045f933adf0607292468ad1c1dedaa74d5ad166392590e72676a34d01d7b763";
+};
+/**
+ * USDC contract addresses by chain (for price quotes)
+ */
+declare const USDC_ADDRESSES: {
+    readonly "23448594291968334": "0x033068F6539f8e6e6b131e6B2B814e6c34A5224bC66947c47DaB9dFeE93b35fb";
+    readonly "393402133025997798000961": "0x053b40a647cedfca6ca84f542a0fe36736031905a9639a7f19a3c1e66bfd5080";
+};
+/**
+ * API base URLs
+ */
+declare const API_URLS: {
+    /** Quoter API for swap quotes */
+    readonly QUOTER: "https://prod-api-quoter.ekubo.org";
+    /** Main API for tokens, prices, stats, etc. */
+    readonly API: "https://prod-api.ekubo.org";
+};
+/**
+ * Chain configuration preset
+ */
+interface ChainConfig {
+    chainId: string;
+    quoterApiUrl: string;
+    apiUrl: string;
+    routerAddress: string;
+    usdcAddress: string;
+}
+/**
+ * Pre-configured chain configurations
+ */
+declare const CHAIN_CONFIGS: Record<"mainnet" | "sepolia", ChainConfig>;
+/**
+ * Map starknet.js chain IDs to Ekubo chain IDs
+ */
+declare const STARKNET_TO_EKUBO_CHAIN: Record<string, string>;
+/**
+ * Get Ekubo chain ID from starknet.js chain ID
+ */
+declare function getEkuboChainId(starknetChainId: string): string | undefined;
+/**
+ * Get chain config by chain name or ID
+ */
+declare function getChainConfig(chainOrId: "mainnet" | "sepolia" | string): ChainConfig | undefined;
+
+/**
+ * Calculate exponential backoff delay with jitter
+ */
+declare function calculateBackoff(attempt: number, baseBackoff: number, maxBackoff: number, retryAfter?: string | null): number;
+/**
+ * Sleep for a specified duration
+ */
+declare function sleep(ms: number): Promise<void>;
+/**
+ * Options for withRetry function
+ */
+interface RetryOptions {
+    maxRetries: number;
+    baseBackoff: number;
+    maxBackoff: number;
+    signal?: AbortSignal;
+    onRetry?: (attempt: number, error: Error, delay: number) => void;
+}
+/**
+ * Execute a function with retry logic
+ */
+declare function withRetry<T>(fn: () => Promise<T>, options: RetryOptions): Promise<T>;
+
+/**
+ * Parse total_calculated from API response (handles string or number)
+ * Returns absolute value since negative is just API convention for swap direction
+ */
+declare function parseTotalCalculated(totalCalculated: string | number): bigint;
+/**
+ * Return absolute value of a bigint
+ */
+declare function abs(value: bigint): bigint;
+/**
+ * Apply slippage to an amount
+ * @param amount - Base amount
+ * @param slippagePercent - Slippage as percentage (e.g., 5n = 5%)
+ * @returns Amount with slippage buffer added
+ */
+declare function addSlippage(amount: bigint, slippagePercent: bigint): bigint;
+/**
+ * Calculate minimum received after slippage
+ * @param amount - Expected amount
+ * @param slippagePercent - Slippage as percentage (e.g., 5n = 5%)
+ * @returns Minimum acceptable amount
+ */
+declare function subtractSlippage(amount: bigint, slippagePercent: bigint): bigint;
+
+/**
+ * Convert a value to hex string (without leading zeros normalization)
+ */
+declare function toHex(value: bigint | number | string): string;
+/**
+ * Normalize an address to lowercase hex format
+ */
+declare function normalizeAddress(address: string): string;
+/**
+ * Check if a string looks like an address (hex format)
+ */
+declare function isAddress(value: string): boolean;
+/**
+ * Split a u256 value into low and high parts for calldata
+ */
+declare function splitU256(value: bigint): {
+    low: string;
+    high: string;
+};
+
+/**
+ * Base error class for all Ekubo SDK errors
+ */
+declare class EkuboError extends Error {
+    readonly code: string;
+    readonly cause?: unknown | undefined;
+    constructor(message: string, code: string, cause?: unknown | undefined);
+}
+/**
+ * Error thrown when there is insufficient liquidity for a swap
+ * This error should NOT be retried
+ */
+declare class InsufficientLiquidityError extends EkuboError {
+    constructor(message?: string);
+}
+/**
+ * Error thrown when an API request fails after all retries
+ */
+declare class ApiError extends EkuboError {
+    readonly statusCode?: number | undefined;
+    constructor(message: string, statusCode?: number | undefined, cause?: unknown);
+}
+/**
+ * Error thrown when rate limited by the API
+ */
+declare class RateLimitError extends EkuboError {
+    readonly retryAfter?: number | undefined;
+    constructor(message?: string, retryAfter?: number | undefined);
+}
+/**
+ * Error thrown when a request times out
+ */
+declare class TimeoutError extends EkuboError {
+    readonly timeout: number;
+    constructor(message: string | undefined, timeout: number);
+}
+/**
+ * Error thrown when a request is aborted
+ */
+declare class AbortError extends EkuboError {
+    constructor(message?: string);
+}
+/**
+ * Error thrown when token resolution fails
+ */
+declare class TokenNotFoundError extends EkuboError {
+    readonly tokenIdentifier: string;
+    constructor(tokenIdentifier: string, message?: string);
+}
+/**
+ * Error thrown when chain configuration is invalid or missing
+ */
+declare class InvalidChainError extends EkuboError {
+    readonly chainId: string;
+    constructor(chainId: string, message?: string);
+}
+/**
+ * Check if an error should not be retried
+ */
+declare function isNonRetryableError(error: unknown): boolean;
+
+export { API_URLS, AbortError, ApiError, type ApiTokenInfo, CHAIN_CONFIGS, CHAIN_IDS, type ChainConfig, DEFAULT_POLLING_CONFIG, EkuboClient, type EkuboClientConfig, EkuboError, type EncodedRoute, type FetchConfig, type FetchQuoteParams, type FetchSwapQuoteParams, type FetchTokenParams, type FetchTokensBatchParams, type FetchTokensParams, type GenerateSwapCallsParams, type GetPriceHistoryParams, InsufficientLiquidityError, InvalidChainError, MAINNET_TOKENS, type OverviewStats, type PairStats, type PairStatsParams, type PollingConfig, type PoolInfo, type PoolKey, type PriceDataPoint, type PriceHistoryResponse, QuotePoller, type QuotePollerCallbacks, type QuotePollerParams, ROUTER_ADDRESSES, RateLimitError, type ResolvedConfig, type RetryOptions, type RouteNode, STARKNET_CHAIN_IDS, STARKNET_TO_EKUBO_CHAIN, type StatsBaseParams, type SwapCall, type SwapCallsResult, type SwapQuote, type SwapQuoteApiResponse, type SwapQuoteErrorResponse, type SwapSplit, TimeoutError, type TokenInfo, TokenNotFoundError, TokenRegistry, type TvlDataPoint, USDC_ADDRESSES, type VolumeDataPoint, abs, addSlippage, calculateBackoff, canResolveToken, createEkuboClient, createQuotePoller, createTokenRegistry, encodeRoute, encodeRouteNode, fetchPairPools, fetchPairTvl, fetchPairVolume, fetchSwapQuote, fetchSwapQuoteInUsdc, fetchToken, fetchTokens, fetchTokensBatch, fetchTopPairs, fetchTvl, fetchVolume, generateSwapCalls, getChainConfig, getDefaultRegistry, getEkuboChainId, getMainnetTokensMap, getPriceHistory, isAddress, isNonRetryableError, normalizeAddress, parseTotalCalculated, prepareSwapCalls, resolveToken, resolveTokenInfo, sleep, splitU256, subtractSlippage, toHex, withRetry };