@b3dotfun/sdk 0.0.58 → 0.0.59-alpha.1

package/dist/cjs/shared/react/components/FormattedCurrency.js

@@ -8,21 +8,30 @@ const utils_1 = require("../../../shared/utils");
 const tooltip_1 = require("../../../global-account/react/components/ui/tooltip");
 const useCurrencyConversion_1 = require("../hooks/useCurrencyConversion");
 const currencyModalStore_1 = require("../stores/currencyModalStore");
-function FormattedCurrency({ amount, showChange = false, showColor = false, className, subB3Icon = true, clickable = true, decimals, currency, }) {
+const currencyStore_1 = require("../stores/currencyStore");
+function FormattedCurrency({ amount, sourceCurrency, showChange = false, showColor = false, className, subB3Icon = true, clickable = true, decimals, }) {
     const { formatCurrencyValue, formatTooltipValue, selectedCurrency, baseCurrency } = (0, useCurrencyConversion_1.useCurrencyConversion)();
     const { openModal } = (0, currencyModalStore_1.useCurrencyModalStore)();
-    // Use passed currency or fall back to selected currency
-    const activeCurrency = currency || selectedCurrency;
-    const isPositive = amount >= 0;
-    // Get the formatted value (using absolute value for negative numbers when showing change)
-    const baseAmount = showChange ? Math.abs(amount) : amount;
-    // Use centralized formatting from hook with optional overrides
-    const formattedValue = formatCurrencyValue(baseAmount, {
-        decimals,
-        currency,
-    });
+    // Convert from smallest unit to human-readable using currency's decimal places
+    const decimalPlaces = (0, currencyStore_1.getCurrencyDecimalPlaces)(sourceCurrency);
+    const divisor = Math.pow(10, decimalPlaces);
+    // Parse amount - handle both string and numeric inputs, including negatives
+    let parsedAmount;
+    if (typeof amount === "string") {
+        // Handle BigInt strings and negative values
+        const numericAmount = amount.startsWith("-") ? -Math.abs(parseFloat(amount.replace("-", ""))) : parseFloat(amount);
+        parsedAmount = numericAmount / divisor;
+    }
+    else {
+        parsedAmount = amount / divisor;
+    }
+    const isPositive = parsedAmount >= 0;
+    // Always format with absolute value, we'll add the sign separately
+    const absoluteAmount = Math.abs(parsedAmount);
+    // Format value with automatic conversion from source to display currency
+    const formattedValue = formatCurrencyValue(absoluteAmount, sourceCurrency, { decimals });
     // Generate tooltip using the centralized hook function
-    const baseTooltipValue = formatTooltipValue(amount, currency);
+    const baseTooltipValue = formatTooltipValue(parsedAmount, sourceCurrency);
     // Add change indicator if needed
     const tooltipValue = showChange ? `${isPositive ? "+" : "-"}${baseTooltipValue}` : baseTooltipValue;
     // Determine color class
@@ -35,26 +44,22 @@ function FormattedCurrency({ amount, showChange = false, showColor = false, clas
             colorClass = "text-red-400";
         }
     }
-    // Add change indicator
+    // Build display value with appropriate sign
     let displayValue = formattedValue;
     if (showChange) {
-        if (isPositive) {
-            displayValue = `+${formattedValue}`;
-        }
-        else {
-            displayValue = `-${formattedValue}`;
-        }
+        // Add +/- prefix for change indicators
+        displayValue = `${isPositive ? "+" : "-"}${formattedValue}`;
+    }
+    else if (!isPositive) {
+        // Add minus sign for negative values
+        displayValue = `-${formattedValue}`;
     }
     const handleClick = () => {
         if (clickable) {
             openModal();
         }
     };
-    return ((0, jsx_runtime_1.jsxs)(tooltip_1.Tooltip, { children: [(0, jsx_runtime_1.jsx)(tooltip_1.TooltipTrigger, { asChild: true, children: (0, jsx_runtime_1.jsxs)("span", { onClick: handleClick, className: (0, utils_1.cn)("inline-flex items-center gap-1 whitespace-nowrap", colorClass, className, clickable && "cursor-pointer transition-opacity hover:opacity-80"), children: [subB3Icon &&
-                            (currency === baseCurrency || (!currency && activeCurrency === baseCurrency)) &&
-                            baseCurrency === "B3"
-                            ? displayValue.split(" ")[0]
-                            : displayValue, subB3Icon &&
-                            (currency === baseCurrency || (!currency && activeCurrency === baseCurrency)) &&
-                            baseCurrency === "B3" && ((0, jsx_runtime_1.jsx)("img", { src: currency_1.B3_COIN_IMAGE_URL, className: "inline-block h-4 w-4 align-middle", alt: "B3 coin" }))] }) }), (0, jsx_runtime_1.jsx)(tooltip_1.TooltipContent, { children: tooltipValue })] }));
+    // Check if we should show B3 icon (when displaying in B3 and baseCurrency is B3)
+    const shouldShowB3Icon = subB3Icon && selectedCurrency === "B3" && baseCurrency === "B3";
+    return ((0, jsx_runtime_1.jsxs)(tooltip_1.Tooltip, { children: [(0, jsx_runtime_1.jsx)(tooltip_1.TooltipTrigger, { asChild: true, children: (0, jsx_runtime_1.jsxs)("span", { onClick: handleClick, className: (0, utils_1.cn)("inline-flex items-center gap-1 whitespace-nowrap", colorClass, className, clickable && "cursor-pointer transition-opacity hover:opacity-80"), children: [shouldShowB3Icon ? displayValue.split(" ")[0] : displayValue, shouldShowB3Icon && ((0, jsx_runtime_1.jsx)("img", { src: currency_1.B3_COIN_IMAGE_URL, className: "inline-block h-4 w-4 align-middle", alt: "B3 coin" }))] }) }), (0, jsx_runtime_1.jsx)(tooltip_1.TooltipContent, { children: tooltipValue })] }));
 }

package/dist/cjs/shared/react/hooks/useCurrencyConversion.d.ts

@@ -16,20 +16,23 @@
  */
 export declare function useCurrencyConversion(): {
     /** Currently selected display currency */
-    selectedCurrency: import("../stores/currencyStore").SupportedCurrency;
+    selectedCurrency: string;
     /** Base currency used for conversion (typically B3) */
-    baseCurrency: import("../stores/currencyStore").SupportedCurrency;
+    baseCurrency: string;
     /** Current exchange rate from base to selected currency (undefined while loading) */
     exchangeRate: number | undefined;
     /** Format a value with currency conversion and proper symbol/decimal handling */
-    formatCurrencyValue: (value: number, options?: {
+    formatCurrencyValue: (value: number, sourceCurrency: string, options?: {
         decimals?: number;
-        currency?: string;
     }) => string;
     /** Format a tooltip value showing alternate currency representation */
-    formatTooltipValue: (value: number, customCurrency?: string) => string;
+    formatTooltipValue: (value: number, sourceCurrency: string) => string;
     /** Symbol for the currently selected currency (e.g., "$", "€", "ETH") */
     selectedCurrencySymbol: string;
     /** Symbol for the base currency */
     baseCurrencySymbol: string;
+    /** Get exchange rate between any two currencies */
+    getExchangeRate: (from: string, to: string) => number | undefined;
+    /** All registered custom currencies */
+    customCurrencies: Record<string, import("../stores/currencyStore").CurrencyMetadata>;
 };

package/dist/cjs/shared/react/hooks/useCurrencyConversion.js

@@ -40,8 +40,10 @@ async function fetchAllExchangeRates(baseCurrency) {
 function useCurrencyConversion() {
     const selectedCurrency = (0, currencyStore_1.useCurrencyStore)(state => state.selectedCurrency);
     const baseCurrency = (0, currencyStore_1.useCurrencyStore)(state => state.baseCurrency);
-    // Fetch all exchange rates for the base currency
-    const { data: exchangeRates } = (0, react_query_1.useQuery)({
+    const getCustomExchangeRate = (0, currencyStore_1.useCurrencyStore)(state => state.getExchangeRate);
+    const customCurrencies = (0, currencyStore_1.useCurrencyStore)(state => state.customCurrencies);
+    // Fetch all exchange rates for the base currency from Coinbase API
+    const { data: apiExchangeRates } = (0, react_query_1.useQuery)({
         queryKey: ["exchangeRates", baseCurrency],
         queryFn: () => fetchAllExchangeRates(baseCurrency),
         refetchInterval: REFETCH_INTERVAL_MS,
@@ -49,155 +51,208 @@ function useCurrencyConversion() {
         retry: 3,
         retryDelay: attemptIndex => Math.min(1000 * 2 ** attemptIndex, REFETCH_INTERVAL_MS),
     });
-    // Extract specific rates from the full rates object
-    const exchangeRate = exchangeRates?.[selectedCurrency];
-    const usdRate = exchangeRates?.["USD"];
     /**
-     * Formats a numeric value as a currency string with proper conversion and formatting.
+     * Get exchange rate between two currencies, checking custom rates first, then API rates.
+     * Supports chaining through base currency for custom currencies.
      *
-     * Behavior:
-     * - When exchange rate is unavailable, displays value in base currency
-     * - Applies currency-specific formatting rules:
-     *   - JPY/KRW: No decimal places
-     *   - ETH/SOL: 6 significant digits with subscript notation for small values
-     *   - Fiat (USD/EUR/GBP/CAD/AUD): 2 decimal places minimum for values < 1000
-     * - Handles symbol positioning (prefix for fiat, suffix for crypto)
+     * Examples:
+     * - WIN → USD: Checks WIN→USD custom rate, then chains WIN→B3→USD
+     * - BTC → EUR: Checks BTC→EUR custom rate, then chains BTC→B3→EUR
+     */
+    const getExchangeRate = (from, to) => {
+        // If same currency, rate is 1
+        if (from === to)
+            return 1;
+        // 1. Check direct custom exchange rate first
+        const directCustomRate = getCustomExchangeRate(from, to);
+        if (directCustomRate !== undefined) {
+            return directCustomRate;
+        }
+        // 2. Check direct API rate (from base currency)
+        if (from === baseCurrency && apiExchangeRates) {
+            return apiExchangeRates[to];
+        }
+        // 3. Try to chain through base currency using custom rates
+        // e.g., WIN → B3 → USD (where WIN→B3 is custom, B3→USD is API)
+        const customFromToBase = getCustomExchangeRate(from, baseCurrency);
+        if (customFromToBase !== undefined) {
+            // We have a custom rate from 'from' to base
+            // Now get rate from base to 'to'
+            const baseToTo = apiExchangeRates?.[to] ?? getCustomExchangeRate(baseCurrency, to);
+            if (baseToTo !== undefined) {
+                return customFromToBase * baseToTo;
+            }
+        }
+        // 4. Try reverse: chain from base currency through custom rate
+        // e.g., USD → B3 → WIN (where B3→WIN is custom)
+        const customBaseToTo = getCustomExchangeRate(baseCurrency, to);
+        if (customBaseToTo !== undefined && apiExchangeRates) {
+            // We have a custom rate from base to 'to'
+            // Now get rate from 'from' to base
+            const fromToBase = apiExchangeRates[from];
+            if (fromToBase !== undefined && fromToBase !== 0) {
+                return fromToBase * customBaseToTo;
+            }
+        }
+        // 5. Fall back to pure API conversion through base
+        // e.g., EUR to GBP = (EUR to B3) * (B3 to GBP)
+        if (apiExchangeRates) {
+            const fromToBase = apiExchangeRates[from];
+            const baseToTo = apiExchangeRates[to];
+            if (fromToBase && baseToTo && fromToBase !== 0) {
+                return baseToTo / fromToBase;
+            }
+        }
+        return undefined;
+    };
+    // Extract specific rates
+    const exchangeRate = getExchangeRate(baseCurrency, selectedCurrency);
+    /**
+     * Formats a numeric value as a currency string with automatic conversion.
+     *
+     * New behavior:
+     * - Takes the SOURCE currency (what the value is in) as a required parameter
+     * - Automatically converts from source → display currency (selected in picker)
+     * - Supports multi-hop conversions (e.g., WIN → B3 → USD)
+     * - Applies currency-specific formatting rules to the TARGET currency
      *
-     * @param value - The numeric value to format (in base currency)
+     * @param value - The numeric value to format
+     * @param sourceCurrency - The currency the value is currently in (e.g., "WIN", "B3", "USD")
      * @param options - Optional formatting overrides
-     * @param options.decimals - Override number of decimal places
-     * @param options.currency - Override currency (bypasses conversion)
+     * @param options.decimals - Override number of decimal places for display
      * @returns Formatted currency string with appropriate symbol and decimal places
      *
      * @example
      * ```tsx
-     * formatCurrencyValue(100) // Returns "$100.00" if USD is selected
-     * formatCurrencyValue(0.0001) // Returns "0.0₄1 ETH" if ETH is selected
-     * formatCurrencyValue(1500) // Returns "¥1,500" if JPY is selected
-     * formatCurrencyValue(100, { decimals: 4, currency: "ETH" }) // Returns "100.0000 ETH"
+     * // Value is 3031 WIN, user has USD selected
+     * formatCurrencyValue(3031, "WIN") // Returns "$30.31" (converts WIN→B3→USD)
+     *
+     * // Value is 100 B3, user has B3 selected (no conversion)
+     * formatCurrencyValue(100, "B3") // Returns "100 B3"
+     *
+     * // Value is 50 USD, user has EUR selected
+     * formatCurrencyValue(50, "USD") // Returns "€45.50" (converts USD→EUR)
      * ```
      */
-    const formatCurrencyValue = (value, options) => {
-        const overrideCurrency = options?.currency;
+    const formatCurrencyValue = (value, sourceCurrency, options) => {
         const overrideDecimals = options?.decimals;
-        // Custom currency provided - bypass conversion and use simple formatting
-        if (overrideCurrency) {
-            const decimalsToUse = overrideDecimals !== undefined ? overrideDecimals : overrideCurrency === "B3" ? 0 : 2;
+        // If source and display currency are the same, no conversion needed
+        if (sourceCurrency === selectedCurrency) {
+            const customMetadata = (0, currencyStore_1.getCurrencyMetadata)(sourceCurrency);
+            const decimalsToUse = overrideDecimals !== undefined ? overrideDecimals : customMetadata?.decimals;
             const formatted = (0, number_1.formatDisplayNumber)(value, {
                 fractionDigits: decimalsToUse,
-                showSubscripts: false,
+                significantDigits: decimalsToUse === undefined ? 6 : undefined,
+                showSubscripts: customMetadata?.showSubscripts ?? false,
             });
-            return `${formatted} ${overrideCurrency}`;
+            const symbol = (0, currencyStore_1.getCurrencySymbol)(sourceCurrency);
+            const usePrefix = customMetadata?.prefixSymbol ?? ["USD", "EUR", "GBP", "CAD", "AUD"].includes(sourceCurrency);
+            return usePrefix ? `${symbol}${formatted}` : `${formatted} ${symbol}`;
         }
-        // Custom decimals for base currency without conversion
-        if (overrideDecimals !== undefined && selectedCurrency === baseCurrency) {
+        // Get exchange rate from source to display currency
+        const conversionRate = getExchangeRate(sourceCurrency, selectedCurrency);
+        // If no conversion rate available, display in source currency
+        if (conversionRate === undefined) {
+            const customMetadata = (0, currencyStore_1.getCurrencyMetadata)(sourceCurrency);
             const formatted = (0, number_1.formatDisplayNumber)(value, {
+                significantDigits: 6,
+                showSubscripts: customMetadata?.showSubscripts ?? false,
+            });
+            const symbol = (0, currencyStore_1.getCurrencySymbol)(sourceCurrency);
+            return `${formatted} ${symbol}`;
+        }
+        // Convert value
+        const convertedValue = value * conversionRate;
+        // Get symbol and metadata for display currency
+        const symbol = (0, currencyStore_1.getCurrencySymbol)(selectedCurrency);
+        const customMetadata = (0, currencyStore_1.getCurrencyMetadata)(selectedCurrency);
+        const usePrefix = customMetadata?.prefixSymbol ?? ["USD", "EUR", "GBP", "CAD", "AUD"].includes(selectedCurrency);
+        let formatted;
+        // Apply formatting based on display currency
+        if (overrideDecimals !== undefined) {
+            formatted = (0, number_1.formatDisplayNumber)(convertedValue, {
                 fractionDigits: overrideDecimals,
                 showSubscripts: false,
             });
-            return `${formatted} ${baseCurrency}`;
         }
-        // If showing base currency, no conversion needed
-        if (selectedCurrency === baseCurrency || !exchangeRate) {
-            const formatted = (0, number_1.formatDisplayNumber)(value, {
-                significantDigits: baseCurrency === "B3" ? 6 : 8,
-                showSubscripts: true,
+        else if (customMetadata) {
+            formatted = (0, number_1.formatDisplayNumber)(convertedValue, {
+                fractionDigits: customMetadata.decimals,
+                significantDigits: customMetadata.decimals === undefined ? 6 : undefined,
+                showSubscripts: customMetadata.showSubscripts ?? false,
             });
-            return `${formatted} ${baseCurrency}`;
         }
-        // Convert value using current exchange rate
-        const convertedValue = value * exchangeRate;
-        const symbol = currencyStore_1.CURRENCY_SYMBOLS[selectedCurrency];
-        // Currencies that display symbol before the number (e.g., $100.00)
-        const prefixCurrencies = ["USD", "EUR", "GBP", "CAD", "AUD"];
-        let formatted;
-        if (selectedCurrency === "JPY" || selectedCurrency === "KRW") {
-            // Japanese Yen and Korean Won don't use decimal places
+        else if (selectedCurrency === "JPY" || selectedCurrency === "KRW") {
             formatted = (0, number_1.formatDisplayNumber)(convertedValue, {
                 fractionDigits: 0,
                 showSubscripts: false,
             });
         }
         else if (selectedCurrency === "ETH" || selectedCurrency === "SOL") {
-            // Crypto currencies use more precision and subscript notation
-            // for very small amounts (e.g., 0.0₃45 ETH)
             formatted = (0, number_1.formatDisplayNumber)(convertedValue, {
                 significantDigits: 6,
                 showSubscripts: true,
             });
         }
         else {
-            // Standard fiat currencies (USD, EUR, GBP, CAD, AUD)
-            // Use 2 decimal places minimum for amounts under 1000
             formatted = (0, number_1.formatDisplayNumber)(convertedValue, {
                 significantDigits: 6,
                 fractionDigits: convertedValue < 1000 ? 2 : undefined,
                 showSubscripts: true,
             });
         }
-        // Apply currency symbol with correct positioning
-        if (prefixCurrencies.includes(selectedCurrency)) {
-            return `${symbol}${formatted}`;
-        }
-        else {
-            // Suffix currencies: JPY, KRW, ETH, SOL, B3
-            return `${formatted} ${symbol}`;
-        }
+        return usePrefix ? `${symbol}${formatted}` : `${formatted} ${symbol}`;
     };
     /**
      * Formats a tooltip value showing the alternate currency representation.
      *
-     * Behavior:
-     * - When displaying base currency: Shows USD equivalent
-     * - When displaying other currency: Shows base currency equivalent
-     * - For custom currencies: Shows appropriate conversion or original value
+     * New behavior:
+     * - Takes the SOURCE currency (what the value is in)
+     * - When displaying in non-USD: Shows USD equivalent in tooltip
+     * - When displaying in USD: Shows source currency in tooltip
      *
      * @param value - The numeric value to format
-     * @param customCurrency - Optional custom currency override
+     * @param sourceCurrency - The currency the value is currently in
      * @returns Formatted tooltip string
      *
      * @example
      * ```tsx
-     * formatTooltipValue(100) // Returns "$150.00 USD" if displaying B3 with rate 1.5
-     * formatTooltipValue(100, "ETH") // Returns "100.0000 ETH" if custom currency
+     * // Value is 3031 WIN, displaying as EUR
+     * formatTooltipValue(3031, "WIN") // Returns "$30.31 USD"
+     *
+     * // Value is 100 B3, displaying as USD
+     * formatTooltipValue(100, "B3") // Returns "100 B3"
      * ```
      */
-    const formatTooltipValue = (value, customCurrency) => {
-        const displayCurrency = customCurrency || selectedCurrency;
+    const formatTooltipValue = (value, sourceCurrency) => {
         const absoluteValue = Math.abs(value);
-        // Custom currency provided
-        if (customCurrency) {
-            if (customCurrency === baseCurrency) {
-                // Show USD equivalent for base currency using USD rate
-                const usdValue = usdRate ? absoluteValue * usdRate : absoluteValue;
-                const formatted = (0, number_1.formatDisplayNumber)(usdValue, {
-                    significantDigits: 6,
-                    fractionDigits: usdValue < 1000 ? 2 : undefined,
-                    showSubscripts: true,
-                });
-                return `$${formatted} USD`;
-            }
-            else {
-                // Show as-is for other custom currencies
-                return `${(0, number_1.formatDisplayNumber)(absoluteValue, { significantDigits: 6 })} ${customCurrency}`;
-            }
+        // If displaying in USD, show source currency in tooltip
+        if (selectedCurrency === "USD") {
+            const formatted = (0, number_1.formatDisplayNumber)(absoluteValue, {
+                significantDigits: 6,
+                showSubscripts: (0, currencyStore_1.getCurrencyMetadata)(sourceCurrency)?.showSubscripts ?? false,
+            });
+            const symbol = (0, currencyStore_1.getCurrencySymbol)(sourceCurrency);
+            return `${formatted} ${symbol}`;
         }
-        // Showing base currency - display USD equivalent
-        if (displayCurrency === baseCurrency) {
-            const usdValue = usdRate ? absoluteValue * usdRate : absoluteValue;
-            const formatted = (0, number_1.formatDisplayNumber)(usdValue, {
+        // Otherwise, show USD equivalent in tooltip
+        const usdRate = getExchangeRate(sourceCurrency, "USD");
+        if (usdRate === undefined) {
+            // Fallback to source currency if no USD rate
+            const formatted = (0, number_1.formatDisplayNumber)(absoluteValue, {
                 significantDigits: 6,
-                fractionDigits: usdValue < 1000 ? 2 : undefined,
-                showSubscripts: true,
+                showSubscripts: (0, currencyStore_1.getCurrencyMetadata)(sourceCurrency)?.showSubscripts ?? false,
             });
-            return `$${formatted} USD`;
+            const symbol = (0, currencyStore_1.getCurrencySymbol)(sourceCurrency);
+            return `${formatted} ${symbol}`;
         }
-        // Showing other currency - display base currency equivalent
-        const formatted = (0, number_1.formatDisplayNumber)(absoluteValue, {
-            significantDigits: baseCurrency === "B3" ? 6 : 8,
+        const usdValue = absoluteValue * usdRate;
+        const formatted = (0, number_1.formatDisplayNumber)(usdValue, {
+            significantDigits: 6,
+            fractionDigits: usdValue < 1000 ? 2 : undefined,
             showSubscripts: true,
         });
-        return `${formatted} ${baseCurrency}`;
+        return `$${formatted} USD`;
     };
     return {
         /** Currently selected display currency */
@@ -211,8 +266,12 @@ function useCurrencyConversion() {
         /** Format a tooltip value showing alternate currency representation */
         formatTooltipValue,
         /** Symbol for the currently selected currency (e.g., "$", "€", "ETH") */
-        selectedCurrencySymbol: currencyStore_1.CURRENCY_SYMBOLS[selectedCurrency],
+        selectedCurrencySymbol: (0, currencyStore_1.getCurrencySymbol)(selectedCurrency),
         /** Symbol for the base currency */
-        baseCurrencySymbol: currencyStore_1.CURRENCY_SYMBOLS[baseCurrency],
+        baseCurrencySymbol: (0, currencyStore_1.getCurrencySymbol)(baseCurrency),
+        /** Get exchange rate between any two currencies */
+        getExchangeRate,
+        /** All registered custom currencies */
+        customCurrencies,
     };
 }

package/dist/cjs/shared/react/stores/currencyStore.d.ts

@@ -1,8 +1,36 @@
 /**
- * Supported currencies for display and conversion.
+ * Built-in supported currencies for display and conversion.
  * Includes fiat currencies (USD, EUR, GBP, JPY, CAD, AUD, KRW) and crypto (ETH, SOL, B3).
  */
 export type SupportedCurrency = "ETH" | "USD" | "EUR" | "GBP" | "JPY" | "CAD" | "AUD" | "B3" | "SOL" | "KRW";
+/**
+ * Metadata for a custom currency including display formatting rules.
+ */
+export interface CurrencyMetadata {
+    /** The currency code/symbol (e.g., "BTC", "DOGE") */
+    code: string;
+    /** Display symbol for the currency (e.g., "₿", "Ð") */
+    symbol: string;
+    /** Human-readable name (e.g., "Bitcoin", "Dogecoin") */
+    name: string;
+    /** Whether to show symbol before the value (true for $100, false for 100 ETH) */
+    prefixSymbol?: boolean;
+    /** Number of decimal places to show (undefined uses smart formatting) */
+    decimals?: number;
+    /** Whether to use subscript notation for small values */
+    showSubscripts?: boolean;
+}
+/**
+ * Exchange rate between two currencies.
+ */
+export interface ExchangeRate {
+    /** Currency code being converted from */
+    from: string;
+    /** Currency code being converted to */
+    to: string;
+    /** Exchange rate multiplier (amount_in_to = amount_in_from * rate) */
+    rate: number;
+}
 /**
  * Currency symbols used for display formatting.
  * Prefix currencies (USD, EUR, GBP, CAD, AUD) show symbol before the amount.
@@ -17,24 +45,51 @@ export declare const CURRENCY_NAMES: Record<SupportedCurrency, string>;
  * Currency store state interface.
  * @property selectedCurrency - The currency currently selected for display
  * @property baseCurrency - The base currency for conversion (typically B3)
+ * @property customCurrencies - Map of custom currency codes to their metadata
+ * @property customExchangeRates - Map of "FROM-TO" pairs to exchange rates
  * @property setSelectedCurrency - Update the selected display currency
  * @property setBaseCurrency - Update the base currency for conversions
+ * @property addCurrency - Register a new custom currency with metadata
+ * @property removeCurrency - Remove a custom currency
+ * @property setExchangeRate - Set a custom exchange rate between two currencies
+ * @property getExchangeRate - Get exchange rate between two currencies
+ * @property getAllCurrencies - Get all available currencies (built-in + custom)
  */
 interface CurrencyState {
-    selectedCurrency: SupportedCurrency;
-    baseCurrency: SupportedCurrency;
-    setSelectedCurrency: (currency: SupportedCurrency) => void;
-    setBaseCurrency: (currency: SupportedCurrency) => void;
+    selectedCurrency: string;
+    baseCurrency: string;
+    customCurrencies: Record<string, CurrencyMetadata>;
+    customExchangeRates: Record<string, number>;
+    setSelectedCurrency: (currency: string) => void;
+    setBaseCurrency: (currency: string) => void;
+    addCurrency: (metadata: CurrencyMetadata) => void;
+    removeCurrency: (code: string) => void;
+    setExchangeRate: (from: string, to: string, rate: number) => void;
+    getExchangeRate: (from: string, to: string) => number | undefined;
+    getAllCurrencies: () => string[];
 }
 /**
  * Zustand store for managing currency selection and conversion.
  * Persists user's selected currency preference in localStorage.
+ * Supports dynamic currency registration and custom exchange rates.
  *
  * @example
  * ```tsx
- * const { selectedCurrency, setSelectedCurrency } = useCurrencyStore();
- * // Change display currency to USD
- * setSelectedCurrency('USD');
+ * const { selectedCurrency, setSelectedCurrency, addCurrency, setExchangeRate } = useCurrencyStore();
+ *
+ * // Add a new currency
+ * addCurrency({
+ *   code: "BTC",
+ *   symbol: "₿",
+ *   name: "Bitcoin",
+ *   showSubscripts: true,
+ * });
+ *
+ * // Set exchange rate: 1 BTC = 50000 USD
+ * setExchangeRate("BTC", "USD", 50000);
+ *
+ * // Change display currency
+ * setSelectedCurrency('BTC');
  * ```
  */
 export declare const useCurrencyStore: import("zustand").UseBoundStore<Omit<import("zustand").StoreApi<CurrencyState>, "persist"> & {
@@ -48,4 +103,24 @@ export declare const useCurrencyStore: import("zustand").UseBoundStore<Omit<impo
         getOptions: () => Partial<import("zustand/middleware").PersistOptions<CurrencyState, CurrencyState>>;
     };
 }>;
+/**
+ * Get the symbol for any currency (built-in or custom).
+ */
+export declare function getCurrencySymbol(currency: string): string;
+/**
+ * Get the name for any currency (built-in or custom).
+ */
+export declare function getCurrencyName(currency: string): string;
+/**
+ * Get metadata for a custom currency.
+ */
+export declare function getCurrencyMetadata(currency: string): CurrencyMetadata | undefined;
+/**
+ * Get the number of decimal places for a currency (for converting from smallest unit).
+ * Used when parsing amounts from wei/smallest unit format.
+ *
+ * @param currency - Currency code
+ * @returns Number of decimal places (e.g., 18 for ETH/wei, 2 for USD cents, 0 for JPY)
+ */
+export declare function getCurrencyDecimalPlaces(currency: string): number;
 export {};