Resolve "Stock trade compatibility" (#399)

Author: btschwertfeger

.github/workflows/_codecov.yaml

@@ -25,6 +25,10 @@ on:
         required: true
       SPOT_SECRET_KEY:
         required: true
+      XSTOCKS_API_KEY:
+        required: true
+      XSTOCKS_SECRET_KEY:
+        required: true
       FUTURES_API_KEY:
         required: true
       FUTURES_SECRET_KEY:
@@ -81,6 +85,8 @@ jobs:
         env:
           SPOT_API_KEY: ${{ secrets.SPOT_API_KEY }}
           SPOT_SECRET_KEY: ${{ secrets.SPOT_SECRET_KEY }}
+          XSTOCKS_API_KEY: ${{ secrets.XSTOCKS_API_KEY }}
+          XSTOCKS_SECRET_KEY: ${{ secrets.XSTOCKS_SECRET_KEY }}
           FUTURES_API_KEY: ${{ secrets.FUTURES_API_KEY }}
           FUTURES_SECRET_KEY: ${{ secrets.FUTURES_SECRET_KEY }}
           FUTURES_SANDBOX_KEY: ${{ secrets.FUTURES_SANDBOX_KEY }}

.github/workflows/_test_spot_private.yaml

@@ -27,6 +27,10 @@ on:
         required: true
       SPOT_SECRET_KEY:
         required: true
+      XSTOCKS_API_KEY:
+        required: true
+      XSTOCKS_SECRET_KEY:
+        required: true
 
 permissions:
   contents: read
@@ -94,6 +98,8 @@ jobs:
         env:
           SPOT_API_KEY: ${{ secrets.SPOT_API_KEY }}
           SPOT_SECRET_KEY: ${{ secrets.SPOT_SECRET_KEY }}
+          XSTOCKS_API_KEY: ${{ secrets.XSTOCKS_API_KEY }}
+          XSTOCKS_SECRET_KEY: ${{ secrets.XSTOCKS_SECRET_KEY }}
         run: pytest -vv -m "spot and spot_auth and not spot_websocket" tests
 
       - name: Testing Spot websocket client

.github/workflows/cicd.yaml

@@ -17,6 +17,9 @@
 #             for Spot:
 #               * SPOT_API_KEY
 #               * SPOT_SECRET_KEY
+#             for xStocks (Kraken UAT):
+#               * XSTOCKS_API_KEY
+#               * XSTOCKS_SECRET_KEY
 #             ... see the README for information about how to generate
 #             Spot API keys. Please also make sure to enable the
 #             following API permissions:

Makefile

@@ -10,7 +10,7 @@ UV ?= uv
 PYTHON := python
 PYTEST := $(UV) run pytest
 PYTEST_OPTS := -vv --junit-xml=pytest.xml
-PYTEST_COV_OPTS := $(PYTEST_OPTS) --cov=kraken --cov-report=xml:coverage.xml --cov-report=term
+PYTEST_COV_OPTS := $(PYTEST_OPTS) --cov=kraken --cov-report=xml:coverage.xml --cov-report=term-missing
 TEST_DIR := tests
 
 ## ======= M A K E F I L E - T A R G E T S =====================================

README.md

@@ -1,4 +1,4 @@
-<h1 align="center">Futures and Spot REST and Websocket API Python SDK for the Kraken Crypto Asset Exchange 🐙</h1>
+<h1 align="center">Spot, xStocks, and Futures REST and Websocket API Python SDK for the Kraken Crypto Asset Exchange 🐙</h1>
 
 <div align="center">
 
@@ -56,10 +56,10 @@ General:
 
 Available Clients:
 
-- Spot REST Clients (sync and async)
-- Spot Websocket Client (using Websocket API v2)
-- Spot Orderbook Client (using Websocket API v2)
-- Futures REST Clients (sync and async)
+- Spot REST Clients - including xStocks capability
+- Spot Websocket Client (Websocket API v2)
+- Spot Orderbook Client (Websocket API v2)
+- Futures REST Clients
 - Futures Websocket Client
 
 Documentation:
@@ -91,6 +91,7 @@ new releases.
 - [ Installation and setup ](#installation)
 - [ Command-line interface ](#cliusage)
 - [ Spot Clients ](#spotusage)
+- [ xStocks ](#xstocksusage)
 - [ Futures Clients ](#futuresusage)
 - [ Troubleshooting ](#trouble)
 - [ Contributions ](#contribution)
@@ -315,6 +316,57 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
+<a name="xstocksusage"></a>
+
+# 📍 xStocks
+
+Kraken recently added support for trading of tokenized stocks (xStocks) on their
+platform. The python-kraken-sdk fully supports this new feature, allowing users
+to trade xStocks seamlessly alongside other crypto assets.
+
+For accessing xStocks, you can use the same `SpotClient` and `SpotAsyncClient`
+classes that are used for regular spot trading. The endpoints and methods for
+xStocks are integrated into these clients, making it easy to manage your xStock
+trades.
+
+It is important to note that the xStocks feature is not available globally. Please
+check Kraken's documentation to understand the availability zones and ensure
+that you can trade xStocks from your location.
+
+For trading or filtering for xStocks assets, the new asset class
+`tokenized_asset` must be used, e.g. when creating an order:
+
+```python
+   from kraken.spot import SpotClient, Trade
+
+   # Option 1: Create an order using the SpotClient directly:
+   client = SpotClient(key="api-public-key", secret="api-secret-key")
+   client.request(
+       method="POST",
+       uri="/0/private/AddOrder",
+       params={
+           "type": "buy",
+           "volume": "1",
+           "ordertype": "limit",
+           "pair": "AAPLxUSD",
+           "price": "100.0",
+           "validate": True,
+           "asset_class": "tokenized_asset", # <- important!
+       },
+   )
+   # Option 2: Create an order using the Trade client:
+   trade = Trade(key="api-public-key", secret="api-secret-key")
+   trade.create_order(
+       pair="AAPLxUSD",
+       side="buy",
+       ordertype="limit",
+       volume="1",
+       price="100.0",
+       validate=True,
+       extra_params={"asset_class": "tokenized_asset"}, # <- important!
+   )
+```
+
 <a name="futuresusage"></a>
 
 # 📍 Futures Clients
@@ -475,6 +527,8 @@ if __name__ == "__main__":
   keys will result in invalid nonce errors.
 - Always keep an eye on https://status.kraken.com/ when encountering
   connectivity problems.
+- The xStocks feature is not available globally. Please checkout Kraken's
+  documentation to get to know the availability zones.
 
 ---
 

doc/introduction.rst doc/01_introduction.rstdoc/introduction.rst renamed to doc/01_introduction.rst

@@ -51,12 +51,12 @@ and documented.
   accessed, provided that either the base class or one of the clients has been
   initialized with valid credentials.
 - For Futures there is the websocket client
-  :class:`kraken.futures.FuturesWSClient` and for Spot
+  :class:`kraken.futures.FuturesWSClient` and for Spot and xStocks
   :class:`kraken.spot.SpotWSClient`.
 
 
-Disclaimer
-----------
+⚠️ Disclaimer
+-------------
 
 There is no guarantee that this software will work flawlessly at this or later
 times. Of course, no responsibility is taken for possible profits or losses.
@@ -66,8 +66,8 @@ investment. By using this software you release the author(s) from any liability
 regarding the use of this software.
 
 
-Features
---------
+🚀 Features
+-----------
 
 General:
 
@@ -80,14 +80,20 @@ General:
 
 Available Clients:
 
-- Spot REST Clients (sync and async)
+- Spot REST Clients - including xStocks capability
 - Spot Websocket Client (Websocket API v2)
 - Spot Orderbook Client (Websocket API v2)
-- Futures REST Clients (sync and async)
+- Futures REST Clients
 - Futures Websocket Client
 
-Important Notice
------------------
+Projects using this SDK:
+
+- https://github.com/btschwertfeger/infinity-grid
+- https://github.com/btschwertfeger/kraken-rebalance-bot
+- https://github.com/btschwertfeger/python-kraken-sdk/network/dependents
+
+📌 Important Notice
+-------------------
 
 **ONLY tagged releases are available at PyPI**. The content of the master branch
 may not match with the content of the latest release. - Please have a look at
@@ -99,8 +105,9 @@ on new releases.
 
 .. _section-troubleshooting:
 
-Troubleshooting
----------------
+💡 Troubleshooting
+------------------
+
 - Check if you downloaded and installed the **latest version** of the
   python-kraken-sdk.
 - Check the **permissions of your API keys** and the required permissions on the
@@ -114,9 +121,11 @@ Troubleshooting
 - Always keep an eye on https://status.kraken.com/ when encountering
   connectivity problems.
 - Feel free to open an issue at `python-kraken-sdk/issues`_.
+- The xStocks feature is not available globally. Please checkout Kraken's
+  documentation to get to know the availability zones.
 
-References
-----------
+📜 References
+-------------
 
 - https://python-kraken-sdk.readthedocs.io/en/stable
 - https://docs.kraken.com/api/

doc/getting_started/getting_started.rst …c/02_getting_started/getting_started.rstdoc/getting_started/getting_started.rst renamed to doc/02_getting_started/getting_started.rst doc/getting_started/getting_started.rst renamed to doc/02_getting_started/getting_started.rst

@@ -38,8 +38,9 @@ Projects that use the SDK are listed below:
 .. toctree::
     :maxdepth: 2
 
-    rest_ws_samples/spot_rest_examples.rst
-    rest_ws_samples/spot_ws_examples.rst
+    rest_examples/spot_rest_examples.rst
+    rest_examples/spot_ws_examples.rst
+    rest_examples/xstocks_rest_examples.rst
     market_client_example.ipynb
-    rest_ws_samples/futures_ws_examples.rst
-    rest_ws_samples/futures_rest_examples.rst
+    rest_examples/futures_ws_examples.rst
+    rest_examples/futures_rest_examples.rst