kraken-py-sdk 0.1.0__tar.gz

kraken_py_sdk-0.1.0/.env.example

@@ -0,0 +1,6 @@
+PUBLIC_KEY=
+PRIVATE_KEY=
+
+ORDER_PAIR=
+ORDER_VOLUME=
+ORDER_PRICE=

kraken_py_sdk-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+py.typed
+
+# Virtual environments
+.venv
+
+# IDE files
+.idea/
+
+# Environment variables
+.env
+*.env
+
+# testing
+.coverage
+
+.pi/
+.pi-lens/

kraken_py_sdk-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

kraken_py_sdk-0.1.0/AGENTS.md

@@ -0,0 +1,101 @@
+# Instructions For Coding Agents
+
+**Note:** This is a living document. If patterns emerge that should be codified here, suggest additions.
+
+---
+
+## Project Overview
+
+Typed, production-grade Python SDK for the Kraken crypto exchange API
+
+For complete domain knowledge, refer to the project README.
+
+---
+
+## Meta Instructions
+
+### Session Start Checklist
+
+Every new session, in order:
+
+1. ✓ Read this file (AGENTS.md) -> Your primary instruction set
+2. ✓ Read README.md -> Important Domain knowledge regarding the project
+
+**ALWAYS** await further instructions before taking any action!
+
+### Just as a command runner
+
+- This project uses `just` for task management: [Just Github](https://github.com/casey/just)
+- You can safely assume the user has it installed and available in the PATH
+- Use `just` with no arguments to get a list of available recipes
+- If you need a new recipe, propose it to me first and if I concur we can add it to `./JUSTFILE`
+
+**ALWAYS** prefer to use existing recipes when available rather than running commands directly!
+
+---
+
+## Karpathy's Instructions
+
+*Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.*
+
+> Tradeoff: 
+> 
+> These guidelines bias toward caution over speed. For trivial tasks, use judgment.
+
+### 1. Think Before Coding
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+
+State your assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them - don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+
+### 2. Simplicity First
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+### 3. Surgical Changes
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it - don't delete it.
+
+When your changes create orphans:
+
+- Remove imports/variables/functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked.
+
+The test: Every changed line should trace directly to the user's request.
+
+### 4. Goal-Driven Execution
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+
+- "Add validation" → "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" → "Write a test that reproduces it, then make it pass"
+- "Refactor X" → "Ensure tests pass before and after"
+
+For multi-step tasks, state a brief plan:
+
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+3. [Step] → verify: [check]
+
+Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
+
+These guidelines are working if: fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and 
+clarifying questions come before implementation rather than after mistakes.

kraken_py_sdk-0.1.0/JUSTFILE

@@ -0,0 +1,31 @@
+set dotenv-load := true
+
+# Default recipe - list all available recipes
+list:
+    @just --list
+
+# Run tests with an optional pytest marker expression. State-changing tests are opt-in.
+test marker="":
+    #!/usr/bin/env bash
+    selected_marker="{{marker}}"
+    selected_marker="${selected_marker#marker=}"
+    if [ -n "$selected_marker" ]; then
+        uv run pytest -v -m "$selected_marker"
+    else
+        uv run pytest -v -m "not orders and not mutating"
+    fi
+
+# Analyze the codebase using cloc, excluding certain directories
+cloc:
+    @cloc . --vcs=git --exclude-dir=products,tests
+
+# Build the package distribution
+build:
+    @echo "Building package..."
+    rm -rf dist
+    uv build
+
+# Publish the package to PyPI using UV, with the token provided in the environment variable
+publish:
+    @echo "Publishing package to PyPI..."
+    uv publish --token $UV_PUBLISH_TOKEN

kraken_py_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,29 @@
+Metadata-Version: 2.4
+Name: kraken-py-sdk
+Version: 0.1.0
+Summary: Typed, production-grade Python SDK for the Kraken crypto exchange API
+Project-URL: Homepage, https://github.com/cstone-io/kraken-py
+Project-URL: Repository, https://github.com/cstone-io/kraken-py
+Project-URL: Issues, https://github.com/cstone-io/kraken-py/issues
+Project-URL: Changelog, https://github.com/cstone-io/kraken-py/blob/main/CHANGELOG.md
+Author: Connor Stone
+License: MIT
+Keywords: api,crypto,exchange,kraken,sdk,trading
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: websockets>=15.0
+Description-Content-Type: text/markdown
+
+# kraken-py
+
+Typed, production-grade Python SDK for the [Kraken](https://kraken.com) crypto exchange API.

kraken_py_sdk-0.1.0/README.md

@@ -0,0 +1,3 @@
+# kraken-py
+
+Typed, production-grade Python SDK for the [Kraken](https://kraken.com) crypto exchange API.

kraken_py_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,74 @@
+[project]
+name = "kraken-py-sdk"
+version = "0.1.0"
+description = "Typed, production-grade Python SDK for the Kraken crypto exchange API"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Connor Stone" }]
+requires-python = ">=3.12"
+keywords = ["kraken", "crypto", "exchange", "api", "sdk", "trading"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Office/Business :: Financial",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed",
+]
+dependencies = ["httpx>=0.28.1", "pydantic>=2.12.5", "websockets>=15.0"]
+
+[project.urls]
+Homepage = "https://github.com/cstone-io/kraken-py"
+Repository = "https://github.com/cstone-io/kraken-py"
+Issues = "https://github.com/cstone-io/kraken-py/issues"
+Changelog = "https://github.com/cstone-io/kraken-py/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kraken_py"]
+
+[tool.uv]
+package = true
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+addopts = ["--import-mode=importlib"]
+markers = [
+  "unit: deterministic tests that do not require external services",
+  "integration: tests that exercise the SDK against external APIs",
+  "rest: REST API tests",
+  "ws: WebSocket API tests",
+  "spot: Spot API tests",
+  "orders: tests that may create, amend, or cancel orders",
+  "mutating: tests that may change account or exchange state",
+]
+asyncio_mode = "strict"
+
+[dependency-groups]
+dev = [
+  "pytest>=9.0.2",
+  "pytest-asyncio>=0.24.0",
+  "pytest-cov>=7.0.0",
+  "python-dotenv>=1.2.1",
+]
+
+[tool.ty.environment]
+python-version = "3.12"
+root = ["./src", "./tests"]
+
+[tool.ty.src]
+include = ["src", "tests"]
+
+[tool.ty.rules]
+possibly-unresolved-reference = "warn"
+division-by-zero = "ignore"
+
+[tool.ruff.lint]
+ignore = ["F403", "F405"]

kraken_py_sdk-0.1.0/src/kraken_py/__init__.py

@@ -0,0 +1,19 @@
+"""Typed Python SDK for the Kraken API."""
+
+from kraken_py.instruments import (
+    DerivativesInstrument,
+    SpotPair,
+    SymbolProtocol,
+    format_symbol,
+)
+from kraken_py.rest import ApiCredentials, Authenticator, RestClient
+
+__all__ = [
+    "ApiCredentials",
+    "Authenticator",
+    "DerivativesInstrument",
+    "RestClient",
+    "SpotPair",
+    "SymbolProtocol",
+    "format_symbol",
+]

kraken_py_sdk-0.1.0/src/kraken_py/errors.py

@@ -0,0 +1,11 @@
+"""Protocol-neutral exceptions raised by kraken-py."""
+
+from __future__ import annotations
+
+
+class KrakenError(Exception):
+    """Base exception for all SDK failures."""
+
+
+class KrakenProtocolError(KrakenError):
+    """A Kraken response does not match its documented wire schema."""

kraken_py_sdk-0.1.0/src/kraken_py/instruments.py

@@ -0,0 +1,101 @@
+"""Protocol-aware Kraken trading instruments and symbol formatting."""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any, Final
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_serializer, model_validator
+
+
+class SymbolProtocol(str, Enum):
+    """Protocol whose symbol format should be produced."""
+
+    REST = "rest"
+    WEBSOCKET = "websocket"
+    FIX = "fix"
+
+
+class SpotPair(BaseModel):
+    """A human-readable Spot market pair."""
+
+    model_config = ConfigDict(frozen=True)
+
+    base: str = Field(min_length=1)
+    quote: str = Field(min_length=1)
+
+    @model_validator(mode="before")
+    @classmethod
+    def parse_symbol(cls, value: Any) -> Any:
+        """Accept a readable ``BASE/QUOTE`` symbol at model boundaries."""
+        if isinstance(value, str):
+            try:
+                base, quote = value.split("/", maxsplit=1)
+            except ValueError as error:
+                raise ValueError("Spot symbols must use the BASE/QUOTE format") from error
+            return {"base": base, "quote": quote}
+        return value
+
+    @field_validator("base", "quote", mode="before")
+    @classmethod
+    def normalize_asset(cls, value: Any) -> str:
+        """Normalize asset symbols while preserving Kraken's asset spelling."""
+        if not isinstance(value, str):
+            raise ValueError("asset symbols must be strings")
+        return value.strip().upper()
+
+    def symbol(self, protocol: SymbolProtocol = SymbolProtocol.REST) -> str:
+        """Render this pair using the requested protocol's symbol format."""
+        if protocol is SymbolProtocol.FIX:
+            base = _FIX_ASSET_ALIASES.get(self.base, self.base)
+            return f"{base}/{self.quote}"
+        return f"{self.base}/{self.quote}"
+
+    @model_serializer(mode="plain")
+    def serialize(self) -> str:
+        """Serialize nested pairs as the readable REST/Spot WebSocket symbol."""
+        return self.symbol()
+
+
+class DerivativesInstrument(BaseModel):
+    """A Kraken Derivatives instrument identified by its exchange symbol."""
+
+    model_config = ConfigDict(frozen=True)
+
+    symbol: str = Field(min_length=1)
+
+    @field_validator("symbol", mode="before")
+    @classmethod
+    def normalize_symbol(cls, value: Any) -> str:
+        """Normalize a Derivatives symbol without changing its structure."""
+        if not isinstance(value, str):
+            raise ValueError("instrument symbols must be strings")
+        return value.strip().upper()
+
+    def formatted_symbol(self, protocol: SymbolProtocol = SymbolProtocol.REST) -> str:
+        """Return this instrument's symbol for the requested protocol."""
+        _ = protocol
+        return self.symbol
+
+    @model_serializer(mode="plain")
+    def serialize(self) -> str:
+        """Serialize nested instruments as their exchange symbol."""
+        return self.symbol
+
+
+Instrument = SpotPair | DerivativesInstrument
+
+
+_FIX_ASSET_ALIASES: Final[dict[str, str]] = {
+    "BTC": "XBT",
+}
+
+
+def format_symbol(
+    instrument: Instrument,
+    protocol: SymbolProtocol = SymbolProtocol.REST,
+) -> str:
+    """Render an instrument using the requested protocol's symbol format."""
+    if isinstance(instrument, SpotPair):
+        return instrument.symbol(protocol)
+    return instrument.formatted_symbol(protocol)

kraken_py_sdk-0.1.0/src/kraken_py/rest/__init__.py

@@ -0,0 +1,9 @@
+"""Access to Kraken REST API products."""
+
+from kraken_py.rest.spot import (
+    ApiCredentials,
+    Authenticator,
+    RestClient,
+)
+
+__all__ = ["ApiCredentials", "Authenticator", "RestClient"]

kraken_py_sdk-0.1.0/src/kraken_py/rest/spot/__init__.py

@@ -0,0 +1,39 @@
+"""Kraken Spot REST API support."""
+
+from kraken_py.rest.spot.auth import (
+    ApiCredentials,
+    Authenticator,
+    MonotonicNonceProvider,
+    NonceProvider,
+    SignedRequest,
+)
+from kraken_py.rest.spot.client import RestClient
+from kraken_py.rest.spot.errors import (
+    KrakenRestApiError,
+    KrakenRestMessage,
+    KrakenRestRequestContext,
+    KrakenRestTransportError,
+    RestErrorCode,
+    RestMessageCategory,
+    RestMessageSeverity,
+    RestRetryAdvice,
+)
+from kraken_py.rest.spot.response import KrakenRestResponse
+
+__all__ = [
+    "ApiCredentials",
+    "Authenticator",
+    "KrakenRestApiError",
+    "KrakenRestMessage",
+    "KrakenRestRequestContext",
+    "KrakenRestResponse",
+    "KrakenRestTransportError",
+    "MonotonicNonceProvider",
+    "NonceProvider",
+    "RestClient",
+    "RestErrorCode",
+    "RestMessageCategory",
+    "RestMessageSeverity",
+    "RestRetryAdvice",
+    "SignedRequest",
+]

kraken_py_sdk-0.1.0/src/kraken_py/rest/spot/auth.py

@@ -0,0 +1,166 @@
+"""Authentication primitives for Kraken Spot private REST requests."""
+
+from __future__ import annotations
+
+import base64
+import binascii
+from abc import abstractmethod
+import hashlib
+import hmac
+import json
+import threading
+import time
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+from pydantic import BaseModel, ConfigDict, Field, SecretStr, field_validator
+
+_MAX_NONCE = 2**64 - 1
+_PRIVATE_PREFIX = "/0/private/"
+
+
+class NonceProvider(Protocol):
+    """Source of strictly increasing unsigned 64-bit nonces."""
+
+    @abstractmethod
+    def next_nonce(self) -> int:
+        """Return the next nonce for an API key."""
+        return 0
+
+
+class MonotonicNonceProvider:
+    """Thread-safe millisecond nonce provider.
+
+    This guarantees monotonicity within one Python process. Applications that
+    share an API key between processes must provide a shared NonceProvider.
+    """
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._last_nonce = 0
+
+    def next_nonce(self) -> int:
+        now = time.time_ns() // 1_000_000
+        with self._lock:
+            nonce = max(now, self._last_nonce + 1)
+            if nonce > _MAX_NONCE:
+                raise OverflowError("Kraken nonce exceeds unsigned 64-bit range")
+            self._last_nonce = nonce
+            return nonce
+
+
+class ApiCredentials(BaseModel):
+    """Credentials used to authenticate private Spot REST requests."""
+
+    model_config = ConfigDict(frozen=True)
+
+    api_key: str = Field(min_length=1)
+    api_secret: SecretStr
+    otp: str | None = Field(default=None, min_length=1)
+
+    @field_validator("api_secret")
+    @classmethod
+    def validate_api_secret(cls, value: SecretStr) -> SecretStr:
+        try:
+            decoded = base64.b64decode(value.get_secret_value(), validate=True)
+            if not decoded:
+                raise ValueError("api_secret must not be empty")
+        except (ValueError, binascii.Error) as error:
+            raise ValueError("api_secret must be valid Base64") from error
+        return value
+
+    @field_validator("api_key")
+    @classmethod
+    def strip_api_key(cls, value: str) -> str:
+        value = value.strip()
+        if not value:
+            raise ValueError("api_key must not be blank")
+        return value
+
+    @property
+    def secret_bytes(self) -> bytes:
+        """Return the decoded secret for HMAC use."""
+        return base64.b64decode(self.api_secret.get_secret_value(), validate=True)
+
+
+@dataclass(frozen=True, slots=True)
+class SignedRequest:
+    """The exact JSON body and headers for an authenticated request."""
+
+    body: bytes
+    headers: Mapping[str, str]
+    nonce: int
+
+
+def _payload_mapping(payload: BaseModel | Mapping[str, Any]) -> dict[str, Any]:
+    if isinstance(payload, BaseModel):
+        return payload.model_dump(mode="json", by_alias=True, exclude_none=True)
+    return dict(payload)
+
+
+def encode_json_payload(payload: Mapping[str, Any]) -> bytes:
+    """Encode a Kraken request payload exactly as it is sent on the wire."""
+    return json.dumps(
+        payload,
+        ensure_ascii=False,
+        separators=(",", ":"),
+    ).encode("utf-8")
+
+
+def generate_signature(uri_path: str, encoded_payload: bytes, nonce: int, secret: bytes) -> str:
+    """Generate an API-Sign value from an already encoded request payload."""
+    if not uri_path.startswith(_PRIVATE_PREFIX):
+        raise ValueError("uri_path must begin with /0/private/")
+    if not 0 <= nonce <= _MAX_NONCE:
+        raise ValueError("nonce must be an unsigned 64-bit integer")
+
+    message = uri_path.encode("utf-8") + hashlib.sha256(
+        str(nonce).encode("ascii") + encoded_payload
+    ).digest()
+    digest = hmac.new(secret, message, hashlib.sha512).digest()
+    return base64.b64encode(digest).decode("ascii")
+
+
+class Authenticator:
+    """Create signed Kraken private REST requests."""
+
+    def __init__(
+        self,
+        credentials: ApiCredentials,
+        nonce_provider: NonceProvider | None = None,
+    ) -> None:
+        self.credentials = credentials
+        self.nonce_provider = nonce_provider or MonotonicNonceProvider()
+
+    def sign(
+        self,
+        uri_path: str,
+        payload: BaseModel | Mapping[str, Any] | None = None,
+        *,
+        otp: str | None = None,
+    ) -> SignedRequest:
+        values = _payload_mapping(payload or {})
+        if "nonce" in values:
+            raise ValueError("nonce is managed by Authenticator and must not be supplied")
+
+        nonce = self.nonce_provider.next_nonce()
+        values = {"nonce": nonce, **values}
+        selected_otp = otp if otp is not None else self.credentials.otp
+        if selected_otp is not None:
+            values["otp"] = selected_otp
+
+        body = encode_json_payload(values)
+        signature = generate_signature(uri_path, body, nonce, self.credentials.secret_bytes)
+        return SignedRequest(
+            body=body,
+            headers={
+                "API-Key": self.credentials.api_key,
+                "API-Sign": signature,
+                "Content-Type": "application/json",
+            },
+            nonce=nonce,
+        )
+
+    def __repr__(self) -> str:
+        return f"Authenticator(api_key={self.credentials.api_key!r})"