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

bitvavo_api_upgraded/bitvavo.py

@@ -653,7 +653,7 @@ class Bitvavo:
         postfix = createPostfix(options)
         return self.publicRequest(f"{self.base}/{market}/trades{postfix}", 5)  # type: ignore[return-value]
 
-    def candles(  # noqa: PLR0913
+    def candles(
         self,
         market: str,
         interval: str,
@@ -876,7 +876,95 @@ class Bitvavo:
         postfix = createPostfix(options)
         return self.publicRequest(f"{self.base}/ticker/24h{postfix}", rateLimitingWeight)  # type: ignore[return-value]
 
-    def placeOrder(self, market: str, side: str, orderType: str, body: anydict) -> anydict:
+    def reportTrades(self, market: str, options: strintdict | None = None) -> list[anydict] | errordict:
+        """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
+        }
+        ```
+
+        ---
+        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)
+        return self.publicRequest(f"{self.base}/report/{market}/trades{postfix}", 5)  # type: ignore[return-value]
+
+    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 +974,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 +994,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 +1007,7 @@ class Bitvavo:
         orderType="stopLoss"
         # or
         orderType="takeProfit"
+        operatorId=123
         body={
           "amount": "1.567",
           "amountQuote": "5000",
@@ -931,6 +1023,7 @@ class Bitvavo:
         orderType="stopLossLimit"
         # or
         orderType="takeProfitLimit"
+        operatorId=123
         body={
           "amount": "1.567",
           "price": "6000",
@@ -999,9 +1092,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 +1103,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 +1178,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 +1212,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:
@@ -1421,6 +1542,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
@@ -1460,6 +1610,53 @@ class Bitvavo:
         postfix = createPostfix(options)
         return self.privateRequest("/balance", postfix, {}, "GET", 5)  # type: ignore[return-value]
 
+    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("/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
 
@@ -2311,6 +2508,7 @@ class Bitvavo:
             market: str,
             side: str,
             orderType: str,
+            operatorId: int,
             body: anydict,
             callback: Callable[[Any], None],
         ) -> None:
@@ -2323,9 +2521,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 +2541,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 +2554,7 @@ class Bitvavo:
             orderType="stopLoss"
             # or
             orderType="takeProfit"
+            operatorId=123
             body={
               "amount": "1.567",
               "amountQuote": "5000",
@@ -2368,6 +2570,7 @@ class Bitvavo:
             orderType="stopLossLimit"
             # or
             orderType="takeProfitLimit"
+            operatorId=123
             body={
               "amount": "1.567",
               "price": "6000",
@@ -2438,6 +2641,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 +2649,7 @@ class Bitvavo:
             self,
             market: str,
             orderId: str,
+            operatorId: int,
             body: anydict,
             callback: Callable[[Any], None],
         ) -> None:
@@ -2457,11 +2662,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 +2739,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 +2776,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:

{bitvavo_api_upgraded-1.17.2.dist-info → bitvavo_api_upgraded-2.0.0.dist-info}/METADATA

@@ -1,15 +1,10 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.3
 Name: bitvavo-api-upgraded
-Version: 1.17.2
+Version: 2.0.0
 Summary: A unit-tested fork of the Bitvavo API
-Project-URL: homepage, https://github.com/Thaumatorium/bitvavo-api-upgraded
-Project-URL: repository, https://github.com/Thaumatorium/bitvavo-api-upgraded
-Project-URL: changelog, https://github.com/Thaumatorium/bitvavo-api-upgraded/blob/master/CHANGELOG.md
-Author: Bitvavo BV (original code)
+Author: Bitvavo BV (original code), NostraDavid
 Author-email: NostraDavid <55331731+NostraDavid@users.noreply.github.com>
-Maintainer-email: NostraDavid <55331731+NostraDavid@users.noreply.github.com>
 License: ISC License
-License-File: LICENSE.txt
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Environment :: Console
 Classifier: Framework :: Pytest
@@ -20,93 +15,323 @@ Classifier: License :: OSI Approved :: ISC License (ISCL)
 Classifier: Operating System :: MacOS :: MacOS X
 Classifier: Operating System :: Microsoft :: Windows
 Classifier: Operating System :: POSIX
-Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python
 Classifier: Typing :: Typed
-Requires-Python: >=3.9
 Requires-Dist: pydantic-settings==2.*,>=2.6
 Requires-Dist: requests==2.*,>=2.26
-Requires-Dist: structlog==25.*,>=21.5
+Requires-Dist: structlog>=21.5,==25.*
 Requires-Dist: websocket-client==1.*,>=1.2
+Maintainer: NostraDavid
+Maintainer-email: NostraDavid <55331731+NostraDavid@users.noreply.github.com>
+Requires-Python: >=3.9
+Project-URL: changelog, https://github.com/Thaumatorium/bitvavo-api-upgraded/blob/master/CHANGELOG.md
+Project-URL: homepage, https://github.com/Thaumatorium/bitvavo-api-upgraded
+Project-URL: repository, https://github.com/Thaumatorium/bitvavo-api-upgraded
 Description-Content-Type: text/markdown
 
 # Bitvavo API (upgraded)
 
-## Userguide
+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.
+
+## Quick Start
+
+```bash
+pip install bitvavo_api_upgraded
+```
+
+Scroll down for detailed usage examples and configuration instructions.
+
+## What Makes This "Upgraded"?
+
+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)
+- ⚡ **Better error handling** and rate limiting
+- 🔧 **Developer-friendly tooling** (ruff, mypy, pre-commit hooks)
+
+## Features
 
-`pip install bitvavo_api_upgraded`
+### Full API Coverage
 
-Works the same as the official API lib, but I have:
+- ✅ All REST endpoints (public and private)
+- ✅ WebSocket support with reconnection logic
+- ✅ Rate limiting with automatic throttling
+- ✅ MiCA compliance reporting endpoints
 
-- typing for _all_ functions and classes
-- unit tests (I already found three bugs that I fixed, because the original code
-  wasn't tested, at all)
-- a changelog, so you can track of the changes that I make
-- compatible with Python 3.7 and newer ([3.6 isn't supported as of
-  2021-12-23](https://endoflife.date/python))
+### Developer Experience
 
-## Devguide
+- ✅ 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
+- ✅ Connection retry logic
+- ✅ Proper error responses
+- ✅ Memory efficient WebSocket handling
+
+## Configuration
+
+Create a `.env` file in your project root:
+
+```env
+BITVAVO_APIKEY=your-api-key-here
+BITVAVO_APISECRET=your-api-secret-here
+```
+
+Then use the settings:
+
+```python
+from bitvavo_api_upgraded import Bitvavo, BitvavoSettings
+
+# Option 1: Manual configuration
+bitvavo = Bitvavo({
+    'APIKEY': 'your-key',
+    'APISECRET': 'your-secret'
+})
+
+# Option 2: Auto-load from .env
+settings = BitvavoSettings()
+bitvavo = Bitvavo(settings.model_dump())
+```
+
+## WebSocket Usage
+
+```python
+from bitvavo_api_upgraded import Bitvavo
+
+def handle_ticker(data):
+    print(f"Ticker update: {data}")
+
+def handle_error(error):
+    print(f"Error: {error}")
+
+# Initialize WebSocket
+bitvavo = Bitvavo({'APIKEY': 'key', 'APISECRET': 'secret'})
+ws = bitvavo.newWebsocket()
+ws.setErrorCallback(handle_error)
+
+# Subscribe to ticker updates
+ws.subscriptionTicker("BTC-EUR", handle_ticker)
+
+# Keep connection alive
+try:
+    while True:
+        time.sleep(1)
+except KeyboardInterrupt:
+    ws.closeSocket()
+```
+
+## API Examples
+
+### Public Endpoints (No Authentication)
+
+```python
+# Get server time
+time_resp = bitvavo.time()
+
+# Get all markets
+markets = bitvavo.markets({})
+
+# Get specific market
+btc_market = bitvavo.markets({'market': 'BTC-EUR'})
+
+# Get order book
+book = bitvavo.book('BTC-EUR', {})
+
+# Get recent trades
+trades = bitvavo.publicTrades('BTC-EUR', {})
+
+# Get 24h ticker
+ticker = bitvavo.ticker24h({'market': 'BTC-EUR'})
+```
+
+### Private Endpoints (Authentication Required)
+
+```python
+# Get account info
+account = bitvavo.account()
+
+# Get balance
+balance = bitvavo.balance({})
+
+# Place order (requires operatorId for MiCA compliance)
+order = bitvavo.placeOrder(
+    market="BTC-EUR",
+    side="buy",
+    orderType="limit",
+    body={"amount": "0.01", "price": "45000"},
+    operatorId=12345
+)
+
+# Get order history
+orders = bitvavo.getOrders('BTC-EUR', {})
+
+# Cancel order
+cancel_result = bitvavo.cancelOrder(
+    market="BTC-EUR",
+    orderId="order-id-here",
+    operatorId=12345
+)
+```
+
+### MiCA Compliance Features
+
+```python
+# Generate trade report
+trade_report = bitvavo.reportTrades(
+    market="BTC-EUR",
+    options={
+        "startDate": "2025-01-01T00:00:00.000Z",
+        "endDate": "2025-01-31T23:59:59.999Z"
+    }
+)
+
+# Generate order book report
+book_report = bitvavo.reportBook(
+    market="BTC-EUR",
+    options={
+        "startDate": "2025-01-01T00:00:00.000Z",
+        "endDate": "2025-01-31T23:59:59.999Z"
+    }
+)
+
+# Get account history
+history = bitvavo.accountHistory(options={})
+```
+
+## Error Handling
+
+```python
+from bitvavo_api_upgraded import Bitvavo
+
+bitvavo = Bitvavo({'APIKEY': 'key', 'APISECRET': 'secret'})
+
+response = bitvavo.placeOrder(
+    market="BTC-EUR",
+    side="buy",
+    orderType="limit",
+    body={"amount": "0.01", "price": "45000"},
+    operatorId=12345
+)
+
+# Check for errors
+if isinstance(response, dict) and 'errorCode' in response:
+    print(f"Error {response['errorCode']}: {response['error']}")
+else:
+    print(f"Order placed successfully: {response['orderId']}")
+```
+
+## Rate Limiting
+
+```python
+# Check remaining rate limit
+remaining = bitvavo.getRemainingLimit()
+print(f"Remaining API calls: {remaining}")
+
+# The library automatically handles rate limiting
+# But you can check limits before making calls
+if remaining > 10:
+    # Safe to make API calls
+    response = bitvavo.balance({})
+```
+
+## Development & Contributing
 
 ```shell
 echo "install development requirements"
 uv sync
 echo "run tox, a program that creates separate environments for different python versions, for testing purposes (among other things)"
 uv run tox
-```
-
-### Semantic Versioning (SemVer)
+## Development & Contributing
 
-I'm using semantic versioning, which means that changes mean this:
+### Setup Development Environment
 
-1. MAJOR version when you make incompatible API changes,
-1. MINOR version when you add functionality in a backwards compatible manner,
-   and
-1. PATCH version when you make backwards compatible bug fixes.
+```shell
+# Install uv (modern Python package manager)
+curl -LsSf https://astral.sh/uv/install.sh | sh
 
-### Versioning
+# Clone and setup
+git clone https://github.com/Thaumatorium/bitvavo-api-upgraded.git
+cd bitvavo-api-upgraded
 
-Copy the following block to CHANGELOG.md and add all information since last
-version bump
+# Install dependencies
+uv sync
 
-```markdown
-## $UNRELEASED
+# Run tests across Python versions
+uv run tox
 
-### Added
+# Run tests for current Python version
+uv run pytest
 
-...
+# Type checking
+uv run mypy src/
 
-### Changed
+# Linting and formatting
+uv run ruff check
+uv run ruff format
+```
 
-...
+### Project Structure
 
-### Removed
+```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
 ```
 
-Commit those changes.
+### Semantic Versioning
+
+This project follows [semantic versioning](https://semver.org/):
 
-After that, run `bump-my-version bump (major|minor|patch)` to automatically
-replace `$UNRELEASED` with the new version number, and also automatically tag
-and commit (with tag) to release a new version via the Github workflow.
+1. **MAJOR** version for incompatible API changes
+2. **MINOR** version for backwards-compatible functionality additions
+3. **PATCH** version for backwards-compatible bug fixes
 
-## py.typed
+## Type Annotations
 
-Perhaps a curious file, but it simply exists to let `mypy` know that the code is
-typed: [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/)
+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/)
 
-## Last note
+## Migration from Official SDK
 
-_below this line is the old README.md_
+### Key Differences
+
+- Import: `from bitvavo_api_upgraded import Bitvavo` (instead of `from python_bitvavo_api.bitvavo import Bitvavo`)
+- **Breaking Change**: Trading operations require `operatorId` parameter
+- Enhanced error handling and type safety
+- Better configuration management with `.env` support
+
+### Migration Steps
+
+1. Update import statements
+2. Add `operatorId` to trading method calls
+3. Optional: Migrate to `.env` configuration
+4. Enjoy improved type hints and error handling!
 
 ---
 
-# Bitvavo SDK for Python
+## Original Bitvavo SDK Documentation
+
+The following is preserved from the original Bitvavo SDK for reference.
 
 Crypto starts with Bitvavo. You use Bitvavo SDK for Python to buy, sell, and
 store over 200 digital assets on Bitvavo from inside your app.

bitvavo_api_upgraded-2.0.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+bitvavo_api_upgraded/__init__.py,sha256=0922b82678a737a9f1314aa84fe4bf565f5425ce0d3aac1f6db65ff909efa68e,222
+bitvavo_api_upgraded/bitvavo.py,sha256=e4d986ae3529b082d329f1da51027e7400f7a342faa023e037181dceb439d481,134183
+bitvavo_api_upgraded/helper_funcs.py,sha256=e2805d435c41f82d979104e637eade7f323359f3be214a300d25a139215d0915,3212
+bitvavo_api_upgraded/py.typed,sha256=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855,0
+bitvavo_api_upgraded/settings.py,sha256=647dac47d894c8e0bf9526aa993e74c04467814ba86efbbc7744cb8983799d38,2266
+bitvavo_api_upgraded/type_aliases.py,sha256=3409cc4a4e67e9268422f1c579230a9d73b17cec276c5b849d129a01795c998c,932
+bitvavo_api_upgraded-2.0.0.dist-info/WHEEL,sha256=2b400f346628f0064eb5bbf656b39df8dfcb092437ab08244409d295749b81a3,78
+bitvavo_api_upgraded-2.0.0.dist-info/METADATA,sha256=e7e9d2261c0af757cfe323dc911012b2f834a030848684ac6d18585911eb6691,17102
+bitvavo_api_upgraded-2.0.0.dist-info/RECORD,,

bitvavo_api_upgraded-2.0.0.dist-info/WHEEL

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

bitvavo_api_upgraded-1.17.2.dist-info/RECORD

@@ -1,10 +0,0 @@
-bitvavo_api_upgraded/__init__.py,sha256=CSK4JninN6nxMUqoT-S_Vl9UJc4NOqwfbbZf-Qnvpo4,222
-bitvavo_api_upgraded/bitvavo.py,sha256=s7l-cAl0FteBrm5iF-gnM_U9_-Yds9lpn5pN6f0oaZU,125981
-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=ZH2sR9iUyOC_lSaqmT50wERngUuobvu8d0TLiYN5nTg,2266
-bitvavo_api_upgraded/type_aliases.py,sha256=NAnMSk5n6SaEIvHFeSMKnXOxfOwnbFuEnRKaAXlcmYw,932
-bitvavo_api_upgraded-1.17.2.dist-info/METADATA,sha256=U_5w2WGTB4xykCwIgh3KtcfsVzsYDS3NZWlHwVRz1Tk,11547
-bitvavo_api_upgraded-1.17.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-bitvavo_api_upgraded-1.17.2.dist-info/licenses/LICENSE.txt,sha256=hiFyor_njVlzVblnb-78mzx1Um3CGvuFxEH3YR735rc,744
-bitvavo_api_upgraded-1.17.2.dist-info/RECORD,,

bitvavo_api_upgraded-1.17.2.dist-info/WHEEL

@@ -1,4 +0,0 @@
-Wheel-Version: 1.0
-Generator: hatchling 1.27.0
-Root-Is-Purelib: true
-Tag: py3-none-any

bitvavo_api_upgraded-1.17.2.dist-info/licenses/LICENSE.txt

@@ -1,15 +0,0 @@
-ISC License
-
-Copyright (c) 2024, Bitvavo B.V.
-
-Permission to use, copy, modify, and/or distribute this software for any
-purpose with or without fee is hereby granted, provided that the above
-copyright notice and this permission notice appear in all copies.
-
-THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
-WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
-MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
-ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
-WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
-ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
-OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.