bitvavo-api-upgraded 1.17.2__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,12 +958,16 @@ 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(  # noqa: PLR0913
+    def candles(
         self,
         market: str,
         interval: str,
@@ -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,117 @@ 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,
+        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.
+        The returned trades are sorted by timestamp in descending order (latest to earliest).
+        Includes data compliant with the European Markets in Crypto-Assets (MiCA) regulation.
+
+        ---
+        Examples:
+        * https://api.bitvavo.com/v2/report/BTC-EUR/trades
+        * https://api.bitvavo.com/v2/report/BTC-EUR/trades?limit=100&start=1640995200000
+
+        ---
+        Args:
+        ```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
+        }
+
+        # 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
+        [
+          {
+          "timestamp": 1542967486256,
+          "id": "57b1159b-6bf5-4cde-9e2c-6bd6a5678baf",
+          "amount": "0.1",
+          "price": "5012",
+          "side": "sell"
+          }
+        ]
+        ```
+        """
+        postfix = createPostfix(options)
+        result = self.publicRequest(f"{self.base}/report/{market}/trades{postfix}", 5)  # type: ignore[return-value]
+        return convert_to_dataframe(result, output_format)
 
-    def placeOrder(self, market: str, side: str, orderType: str, body: anydict) -> anydict:
+    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
+
+        Returns the list of all bids and asks for the specified market, sorted by price.
+        Includes data compliant with the European Markets in Crypto-Assets (MiCA) regulation.
+
+        ---
+        Examples:
+        * https://api.bitvavo.com/v2/report/BTC-EUR/book
+        * https://api.bitvavo.com/v2/report/BTC-EUR/book?depth=100
+
+        ---
+        Args:
+        ```python
+        market="BTC-EUR"
+        options={"depth": 100}  # returns the best 100 asks and 100 bids, default 1000
+        options={}  # returns up to 1000 bids and asks for that book
+        ```
+
+        ---
+        Rate Limit Weight:
+        ```python
+        1
+        ```
+
+        ---
+        Returns:
+        ```python
+        {
+          "market": "BTC-EUR",
+          "nonce": 10378032,
+          "bids": [["41648", "0.12"], ["41647", "0.25"], ["41646", "0.33"]],
+          "asks": [["41649", "0.15"], ["41650", "0.28"], ["41651", "0.22"]],
+          "timestamp": 1700000000000,
+        }
+        ```
+        """
+        postfix = createPostfix(options)
+        return self.publicRequest(f"{self.base}/report/{market}/book{postfix}")  # type: ignore[return-value]
+
+    def placeOrder(self, market: str, side: str, orderType: str, operatorId: int, body: anydict) -> anydict:
         """Place a new order on the exchange
 
         ---
@@ -886,9 +1404,11 @@ class Bitvavo:
         side="buy" # Choose: buy, sell
         # For market orders either `amount` or `amountQuote` is required
         orderType="market"  # Choose: market, limit, stopLoss, stopLossLimit, takeProfit, takeProfitLimit
+        operatorId=123  # Your identifier for the trader or bot that made the request
         body={
           "amount": "1.567",
           "amountQuote": "5000",
+          "clientOrderId": "2be7d0df-d8dc-7b93-a550-8876f3b393e9",  # Optional: your identifier for the order
           # GTC orders will remain on the order book until they are filled or canceled.
           # IOC orders will fill against existing orders, but will cancel any remaining amount after that.
           # FOK orders will fill against existing orders in its entirety, or will be canceled (if the entire order cannot be filled).
@@ -904,6 +1424,7 @@ class Bitvavo:
 
         # For limit orders `amount` and `price` are required.
         orderType="limit"  # Choose: market, limit, stopLoss, stopLossLimit, takeProfit, takeProfitLimit
+        operatorId=123
         body={
           "amount": "1.567",
           "price": "6000",
@@ -916,6 +1437,7 @@ class Bitvavo:
         orderType="stopLoss"
         # or
         orderType="takeProfit"
+        operatorId=123
         body={
           "amount": "1.567",
           "amountQuote": "5000",
@@ -931,6 +1453,7 @@ class Bitvavo:
         orderType="stopLossLimit"
         # or
         orderType="takeProfitLimit"
+        operatorId=123
         body={
           "amount": "1.567",
           "price": "6000",
@@ -999,9 +1522,10 @@ class Bitvavo:
         body["market"] = market
         body["side"] = side
         body["orderType"] = orderType
+        body["operatorId"] = operatorId
         return self.privateRequest("/order", "", body, "POST")  # type: ignore[return-value]
 
-    def updateOrder(self, market: str, orderId: str, body: anydict) -> anydict:
+    def updateOrder(self, market: str, orderId: str, operatorId: int, body: anydict) -> anydict:
         """Update an existing order for a specific market. Make sure that at least one of the optional parameters is set, otherwise nothing will be updated.
 
         ---
@@ -1009,11 +1533,13 @@ class Bitvavo:
         ```python
         market="BTC-EUR"
         orderId="95d92d6c-ecf0-4960-a608-9953ef71652e"
+        operatorId=123  # Your identifier for the trader or bot that made the request
         body={
           "amount": "1.567",
           "amountRemaining": "1.567",
           "price": "6000",
           "triggerAmount": "4000",  # only for stop orders
+          "clientOrderId": "2be7d0df-d8dc-7b93-a550-8876f3b393e9",  # Optional: your identifier for the order
           # GTC orders will remain on the order book until they are filled or canceled.
           # IOC orders will fill against existing orders, but will cancel any remaining amount after that.
           # FOK orders will fill against existing orders in its entirety, or will be canceled (if the entire order cannot be filled).
@@ -1082,22 +1608,32 @@ class Bitvavo:
         """  # noqa: E501
         body["market"] = market
         body["orderId"] = orderId
+        body["operatorId"] = operatorId
         return self.privateRequest("/order", "", body, "PUT")  # type: ignore[return-value]
 
-    def cancelOrder(self, market: str, orderId: str) -> strdict:
+    def cancelOrder(
+        self,
+        market: str,
+        operatorId: int,
+        orderId: str | None = None,
+        clientOrderId: str | None = None,
+    ) -> strdict:
         """Cancel an existing order for a specific market
 
         ---
         Args:
         ```python
         market="BTC-EUR"
-        orderId="a4a5d310-687c-486e-a3eb-1df832405ccd"
+        operatorId=123  # Your identifier for the trader or bot that made the request
+        orderId="a4a5d310-687c-486e-a3eb-1df832405ccd"  # Either orderId or clientOrderId required
+        clientOrderId="2be7d0df-d8dc-7b93-a550-8876f3b393e9"  # Either orderId or clientOrderId required
+        # If both orderId and clientOrderId are provided, clientOrderId takes precedence
         ```
 
         ---
         Rate Limit Weight:
         ```python
-        1
+        N/A
         ```
 
         ---
@@ -1106,7 +1642,22 @@ class Bitvavo:
         {"orderId": "2e7ce7fc-44e2-4d80-a4a7-d079c4750b61"}
         ```
         """
-        postfix = createPostfix({"market": market, "orderId": orderId})
+        if orderId is None and clientOrderId is None:
+            msg = "Either orderId or clientOrderId must be provided"
+            raise ValueError(msg)
+
+        params = {
+            "market": market,
+            "operatorId": operatorId,
+        }
+
+        # clientOrderId takes precedence if both are provided
+        if clientOrderId is not None:
+            params["clientOrderId"] = clientOrderId
+        elif orderId is not None:
+            params["orderId"] = orderId
+
+        postfix = createPostfix(params)
         return self.privateRequest("/order", postfix, {}, "DELETE")  # type: ignore[return-value]
 
     def getOrder(self, market: str, orderId: str) -> list[anydict] | errordict:
@@ -1350,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
 
         ---
@@ -1358,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
           }
         ]
         ```
@@ -1395,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
@@ -1421,6 +1990,35 @@ class Bitvavo:
         return self.privateRequest("/account", "", {}, "GET")  # type: ignore[return-value]
 
     def fees(self, market: str | None = None, quote: str | None = None) -> list[strdict] | errordict:
+        """Get market fees for a specific market or quote currency
+
+        ---
+        Args:
+        ```python
+        market="BTC-EUR"  # Optional: get fees for specific market
+        quote="EUR"       # Optional: get fees for all markets with EUR as quote currency
+        # If both are provided, market takes precedence
+        # If neither are provided, returns fees for all markets
+        ```
+
+        ---
+        Rate Limit Weight:
+        ```python
+        1
+        ```
+
+        ---
+        Returns:
+        ```python
+        [
+          {
+            "market": "BTC-EUR",
+            "maker": "0.0015",
+            "taker": "0.0025"
+          }
+        ]
+        ```
+        """
         options = {}
         if market is not None:
             options["market"] = market
@@ -1429,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
 
         ---
@@ -1437,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.
         ```
 
         ---
@@ -1448,6 +2067,7 @@ class Bitvavo:
         ---
         Returns:
         ```python
+        # When output_format='dict' (default):
         [
           {
             "symbol": "BTC",
@@ -1455,10 +2075,62 @@ 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)
+        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
+
+        ---
+        Args:
+        ```python
+        options={
+            "fromDate": int timestamp in ms >= 0,  # Starting timestamp to return transactions from
+            "toDate": int timestamp in ms <= 8_640_000_000_000_000,  # Timestamp up to which to return transactions
+            "maxItems": [ 1 .. 100 ], default 100,  # Maximum number of transactions per page
+            "page": 1,  # Page number to return (1-indexed)
+        }
+        ```
+
+        ---
+        Rate Limit Weight:
+        ```python
+        1
+        ```
+
+        ---
+        Returns:
+        ```python
+        {
+          "items": [
+            {
+              "transactionId": "5f5e7b3b-4f5b-4b2d-8b2f-4f2b5b3f5e5f",
+              "timestamp": 1542967486256,
+              "type": "deposit",
+              "symbol": "BTC",
+              "amount": "0.99994",
+              "description": "Deposit via bank transfer",
+              "status": "completed",
+              "feesCurrency": "EUR",
+              "feesAmount": "0.01",
+              "address": "BitcoinAddress"
+            }
+          ],
+          "currentPage": 1,
+          "totalPages": 1,
+          "maxItems": 100
+        }
         ```
         """
         postfix = createPostfix(options)
-        return self.privateRequest("/balance", postfix, {}, "GET", 5)  # type: ignore[return-value]
+        return self.privateRequest("/account/history", postfix, {}, "GET")  # type: ignore[return-value]
 
     def depositAssets(self, symbol: str) -> strdict:
         """Get the deposit address (with paymentId for some assets) or bank account information to increase your balance
@@ -1583,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
 
         ---
@@ -1595,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
@@ -1617,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)
@@ -1678,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)
@@ -1792,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:
@@ -2311,6 +3118,7 @@ class Bitvavo:
             market: str,
             side: str,
             orderType: str,
+            operatorId: int,
             body: anydict,
             callback: Callable[[Any], None],
         ) -> None:
@@ -2323,9 +3131,11 @@ class Bitvavo:
             side="buy" # Choose: buy, sell
             # For market orders either `amount` or `amountQuote` is required
             orderType="market"  # Choose: market, limit, stopLoss, stopLossLimit, takeProfit, takeProfitLimit
+            operatorId=123  # Your identifier for the trader or bot that made the request
             body={
               "amount": "1.567",
               "amountQuote": "5000",
+              "clientOrderId": "2be7d0df-d8dc-7b93-a550-8876f3b393e9",  # Optional: your identifier for the order
               # GTC orders will remain on the order book until they are filled or canceled.
               # IOC orders will fill against existing orders, but will cancel any remaining amount after that.
               # FOK orders will fill against existing orders in its entirety, or will be canceled (if the entire order cannot be filled).
@@ -2341,6 +3151,7 @@ class Bitvavo:
 
             # For limit orders `amount` and `price` are required.
             orderType="limit"  # Choose: market, limit, stopLoss, stopLossLimit, takeProfit, takeProfitLimit
+            operatorId=123
             body={
               "amount": "1.567",
               "price": "6000",
@@ -2353,6 +3164,7 @@ class Bitvavo:
             orderType="stopLoss"
             # or
             orderType="takeProfit"
+            operatorId=123
             body={
               "amount": "1.567",
               "amountQuote": "5000",
@@ -2368,6 +3180,7 @@ class Bitvavo:
             orderType="stopLossLimit"
             # or
             orderType="takeProfitLimit"
+            operatorId=123
             body={
               "amount": "1.567",
               "price": "6000",
@@ -2438,6 +3251,7 @@ class Bitvavo:
             body["market"] = market
             body["side"] = side
             body["orderType"] = orderType
+            body["operatorId"] = operatorId
             body["action"] = "privateCreateOrder"
             self.doSend(self.ws, json.dumps(body), True)
 
@@ -2445,6 +3259,7 @@ class Bitvavo:
             self,
             market: str,
             orderId: str,
+            operatorId: int,
             body: anydict,
             callback: Callable[[Any], None],
         ) -> None:
@@ -2457,11 +3272,13 @@ class Bitvavo:
             ```python
             market="BTC-EUR"
             orderId="95d92d6c-ecf0-4960-a608-9953ef71652e"
+            operatorId=123  # Your identifier for the trader or bot that made the request
             body={
               "amount": "1.567",
               "amountRemaining": "1.567",
               "price": "6000",
               "triggerAmount": "4000",  # only for stop orders
+              "clientOrderId": "2be7d0df-d8dc-7b93-a550-8876f3b393e9",  # Optional: your identifier for the order
               # GTC orders will remain on the order book until they are filled or canceled.
               # IOC orders will fill against existing orders, but will cancel any remaining amount after that.
               # FOK orders will fill against existing orders in its entirety, or will be canceled (if the entire order cannot be filled).
@@ -2532,24 +3349,35 @@ class Bitvavo:
             self.callbacks["updateOrder"] = callback
             body["market"] = market
             body["orderId"] = orderId
+            body["operatorId"] = operatorId
             body["action"] = "privateUpdateOrder"
             self.doSend(self.ws, json.dumps(body), True)
 
-        def cancelOrder(self, market: str, orderId: str, callback: Callable[[Any], None]) -> None:
+        def cancelOrder(
+            self,
+            market: str,
+            operatorId: int,
+            callback: Callable[[Any], None],
+            orderId: str | None = None,
+            clientOrderId: str | None = None,
+        ) -> None:
             """Cancel an existing order for a specific market
 
             ---
             Args:
             ```python
             market="BTC-EUR"
-            orderId="a4a5d310-687c-486e-a3eb-1df832405ccd"
+            operatorId=123  # Your identifier for the trader or bot that made the request
             callback=callback_example
+            orderId="a4a5d310-687c-486e-a3eb-1df832405ccd"  # Either orderId or clientOrderId required
+            clientOrderId="2be7d0df-d8dc-7b93-a550-8876f3b393e9"  # Either orderId or clientOrderId required
+            # If both orderId and clientOrderId are provided, clientOrderId takes precedence
             ```
 
             ---
             Rate Limit Weight:
             ```python
-            1
+            N/A
             ```
 
             ---
@@ -2558,12 +3386,23 @@ class Bitvavo:
             {"orderId": "2e7ce7fc-44e2-4d80-a4a7-d079c4750b61"}
             ```
             """
+            if orderId is None and clientOrderId is None:
+                msg = "Either orderId or clientOrderId must be provided"
+                raise ValueError(msg)
+
             self.callbacks["cancelOrder"] = callback
             options = {
                 "action": "privateCancelOrder",
                 "market": market,
-                "orderId": orderId,
+                "operatorId": operatorId,
             }
+
+            # clientOrderId takes precedence if both are provided
+            if clientOrderId is not None:
+                options["clientOrderId"] = clientOrderId
+            elif orderId is not None:
+                options["orderId"] = orderId
+
             self.doSend(self.ws, json.dumps(options), True)
 
         def getOrder(self, market: str, orderId: str, callback: Callable[[Any], None]) -> None: