python-kraken-sdk
Command-line tool, MCP server, and SDK to access the Kraken Crypto Asset Exchange API (Spot, xStocks, and Futures, REST and Websocket API)
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/btschwertfeger--python-kraken-sdk)HTML
<a href="/listings/btschwertfeger--python-kraken-sdk"><img src="/api/listings/btschwertfeger--python-kraken-sdk/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
1. Install the package into the desired environment
python3 -m pip install python-kraken-sdk
2. Register at [Kraken](https://www.kraken.com) and generate API keys
- Spot Trading: https://www.kraken.com/u/security/api - Futures Trading: https://futures.kraken.com/trade/settings/api (see _[help](https://docs.futures.kraken.com/#introduction-generate-api-keys)_) - Futures Sandbox: https://demo-futures.kraken.com/settings/api
3. Start using the provided example scripts
4. Error handling
If any unexpected behavior occurs, please check <b style="color: yellow">your API permissions</b>, <b style="color: yellow">rate limits</b>, update the python-kraken-sdk, see the [Troubleshooting](#trouble) section, and if the error persists please open an issue.
<a name="cliusage"></a>
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 622 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- <h1 align="center">Spot, xStocks, and Futures REST and Websocket API Python SDK for the Kraken Crypto Asset Exchange 🐙</h1>
- <div align="center">
- [](https://github.com/btschwertfeger/python-kraken-sdk)
- [](https://opensource.org/licenses/Apache-2.0)
- [](https://shields.io/)
- [](https://pepy.tech/project/python-kraken-sdk)
- [](https://github.com/astral-sh/ruff)
- [](https://mypy-lang.org/)
- [](https://github.com/btschwertfeger/python-kraken-sdk/actions/workflows/cicd.yaml)
- [](https://app.codecov.io/gh/btschwertfeger/python-kraken-sdk)
- [](https://securityscorecards.dev/viewer/?uri=github.com/btschwertfeger/python-kraken-sdk)
- [](https://www.bestpractices.dev/projects/8673)
- [](https://github.com/btschwertfeger/python-kraken-sdk/releases)
- [](https://pypi.org/project/python-kraken-sdk/)
- [](https://zenodo.org/badge/latestdoi/510751854)
- [](https://python-kraken-sdk.readthedocs.io/en/stable)
- </div>
- > ⚠️ This is an unofficial collection of REST and websocket clients for Spot and
- > Futures trading on the Kraken Crypto Asset Exchange using Python. Payward
- > Ltd. and Kraken are in no way associated with the authors of this package and
- > documentation.
- >
- > Please note that this project is independent and not endorsed by Kraken or
- > Payward Ltd. Users should be aware that they are using third-party software,
- > and the authors of this project are not responsible for any issues, losses, or
- > risks associated with its usage.
- ## 📌 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.
- This software probably has some errors in it, so use it at your own risk. Also
- no one should be motivated or tempted to invest assets in speculative forms of
- investment. By using this software you release the author(s) from any liability
- regarding the use of this software.
- ---
- ## Features
- General:
- - Command-line interface
- - Access both public and private, REST and websocket endpoints
- - Responsive error handling and custom exceptions
- - Extensive example scripts (see `/examples` and `/tests`)
- - Tested using the [pytest](https://docs.pytest.org/en/7.3.x/) framework
- - Releases are permanently archived at [Zenodo](https://zenodo.org/badge/latestdoi/510751854)
- Available Clients:
- - 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:
- - [https://python-kraken-sdk.readthedocs.io/en/stable](https://python-kraken-sdk.readthedocs.io/en/stable)
- - [https://python-kraken-sdk.readthedocs.io/en/latest](https://python-kraken-sdk.readthedocs.io/en/latest)
- 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
- ---
- ## ❗️ Attention
- **ONLY** tagged releases are available at PyPI. So the content of the master may
- not match with the content of the latest release. - Please have a look at the
- release specific READMEs and changelogs.
- It is also recommended to _pin the used version_ to avoid unexpected behavior on
- new releases.
- ---
- ## Table of Contents
- - [ Installation and setup ](#installation)
- - [ Command-line interface ](#cliusage)
- - [ MCP Server ](#mcpusage)
- - [ Spot Clients ](#spotusage)
- - [ xStocks ](#xstocksusage)
- - [ Futures Clients ](#futuresusage)
- - [ Troubleshooting ](#trouble)
- - [ Contributions ](#contribution)
- - [ Notes ](#notes)
- - [ Considerations ](#considerations)
- - [ References ](#references)
- <a name="installation"></a>
- # 🛠 Installation and setup
- ### 1. Install the package into the desired environment
- ```bash
- python3 -m pip install python-kraken-sdk
- ```
- ### 2. Register at [Kraken](https://www.kraken.com) and generate API keys
- - Spot Trading: https://www.kraken.com/u/security/api
- - Futures Trading: https://futures.kraken.com/trade/settings/api (see _[help](https://docs.futures.kraken.com/#introduction-generate-api-keys)_)
- - Futures Sandbox: https://demo-futures.kraken.com/settings/api
- ### 3. Start using the provided example scripts
- ### 4. Error handling
- If any unexpected behavior occurs, please check <b style="color: yellow">your
- API permissions</b>, <b style="color: yellow">rate limits</b>, update the
- python-kraken-sdk, see the [Troubleshooting](#trouble) section, and if the error
- persists please open an issue.
- <a name="cliusage"></a>
- # 📍 Command-line interface
- The python-kraken-sdk provides a command-line interface to access the Kraken API
- using basic instructions while performing authentication tasks in the
- background. The Spot and Futures API are accessible and follow the pattern
- `kraken {spot,futures} [OPTIONS] URL`. See examples below.
- ```bash
- # get server time
- kraken spot https://api.kraken.com/0/public/Time
- {'unixtime': 1716707589, 'rfc1123': 'Sun, 26 May 24 07:13:09 +0000'}
- # get user's balances
- kraken spot --api-key=<api-key> --secret-key=<secret-key> -X POST https://api.kraken.com/0/private/Balance
- {'ATOM': '17.28229999', 'BCH': '0.0000077100', 'ZUSD': '1000.0000'}
- # get user's trade balances
- kraken spot --api-key=<api-key> --secret-key=<secret-key> -X POST https://api.kraken.com/0/private/TradeBalance --data '{"asset": "DOT"}'
- {'eb': '2.8987347115', 'tb': '1.1694303513', 'm': '0.0000000000', 'uv': '0', 'n': '0.0000000000', 'c': '0.0000000000', 'v': '0.0000000000', 'e': '1.1694303513', 'mf': '1.1694303513'}
- # get 1D candles for a futures instrument
- kraken futures https://futures.kraken.com/api/charts/v1/spot/PF_XBTUSD/1d
- {'candles': [{'time': 1625616000000, 'open': '34557.84000000000', 'high': '34803.20000000000', 'low': '33816.32000000000', 'close': '33880.22000000000', 'volume': '0' ...
- # get user's open futures positions
- kraken futures --api-key=<api-key> --secret-key=<secret-key> https://futures.kraken.com/derivatives/api/v3/openpositions
- {'result': 'success', 'openPositions': [], 'serverTime': '2024-05-26T07:15:38.91Z'}
- ```
- ... All endpoints of the Kraken Spot and Futurs API can be accessed like that.
- <a name="mcpusage"></a>
- # 📍 MCP Server
- The python-kraken-sdk also ships an MCP server exposing the Spot (incl.
- xStocks — pass `"asset_class": "tokenized_asset"` inside `params` where the
- Kraken API docs require it) and Futures `request` methods as two tools,
- `spot_request` and `futures_request`.
- ```bash
- uv tool install "python-kraken-sdk[mcp]"
- # e.g. Claude setup:
- claude mcp add kraken --scope user -- kraken-mcp
- ```
- Credentials are never tool arguments. Configure them as environment
- variables instead: `KRAKEN_SPOT_API_KEY` / `KRAKEN_SPOT_SECRET_KEY`,
- `KRAKEN_FUTURES_API_KEY` / `KRAKEN_FUTURES_SECRET_KEY`, and optionally
- `KRAKEN_FUTURES_SANDBOX=1` to target the Futures demo environment. Example
- client for Claude Code configuration:
- ```json
- // ~/.claude.json
- {
- "mcpServers": {
- "kraken": {
- "command": "kraken-mcp",
- "env": {
- // Only public endpoints are available without credentials
- "KRAKEN_SPOT_API_KEY": "<your-api-key>",
- "KRAKEN_SPOT_SECRET_KEY": "<your-secret-key>"
- }
- }
- }
- }
- ```
- <a name="spotusage"></a>
- # 📍 Spot Clients
- The python-kraken-sdk provides lots of functions to easily access most of the
- REST and websocket endpoints of the Kraken Crypto Asset Exchange API. Since
- these endpoints and their parameters may change, all implemented endpoints are
- tested on a regular basis.
- The Kraken Spot API can be accessed by executing requests to the endpoints
- directly using the `request` method provided by any client. This is demonstrated
- below.
- See https://docs.kraken.com/api/docs/guides/global-intro for information about
- the available endpoints and their usage.
- ### `SpotClient`
- The Spot client provides access to all un-and authenticated endpoints of
- Kraken's Spot API.
- ```python
- from kraken.spot import SpotClient
- client = SpotClient(key="<your-api-key>", secret="<your-secret-key>")
- print(client.request("POST", "/0/private/Balance"))
- ```
- ### `SpotAsyncClient`
- The async Spot client allows for asynchronous access to Kraken's Spot API
- endpoints. Below are two examples demonstrating its usage.
- Using SpotAsyncClient without a context manager; In this example, the client is
- manually closed after the request is made.
- ```python
- import asyncio
- from kraken.spot import SpotAsyncClient
- async def main():
- client = SpotAsyncClient(key="<your-api-key>", secret="<your-secret-key>")
- try:
- response = await client.request("POST", "/0/private/Balance")
- print(response)
- finally:
- await client.close()
- if __name__ == "__main__":
- asyncio.run(main())
- ```
- Using SpotAsyncClient as a context manager; This example demonstrates the use of
- the context manager, which ensures the client is automatically closed after the
- request is completed.
- ```python
- import asyncio
- from kraken.spot import SpotAsyncClient
- async def main():
- async with SpotAsyncClient(key="<your-api-key>", secret="<your-secret-key>") as client:
- response = await client.request("POST", "/0/private/Balance")
- print(response)
- if __name__ == "__main__":
- asyncio.run(main())
- ```
- <a name="spotws"></a>
- ### `SpotWSClient` (Websocket API)
- Kraken offers two versions of their websocket API (V1 and V2). Since V2 is
- offers more possibilities, is way faster and easier to use, only the never
- version is supported by this SDK.
- The official documentation for can be found at:
- - https://docs.kraken.com/api/docs/guides/global-intro
- - https://docs.kraken.com/websockets-v2
- Note that authenticated Spot websocket clients can also un-/subscribe from/to
- public feeds.
- The example below can be found in an extended way in
- `examples/spot_ws_examples.py`.
- ```python
- import asyncio
- from kraken.spot import SpotWSClient
- class Client(SpotWSClient):
- """Can be used to create a custom trading strategy"""
- async def on_message(self, message):
- """Receives the websocket messages"""
- if message.get("method") == "pong" \
- or message.get("channel") == "heartbeat":
- return
- print(message)
- # Here we can access lots of methods, for example to create an order:
- # if self.is_auth: # only if the client is authenticated …
- # await self.send_message(
- # message={
- # "method": "add_order",
- # "params": {
- # "limit_price": 1234.56,
- # "order_type": "limit",
- # "order_userref": 123456789,
- # "order_qty": 1.0,
- # "side": "buy",
- # "symbol": "BTC/USD",
- # "validate": True,
- # },
- # }
- # )
- # … it is also possible to call regular REST endpoints
- # but using the websocket messages is more efficient.
- # You can also un-/subscribe here using self.subscribe/self.unsubscribe.
- async def main():
- try:
- # Public/unauthenticated websocket client
- client = Client() # only use this one if you don't need private feeds
- await client.start()
- await client.subscribe(
- params={"channel": "ticker", "symbol": ["BTC/USD", "DOT/USD"]}
- )
- await client.subscribe(
- params={"channel": "book", "depth": 25, "symbol": ["BTC/USD"]}
- )
- # wait because unsubscribing is faster than unsubscribing … (just for that example)
- await asyncio.sleep(3)
- # print(client.active_public_subscriptions) # to list active subscriptions
- await client.unsubscribe(
- params={"channel": "ticker", "symbol": ["BTC/USD", "DOT/USD"]}
- )
- # …
- # AS default, the authenticated client starts two websocket connections,
- # one for authenticated and one for public messages. If there is no need
- # for a public connection, it can be disabled using the ``no_public``
- # parameter.
- client_auth = Client(key="api-key", secret="secret-key", no_public=True)
- await client_auth.start()
- await client_auth.subscribe(params={"channel": "balances"})
- while not client.exception_occur and not client_auth.exception_occur:
- await asyncio.sleep(6)
- finally:
- await client.close()
- await client_auth.close()
- 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
- The Kraken Spot API can be accessed by executing requests to the endpoints
- directly using the `request` method provided by any client. This is demonstrated
- below.
- See https://docs.kraken.com/api/docs/guides/global-intro for information about
- the available endpoints and their usage.
- ### `FuturesClient`
- The simple Futures client provides access to all un-and authenticated endpoints.
- ```python
- from kraken.futures import FuturesClient
- client = FuturesClient(key="<your-api-key>", secret="<your-secret-key>")
- print(client.request("GET", "/derivatives/api/v3/accounts"))
- ```
- ### `FuturesAsyncClient`
- The async Futures client allows for asynchronous access to Kraken's Futures
- endpoints. Below are two examples demonstrating its usage.
- Using FuturesAsyncClient without a context manager; In this example, the client
- is manually closed after the request is made.
- ```python
- import asyncio
- from kraken.futures import FuturesAsyncClient
- async def main():
- client = FuturesAsyncClient(key="<your-api-key>", secret="<your-secret-key>")
- try:
- response = await client.request("GET", "/derivatives/api/v3/accounts")
- print(response)
- finally:
- await client.close()
- if __name__ == "__main__":
- asyncio.run(main())
- ```
- Using FuturesAsyncClient as context manager; This example demonstrates the use
- of the context manager, which ensures the client is automatically closed after
- the request is completed.
- ```python
- import asyncio
- from kraken.futures import FuturesAsyncClient
- async def main():
- async with FuturesAsyncClient(key="<your-api-key>", secret="<your-secret-key>") as client:
- response = await client.request("GET", "/derivatives/api/v3/accounts")
- print(response)
- if __name__ == "__main__":
- asyncio.run(main())
- ```
- <a name="futuresws"></a>
- ### `FuturesWSClient` (Websocket API)
- Not only REST, also the websocket API for Kraken Futures is available. Examples
- are shown below and demonstrated in `examples/futures_ws_examples.py`.
- - https://docs.futures.kraken.com/#websocket-api
- Note: Authenticated Futures websocket clients can also un-/subscribe from/to
- public feeds.
- ```python
- import asyncio
- from kraken.futures import FuturesWSClient
- class Client(FuturesWSClient):
- async def on_message(self, event):
- print(event)
- async def main():
- try:
- # Public/unauthenticated websocket connection
- client = Client()
- await client.start()
- products = ["PF_XBTUSD", "PF_ETHUSD"]
- # subscribe to a public websocket feed
- await client.subscribe(feed="ticker", products=products)
- # await client.subscribe(feed="book", products=products)
- # …
- # unsubscribe from a public websocket feed
- # await client.unsubscribe(feed="ticker", products=products)
- # Private/authenticated websocket connection (+public)
- client_auth = Client(key="key-key", secret="secret-key")
- await client_auth.start()
- # print(client_auth.get_available_private_subscription_feeds())
- # subscribe to a private/authenticated websocket feed
- await client_auth.subscribe(feed="fills")
- await client_auth.subscribe(feed="open_positions")
- await client_auth.subscribe(feed="open_orders")
- # …
- # unsubscribe from a private/authenticated websocket feed
- await client_auth.unsubscribe(feed="fills")
- while not client.exception_occur and not client_auth.exception_occur:
- await asyncio.sleep(6)
- finally:
- await client.close()
- await client_auth.close()
- if __name__ == "__main__":
- asyncio.run(main())
- ```
- ---
- <a name="contribution"></a>
- # 🆕 Contributions
- … are welcome - but:
- - First check if there is an existing issue or PR that addresses your
- problem/solution. If not - create one first - before creating a PR.
- - Typo fixes, project configuration, CI, documentation or style/formatting PRs
- will be rejected. Please create an issue for that.
- - PRs must provide a reasonable, easy to understand and maintain solution for an
- existing problem. You may want to propose a solution when creating the issue
- to discuss the approach before creating a PR.
- - Please have a look at [CONTRIBUTION.md](./CONTRIBUTING.md).
- ---
- <a name="trouble"></a>
- # 🚨 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
- respective endpoints.
- - If you get some Cloudflare or **rate limit errors**, please check your Kraken
- Tier level and maybe apply for a higher rank if required.
- - **Use different API keys for different algorithms**, because the nonce
- calculation is based on timestamps and a sent nonce must always be the highest
- nonce ever sent of that API key. Having multiple algorithms using the same
- 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.
- ---
- <a name="notes"></a>
- # 📝 Notes
- The versioning scheme follows the pattern `v<Major>.<Minor>.<Patch>`. Here's
- what each part signifies:
- - **Major**: This denotes significant changes that may introduce new features or
- modify existing ones. It's possible for these changes to be breaking, meaning
- backward compatibility is not guaranteed. To avoid unexpected behavior, it's
- advisable to specify at least the major version when pinning dependencies.
- - **Minor**: This level indicates additions of new features or extensions to
- existing ones. Typically, these changes do not break existing implementations.
- - **Patch**: Here, you'll find bug fixes, documentation updates, and changes
- related to continuous integration (CI). These updates are intended to enhance
- stability and reliability without altering existing functionality.
- Coding standards are not always followed to make arguments and function names as
- similar as possible to those of the Kraken API documentations.
- <a name="considerations"></a>
- # Considerations
- The tool aims to be fast, easy to use and maintain. In the past, lots of clients
- were implemented, that provided functions for almost all available endpoints of
- the Kraken API. The effort to maintain this collection grew to a level where it
- was not possible to check various changelogs to apply new updates on a regular
- basis. Instead, it was decided to concentrate on the `request` functions of
- the `SpotClient`, `SpotAsyncClient`, `FuturesClient` and the
- `FuturesAsyncClient` (as well as their websocket client implementations). All
- those clients named "User", "Trade", "Market", "Funding" and so on will no
- longer be extended, but maintained to a certain degree. The client's `request`
- method takes the raw method, URI, and parameters directly, so every endpoint
- and parameter documented by Kraken's API is already reachable without a named
- wrapper method. Existing wrapper methods still receive bug fixes. Websocket
- clients keep gaining new channels and features, since those cannot be reached
- through a plain `request` call.
- <a name="references"></a>
- # 🔭 References
- - https://python-kraken-sdk.readthedocs.io/en/stable
- - https://docs.kraken.com/api/
- - https://docs.kraken.com/api/docs/guides/global-intro
- - https://support.kraken.com/hc/en-us/sections/360012894412-Futures-API
- ---
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.