bitvavo-api-upgraded 2.0.0__py3-none-any.whl → 2.2.0__py3-none-any.whl

bitvavo_api_upgraded/bitvavo.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import contextlib
 import datetime as dt
 import hashlib
 import hmac
@@ -14,9 +15,10 @@ from requests import delete, get, post, put
 from structlog.stdlib import get_logger
 from websocket import WebSocketApp  # missing stubs for WebSocketApp
 
+from bitvavo_api_upgraded.dataframe_utils import convert_candles_to_dataframe, convert_to_dataframe
 from bitvavo_api_upgraded.helper_funcs import configure_loggers, time_ms, time_to_wait
-from bitvavo_api_upgraded.settings import bitvavo_upgraded_settings
-from bitvavo_api_upgraded.type_aliases import anydict, errordict, intdict, ms, s_f, strdict, strintdict
+from bitvavo_api_upgraded.settings import bitvavo_settings, bitvavo_upgraded_settings
+from bitvavo_api_upgraded.type_aliases import OutputFormat, anydict, errordict, intdict, ms, s_f, strdict, strintdict
 
 configure_loggers()
 
@@ -216,6 +218,7 @@ class Bitvavo:
     Example code to get your started:
 
     ```python
+    # Single API key (backward compatible)
     bitvavo = Bitvavo(
         {
             "APIKEY": "$YOUR_API_KEY",
@@ -227,22 +230,198 @@ class Bitvavo:
         },
     )
     time_dict = bitvavo.time()
+
+    # Multiple API keys with keyless preference
+    bitvavo = Bitvavo(
+        {
+            "APIKEYS": [
+                {"key": "$YOUR_API_KEY_1", "secret": "$YOUR_API_SECRET_1"},
+                {"key": "$YOUR_API_KEY_2", "secret": "$YOUR_API_SECRET_2"},
+                {"key": "$YOUR_API_KEY_3", "secret": "$YOUR_API_SECRET_3"},
+            ],
+            "PREFER_KEYLESS": True,  # Use keyless requests first, then API keys
+            "RESTURL": "https://api.bitvavo.com/v2",
+            "WSURL": "wss://ws.bitvavo.com/v2/",
+            "ACCESSWINDOW": 10000,
+            "DEBUGGING": True,
+        },
+    )
+    time_dict = bitvavo.time()
+
+    # Keyless only (no API keys)
+    bitvavo = Bitvavo(
+        {
+            "PREFER_KEYLESS": True,
+            "RESTURL": "https://api.bitvavo.com/v2",
+            "WSURL": "wss://ws.bitvavo.com/v2/",
+            "ACCESSWINDOW": 10000,
+            "DEBUGGING": True,
+        },
+    )
+    markets = bitvavo.markets()  # Only public endpoints will work
     ```
     """
 
-    def __init__(self, options: dict[str, str | int] | None = None) -> None:
+    def __init__(self, options: dict[str, str | int | list[dict[str, str]]] | None = None) -> None:
         if options is None:
             options = {}
         _options = {k.upper(): v for k, v in options.items()}
-        self.base: str = str(_options.get("RESTURL", "https://api.bitvavo.com/v2"))
-        self.wsUrl: str = str(_options.get("WSURL", "wss://ws.bitvavo.com/v2/"))
-        self.ACCESSWINDOW = ms(_options.get("ACCESSWINDOW", 10000))
-        self.APIKEY = str(_options.get("APIKEY", ""))
-        self.APISECRET = str(_options.get("APISECRET", ""))
-        self.rateLimitRemaining: int = 1000
+
+        # Options take precedence over settings
+        self.base: str = str(_options.get("RESTURL", bitvavo_settings.RESTURL))
+        self.wsUrl: str = str(_options.get("WSURL", bitvavo_settings.WSURL))
+        self.ACCESSWINDOW: int = int(_options.get("ACCESSWINDOW", bitvavo_settings.ACCESSWINDOW))
+
+        # Support for multiple API keys - options take absolute precedence
+        if "APIKEY" in _options and "APISECRET" in _options:
+            # Single API key explicitly provided in options - takes precedence
+            single_key = str(_options["APIKEY"])
+            single_secret = str(_options["APISECRET"])
+            self.api_keys: list[dict[str, str]] = [{"key": single_key, "secret": single_secret}]
+        elif "APIKEYS" in _options:
+            # Multiple API keys provided in options - takes precedence
+            api_keys = _options["APIKEYS"]
+            if isinstance(api_keys, list) and api_keys:
+                self.api_keys = api_keys
+            else:
+                self.api_keys = []
+        else:
+            # Fall back to settings only if no API key options provided
+            api_keys = bitvavo_settings.APIKEYS
+            if isinstance(api_keys, list) and api_keys:
+                self.api_keys = api_keys
+            else:
+                # Single API key from settings (backward compatibility)
+                single_key = str(bitvavo_settings.APIKEY)
+                single_secret = str(bitvavo_settings.APISECRET)
+                if single_key and single_secret:
+                    self.api_keys = [{"key": single_key, "secret": single_secret}]
+                else:
+                    self.api_keys = []
+
+        # Current API key index and keyless preference - options take precedence
+        self.current_api_key_index: int = 0
+        self.prefer_keyless: bool = bool(_options.get("PREFER_KEYLESS", bitvavo_upgraded_settings.PREFER_KEYLESS))
+
+        # Rate limiting per API key (keyless has index -1)
+        self.rate_limits: dict[int, dict[str, int | ms]] = {}
+        # Get default rate limit from options or settings
+        default_rate_limit_option = _options.get("DEFAULT_RATE_LIMIT", bitvavo_upgraded_settings.DEFAULT_RATE_LIMIT)
+        default_rate_limit = (
+            int(default_rate_limit_option)
+            if isinstance(default_rate_limit_option, (int, str))
+            else bitvavo_upgraded_settings.DEFAULT_RATE_LIMIT
+        )
+
+        self.rate_limits[-1] = {"remaining": default_rate_limit, "resetAt": ms(0)}  # keyless
+        for i in range(len(self.api_keys)):
+            self.rate_limits[i] = {"remaining": default_rate_limit, "resetAt": ms(0)}
+
+        # Legacy properties for backward compatibility
+        self.APIKEY: str = self.api_keys[0]["key"] if self.api_keys else ""
+        self.APISECRET: str = self.api_keys[0]["secret"] if self.api_keys else ""
+        self._current_api_key: str = self.APIKEY
+        self._current_api_secret: str = self.APISECRET
+        self.rateLimitRemaining: int = default_rate_limit
         self.rateLimitResetAt: ms = 0
-        # TODO(NostraDavid): for v2: remove this functionality - logger.debug is a level that can be set
-        self.debugging = bool(_options.get("DEBUGGING", False))
+
+        # Options take precedence over settings for debugging
+        self.debugging: bool = bool(_options.get("DEBUGGING", bitvavo_settings.DEBUGGING))
+
+    def get_best_api_key_config(self, rateLimitingWeight: int = 1) -> tuple[str, str, int]:
+        """
+        Get the best API key configuration to use for a request.
+
+        Returns:
+            tuple: (api_key, api_secret, key_index) where key_index is -1 for keyless
+        """
+        # If prefer keyless and keyless has enough rate limit, use keyless
+        if self.prefer_keyless and self._has_rate_limit_available(-1, rateLimitingWeight):
+            return "", "", -1
+
+        # Try to find an API key with enough rate limit
+        for i in range(len(self.api_keys)):
+            if self._has_rate_limit_available(i, rateLimitingWeight):
+                return self.api_keys[i]["key"], self.api_keys[i]["secret"], i
+
+        # If keyless is available, use it as fallback
+        if self._has_rate_limit_available(-1, rateLimitingWeight):
+            return "", "", -1
+
+        # No keys available, use current key and let rate limiting handle the wait
+        if self.api_keys:
+            return (
+                self.api_keys[self.current_api_key_index]["key"],
+                self.api_keys[self.current_api_key_index]["secret"],
+                self.current_api_key_index,
+            )
+        return "", "", -1
+
+    def _has_rate_limit_available(self, key_index: int, weight: int) -> bool:
+        """Check if a specific API key (or keyless) has enough rate limit."""
+        if key_index not in self.rate_limits:
+            return False
+        remaining = self.rate_limits[key_index]["remaining"]
+        return (remaining - weight) > bitvavo_upgraded_settings.RATE_LIMITING_BUFFER
+
+    def _update_rate_limit_for_key(self, key_index: int, response: anydict | errordict) -> None:
+        """Update rate limit for a specific API key index."""
+        if key_index not in self.rate_limits:
+            self.rate_limits[key_index] = {"remaining": 1000, "resetAt": ms(0)}
+
+        if "errorCode" in response and response["errorCode"] == 105:  # noqa: PLR2004
+            self.rate_limits[key_index]["remaining"] = 0
+            # rateLimitResetAt is a value that's stripped from a string.
+            reset_time_str = str(response.get("error", "")).split(" at ")
+            if len(reset_time_str) > 1:
+                try:
+                    reset_time = ms(int(reset_time_str[1].split(".")[0]))
+                    self.rate_limits[key_index]["resetAt"] = reset_time
+                except (ValueError, IndexError):
+                    # Fallback to current time + 60 seconds if parsing fails
+                    self.rate_limits[key_index]["resetAt"] = ms(time_ms() + 60000)
+            else:
+                self.rate_limits[key_index]["resetAt"] = ms(time_ms() + 60000)
+
+            timeToWait = time_to_wait(ms(self.rate_limits[key_index]["resetAt"]))
+            key_name = f"API_KEY_{key_index}" if key_index >= 0 else "KEYLESS"
+            logger.warning(
+                "api-key-banned",
+                info={
+                    "key_name": key_name,
+                    "wait_time_seconds": timeToWait + 1,
+                    "until": (dt.datetime.now(tz=dt.timezone.utc) + dt.timedelta(seconds=timeToWait + 1)).isoformat(),
+                },
+            )
+
+        if "bitvavo-ratelimit-remaining" in response:
+            with contextlib.suppress(ValueError, TypeError):
+                self.rate_limits[key_index]["remaining"] = int(response["bitvavo-ratelimit-remaining"])
+
+        if "bitvavo-ratelimit-resetat" in response:
+            with contextlib.suppress(ValueError, TypeError):
+                self.rate_limits[key_index]["resetAt"] = ms(int(response["bitvavo-ratelimit-resetat"]))
+
+    def _sleep_for_key(self, key_index: int) -> None:
+        """Sleep until the specified API key's rate limit resets."""
+        if key_index not in self.rate_limits:
+            return
+
+        reset_at = ms(self.rate_limits[key_index]["resetAt"])
+        napTime = time_to_wait(reset_at)
+        key_name = f"API_KEY_{key_index}" if key_index >= 0 else "KEYLESS"
+
+        logger.warning(
+            "rate-limit-reached", key_name=key_name, rateLimitRemaining=self.rate_limits[key_index]["remaining"]
+        )
+        logger.info(
+            "napping-until-reset",
+            key_name=key_name,
+            napTime=napTime,
+            currentTime=dt.datetime.now(tz=dt.timezone.utc).isoformat(),
+            targetDatetime=dt.datetime.fromtimestamp(reset_at / 1000.0, tz=dt.timezone.utc).isoformat(),
+        )
+        time.sleep(napTime + 1)  # +1 to add a tiny bit of buffer time
 
     def calcLag(self) -> ms:
         """
@@ -284,14 +463,20 @@ class Bitvavo:
         If you're banned, use the errordict to sleep until you're not banned
 
         If you're not banned, then use the received headers to update the variables.
+
+        This method maintains backward compatibility by updating the legacy properties.
         """
+        # Update rate limit for the current API key being used
+        current_key = self.current_api_key_index if self.APIKEY else -1
+        self._update_rate_limit_for_key(current_key, response)
+
+        # Update legacy properties for backward compatibility
+        if current_key in self.rate_limits:
+            self.rateLimitRemaining = int(self.rate_limits[current_key]["remaining"])
+            self.rateLimitResetAt = ms(self.rate_limits[current_key]["resetAt"])
+
+        # Handle ban with sleep (legacy behavior)
         if "errorCode" in response and response["errorCode"] == 105:  # noqa: PLR2004
-            self.rateLimitRemaining = 0
-            # rateLimitResetAt is a value that's stripped from a string.
-            # Kind of a terrible way to pass that information, but eh, whatever, I guess...
-            # Anyway, here is the string that's being pulled apart:
-            # "Your IP or API key has been banned for not respecting the rate limit. The ban expires at ${expiryInMs}""
-            self.rateLimitResetAt = ms(response["error"].split(" at ")[1].split(".")[0])
             timeToWait = time_to_wait(self.rateLimitResetAt)
             logger.warning(
                 "banned",
@@ -302,10 +487,6 @@ class Bitvavo:
             )
             logger.info("napping-until-ban-lifted")
             time.sleep(timeToWait + 1)  # plus one second to ENSURE we're able to run again.
-        if "bitvavo-ratelimit-remaining" in response:
-            self.rateLimitRemaining = int(response["bitvavo-ratelimit-remaining"])
-        if "bitvavo-ratelimit-resetat" in response:
-            self.rateLimitResetAt = int(response["bitvavo-ratelimit-resetat"])
 
     def publicRequest(
         self,
@@ -330,22 +511,39 @@ class Bitvavo:
         list[list[str]]
         ```
         """
-        if (self.rateLimitRemaining - rateLimitingWeight) <= bitvavo_upgraded_settings.RATE_LIMITING_BUFFER:
-            self.sleep_until_can_continue()
+        # Get the best API key configuration (keyless preferred, then available keys)
+        api_key, api_secret, key_index = self.get_best_api_key_config(rateLimitingWeight)
+
+        # Check if we need to wait for rate limit
+        if not self._has_rate_limit_available(key_index, rateLimitingWeight):
+            self._sleep_for_key(key_index)
+
+        # Update current API key for legacy compatibility
+        if api_key:
+            self._current_api_key = api_key
+            self._current_api_secret = api_secret
+            self.current_api_key_index = key_index
+        else:
+            # Using keyless
+            self._current_api_key = ""
+            self._current_api_secret = ""
+
         if self.debugging:
             logger.debug(
                 "api-request",
                 info={
                     "url": url,
-                    "with_api_key": bool(self.APIKEY != ""),
+                    "with_api_key": bool(api_key != ""),
                     "public_or_private": "public",
+                    "key_index": key_index,
                 },
             )
-        if self.APIKEY != "":
+
+        if api_key:
             now = time_ms() + bitvavo_upgraded_settings.LAG
-            sig = createSignature(now, "GET", url.replace(self.base, ""), None, self.APISECRET)
+            sig = createSignature(now, "GET", url.replace(self.base, ""), None, api_secret)
             headers = {
-                "bitvavo-access-key": self.APIKEY,
+                "bitvavo-access-key": api_key,
                 "bitvavo-access-signature": sig,
                 "bitvavo-access-timestamp": str(now),
                 "bitvavo-access-window": str(self.ACCESSWINDOW),
@@ -353,10 +551,16 @@ class Bitvavo:
             r = get(url, headers=headers, timeout=(self.ACCESSWINDOW / 1000))
         else:
             r = get(url, timeout=(self.ACCESSWINDOW / 1000))
+
+        # Update rate limit for the specific key used
         if "error" in r.json():
-            self.updateRateLimit(r.json())
+            self._update_rate_limit_for_key(key_index, r.json())
         else:
-            self.updateRateLimit(dict(r.headers))
+            self._update_rate_limit_for_key(key_index, dict(r.headers))
+
+        # Also update legacy rate limit tracking
+        self.updateRateLimit(r.json() if "error" in r.json() else dict(r.headers))
+
         return r.json()  # type:ignore[no-any-return]
 
     def privateRequest(
@@ -366,7 +570,7 @@ class Bitvavo:
         body: anydict | None = None,
         method: str = "GET",
         rateLimitingWeight: int = 1,
-    ) -> list[anydict] | list[list[str]] | intdict | strdict | anydict | Any | errordict:
+    ) -> list[anydict] | list[list[str]] | intdict | strdict | anydict | errordict:
         """Execute a request to the private  part of the API. API key and SECRET are required.
         Will return the reponse as one of three types.
 
@@ -389,14 +593,33 @@ class Bitvavo:
         list[list[str]]
         ```
         """
-        if (self.rateLimitRemaining - rateLimitingWeight) <= bitvavo_upgraded_settings.RATE_LIMITING_BUFFER:
-            self.sleep_until_can_continue()
-        # if this method breaks: add `= {}` after `body: dict`
+        # Private requests require an API key, so get the best available one
+        api_key, api_secret, key_index = self.get_best_api_key_config(rateLimitingWeight)
+
+        # If no API keys available, use the configured one (may fail)
+        if not api_key and self.api_keys:
+            api_key = self.api_keys[self.current_api_key_index]["key"]
+            api_secret = self.api_keys[self.current_api_key_index]["secret"]
+            key_index = self.current_api_key_index
+        elif not api_key:
+            # No API keys configured at all
+            api_key = self.APIKEY
+            api_secret = self.APISECRET
+            key_index = 0 if api_key else -1
+
+        # Check if we need to wait for rate limit
+        if not self._has_rate_limit_available(key_index, rateLimitingWeight):
+            self._sleep_for_key(key_index)
+
+        # Update current API key for legacy compatibility
+        self._current_api_key = api_key
+        self._current_api_secret = api_secret
+
         now = time_ms() + bitvavo_upgraded_settings.LAG
-        sig = createSignature(now, method, (endpoint + postfix), body, self.APISECRET)
+        sig = createSignature(now, method, (endpoint + postfix), body, api_secret)
         url = self.base + endpoint + postfix
         headers = {
-            "bitvavo-access-key": self.APIKEY,
+            "bitvavo-access-key": api_key,
             "bitvavo-access-signature": sig,
             "bitvavo-access-timestamp": str(now),
             "bitvavo-access-window": str(self.ACCESSWINDOW),
@@ -406,9 +629,10 @@ class Bitvavo:
                 "api-request",
                 info={
                     "url": url,
-                    "with_api_key": bool(self.APIKEY != ""),
+                    "with_api_key": bool(api_key != ""),
                     "public_or_private": "private",
                     "method": method,
+                    "key_index": key_index,
                 },
             )
         if method == "DELETE":
@@ -419,10 +643,16 @@ class Bitvavo:
             r = put(url, headers=headers, json=body, timeout=(self.ACCESSWINDOW / 1000))
         else:  # method == "GET"
             r = get(url, headers=headers, timeout=(self.ACCESSWINDOW / 1000))
+
+        # Update rate limit for the specific key used
         if "error" in r.json():
-            self.updateRateLimit(r.json())
+            self._update_rate_limit_for_key(key_index, r.json())
         else:
-            self.updateRateLimit(dict(r.headers))
+            self._update_rate_limit_for_key(key_index, dict(r.headers))
+
+        # Also update legacy rate limit tracking
+        self.updateRateLimit(r.json() if "error" in r.json() else dict(r.headers))
+
         return r.json()
 
     def sleep_until_can_continue(self) -> None:
@@ -457,7 +687,11 @@ class Bitvavo:
         """
         return self.publicRequest(f"{self.base}/time")  # type: ignore[return-value]
 
-    def markets(self, options: strdict | None = None) -> list[anydict] | anydict | errordict:
+    def markets(
+        self,
+        options: strdict | None = None,
+        output_format: OutputFormat = OutputFormat.DICT,
+    ) -> list[anydict] | anydict | errordict | Any:
         """Get all available markets with some meta-information, unless options is given a `market` key.
         Then you will get a single market, instead of a list of markets.
 
@@ -474,6 +708,23 @@ class Bitvavo:
         options={}  # returns all markets
         options={"market": "BTC-EUR"}  # returns only the BTC-EUR market
         # If you want multiple markets, but not all, make multiple calls
+
+        # Output format selection:
+        output_format=OutputFormat.DICT      # Default: returns standard Python dict/list
+        output_format=OutputFormat.PANDAS    # Returns pandas DataFrame
+        output_format=OutputFormat.POLARS    # Returns polars DataFrame
+        output_format=OutputFormat.CUDF      # Returns NVIDIA cuDF (GPU-accelerated)
+        output_format=OutputFormat.MODIN     # Returns modin (distributed pandas)
+        output_format=OutputFormat.PYARROW   # Returns Apache Arrow Table
+        output_format=OutputFormat.DASK      # Returns Dask DataFrame (distributed)
+        output_format=OutputFormat.DUCKDB    # Returns DuckDB relation
+        output_format=OutputFormat.IBIS      # Returns Ibis expression
+        output_format=OutputFormat.PYSPARK   # Returns PySpark DataFrame
+        output_format=OutputFormat.PYSPARK_CONNECT  # Returns PySpark Connect DataFrame
+        output_format=OutputFormat.SQLFRAME  # Returns SQLFrame DataFrame
+
+        # Note: DataFrame formats require narwhals and the respective library to be installed.
+        # Install with: pip install 'bitvavo-api-upgraded[pandas]' or similar for other formats.
         ```
 
         ---
@@ -485,6 +736,7 @@ class Bitvavo:
         ---
         Returns:
         ```python
+        # When output_format=OutputFormat.DICT (default):
         [
           {
             "market": "BTC-EUR",
@@ -504,12 +756,22 @@ class Bitvavo:
             ]
           }
         ]
+
+        # When output_format is any DataFrame format (pandas, polars, cudf, etc.):
+        # Returns a DataFrame with columns: market, status, base, quote, pricePrecision,
+        # minOrderInQuoteAsset, minOrderInBaseAsset, orderTypes
+        # The specific DataFrame type depends on the selected format.
         ```
         """
         postfix = createPostfix(options)
-        return self.publicRequest(f"{self.base}/markets{postfix}")  # type: ignore[return-value]
+        result = self.publicRequest(f"{self.base}/markets{postfix}")  # type: ignore[return-value]
+        return convert_to_dataframe(result, output_format)
 
-    def assets(self, options: strdict | None = None) -> list[anydict] | anydict:
+    def assets(
+        self,
+        options: strdict | None = None,
+        output_format: OutputFormat = OutputFormat.DICT,
+    ) -> list[anydict] | anydict | Any:
         """Get all available assets, unless `options` is given a `symbol` key.
         Then you will get a single asset, instead of a list of assets.
 
@@ -527,6 +789,23 @@ class Bitvavo:
         # pick one
         options={}  # returns all assets
         options={"symbol": "BTC"} # returns a single asset (the one of Bitcoin)
+
+        # Output format selection:
+        output_format=OutputFormat.DICT      # Default: returns standard Python dict/list
+        output_format=OutputFormat.PANDAS    # Returns pandas DataFrame
+        output_format=OutputFormat.POLARS    # Returns polars DataFrame
+        output_format=OutputFormat.CUDF      # Returns NVIDIA cuDF (GPU-accelerated)
+        output_format=OutputFormat.MODIN     # Returns modin (distributed pandas)
+        output_format=OutputFormat.PYARROW   # Returns Apache Arrow Table
+        output_format=OutputFormat.DASK      # Returns Dask DataFrame (distributed)
+        output_format=OutputFormat.DUCKDB    # Returns DuckDB relation
+        output_format=OutputFormat.IBIS      # Returns Ibis expression
+        output_format=OutputFormat.PYSPARK   # Returns PySpark DataFrame
+        output_format=OutputFormat.PYSPARK_CONNECT  # Returns PySpark Connect DataFrame
+        output_format=OutputFormat.SQLFRAME  # Returns SQLFrame DataFrame
+
+        # Note: DataFrame formats require narwhals and the respective library to be installed.
+        # Install with: pip install 'bitvavo-api-upgraded[pandas]' or similar for other formats.
         ```
 
         ---
@@ -538,6 +817,7 @@ class Bitvavo:
         ---
         Returns:
         ```python
+        # When output_format=OutputFormat.DICT (default):
         [
           {
             "symbol": "BTC",
@@ -553,10 +833,17 @@ class Bitvavo:
             "message": ""
           }
         ]
+
+        # When output_format is any DataFrame format (pandas, polars, cudf, etc.):
+        # Returns a DataFrame with columns: symbol, name, decimals, depositFee,
+        # depositConfirmations, depositStatus, withdrawalFee, withdrawalMinAmount,
+        # withdrawalStatus, networks, message
+        # The specific DataFrame type depends on the selected format.
         ```
         """
         postfix = createPostfix(options)
-        return self.publicRequest(f"{self.base}/assets{postfix}")  # type: ignore[return-value]
+        result = self.publicRequest(f"{self.base}/assets{postfix}")  # type: ignore[return-value]
+        return convert_to_dataframe(result, output_format)
 
     def book(self, market: str, options: intdict | None = None) -> dict[str, str | int | list[str]] | errordict:
         """Get a book (with two lists: asks and bids, as they're called)
@@ -603,7 +890,12 @@ class Bitvavo:
         postfix = createPostfix(options)
         return self.publicRequest(f"{self.base}/{market}/book{postfix}")  # type: ignore[return-value]
 
-    def publicTrades(self, market: str, options: strintdict | None = None) -> list[anydict] | errordict:
+    def publicTrades(
+        self,
+        market: str,
+        options: strintdict | None = None,
+        output_format: OutputFormat = OutputFormat.DICT,
+    ) -> list[anydict] | errordict | Any:
         """Publically available trades
 
         ---
@@ -628,6 +920,23 @@ class Bitvavo:
             "tradeIdFrom": ""  # if you get a list and want everything AFTER a certain id, put that id here
             "tradeIdTo": ""  # if you get a list and want everything BEFORE a certain id, put that id here
         }
+
+        # Output format selection:
+        output_format=OutputFormat.DICT      # Default: returns standard Python dict/list
+        output_format=OutputFormat.PANDAS    # Returns pandas DataFrame
+        output_format=OutputFormat.POLARS    # Returns polars DataFrame
+        output_format=OutputFormat.CUDF      # Returns NVIDIA cuDF (GPU-accelerated)
+        output_format=OutputFormat.MODIN     # Returns modin (distributed pandas)
+        output_format=OutputFormat.PYARROW   # Returns Apache Arrow Table
+        output_format=OutputFormat.DASK      # Returns Dask DataFrame (distributed)
+        output_format=OutputFormat.DUCKDB    # Returns DuckDB relation
+        output_format=OutputFormat.IBIS      # Returns Ibis expression
+        output_format=OutputFormat.PYSPARK   # Returns PySpark DataFrame
+        output_format=OutputFormat.PYSPARK_CONNECT  # Returns PySpark Connect DataFrame
+        output_format=OutputFormat.SQLFRAME  # Returns SQLFrame DataFrame
+
+        # Note: DataFrame formats require narwhals and the respective library to be installed.
+        # Install with: pip install 'bitvavo-api-upgraded[pandas]' or similar for other formats.
         ```
 
         ---
@@ -639,6 +948,7 @@ class Bitvavo:
         ---
         Returns:
         ```python
+        # When output_format='dict' (default):
         [
           {
             "timestamp": 1542967486256,
@@ -648,10 +958,14 @@ class Bitvavo:
             "side": "sell"
           }
         ]
+
+        # When output_format is any DataFrame format:
+        # Returns the above data as a DataFrame in the requested format (pandas, polars, etc.)
         ```
         """
         postfix = createPostfix(options)
-        return self.publicRequest(f"{self.base}/{market}/trades{postfix}", 5)  # type: ignore[return-value]
+        result = self.publicRequest(f"{self.base}/{market}/trades{postfix}", 5)  # type: ignore[return-value]
+        return convert_to_dataframe(result, output_format)
 
     def candles(
         self,
@@ -661,7 +975,8 @@ class Bitvavo:
         limit: int | None = None,
         start: dt.datetime | None = None,
         end: dt.datetime | None = None,
-    ) -> list[list[str]] | errordict:
+        output_format: OutputFormat = OutputFormat.DICT,
+    ) -> list[list[str]] | errordict | Any:
         """Get up to 1440 candles for a market, with a specific interval (candle size)
 
         Extra reading material: https://en.wikipedia.org/wiki/Candlestick_chart
@@ -684,6 +999,23 @@ class Bitvavo:
             "start": int timestamp in ms >= 0
             "end": int timestamp in ms <= 8640000000000000
         }
+
+        # Output format selection:
+        output_format=OutputFormat.DICT      # Default: returns standard Python list/dict
+        output_format=OutputFormat.PANDAS    # Returns pandas DataFrame
+        output_format=OutputFormat.POLARS    # Returns polars DataFrame
+        output_format=OutputFormat.CUDF      # Returns NVIDIA cuDF (GPU-accelerated)
+        output_format=OutputFormat.MODIN     # Returns modin (distributed pandas)
+        output_format=OutputFormat.PYARROW   # Returns Apache Arrow Table
+        output_format=OutputFormat.DASK      # Returns Dask DataFrame (distributed)
+        output_format=OutputFormat.DUCKDB    # Returns DuckDB relation
+        output_format=OutputFormat.IBIS      # Returns Ibis expression
+        output_format=OutputFormat.PYSPARK   # Returns PySpark DataFrame
+        output_format=OutputFormat.PYSPARK_CONNECT  # Returns PySpark Connect DataFrame
+        output_format=OutputFormat.SQLFRAME  # Returns SQLFrame DataFrame
+
+        # Note: DataFrame formats require narwhals and the respective library to be installed.
+        # Install with: pip install 'bitvavo-api-upgraded[pandas]' or similar for other formats.
         ```
 
         ---
@@ -695,6 +1027,7 @@ class Bitvavo:
         ---
         Returns:
         ```python
+        # When output_format='dict' (default):
         [
           # For whatever reason, you're getting a list of lists; no keys,
           # so here is the explanation of what's what.
@@ -705,6 +1038,11 @@ class Bitvavo:
           [1640804400000, "41937", "41955", "41449", "41540", "23.64498292"],
           [1640800800000, "41955", "42163", "41807", "41939", "10.40093845"],
         ]
+
+        # When output_format is any DataFrame format:
+        # Returns the above data as a DataFrame in the requested format (pandas, polars, etc.)
+        # with columns: timestamp, open, high, low, close, volume
+        # timestamp is converted to datetime, numeric columns to float
         ```
         """
         options = _default(options, {})
@@ -716,9 +1054,14 @@ class Bitvavo:
         if end is not None:
             options["end"] = _epoch_millis(end)
         postfix = createPostfix(options)
-        return self.publicRequest(f"{self.base}/{market}/candles{postfix}")  # type: ignore[return-value]
+        result = self.publicRequest(f"{self.base}/{market}/candles{postfix}")  # type: ignore[return-value]
+        return convert_candles_to_dataframe(result, output_format)
 
-    def tickerPrice(self, options: strdict | None = None) -> list[strdict] | strdict:
+    def tickerPrice(
+        self,
+        options: strdict | None = None,
+        output_format: OutputFormat = OutputFormat.DICT,
+    ) -> list[strdict] | strdict | Any:
         """Get the current price for each market
 
         ---
@@ -735,6 +1078,23 @@ class Bitvavo:
         ```python
         options={}
         options={"market": "BTC-EUR"}
+
+        # Output format selection:
+        output_format=OutputFormat.DICT      # Default: returns standard Python dict/list
+        output_format=OutputFormat.PANDAS    # Returns pandas DataFrame
+        output_format=OutputFormat.POLARS    # Returns polars DataFrame
+        output_format=OutputFormat.CUDF      # Returns NVIDIA cuDF (GPU-accelerated)
+        output_format=OutputFormat.MODIN     # Returns modin (distributed pandas)
+        output_format=OutputFormat.PYARROW   # Returns Apache Arrow Table
+        output_format=OutputFormat.DASK      # Returns Dask DataFrame (distributed)
+        output_format=OutputFormat.DUCKDB    # Returns DuckDB relation
+        output_format=OutputFormat.IBIS      # Returns Ibis expression
+        output_format=OutputFormat.PYSPARK   # Returns PySpark DataFrame
+        output_format=OutputFormat.PYSPARK_CONNECT  # Returns PySpark Connect DataFrame
+        output_format=OutputFormat.SQLFRAME  # Returns SQLFrame DataFrame
+
+        # Note: DataFrame formats require narwhals and the respective library to be installed.
+        # Install with: pip install 'bitvavo-api-upgraded[pandas]' or similar for other formats.
         ```
 
         ---
@@ -746,6 +1106,7 @@ class Bitvavo:
         ---
         Returns:
         ```python
+        # When output_format=OutputFormat.DICT (default):
         # Note that `price` is unconverted
         [
           {"market": "1INCH-EUR", "price": "2.1594"},
@@ -761,12 +1122,20 @@ class Bitvavo:
           {"market": "ALGO-EUR", "price": "1.3942"},
           # and another 210 markets below this point
         ]
+
+        # When output_format is any DataFrame format (pandas, polars, cudf, etc.):
+        # Returns a DataFrame with columns: market, price
         ```
         """
         postfix = createPostfix(options)
-        return self.publicRequest(f"{self.base}/ticker/price{postfix}")  # type: ignore[return-value]
+        result = self.publicRequest(f"{self.base}/ticker/price{postfix}")  # type: ignore[return-value]
+        return convert_to_dataframe(result, output_format)
 
-    def tickerBook(self, options: strdict | None = None) -> list[strdict] | strdict:
+    def tickerBook(
+        self,
+        options: strdict | None = None,
+        output_format: OutputFormat = OutputFormat.DICT,
+    ) -> list[strdict] | strdict | Any:
         """Get current bid/ask, bidsize/asksize per market
 
         ---
@@ -783,6 +1152,23 @@ class Bitvavo:
         ```python
         options={}
         options={"market": "BTC-EUR"}
+
+        # Output format selection:
+        output_format=OutputFormat.DICT      # Default: returns standard Python dict/list
+        output_format=OutputFormat.PANDAS    # Returns pandas DataFrame
+        output_format=OutputFormat.POLARS    # Returns polars DataFrame
+        output_format=OutputFormat.CUDF      # Returns NVIDIA cuDF (GPU-accelerated)
+        output_format=OutputFormat.MODIN     # Returns modin (distributed pandas)
+        output_format=OutputFormat.PYARROW   # Returns Apache Arrow Table
+        output_format=OutputFormat.DASK      # Returns Dask DataFrame (distributed)
+        output_format=OutputFormat.DUCKDB    # Returns DuckDB relation
+        output_format=OutputFormat.IBIS      # Returns Ibis expression
+        output_format=OutputFormat.PYSPARK   # Returns PySpark DataFrame
+        output_format=OutputFormat.PYSPARK_CONNECT  # Returns PySpark Connect DataFrame
+        output_format=OutputFormat.SQLFRAME  # Returns SQLFrame DataFrame
+
+        # Note: DataFrame formats require narwhals and the respective library to be installed.
+        # Install with: pip install 'bitvavo-api-upgraded[pandas]' or similar for other formats.
         ```
 
         ---
@@ -794,6 +1180,7 @@ class Bitvavo:
         ---
         Returns:
         ```python
+        # When output_format=OutputFormat.DICT (default):
         [
           {"market": "1INCH-EUR", "bid": "2.1534", "ask": "2.1587", "bidSize": "194.8", "askSize": "194.8"},
           {"market": "AAVE-EUR", "bid": "213.7", "ask": "214.05", "bidSize": "212.532", "askSize": "4.77676965"},
@@ -802,12 +1189,20 @@ class Bitvavo:
           {"market": "AION-EUR", "bid": "0.12531", "ask": "0.12578", "bidSize": "3345", "askSize": "10958.49228653"},
           # and another 215 markets below this point
         ]
+
+        # When output_format is any DataFrame format (pandas, polars, cudf, etc.):
+        # Returns a DataFrame with columns: market, bid, ask, bidSize, askSize
         ```
         """
         postfix = createPostfix(options)
-        return self.publicRequest(f"{self.base}/ticker/book{postfix}")  # type: ignore[return-value]
+        result = self.publicRequest(f"{self.base}/ticker/book{postfix}")  # type: ignore[return-value]
+        return convert_to_dataframe(result, output_format)
 
-    def ticker24h(self, options: strdict | None = None) -> list[anydict] | anydict | errordict:
+    def ticker24h(
+        self,
+        options: strdict | None = None,
+        output_format: OutputFormat = OutputFormat.DICT,
+    ) -> list[anydict] | anydict | errordict | Any:
         """Get current bid/ask, bidsize/asksize per market
 
         ---
@@ -824,15 +1219,30 @@ class Bitvavo:
         ```python
         options={}
         options={"market": "BTC-EUR"}
-        ```
 
+        # Output format selection:
+        output_format=OutputFormat.DICT      # Default: returns standard Python dict/list
+        output_format=OutputFormat.PANDAS    # Returns pandas DataFrame
+        output_format=OutputFormat.POLARS    # Returns polars DataFrame
+        output_format=OutputFormat.CUDF      # Returns NVIDIA cuDF (GPU-accelerated)
+        output_format=OutputFormat.MODIN     # Returns modin (distributed pandas)
+        output_format=OutputFormat.PYARROW   # Returns Apache Arrow Table
+        output_format=OutputFormat.DASK      # Returns Dask DataFrame (distributed)
+        output_format=OutputFormat.DUCKDB    # Returns DuckDB relation
+        output_format=OutputFormat.IBIS      # Returns Ibis expression
+        output_format=OutputFormat.PYSPARK   # Returns PySpark DataFrame
+        output_format=OutputFormat.PYSPARK_CONNECT  # Returns PySpark Connect DataFrame
+        output_format=OutputFormat.SQLFRAME  # Returns SQLFrame DataFrame
+
+        # Note: DataFrame formats require narwhals and the respective library to be installed.
+        # Install with: pip install 'bitvavo-api-upgraded[pandas]' or similar for other formats.
+        ```
         ---
         Rate Limit Weight:
         ```python
         25  # if no market option is used
         1  # if a market option is used
         ```
-
         ---
         Returns:
         ```python
@@ -874,9 +1284,15 @@ class Bitvavo:
         if "market" in options:
             rateLimitingWeight = 1
         postfix = createPostfix(options)
-        return self.publicRequest(f"{self.base}/ticker/24h{postfix}", rateLimitingWeight)  # type: ignore[return-value]
+        result = self.publicRequest(f"{self.base}/ticker/24h{postfix}", rateLimitingWeight)  # type: ignore[return-value]
+        return convert_to_dataframe(result, output_format)
 
-    def reportTrades(self, market: str, options: strintdict | None = None) -> list[anydict] | errordict:
+    def reportTrades(
+        self,
+        market: str,
+        options: strintdict | None = None,
+        output_format: OutputFormat = OutputFormat.DICT,
+    ) -> list[anydict] | errordict | Any:
         """Get MiCA-compliant trades report for a specific market
 
         Returns trades from the specified market and time period made by all Bitvavo users.
@@ -893,14 +1309,27 @@ class Bitvavo:
         ```python
         market="BTC-EUR"
         options={
-            "limit": [ 1 .. 1000 ], default 500
-            "start": int timestamp in ms >= 0
-            "end": int timestamp in ms <= 8_640_000_000_000_000  # Cannot be more than 24 hours after start
-            "tradeIdFrom": ""  # if you get a list and want everything AFTER a certain id, put that id here
-            "tradeIdTo": ""  # if you get a list and want everything BEFORE a certain id, put that id here
+          "limit": [ 1 .. 1000 ], default 500
+          "start": int timestamp in ms >= 0
+          "end": int timestamp in ms <= 8_640_000_000_000_000  # Cannot be more than 24 hours after start
+          "tradeIdFrom": ""  # if you get a list and want everything AFTER a certain id, put that id here
+          "tradeIdTo": ""  # if you get a list and want everything BEFORE a certain id, put that id here
         }
-        ```
 
+        # Output format selection:
+        output_format=OutputFormat.DICT      # Default: returns standard Python dict/list
+        output_format=OutputFormat.PANDAS    # Returns pandas DataFrame
+        output_format=OutputFormat.POLARS    # Returns polars DataFrame
+        output_format=OutputFormat.CUDF      # Returns NVIDIA cuDF (GPU-accelerated)
+        output_format=OutputFormat.MODIN     # Returns modin (distributed pandas)
+        output_format=OutputFormat.PYARROW   # Returns Apache Arrow Table
+        output_format=OutputFormat.DASK      # Returns Dask DataFrame (distributed)
+        output_format=OutputFormat.DUCKDB    # Returns DuckDB relation
+        output_format=OutputFormat.IBIS      # Returns Ibis expression
+        output_format=OutputFormat.PYSPARK   # Returns PySpark DataFrame
+        output_format=OutputFormat.PYSPARK_CONNECT  # Returns PySpark Connect DataFrame
+        output_format=OutputFormat.SQLFRAME  # Returns SQLFrame DataFrame
+        ```
         ---
         Rate Limit Weight:
         ```python
@@ -912,17 +1341,18 @@ class Bitvavo:
         ```python
         [
           {
-            "timestamp": 1542967486256,
-            "id": "57b1159b-6bf5-4cde-9e2c-6bd6a5678baf",
-            "amount": "0.1",
-            "price": "5012",
-            "side": "sell"
+          "timestamp": 1542967486256,
+          "id": "57b1159b-6bf5-4cde-9e2c-6bd6a5678baf",
+          "amount": "0.1",
+          "price": "5012",
+          "side": "sell"
           }
         ]
         ```
         """
         postfix = createPostfix(options)
-        return self.publicRequest(f"{self.base}/report/{market}/trades{postfix}", 5)  # type: ignore[return-value]
+        result = self.publicRequest(f"{self.base}/report/{market}/trades{postfix}", 5)  # type: ignore[return-value]
+        return convert_to_dataframe(result, output_format)
 
     def reportBook(self, market: str, options: intdict | None = None) -> dict[str, str | int | list[str]] | errordict:
         """Get MiCA-compliant order book report for a specific market
@@ -1471,7 +1901,12 @@ class Bitvavo:
         postfix = createPostfix(options)
         return self.privateRequest("/ordersOpen", postfix, {}, "GET", rateLimitingWeight)  # type: ignore[return-value]
 
-    def trades(self, market: str, options: anydict | None = None) -> list[anydict] | errordict:
+    def trades(
+        self,
+        market: str,
+        options: anydict | None = None,
+        output_format: OutputFormat = OutputFormat.DICT,
+    ) -> list[anydict] | errordict | Any:
         """Get all historic trades from this account
 
         ---
@@ -1479,36 +1914,48 @@ class Bitvavo:
         ```python
         market="BTC-EUR"
         options={
-            "limit": [ 1 .. 1000 ], default 500
-            "start": int timestamp in ms >= 0
-            "end": int timestamp in ms <= 8_640_000_000_000_000 # (that's somewhere in the year 2243, or near the number 2^52)
-            "tradeIdFrom": ""  # if you get a list and want everything AFTER a certain id, put that id here
-            "tradeIdTo": ""  # if you get a list and want everything BEFORE a certain id, put that id here
+          "limit": [ 1 .. 1000 ], default 500
+          "start": int timestamp in ms >= 0
+          "end": int timestamp in ms <= 8_640_000_000_000_000 # (that's somewhere in the year 2243, or near the number 2^52)
+          "tradeIdFrom": ""  # if you get a list and want everything AFTER a certain id, put that id here
+          "tradeIdTo": ""  # if you get a list and want everything BEFORE a certain id, put that id here
         }
-        ```
 
+        # Output format selection:
+        output_format=OutputFormat.DICT      # Default: returns standard Python dict/list
+        output_format=OutputFormat.PANDAS    # Returns pandas DataFrame
+        output_format=OutputFormat.POLARS    # Returns polars DataFrame
+        output_format=OutputFormat.CUDF      # Returns NVIDIA cuDF (GPU-accelerated)
+        output_format=OutputFormat.MODIN     # Returns modin (distributed pandas)
+        output_format=OutputFormat.PYARROW   # Returns Apache Arrow Table
+        output_format=OutputFormat.DASK      # Returns Dask DataFrame (distributed)
+        output_format=OutputFormat.DUCKDB    # Returns DuckDB relation
+        output_format=OutputFormat.IBIS      # Returns Ibis expression
+        output_format=OutputFormat.PYSPARK   # Returns PySpark DataFrame
+        output_format=OutputFormat.PYSPARK_CONNECT  # Returns PySpark Connect DataFrame
+        output_format=OutputFormat.SQLFRAME  # Returns SQLFrame DataFrame
+        ```
         ---
         Rate Limit Weight:
         ```python
         5
         ```
-
         ---
         Returns:
         ```python
         [
           {
-            "id": "108c3633-0276-4480-a902-17a01829deae",
-            "orderId": "1d671998-3d44-4df4-965f-0d48bd129a1b",
-            "timestamp": 1542967486256,
-            "market": "BTC-EUR",
-            "side": "buy",
-            "amount": "0.005",
-            "price": "5000.1",
-            "taker": true,
-            "fee": "0.03",
-            "feeCurrency": "EUR",
-            "settled": true
+          "id": "108c3633-0276-4480-a902-17a01829deae",
+          "orderId": "1d671998-3d44-4df4-965f-0d48bd129a1b",
+          "timestamp": 1542967486256,
+          "market": "BTC-EUR",
+          "side": "buy",
+          "amount": "0.005",
+          "price": "5000.1",
+          "taker": true,
+          "fee": "0.03",
+          "feeCurrency": "EUR",
+          "settled": true
           }
         ]
         ```
@@ -1516,7 +1963,8 @@ class Bitvavo:
         options = _default(options, {})
         options["market"] = market
         postfix = createPostfix(options)
-        return self.privateRequest("/trades", postfix, {}, "GET", 5)  # type: ignore[return-value]
+        result = self.privateRequest("/trades", postfix, {}, "GET", 5)  # type: ignore[return-value]
+        return convert_to_dataframe(result, output_format)
 
     def account(self) -> dict[str, strdict]:
         """Get all fees for this account
@@ -1579,7 +2027,11 @@ class Bitvavo:
         postfix = createPostfix(options)
         return self.privateRequest("/account/fees", postfix, {}, "GET")  # type: ignore[return-value]
 
-    def balance(self, options: strdict | None = None) -> list[strdict] | errordict:
+    def balance(
+        self,
+        options: strdict | None = None,
+        output_format: OutputFormat = OutputFormat.DICT,
+    ) -> list[strdict] | errordict | Any:
         """Get the balance for this account
 
         ---
@@ -1587,6 +2039,23 @@ class Bitvavo:
         ```python
         options={}  # return all balances
         options={symbol="BTC"} # return a single balance
+
+        # Output format selection:
+        output_format=OutputFormat.DICT      # Default: returns standard Python dict/list
+        output_format=OutputFormat.PANDAS    # Returns pandas DataFrame
+        output_format=OutputFormat.POLARS    # Returns polars DataFrame
+        output_format=OutputFormat.CUDF      # Returns NVIDIA cuDF (GPU-accelerated)
+        output_format=OutputFormat.MODIN     # Returns modin (distributed pandas)
+        output_format=OutputFormat.PYARROW   # Returns Apache Arrow Table
+        output_format=OutputFormat.DASK      # Returns Dask DataFrame (distributed)
+        output_format=OutputFormat.DUCKDB    # Returns DuckDB relation
+        output_format=OutputFormat.IBIS      # Returns Ibis expression
+        output_format=OutputFormat.PYSPARK   # Returns PySpark DataFrame
+        output_format=OutputFormat.PYSPARK_CONNECT  # Returns PySpark Connect DataFrame
+        output_format=OutputFormat.SQLFRAME  # Returns SQLFrame DataFrame
+
+        # Note: DataFrame formats require narwhals and the respective library to be installed.
+        # Install with: pip install 'bitvavo-api-upgraded[pandas]' or similar for other formats.
         ```
 
         ---
@@ -1598,6 +2067,7 @@ class Bitvavo:
         ---
         Returns:
         ```python
+        # When output_format='dict' (default):
         [
           {
             "symbol": "BTC",
@@ -1605,10 +2075,15 @@ class Bitvavo:
             "inOrder": "0.74832374"
           }
         ]
+
+        # When output_format is any DataFrame format:
+        # Returns the above data as a DataFrame in the requested format (pandas, polars, etc.)
+        # with columns: symbol, available, inOrder
         ```
         """
         postfix = createPostfix(options)
-        return self.privateRequest("/balance", postfix, {}, "GET", 5)  # type: ignore[return-value]
+        result = self.privateRequest("/balance", postfix, {}, "GET", 5)  # type: ignore[return-value]
+        return convert_to_dataframe(result, output_format)
 
     def accountHistory(self, options: strintdict | None = None) -> anydict | errordict:
         """Get all past transactions for your account
@@ -1780,7 +2255,11 @@ class Bitvavo:
         body["address"] = address
         return self.privateRequest("/withdrawal", "", body, "POST")  # type: ignore[return-value]
 
-    def withdrawalHistory(self, options: anydict | None = None) -> list[anydict] | errordict:
+    def withdrawalHistory(
+        self,
+        options: anydict | None = None,
+        output_format: OutputFormat = OutputFormat.DICT,
+    ) -> list[anydict] | errordict | Any:
         """Get the withdrawal history
 
         ---
@@ -1792,8 +2271,24 @@ class Bitvavo:
             "start": int timestamp in ms >= 0
             "end": int timestamp in ms <= 8_640_000_000_000_000 # (that's somewhere in the year 2243, or near the number 2^52)
         }
-        ```
 
+        # Output format selection:
+        output_format=OutputFormat.DICT      # Default: returns standard Python dict/list
+        output_format=OutputFormat.PANDAS    # Returns pandas DataFrame
+        output_format=OutputFormat.POLARS    # Returns polars DataFrame
+        output_format=OutputFormat.CUDF      # Returns NVIDIA cuDF (GPU-accelerated)
+        output_format=OutputFormat.MODIN     # Returns modin (distributed pandas)
+        output_format=OutputFormat.PYARROW   # Returns Apache Arrow Table
+        output_format=OutputFormat.DASK      # Returns Dask DataFrame (distributed)
+        output_format=OutputFormat.DUCKDB    # Returns DuckDB relation
+        output_format=OutputFormat.IBIS      # Returns Ibis expression
+        output_format=OutputFormat.PYSPARK   # Returns PySpark DataFrame
+        output_format=OutputFormat.PYSPARK_CONNECT  # Returns PySpark Connect DataFrame
+        output_format=OutputFormat.SQLFRAME  # Returns SQLFrame DataFrame
+
+        # Note: DataFrame formats require narwhals and the respective library to be installed.
+        # Install with: pip install 'bitvavo-api-upgraded[pandas]' or similar for other formats.
+        ```
         ---
         Rate Limit Weight:
         ```python
@@ -1814,11 +2309,124 @@ class Bitvavo:
             "fee": "0.00006",
             "status": "awaiting_processing"
           }
-        }
+        ]
         ```
         """  # noqa: E501
         postfix = createPostfix(options)
-        return self.privateRequest("/withdrawalHistory", postfix, {}, "GET", 5)  # type: ignore[return-value]
+        result = self.privateRequest("/withdrawalHistory", postfix, {}, "GET", 5)  # type: ignore[return-value]
+        return convert_to_dataframe(result, output_format)
+
+    # API Key Management Helper Methods
+
+    def add_api_key(self, api_key: str, api_secret: str) -> None:
+        """Add a new API key to the available keys.
+
+        Args:
+            api_key: The API key to add
+            api_secret: The corresponding API secret
+        """
+        new_key = {"key": api_key, "secret": api_secret}
+        self.api_keys.append(new_key)
+
+        # Initialize rate limit tracking for this key using settings default
+        key_index = len(self.api_keys) - 1
+        default_rate_limit = bitvavo_upgraded_settings.DEFAULT_RATE_LIMIT
+        self.rate_limits[key_index] = {"remaining": default_rate_limit, "resetAt": ms(0)}
+
+        logger.info("api-key-added", key_index=key_index)
+
+    def remove_api_key(self, api_key: str) -> bool:
+        """Remove an API key from the available keys.
+
+        Args:
+            api_key: The API key to remove
+
+        Returns:
+            bool: True if the key was found and removed, False otherwise
+        """
+        for i, key_data in enumerate(self.api_keys):
+            if key_data["key"] == api_key:
+                _ = self.api_keys.pop(i)
+                # Remove rate limit tracking for this key
+                if i in self.rate_limits:
+                    del self.rate_limits[i]
+                # Update rate limit tracking indices (shift them down)
+                new_rate_limits = {}
+                for key_idx, limits in self.rate_limits.items():
+                    if key_idx == -1 or key_idx < i:  # keyless
+                        new_rate_limits[key_idx] = limits
+                    elif key_idx > i:
+                        new_rate_limits[key_idx - 1] = limits
+                self.rate_limits = new_rate_limits
+
+                # Update current index if needed
+                if self.current_api_key_index >= i:
+                    self.current_api_key_index = max(0, self.current_api_key_index - 1)
+
+                logger.info("api-key-removed", key_index=i)
+                return True
+        return False
+
+    def get_api_key_status(self) -> dict[str, dict[str, int | str | bool]]:
+        """Get the current status of all API keys including rate limits.
+
+        Returns:
+            dict: Status information for keyless and all API keys
+        """
+        status = {}
+
+        # Keyless status
+        keyless_limits = self.rate_limits.get(-1, {"remaining": 0, "resetAt": ms(0)})
+        status["keyless"] = {
+            "remaining": int(keyless_limits["remaining"]),
+            "resetAt": int(keyless_limits["resetAt"]),
+            "available": self._has_rate_limit_available(-1, 1),
+        }
+
+        # API key status
+        for i, key_data in enumerate(self.api_keys):
+            key_limits = self.rate_limits.get(i, {"remaining": 0, "resetAt": ms(0)})
+            KEY_LENGTH = 12
+            key_masked = (
+                key_data["key"][:8] + "..." + key_data["key"][-4:]
+                if len(key_data["key"]) > KEY_LENGTH
+                else key_data["key"]
+            )
+            status[f"api_key_{i}"] = {
+                "key": key_masked,
+                "remaining": int(key_limits["remaining"]),
+                "resetAt": int(key_limits["resetAt"]),
+                "available": self._has_rate_limit_available(i, 1),
+            }
+
+        return status
+
+    def set_keyless_preference(self, prefer_keyless: bool) -> None:  # noqa: FBT001 (Boolean-typed positional argument in function definition)
+        """Set whether to prefer keyless requests.
+
+        Args:
+            prefer_keyless: If True, use keyless requests first when available
+        """
+        self.prefer_keyless = prefer_keyless
+        logger.info("keyless-preference-changed", prefer_keyless=prefer_keyless)
+
+    def get_current_config(self) -> dict[str, str | bool | int]:
+        """Get the current configuration.
+
+        Returns:
+            dict: Current configuration including key count and preferences
+        """
+        KEY_LENGTH = 12
+        return {
+            "api_key_count": len(self.api_keys),
+            "prefer_keyless": self.prefer_keyless,
+            "current_api_key_index": self.current_api_key_index,
+            "current_api_key": self._current_api_key[:8] + "..." + self._current_api_key[-4:]
+            if len(self._current_api_key) > KEY_LENGTH
+            else self._current_api_key,
+            "rate_limit_remaining": self.rateLimitRemaining,
+            "rate_limit_reset_at": int(self.rateLimitResetAt),
+        }
 
     def newWebsocket(self) -> Bitvavo.WebSocketAppFacade:
         return Bitvavo.WebSocketAppFacade(self.APIKEY, self.APISECRET, self.ACCESSWINDOW, self.wsUrl, self)
@@ -1875,7 +2483,7 @@ class Bitvavo:
             self.receiveThread.join()
 
         def waitForSocket(self, ws: WebSocketApp, message: str, private: bool) -> None:  # noqa: ARG002, FBT001
-            while True:
+            while self.keepAlive:
                 if (not private and self.open) or (private and self.authenticated and self.open):
                     return
                 time.sleep(0.1)
@@ -1989,6 +2597,8 @@ class Bitvavo:
                         callbacks["subscriptionTrades"][market](msg_dict)
 
         def on_error(self, ws: Any, error: Any) -> None:  # noqa: ARG002
+            # Stop the receive thread on error to prevent hanging
+            self.receiveThread.stop()
             if "error" in self.callbacks:
                 self.callbacks["error"](error)
             else: