bitvavo-api-upgraded 4.0.0__py3-none-any.whl → 4.1.0__py3-none-any.whl

bitvavo_api_upgraded/bitvavo.py

@@ -2,16 +2,16 @@ from __future__ import annotations
 
 import contextlib
 import datetime as dt
-import hashlib
-import hmac
 import json
+import statistics
 import time
+from concurrent.futures import ThreadPoolExecutor, as_completed
 from pathlib import Path
 from threading import Thread
-from typing import Any, Callable
+from typing import TYPE_CHECKING, Any
 
 import websocket as ws_lib
-from requests import delete, get, post, put
+from httpx import delete, get, post, put
 from structlog.stdlib import get_logger
 from websocket import WebSocketApp  # missing stubs for WebSocketApp
 
@@ -19,88 +19,24 @@ from bitvavo_api_upgraded.dataframe_utils import convert_candles_to_dataframe, c
 from bitvavo_api_upgraded.helper_funcs import configure_loggers, time_ms, time_to_wait
 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
+from bitvavo_client.auth.signing import create_signature
+from bitvavo_client.endpoints.common import (
+    asks_compare,
+    bids_compare,
+    create_postfix,
+    default,
+    epoch_millis,
+    sort_and_insert,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
 
 configure_loggers()
 
 logger = get_logger(__name__)
 
 
-def create_signature(timestamp: ms, method: str, url: str, body: anydict | None, api_secret: str) -> str:
-    string = f"{timestamp}{method}/v2{url}"
-    if body is not None and len(body.keys()) > 0:
-        string += json.dumps(body, separators=(",", ":"))
-    signature = hmac.new(api_secret.encode("utf-8"), string.encode("utf-8"), hashlib.sha256).hexdigest()
-    return signature
-
-
-def create_postfix(options: anydict | None) -> str:
-    """Generate a URL postfix, based on the `options` dict.
-
-    ---
-    Args:
-        options (anydict): [description]
-
-    ---
-    Returns:
-        str: [description]
-    """
-    options = _default(options, {})
-    params = [f"{key}={options[key]}" for key in options]
-    postfix = "&".join(params)  # intersperse
-    return f"?{postfix}" if len(options) > 0 else postfix
-
-
-def _default(value: anydict | None, fallback: anydict) -> anydict:
-    """
-    Note that is close, but not actually equal to:
-
-    `return value or fallback`
-
-    I checked this with a temporary hypothesis test.
-
-    This note is all you will get out of me.
-    """
-    return value if value is not None else fallback
-
-
-def _epoch_millis(dt: dt.datetime) -> int:
-    return int(dt.timestamp() * 1000)
-
-
-def asks_compare(a: float, b: float) -> bool:
-    return a < b
-
-
-def bids_compare(a: float, b: float) -> bool:
-    return a > b
-
-
-def sort_and_insert(
-    asks_or_bids: list[list[str]],
-    update: list[list[str]],
-    compareFunc: Callable[[float, float], bool],
-) -> list[list[str]] | errordict:
-    for updateEntry in update:
-        entrySet: bool = False
-        for j in range(len(asks_or_bids)):
-            bookItem = asks_or_bids[j]
-            if compareFunc(float(updateEntry[0]), float(bookItem[0])):
-                asks_or_bids.insert(j, updateEntry)
-                entrySet = True
-                break
-            if float(updateEntry[0]) == float(bookItem[0]):
-                if float(updateEntry[1]) > 0.0:
-                    asks_or_bids[j] = updateEntry
-                    entrySet = True
-                    break
-                asks_or_bids.pop(j)
-                entrySet = True
-                break
-        if not entrySet:
-            asks_or_bids.append(updateEntry)
-    return asks_or_bids
-
-
 def process_local_book(ws: Bitvavo.WebSocketAppFacade, message: anydict) -> None:
     market: str = ""
     if "action" in message:
@@ -412,7 +348,9 @@ class Bitvavo:
         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"]
+            "rate-limit-reached",
+            key_name=key_name,
+            rateLimitRemaining=self.rate_limits[key_index]["remaining"],
         )
         logger.info(
             "napping-until-reset",
@@ -423,27 +361,108 @@ class Bitvavo:
         )
         time.sleep(napTime + 1)  # +1 to add a tiny bit of buffer time
 
-    def calc_lag(self) -> ms:
+    def calc_lag(self, samples: int = 5, timeout_seconds: float = 5.0) -> ms:  # noqa: C901
         """
-        Calculate the time difference between the client and server; use this value with BITVAVO_API_UPGRADED_LAG,
-        when you make an api call, to precent 304 errors.
+        Calculate the time difference between the client and server using statistical analysis.
+
+        Uses multiple samples with outlier detection to get a more accurate lag measurement.
+
+        Args:
+            samples: Number of time samples to collect (default: 5)
+            timeout_seconds: Maximum time to spend collecting samples (default: 5.0)
+
+        Returns:
+            Average lag in milliseconds
 
-        Raises KeyError if time() returns an error dict.
+        Raises:
+            ValueError: If unable to collect sufficient valid samples
+            RuntimeError: If all API calls fail
         """
-        lag_list = [
-            self.time()["time"] - time_ms(),
-            self.time()["time"] - time_ms(),
-            self.time()["time"] - time_ms(),
-            self.time()["time"] - time_ms(),
-            self.time()["time"] - time_ms(),
-            self.time()["time"] - time_ms(),
-            self.time()["time"] - time_ms(),
-            self.time()["time"] - time_ms(),
-            self.time()["time"] - time_ms(),
-            self.time()["time"] - time_ms(),
-        ]
+        ARBITRARY = 3
+        if samples < ARBITRARY:
+            msg = f"Need at least {ARBITRARY} samples for statistical analysis"
+            raise ValueError(msg)
+
+        def measure_single_lag() -> ms | None:
+            """Measure lag for a single request with error handling."""
+            try:
+                client_time_before = time_ms()
+                server_response = self.time()
+                client_time_after = time_ms()
+
+                if isinstance(server_response, dict) and "time" in server_response:
+                    # Use midpoint of request duration for better accuracy
+                    client_time_avg = (client_time_before + client_time_after) // 2
+                    server_time = server_response["time"]
+                    if isinstance(server_time, int):
+                        return ms(server_time - client_time_avg)
+                    return None
+            except (ValueError, TypeError, KeyError):
+                return None
+            else:
+                # If error or unexpected response
+                return None
+
+        lag_measurements: list[ms] = []
+
+        # Collect samples concurrently for better performance
+        with ThreadPoolExecutor(max_workers=min(samples, 5)) as executor:
+            try:
+                # Submit all measurement tasks
+                future_to_sample = {executor.submit(measure_single_lag): i for i in range(samples)}
+
+                # Collect results with timeout
+                for future in as_completed(future_to_sample, timeout=timeout_seconds):
+                    lag = future.result()
+                    if lag is not None:
+                        lag_measurements.append(lag)
+
+            except TimeoutError:
+                if self.debugging:
+                    logger.warning(
+                        "lag-calculation-timeout",
+                        collected_samples=len(lag_measurements),
+                        requested_samples=samples,
+                    )
+
+        if len(lag_measurements) < max(2, samples // 2):
+            msg = f"Insufficient valid samples: got {len(lag_measurements)}, need at least {max(2, samples // 2)}"
+            raise RuntimeError(msg)
+
+        # Remove outliers using interquartile range method
+        QUARTILES = 4
+        if len(lag_measurements) >= QUARTILES:
+            try:
+                q1 = statistics.quantiles(lag_measurements, n=QUARTILES)[0]
+                q3 = statistics.quantiles(lag_measurements, n=QUARTILES)[2]
+                iqr = q3 - q1
+                lower_bound = q1 - 1.5 * iqr
+                upper_bound = q3 + 1.5 * iqr
+
+                filtered_measurements = [lag for lag in lag_measurements if lower_bound <= lag <= upper_bound]
+
+                # Use filtered data if we still have enough samples
+                if len(filtered_measurements) >= 2:  # noqa: PLR2004
+                    lag_measurements = filtered_measurements
+
+            except statistics.StatisticsError:
+                # Fall back to original measurements if filtering fails
+                pass
+
+        # Calculate final lag using median for robustness
+        final_lag = ms(statistics.median(lag_measurements))
+
+        if self.debugging:
+            logger.debug(
+                "lag-calculated",
+                samples_collected=len(lag_measurements),
+                lag_ms=final_lag,
+                min_lag=min(lag_measurements),
+                max_lag=max(lag_measurements),
+                std_dev=statistics.stdev(lag_measurements) if len(lag_measurements) > 1 else 0,
+            )
 
-        return ms(sum(lag_list) / len(lag_list))
+        return final_lag
 
     def get_remaining_limit(self) -> int:
         """Get the remaining rate limit
@@ -576,7 +595,6 @@ class Bitvavo:
 
         ---
         Args:
-        # TODO(NostraDavid) fill these in
         ```python
         endpoint: str = "/order"
         postfix: str = ""  # ?key=value&key2=another_value&...
@@ -1045,14 +1063,14 @@ class Bitvavo:
         # timestamp is converted to datetime, numeric columns to float
         ```
         """
-        options = _default(options, {})
+        options = default(options, {})
         options["interval"] = interval
         if limit is not None:
             options["limit"] = limit
         if start is not None:
-            options["start"] = _epoch_millis(start)
+            options["start"] = epoch_millis(start)
         if end is not None:
-            options["end"] = _epoch_millis(end)
+            options["end"] = epoch_millis(end)
         postfix = create_postfix(options)
         result = self.public_request(f"{self.base}/{market}/candles{postfix}")  # type: ignore[return-value]
         return convert_candles_to_dataframe(result, output_format)
@@ -1279,7 +1297,7 @@ class Bitvavo:
         ]
         ```
         """
-        options = _default(options, {})
+        options = default(options, {})
         rateLimitingWeight = 25
         if "market" in options:
             rateLimitingWeight = 1
@@ -1796,7 +1814,7 @@ class Bitvavo:
         ]
         ```
         """  # noqa: E501
-        options = _default(options, {})
+        options = default(options, {})
         options["market"] = market
         postfix = create_postfix(options)
         return self.private_request("/orders", postfix, {}, "GET", 5)  # type: ignore[return-value]
@@ -1894,7 +1912,7 @@ class Bitvavo:
         ]
         ```
         """
-        options = _default(options, {})
+        options = default(options, {})
         rateLimitingWeight = 25
         if "market" in options:
             rateLimitingWeight = 1
@@ -1960,7 +1978,7 @@ class Bitvavo:
         ]
         ```
         """  # noqa: E501
-        options = _default(options, {})
+        options = default(options, {})
         options["market"] = market
         postfix = create_postfix(options)
         result = self.private_request("/trades", postfix, {}, "GET", 5)  # type: ignore[return-value]
@@ -2489,7 +2507,6 @@ class Bitvavo:
                 time.sleep(0.1)
 
         def do_send(self, ws: WebSocketApp, message: str, private: bool = False) -> None:  # noqa: FBT001, FBT002
-            # TODO(NostraDavid): add nap-time to the websocket, or do it here; I don't know yet.
             if private and self.APIKEY == "":
                 logger.error(
                     "no-apikey",
@@ -3961,8 +3978,6 @@ class Bitvavo:
             self.do_send(self.ws, json.dumps(options), True)
 
         def subscription_ticker(self, market: str, callback: Callable[[Any], None]) -> None:
-            # TODO(NostraDavid): one possible improvement here is to turn `market` into a list of markets, so we can sub
-            # to all of them at once. Same goes for other `subscription*()`
             """
             Subscribe to the ticker channel, which means `callback` gets passed the new best bid or ask whenever they
             change (server-side).

bitvavo_api_upgraded/dataframe_utils.py

@@ -165,7 +165,9 @@ def convert_candles_to_dataframe(data: Any, output_format: str | OutputFormat) -
     # Convert list of lists to list of dicts first
     columns = ["timestamp", "open", "high", "low", "close", "volume"]
     dict_data = [
-        dict(zip(columns, candle)) for candle in data if isinstance(candle, list) and len(candle) >= len(columns)
+        dict(zip(columns, candle, strict=True))
+        for candle in data
+        if isinstance(candle, list) and len(candle) >= len(columns)
     ]
 
     if not dict_data:

bitvavo_api_upgraded/settings.py

@@ -105,7 +105,7 @@ class BitvavoSettings(BaseSettings):
     PREFER_KEYLESS: bool = Field(default=True)
 
     # Configuration for Pydantic Settings
-    model_config: SettingsConfigDict = SettingsConfigDict(
+    model_config = SettingsConfigDict(
         env_file=Path.cwd() / ".env",
         env_file_encoding="utf-8",
         env_prefix="BITVAVO_",

bitvavo_api_upgraded/type_aliases.py

@@ -4,7 +4,7 @@ to clearify the intention or semantics/meaning/unit of a variable
 """
 
 import sys
-from typing import Any, Union
+from typing import Any
 
 if sys.version_info >= (3, 11):
     from enum import StrEnum
@@ -26,7 +26,7 @@ anydict = dict[str, Any]
 strdict = dict[str, str]
 intdict = dict[str, int]
 # can't use | here, with __future__. Not sure why.
-strintdict = dict[str, Union[str, int]]
+strintdict = dict[str, str | int]
 errordict = dict[str, Any]  # same type as anydict, but the semantics/meaning is different
 
 # note: You can also use these for type conversion, so instead of int(some_float / 1000), you can just do ms(some_float

{bitvavo_api_upgraded-4.0.0.dist-info → bitvavo_api_upgraded-4.1.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: bitvavo-api-upgraded
-Version: 4.0.0
+Version: 4.1.0
 Summary: A unit-tested fork of the Bitvavo API
 Author: Bitvavo BV (original code), NostraDavid
 Author-email: NostraDavid <55331731+NostraDavid@users.noreply.github.com>
@@ -21,11 +21,12 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python
 Classifier: Typing :: Typed
-Requires-Dist: pydantic-settings==2.*,>=2.6
-Requires-Dist: requests==2.*,>=2.26
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic-settings>=2.6
+Requires-Dist: requests>=2.26
 Requires-Dist: returns>=0.23.0
-Requires-Dist: structlog>=21.5,==25.*
-Requires-Dist: websocket-client==1.*,>=1.2
+Requires-Dist: structlog>=21.5
+Requires-Dist: websocket-client>=1.2
 Requires-Dist: cudf-cu12>=24.0.0 ; extra == 'cudf'
 Requires-Dist: narwhals>=2.0.0 ; extra == 'cudf'
 Requires-Dist: narwhals[dask]>=2.0.0 ; extra == 'dask'
@@ -34,6 +35,9 @@ Requires-Dist: narwhals[ibis]>=2.0.0 ; extra == 'ibis'
 Requires-Dist: narwhals[modin]>=2.0.0 ; extra == 'modin'
 Requires-Dist: narwhals[pandas]>=2.0.0 ; extra == 'pandas'
 Requires-Dist: narwhals[polars]>=2.0.0 ; extra == 'polars'
+Requires-Dist: cudf-polars-cu12>=24.0.0 ; extra == 'polars-gpu'
+Requires-Dist: polars ; extra == 'polars-gpu'
+Requires-Dist: narwhals>=2.0.0 ; extra == 'polars-gpu'
 Requires-Dist: narwhals[pyarrow]>=2.0.0 ; extra == 'pyarrow'
 Requires-Dist: narwhals[pyspark]>=2.0.0 ; extra == 'pyspark'
 Requires-Dist: narwhals[pyspark-connect]>=2.0.0 ; extra == 'pyspark-connect'
@@ -51,6 +55,7 @@ Provides-Extra: ibis
 Provides-Extra: modin
 Provides-Extra: pandas
 Provides-Extra: polars
+Provides-Extra: polars-gpu
 Provides-Extra: pyarrow
 Provides-Extra: pyspark
 Provides-Extra: pyspark-connect
@@ -59,7 +64,7 @@ Description-Content-Type: text/markdown
 
 # Bitvavo API (upgraded)
 
-A **typed, tested, and enhanced** Python wrapper for the Bitvavo cryptocurrency exchange API. This is an "upgraded" fork of the official Bitvavo SDK with comprehensive type hints, unit tests, and improved developer experience.
+A **typed, tested, and enhanced** Python wrapper for the Bitvavo cryptocurrency exchange API. This is an "upgraded" fork of the official Bitvavo SDK with comprehensive type hints, unit tests, modern architecture, and improved developer experience.
 
 ## Quick Start
 
@@ -67,6 +72,23 @@ A **typed, tested, and enhanced** Python wrapper for the Bitvavo cryptocurrency
 pip install bitvavo_api_upgraded
 ```
 
+### Basic Usage
+
+```python
+# Option 1: Original Bitvavo interface (legacy)
+from bitvavo_api_upgraded import Bitvavo
+
+bitvavo = Bitvavo({'APIKEY': 'your-key', 'APISECRET': 'your-secret'})
+balance = bitvavo.balance({})
+
+# Option 2: New modular BitvavoClient interface (recommended)
+from bitvavo_client import BitvavoClient, BitvavoSettings
+
+client = BitvavoClient()
+result = client.public.time()  # No authentication needed
+result = client.private.balance()  # Authentication required
+```
+
 ### Optional Dataframe Support
 
 This package supports multiple dataframe libraries via [Narwhals](https://narwhals-dev.github.io/narwhals/), providing a unified interface across:
@@ -113,66 +135,127 @@ Scroll down for detailed usage examples and configuration instructions.
 
 This wrapper improves upon the official Bitvavo SDK with:
 
-- 🎯 **Complete type annotations** for all functions and classes
-- 🧪 **Comprehensive test suite** (found and fixed multiple bugs in the original)
-- 📋 **Detailed changelog** tracking all changes and improvements
-- 🔄 **Up-to-date API compliance** including MiCA regulatory requirements
-- 📚 **Enhanced documentation** with examples and clear usage patterns
-- 🐍 **Modern Python support** (3.9+, dropped EOL versions)
-- 🔑 **Multi-key & keyless support** for enhanced rate limiting and public access
-- ⚡ **Better error handling** and rate limiting
-- 🔧 **Developer-friendly tooling** (ruff, mypy, pre-commit hooks)
-- 📊 **Unified dataframe support** via Narwhals (pandas, polars, cuDF, modin, PyArrow, Dask, DuckDB, Ibis, PySpark, SQLFrame)
+### Modern Architecture
+
+- **Modular design**: Clean separation between public/private APIs, transport, and authentication
+- **Two interfaces**: Legacy `Bitvavo` class for backward compatibility + new `BitvavoClient` for modern development
+- **Dependency injection**: Testable, maintainable, and extensible codebase
+- **Type safety**: Comprehensive type annotations with generics and precise return types
+
+### Quality & Reliability
+
+- **Comprehensive test suite** (found and fixed multiple bugs in the original)
+- **100% type coverage** with mypy strict mode
+- **Enhanced error handling** with detailed validation messages
+- **Rate limiting** with automatic throttling and multi-key support
+
+### Data Format Flexibility
+
+- **Unified dataframe support** via Narwhals (pandas, polars, cuDF, modin, PyArrow, Dask, DuckDB, Ibis, PySpark, SQLFrame)
+- **Pydantic models** for validated, structured data
+- **Raw dictionary access** for backward compatibility
+- **Result types** for functional error handling
+
+### Enhanced Performance
+
+- **Multi-key support** for better rate limiting and load distribution
+- **Keyless access** for public endpoints (doesn't count against your API limits)
+- **Connection pooling** and retry logic
+- **Async-ready architecture** (async support coming in future release)
+
+### Developer Experience
+
+- **Modern Python support** (3.9+, dropped EOL versions)
+- **Configuration via environment variables** or Pydantic settings
+- **Detailed changelog** tracking all changes and improvements
+- **Enhanced documentation** with examples and clear usage patterns
+- **Developer-friendly tooling** (ruff, mypy, pre-commit hooks)
 
 ## Features
 
 ### Full API Coverage
 
-- ✅ All REST endpoints (public and private)
-- ✅ **Multiple API key support** with automatic load balancing
-- ✅ **Keyless access** for public endpoints without authentication
-- ✅ **Comprehensive dataframe support** via Narwhals (pandas, polars, cuDF, modin, PyArrow, Dask, DuckDB, Ibis, PySpark, and more)
-- ✅ WebSocket support with reconnection logic
-- ✅ Rate limiting with automatic throttling
-- ✅ MiCA compliance reporting endpoints
+- All REST endpoints (public and private)
+- Multiple API key support with automatic load balancing
+- Keyless access for public endpoints without authentication
+- Comprehensive dataframe support via Narwhals (pandas, polars, cuDF, modin, PyArrow, Dask, DuckDB, Ibis, PySpark, and more)
+- WebSocket support with reconnection logic
+- Rate limiting with automatic throttling
+- MiCA compliance reporting endpoints
 
 ### Developer Experience
 
-- ✅ Type hints for better IDE support
-- ✅ Comprehensive error handling
-- ✅ Detailed logging with `structlog`
-- ✅ Configuration via `.env` files
-- ✅ Extensive test coverage
+- Type hints for better IDE support
+- Comprehensive error handling
+- Detailed logging with `structlog`
+- Configuration via `.env` files
+- Extensive test coverage
 
 ### Production Ready
 
-- ✅ Automatic rate limit management
-- ✅ Multi-key failover support
-- ✅ Connection retry logic
-- ✅ Proper error responses
-- ✅ Memory efficient WebSocket handling
+- Automatic rate limit management
+- Multi-key failover support
+- Connection retry logic
+- Proper error responses
+- Memory efficient WebSocket handling
 
 ## Configuration
 
+### Environment Variables
+
 Create a `.env` file in your project root:
 
 ```env
-# Single API key (traditional)
-BITVAVO_APIKEY=your-api-key-here
-BITVAVO_APISECRET=your-api-secret-here
+# API authentication
+BITVAVO_API_KEY=your-api-key-here
+BITVAVO_API_SECRET=your-api-secret-here
+
+# Multi-key support (JSON array as string)
+# BITVAVO_API_KEYS='[{"key": "key1", "secret": "secret1"}, {"key": "key2", "secret": "secret2"}]'
+
+# Client behavior
+BITVAVO_PREFER_KEYLESS=true          # Use keyless for public endpoints
+BITVAVO_DEFAULT_RATE_LIMIT=1000      # Rate limit per key
+BITVAVO_RATE_LIMIT_BUFFER=50         # Buffer to avoid hitting limits
+BITVAVO_DEBUGGING=false              # Enable debug logging
+
+# API endpoints (usually not needed to change)
+BITVAVO_REST_URL=https://api.bitvavo.com/v2
+BITVAVO_WS_URL=wss://ws.bitvavo.com/v2/
+```
+
+### Usage Examples
+
+#### New BitvavoClient (Recommended)
+
+```python
+from bitvavo_client import BitvavoClient, BitvavoSettings
+
+# Option 1: Auto-load from .env file
+client = BitvavoClient()
+
+# Option 2: Custom settings
+settings = BitvavoSettings(
+    api_key="your-key",
+    api_secret="your-secret",
+    prefer_keyless=True,
+    debugging=True
+)
+client = BitvavoClient(settings)
 
-# Multiple API keys (for rate limiting)
-# BITVAVO_APIKEYS='[{"key": "key1", "secret": "secret1"}, {"key": "key2", "secret": "secret2"}]'
+# Option 3: Manual settings override
+client = BitvavoClient(BitvavoSettings(default_rate_limit=750))
 
-# Keyless access (public endpoints only)
-BITVAVO_PREFER_KEYLESS=true
+# Access public endpoints (no auth needed)
+time_result = client.public.time()
+markets_result = client.public.markets()
 
-# Enhanced settings
-BITVAVO_API_UPGRADED_DEFAULT_RATE_LIMIT=750
-BITVAVO_API_UPGRADED_PREFER_KEYLESS=false
+# Access private endpoints (auth required)
+balance_result = client.private.balance()
+account_result = client.private.account()
 ```
 
-Then use the settings:
+#### Legacy Bitvavo Class (Backward Compatibility)
 
 ```python
 from bitvavo_api_upgraded import Bitvavo, BitvavoSettings
@@ -199,6 +282,68 @@ bitvavo = Bitvavo({
 bitvavo = Bitvavo({'PREFER_KEYLESS': True})
 ```
 
+## Data Format Flexibility
+
+The new BitvavoClient supports multiple output formats to match your workflow:
+
+### Model Preferences
+
+```python
+from bitvavo_client import BitvavoClient
+from bitvavo_client.core.model_preferences import ModelPreference
+
+# Option 1: Raw dictionaries (default, backward compatible)
+client = BitvavoClient(preferred_model=ModelPreference.RAW)
+result = client.public.time()  # Returns: {"time": 1609459200000}
+
+# Option 2: Validated Pydantic models
+client = BitvavoClient(preferred_model=ModelPreference.PYDANTIC)
+result = client.public.time()  # Returns: ServerTime(time=1609459200000)
+
+# Option 3: DataFrame format (pandas, polars, etc.)
+client = BitvavoClient(preferred_model=ModelPreference.DATAFRAME)
+result = client.public.markets()  # Returns: polars.DataFrame with market data
+```
+
+### Per-Request Format Override
+
+```python
+# Set a default preference but override per request
+client = BitvavoClient(preferred_model=ModelPreference.RAW)
+
+# Get raw dict (uses default)
+raw_data = client.public.markets()
+
+# Override to get DataFrame for this request
+import polars as pl
+df_data = client.public.markets(model=pl.DataFrame)
+
+# Override to get Pydantic model
+from bitvavo_client.core.public_models import Markets
+validated_data = client.public.markets(model=Markets)
+```
+
+### Result Types for Error Handling
+
+```python
+from returns.result import Success, Failure
+
+# Use result types for functional error handling
+result = client.public.time()
+
+if isinstance(result, Success):
+    print(f"Server time: {result.unwrap()}")
+elif isinstance(result, Failure):
+    print(f"Error: {result.failure()}")
+
+# Or use match-case (Python 3.10+)
+match result:
+    case Success(value):
+        print(f"Success: {value}")
+    case Failure(error):
+        print(f"Error: {error}")
+```
+
 ## WebSocket Usage
 
 ```python
@@ -288,9 +433,44 @@ balance = bitvavo.balance({})
 
 ## API Examples
 
-### Public Endpoints (No Authentication)
+### Public Endpoints (No Authentication Required)
+
+#### New BitvavoClient Interface
 
 ```python
+from bitvavo_client import BitvavoClient
+
+client = BitvavoClient()
+
+# Get server time
+time_result = client.public.time()
+
+# Get all markets
+markets_result = client.public.markets()
+
+# Get specific market
+btc_market = client.public.markets(market='BTC-EUR')
+
+# Get order book
+book_result = client.public.book('BTC-EUR')
+
+# Get recent trades
+trades_result = client.public.trades('BTC-EUR')
+
+# Get 24h ticker
+ticker_result = client.public.ticker_24h(market='BTC-EUR')
+
+# Get candlestick data
+candles_result = client.public.candles('BTC-EUR', '1h')
+```
+
+#### Legacy Bitvavo Interface
+
+```python
+from bitvavo_api_upgraded import Bitvavo
+
+bitvavo = Bitvavo({'PREFER_KEYLESS': True})  # For public endpoints
+
 # Get server time
 time_resp = bitvavo.time()
 
@@ -312,7 +492,50 @@ ticker = bitvavo.ticker24h({'market': 'BTC-EUR'})
 
 ### Private Endpoints (Authentication Required)
 
+#### New BitvavoClient Interface
+
+```python
+from bitvavo_client import BitvavoClient, BitvavoSettings
+
+# Configure with API credentials
+settings = BitvavoSettings(api_key="your-key", api_secret="your-secret")
+client = BitvavoClient(settings)
+
+# Get account info
+account_result = client.private.account()
+
+# Get balance
+balance_result = client.private.balance()
+
+# Place order
+order_result = client.private.place_order(
+    market="BTC-EUR",
+    side="buy",
+    order_type="limit",
+    amount="0.01",
+    price="45000"
+)
+
+# Get order history
+orders_result = client.private.orders('BTC-EUR')
+
+# Cancel order
+cancel_result = client.private.cancel_order(
+    market="BTC-EUR",
+    order_id="order-id-here"
+)
+
+# Get trades
+trades_result = client.private.trades('BTC-EUR')
+```
+
+#### Legacy Bitvavo Interface
+
 ```python
+from bitvavo_api_upgraded import Bitvavo
+
+bitvavo = Bitvavo({'APIKEY': 'your-key', 'APISECRET': 'your-secret'})
+
 # Get account info
 account = bitvavo.account()
 
@@ -524,15 +747,49 @@ uv run ruff format
 ### Project Structure
 
 ```text
-src/bitvavo_api_upgraded/   # Source code
-├── __init__.py             # Main exports
-├── bitvavo.py              # Core API class
-├── settings.py             # Pydantic settings
-├── helper_funcs.py         # Utility functions
-└── type_aliases.py         # Type definitions
-
-tests/                      # Comprehensive test suite
-docs/                       # Documentation
+src/
+├── bitvavo_api_upgraded/           # Legacy interface (backward compatibility)
+│   ├── __init__.py                 # Main exports
+│   ├── bitvavo.py                  # Original monolithic API class
+│   ├── settings.py                 # Pydantic settings
+│   ├── helper_funcs.py             # Utility functions
+│   └── type_aliases.py             # Type definitions
+└── bitvavo_client/                 # Modern modular interface
+    ├── __init__.py                 # New client exports
+    ├── facade.py                   # Main BitvavoClient class
+    ├── core/                       # Core functionality
+    │   ├── settings.py             # Settings management
+    │   ├── models.py               # Pydantic data models
+    │   ├── validation_helpers.py   # Enhanced error handling
+    │   └── types.py                # Type definitions
+    ├── endpoints/                  # API endpoint handlers
+    │   ├── public.py               # Public API endpoints
+    │   ├── private.py              # Private API endpoints
+    │   └── common.py               # Shared endpoint utilities
+    ├── transport/                  # HTTP transport layer
+    │   └── http.py                 # HTTP client with connection pooling
+    ├── auth/                       # Authentication & authorization
+    │   ├── signing.py              # Request signing
+    │   └── rate_limit.py           # Rate limiting management
+    ├── adapters/                   # External integrations
+    │   └── returns_adapter.py      # Result type adapters
+    ├── schemas/                    # DataFrame schemas
+    │   ├── public_schemas.py       # Public endpoint schemas
+    │   └── private_schemas.py      # Private endpoint schemas
+    └── df/                         # DataFrame conversion
+        └── convert.py              # Narwhals-based converters
+
+tests/                              # Comprehensive test suite
+├── bitvavo_api_upgraded/           # Legacy interface tests
+└── bitvavo_client/                 # Modern interface tests
+    ├── core/                       # Core functionality tests
+    ├── endpoints/                  # Endpoint tests
+    ├── transport/                  # Transport layer tests
+    ├── auth/                       # Authentication tests
+    ├── adapters/                   # Adapter tests
+    └── df/                         # DataFrame tests
+
+docs/                               # Documentation
 ```
 
 ### Semantic Versioning
@@ -547,47 +804,110 @@ This project follows [semantic versioning](https://semver.org/):
 
 This package includes a `py.typed` file to enable type checking. Reference: [Don't forget py.typed for your typed Python package](https://blog.whtsky.me/tech/2021/dont-forget-py.typed-for-your-typed-python-package/)
 
-## Migration from Official SDK
+## Migration & Architecture Options
+
+This package provides **two interfaces** to suit different use cases:
+
+### 1. Legacy Bitvavo Class (Backward Compatibility)
+
+For existing users migrating from the official SDK:
 
-### Key Differences
+```python
+from bitvavo_api_upgraded import Bitvavo
 
-- Import: `from bitvavo_api_upgraded import Bitvavo` (instead of `from python_bitvavo_api.bitvavo import Bitvavo`)
-- **Breaking Change**: Trading operations require `operatorId` parameter
-- **New**: Multiple API key support for better rate limiting
+# Drop-in replacement for python_bitvavo_api.bitvavo
+bitvavo = Bitvavo({'APIKEY': 'key', 'APISECRET': 'secret'})
+balance = bitvavo.balance({})
+```
+
+### 2. New BitvavoClient (Modern Architecture)
+
+For new projects or those wanting better architecture:
+
+```python
+from bitvavo_client import BitvavoClient, BitvavoSettings
+
+# Modern, typed, modular interface
+client = BitvavoClient()
+result = client.public.time()
+result = client.private.balance()
+```
+
+### Migration from Official SDK
+
+#### Key Changes
+
+- **Import**: `from bitvavo_api_upgraded import Bitvavo` (instead of `from python_bitvavo_api.bitvavo import Bitvavo`)
+- **Breaking**: Trading operations require `operatorId` parameter
+- **Enhanced**: Better error handling and type safety
+- **New**: Modern `BitvavoClient` interface available
+- **New**: Multiple API key support for rate limiting
 - **New**: Keyless access for public endpoints
 - **New**: Comprehensive dataframe support
-- Enhanced error handling and type safety
-- Better configuration management with `.env` support
+- **New**: Configuration via `.env` files
 
-### Migration Steps
+#### Migration Steps
 
-1. Update import statements
-2. Add `operatorId` to trading method calls
-3. Optional: Migrate to `.env` configuration
-4. Optional: Configure multiple API keys for better rate limits
-5. Optional: Enable keyless mode for public endpoint efficiency
-6. Enjoy improved type hints and error handling!
+1. **Update import statements**
 
-### Enhanced Features (Optional)
+   ```python
+   # Old
+   from python_bitvavo_api.bitvavo import Bitvavo
 
-```python
-# Traditional single key (works as before)
-bitvavo = Bitvavo({'APIKEY': 'key', 'APISECRET': 'secret'})
+   # New (legacy interface)
+   from bitvavo_api_upgraded import Bitvavo
 
-# New: Multiple keys for rate limiting
-bitvavo = Bitvavo({
-    'APIKEYS': [
-        {'key': 'key1', 'secret': 'secret1'},
-        {'key': 'key2', 'secret': 'secret2'}
-    ]
-})
+   # New (modern interface)
+   from bitvavo_client import BitvavoClient
+   ```
 
-# New: Keyless for public endpoints
-bitvavo = Bitvavo({'PREFER_KEYLESS': True})
+2. **Add operatorId to trading operations**
 
-# New: Dataframe support
-markets_df = bitvavo.markets({}, output_format='pandas')
-```
+   ```python
+   # Add operatorId parameter to placeOrder, cancelOrder, etc.
+   order = bitvavo.placeOrder("BTC-EUR", "buy", "limit", {...}, operatorId=12345)
+   ```
+
+3. **Optional: Migrate to modern interface**
+
+   ```python
+   # Legacy style
+   bitvavo = Bitvavo({'APIKEY': 'key', 'APISECRET': 'secret'})
+
+   # Modern style
+   client = BitvavoClient(BitvavoSettings(api_key='key', api_secret='secret'))
+   ```
+
+4. **Optional: Use new features**
+
+   ```python
+   # Multi-key support
+   bitvavo = Bitvavo({'APIKEYS': [{'key': 'k1', 'secret': 's1'}, {'key': 'k2', 'secret': 's2'}]})
+
+   # Keyless for public endpoints
+   bitvavo = Bitvavo({'PREFER_KEYLESS': True})
+
+   # DataFrame support
+   markets_df = bitvavo.markets({}, output_format='pandas')
+   ```
+
+### Choosing an Interface
+
+| Feature                    | Legacy `Bitvavo`       | Modern `BitvavoClient`     |
+| -------------------------- | ---------------------- | -------------------------- |
+| **Backward compatibility** | ✅ Drop-in replacement | ❌ New interface           |
+| **Type safety**            | ✅ Typed responses     | ✅ Full generics support   |
+| **Error handling**         | ✅ Enhanced errors     | ✅ Result types + enhanced |
+| **Modular design**         | ❌ Monolithic          | ✅ Separated concerns      |
+| **Testing**                | ✅ Testable            | ✅ Highly testable         |
+| **DataFrame support**      | ✅ Via output_format   | ✅ Via model preferences   |
+| **Result types**           | ❌ Exceptions only     | ✅ Success/Failure pattern |
+| **WebSocket support**      | ✅ Full support        | 🚧 Coming soon             |
+
+**Recommendation**:
+
+- Use **Legacy `Bitvavo`** for quick migrations and WebSocket usage
+- Use **Modern `BitvavoClient`** for new projects requiring clean architecture
 
 ---
 

bitvavo_api_upgraded-4.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+bitvavo_api_upgraded/__init__.py,sha256=J_HdGBmZOfb1eOydaxsPmXfOIZ58hVa1qAfE6QErUHs,301
+bitvavo_api_upgraded/bitvavo.py,sha256=_3FRVVPg7_1HrALyGPjcuokCsHF5oz6itN_GKx7yTMo,166155
+bitvavo_api_upgraded/dataframe_utils.py,sha256=UvcDM0HeE-thUvsm9EjCmddmGBzZ9Puu40UVa0fR_p8,5821
+bitvavo_api_upgraded/helper_funcs.py,sha256=4oBdQ1xB-C2XkQTmN-refzIzWfO-IUowDSWhOSFdCRU,3212
+bitvavo_api_upgraded/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+bitvavo_api_upgraded/settings.py,sha256=I1fogU6_kb1hOe_0YDzOgDhzKfnnYFoIR2OXbwtyD4E,5291
+bitvavo_api_upgraded/type_aliases.py,sha256=SbPBcuKWJZPZ8DSDK-Uycu5O-TUO6ejVaTt_7oyGyIU,1979
+bitvavo_api_upgraded-4.1.0.dist-info/WHEEL,sha256=Jb20R3Ili4n9P1fcwuLup21eQ5r9WXhs4_qy7VTrgPI,79
+bitvavo_api_upgraded-4.1.0.dist-info/METADATA,sha256=Go7SrHcYNBc3aZKxf09IBC8nudujCyN_Ze7tZST3mZI,35857
+bitvavo_api_upgraded-4.1.0.dist-info/RECORD,,

{bitvavo_api_upgraded-4.0.0.dist-info → bitvavo_api_upgraded-4.1.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: uv 0.8.13
+Generator: uv 0.8.15
 Root-Is-Purelib: true
 Tag: py3-none-any

bitvavo_api_upgraded-4.0.0.dist-info/RECORD

@@ -1,10 +0,0 @@
-bitvavo_api_upgraded/__init__.py,sha256=J_HdGBmZOfb1eOydaxsPmXfOIZ58hVa1qAfE6QErUHs,301
-bitvavo_api_upgraded/bitvavo.py,sha256=PHN4lPlA2wWB5e6LAOewQLGqN--x_N_BLg1A25z5TxA,164948
-bitvavo_api_upgraded/dataframe_utils.py,sha256=Jf-2zkYuK5Zs9kiMFJlCmO-OykjZyFIvW2aaMJYPUpo,5792
-bitvavo_api_upgraded/helper_funcs.py,sha256=4oBdQ1xB-C2XkQTmN-refzIzWfO-IUowDSWhOSFdCRU,3212
-bitvavo_api_upgraded/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-bitvavo_api_upgraded/settings.py,sha256=br1oqN3K8OoimmKa1JlvzMgpYNHfr2kK2f14tC72dl8,5311
-bitvavo_api_upgraded/type_aliases.py,sha256=EOd3LhruyM1aZYn4xyKYhdoSql8mZH88acN0qGzMMck,1992
-bitvavo_api_upgraded-4.0.0.dist-info/WHEEL,sha256=4n27za1eEkOnA7dNjN6C5-O2rUiw6iapszm14Uj-Qmk,79
-bitvavo_api_upgraded-4.0.0.dist-info/METADATA,sha256=v5Xi6jH4qRBhuZVS_TtNv23Jd6HnmRsXMXKZvV-_15s,25510
-bitvavo_api_upgraded-4.0.0.dist-info/RECORD,,