revolut-x-python 1.0.0__py3-none-any.whl

revolut_x/types.py

@@ -0,0 +1,397 @@
+"""Type definitions, enums, and typed dictionaries for revolut-x-python.
+
+This module provides:
+
+* **Enums** — :class:`OrderSide`, :class:`OrderType`, :class:`Interval`,
+  :class:`TimeInForce` for type-safe parameter passing.
+* **TypedDicts** — :class:`Candle`, :class:`Trade`, :class:`Ticker`,
+  :class:`Balance`, :class:`PairConfig`, etc. for IDE autocompletion
+  on API response data.
+"""
+
+from __future__ import annotations
+from enum import Enum
+from typing import TypedDict
+
+
+# ---------------------------------------------------------------------------
+# Enums
+# ---------------------------------------------------------------------------
+
+class OrderSide(str, Enum):
+    """Direction of an order.
+
+    Example::
+
+        from revolut_x import OrderSide
+        side = OrderSide.BUY
+    """
+
+    BUY = "buy"
+    """Buy the base currency (e.g. buy BTC for EUR)."""
+
+    SELL = "sell"
+    """Sell the base currency (e.g. sell BTC for EUR)."""
+
+
+class OrderType(str, Enum):
+    """Type of an order.
+
+    Example::
+
+        from revolut_x import OrderType
+        order_type = OrderType.LIMIT
+    """
+
+    MARKET = "market"
+    """Market order — executed immediately at the best available price (taker fee: 0.09%)."""
+
+    LIMIT = "limit"
+    """Limit order — placed in the order book at a specific price (maker fee: 0.00%)."""
+
+
+class Interval(int, Enum):
+    """Candlestick interval in minutes, as accepted by the Revolut X API.
+
+    Example::
+
+        from revolut_x import Interval
+        candles = client.get_candles("BTC-EUR", interval=Interval.HOUR_1)
+    """
+
+    MIN_1 = 1
+    """1-minute candles."""
+
+    MIN_5 = 5
+    """5-minute candles."""
+
+    MIN_15 = 15
+    """15-minute candles."""
+
+    MIN_30 = 30
+    """30-minute candles."""
+
+    HOUR_1 = 60
+    """1-hour candles."""
+
+    HOUR_4 = 240
+    """4-hour candles."""
+
+    DAY_1 = 1440
+    """1-day (24h) candles."""
+
+    DAY_2 = 2880
+    """2-day candles."""
+
+    DAY_4 = 5760
+    """4-day candles."""
+
+    WEEK_1 = 10080
+    """1-week candles."""
+
+    WEEK_2 = 20160
+    """2-week candles."""
+
+    WEEK_4 = 40320
+    """4-week (28-day) candles."""
+
+
+class TimeInForce(str, Enum):
+    """Time-in-force policy for limit orders.
+
+    Example::
+
+        from revolut_x import TimeInForce
+        client.place_limit_order(..., time_in_force=TimeInForce.GTC)
+    """
+
+    GTC = "gtc"
+    """Good 'til canceled — the order stays open until filled or manually canceled."""
+
+    IOC = "ioc"
+    """Immediate or cancel — fill as much as possible immediately, cancel the rest."""
+
+
+# ---------------------------------------------------------------------------
+# TypedDicts — structured response types for IDE autocompletion
+# ---------------------------------------------------------------------------
+
+class Candle(TypedDict):
+    """A single OHLCV candlestick returned by :meth:`RevolutXClient.get_candles`.
+
+    Attributes:
+        start: Candle open time as Unix timestamp in milliseconds.
+        open: Opening price (string to preserve decimal precision).
+        high: Highest price during the interval.
+        low: Lowest price during the interval.
+        close: Closing price.
+        volume: Trading volume in the base currency.
+    """
+
+    start: int
+    open: str
+    high: str
+    low: str
+    close: str
+    volume: str
+
+
+class Trade(TypedDict, total=False):
+    """A single public trade returned by :meth:`RevolutXClient.get_trades`.
+
+    Attributes:
+        id: Unique trade identifier (UUID string).
+        symbol: Trading pair (e.g. ``'BTC/EUR'``).
+        price: Execution price.
+        quantity: Traded quantity in the base currency.
+        timestamp: Trade time as Unix timestamp in milliseconds.
+        side: ``'buy'`` or ``'sell'``.
+        region: Venue region the trade was executed in (e.g. ``'EEA'``, ``'UK'``).
+    """
+
+    id: str
+    symbol: str
+    price: str
+    quantity: str
+    timestamp: int
+    side: str
+    region: str
+
+
+class Ticker(TypedDict, total=False):
+    """Ticker data for a trading pair from :meth:`RevolutXClient.get_ticker`.
+
+    Attributes:
+        symbol: Trading pair (e.g. ``'BTC/EUR'``).
+        bid: Best bid (highest buy) price.
+        ask: Best ask (lowest sell) price.
+        mid: Midpoint between ``bid`` and ``ask``.
+        index_price: Reference index price.
+        last_price: Last traded price.
+        low_24h: 24-hour low price.
+        high_24h: 24-hour high price.
+        price_change_24h: Absolute price change over the last 24 hours.
+        volume_24h: 24-hour trading volume in the base currency.
+        quote_volume_24h: 24-hour trading volume in the quote currency.
+        region: Venue region (e.g. ``'EEA'``, ``'UK'``).
+    """
+
+    symbol: str
+    bid: str
+    ask: str
+    mid: str
+    index_price: str
+    last_price: str
+    low_24h: str
+    high_24h: str
+    price_change_24h: str
+    volume_24h: str
+    quote_volume_24h: str
+    region: str
+
+
+class PairConfig(TypedDict, total=False):
+    """Configuration and trading limits for a single pair.
+
+    Returned by :meth:`RevolutXClient.get_pairs` and
+    :meth:`RevolutXClient.get_pair`.
+
+    Attributes:
+        base: Base currency symbol (e.g. ``'BTC'``).
+        quote: Quote currency symbol (e.g. ``'EUR'``).
+        base_step: Minimum quantity increment (e.g. ``'0.00000001'``).
+        quote_step: Minimum price increment (e.g. ``'0.01'``).
+        min_order_size: Minimum order size in the base currency.
+        max_order_size: Maximum order size in the base currency.
+        min_order_size_quote: Minimum order value in the quote currency.
+        max_order_size_quote: Maximum order value in the quote currency.
+        status: Pair status — ``'active'`` or ``'inactive'``.
+        slippage: Maximum allowed slippage percentage.
+    """
+
+    base: str
+    quote: str
+    base_step: str
+    quote_step: str
+    min_order_size: str
+    max_order_size: str
+    min_order_size_quote: str
+    max_order_size_quote: str
+    status: str
+    slippage: int
+
+
+class CurrencyConfig(TypedDict, total=False):
+    """Configuration for a single currency.
+
+    Returned by :meth:`RevolutXClient.get_currencies`.
+
+    Attributes:
+        name: Human-readable currency name (e.g. ``'Bitcoin'``).
+        symbol: Currency ticker (e.g. ``'BTC'``).
+        scale: Number of decimal places.
+        asset_type: ``'crypto'`` or ``'fiat'``.
+        status: ``'active'`` or ``'inactive'``.
+    """
+
+    name: str
+    symbol: str
+    scale: int
+    asset_type: str
+    status: str
+
+
+class OrderBookLevel(TypedDict, total=False):
+    """A single price level in the order book.
+
+    The Revolut X order book uses short field names.  The two fields you
+    normally want are ``p`` (price) and ``q`` (quantity).
+
+    Attributes:
+        p: Price in the quote currency.
+        q: Quantity available at this price, in the base currency.
+        s: Side — ``'BUYI'`` for bids, ``'SELL'`` for asks.
+        pc: Price currency (e.g. ``'EUR'``).
+        qc: Quantity currency (e.g. ``'BTC'``).
+        aid: Asset identifier (e.g. ``'BTC'``).
+        anm: Asset name (e.g. ``'Bitcoin'``).
+        no: Number of orders aggregated into this level.
+        pn: Price notation (e.g. ``'MONE'``).
+        qn: Quantity notation (e.g. ``'UNIT'``).
+        ve: Venue (e.g. ``'REVX'``).
+        ts: Trading system (e.g. ``'CLOB'``).
+        pdt: Price timestamp as an ISO-8601 string.
+    """
+
+    p: str
+    q: str
+    s: str
+    pc: str
+    qc: str
+    aid: str
+    anm: str
+    no: str
+    pn: str
+    qn: str
+    ve: str
+    ts: str
+    pdt: str
+
+
+class OrderBook(TypedDict):
+    """Order book snapshot from :meth:`RevolutXClient.get_order_book`.
+
+    Each entry is an :class:`OrderBookLevel` dictionary — **not** a
+    ``[price, quantity]`` pair.  Read the price and quantity from the
+    ``p`` and ``q`` keys::
+
+        best_bid = book["bids"][0]
+        print(best_bid["p"], best_bid["q"])
+
+    Attributes:
+        bids: Buy levels, sorted best (highest price) first.
+        asks: Sell levels, sorted best (lowest price) first.
+    """
+
+    bids: list[OrderBookLevel]
+    asks: list[OrderBookLevel]
+
+
+class Balance(TypedDict):
+    """Account balance for a single currency.
+
+    Returned by :meth:`RevolutXClient.get_balances`.
+
+    Attributes:
+        currency: Currency symbol (e.g. ``'EUR'``, ``'BTC'``).
+        available: Amount available for trading.
+        reserved: Amount locked in open orders.
+        total: Total balance (available + reserved).
+    """
+
+    currency: str
+    available: str
+    reserved: str
+    total: str
+
+
+class OrderResponse(TypedDict, total=False):
+    """Response returned after placing a new order.
+
+    Attributes:
+        venue_order_id: Exchange-assigned order ID.
+        client_order_id: Client-provided order ID (UUID).
+        state: Initial order state (e.g. ``'new'``).
+    """
+
+    venue_order_id: str
+    client_order_id: str
+    state: str
+
+
+class OrderDetail(TypedDict, total=False):
+    """Detailed order information from :meth:`RevolutXClient.get_order`.
+
+    Attributes:
+        id: Exchange order ID.
+        symbol: Trading pair.
+        side: ``'buy'`` or ``'sell'``.
+        type: ``'market'`` or ``'limit'``.
+        status: Order status (``'new'``, ``'filled'``, ``'canceled'``, …).
+        quantity: Requested quantity.
+        filled_quantity: Actually filled quantity.
+        amount: Requested amount in quote currency.
+        filled_amount: Actually filled amount in quote currency.
+        average_fill_price: Volume-weighted average fill price.
+        total_fee: Total fee charged.
+        fee_currency: Currency of the fee (e.g. ``'EUR'``).
+        created_date: Creation timestamp in milliseconds.
+        updated_date: Last update timestamp in milliseconds.
+    """
+
+    id: str
+    symbol: str
+    side: str
+    type: str
+    status: str
+    quantity: str
+    filled_quantity: str
+    amount: str
+    filled_amount: str
+    average_fill_price: str
+    total_fee: str
+    fee_currency: str
+    created_date: int
+    updated_date: int
+
+
+class Fill(TypedDict, total=False):
+    """A single fill (partial execution) of an order.
+
+    Returned by :meth:`RevolutXClient.get_order_fills`.
+
+    Attributes:
+        tdt: Trade timestamp in milliseconds.
+        aid: Asset ID (e.g. ``'BTC'``).
+        anm: Asset name (e.g. ``'Bitcoin'``).
+        p: Execution price.
+        pc: Price currency (e.g. ``'EUR'``).
+        q: Filled quantity.
+        qc: Quantity currency (e.g. ``'BTC'``).
+        tid: Trade ID.
+        oid: Order ID.
+        s: Side (``'buy'`` or ``'sell'``).
+        im: ``True`` if this fill was a maker trade (0% fee).
+    """
+
+    tdt: int
+    aid: str
+    anm: str
+    p: str
+    pc: str
+    q: str
+    qc: str
+    tid: str
+    oid: str
+    s: str
+    im: bool

revolut_x_python-1.0.0.dist-info/METADATA

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: revolut-x-python
+Version: 1.0.0
+Summary: Python SDK for the Revolut X Crypto Exchange REST API (v1.0)
+Author: Jan Přikryl
+License-Expression: MIT
+Project-URL: Homepage, https://janprikryl1.github.io/revolut-x-python/
+Project-URL: Documentation, https://janprikryl1.github.io/revolut-x-python/
+Project-URL: Repository, https://github.com/janprikryl1/revolut-x-python
+Project-URL: Changelog, https://github.com/janprikryl1/revolut-x-python/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/janprikryl1/revolut-x-python/issues
+Keywords: revolut,revolut-x,crypto,exchange,trading,api,sdk,bitcoin
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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 :: 3.14
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Requires-Dist: cryptography>=41.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.10; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=6.1; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.5.0; extra == "docs"
+Requires-Dist: mkdocs-material>=9.5.0; extra == "docs"
+Requires-Dist: mkdocs-static-i18n>=1.2.0; extra == "docs"
+Requires-Dist: mkdocstrings[python]>=0.24.0; extra == "docs"
+Requires-Dist: pymdown-extensions>=10.0; extra == "docs"
+Dynamic: license-file
+
+# Revolut X Python SDK
+
+Python client library for the **Revolut X Crypto Exchange REST API (v1.0)**.
+
+📖 **Documentation**: [janprikryl1.github.io/revolut-x-python](https://janprikryl1.github.io/revolut-x-python/)  
+🐘 **Looking for PHP?** See [revolut-x-php](https://github.com/janprikryl1/revolut-x-php).
+
+---
+
+## Features
+
+- **Revolut X API v1.0** — Complete coverage of market data, order placement, balances, and transaction history.
+- **Ed25519 Authentication** — Cryptographic request signing using `cryptography` (PKCS#8 PEM).
+- **Smart Maker Strategy (0.00% fee)** — Automatic offset pricing and `post_only` execution to prevent taker fees (0.09%).
+- **Streaming Iterators** — `iter_candles()` and `iter_trades()` automatically handle cursor pagination and rate-limit delays.
+- **100% Type Annotated** — Built with Python `TypedDict`, `Enum`, and type annotations.
+- **AI Agent Skill** — Pre-packaged skill definition for AI coding assistants (Google Antigravity, Claude, Cursor).
+
+---
+
+## Installation
+
+```bash
+pip install revolut-x-python
+```
+
+In a `requirements.txt`:
+
+```
+revolut-x-python>=1.0.0
+```
+
+<details>
+<summary>Pre-release builds (TestPyPI)</summary>
+
+Release candidates go to **TestPyPI** first. Versions `0.0.1` – `0.1.0` were
+published there only; `1.0.0` is the first release on PyPI proper. To install
+a pre-release build:
+
+```bash
+pip install --extra-index-url https://test.pypi.org/simple/ revolut-x-python
+```
+
+Use `--extra-index-url` (rather than `--index-url`) so PyPI stays available
+for the `requests` and `cryptography` dependencies, which are not mirrored on
+TestPyPI.
+
+</details>
+
+---
+
+## Quickstart
+
+### 1. Public Market Data (No API Key Required)
+
+```python
+from revolut_x import RevolutXClient, Interval
+
+client = RevolutXClient()
+
+# Get BTC-EUR ticker
+ticker = client.get_ticker("BTC-EUR")
+print(f"BTC Price: {ticker['last_price']} EUR")
+
+# Get 1-hour OHLCV candles
+candles = client.get_candles("BTC-EUR", Interval.HOUR_1)
+```
+
+### 2. Authenticated Trading & 0% Fee Maker Orders
+
+```python
+from revolut_x import RevolutXClient, OrderSide
+
+client = RevolutXClient(
+    api_key="your-api-key",
+    private_key_path="keys/private.pem",
+)
+
+# Submit zero-fee Maker limit order (post_only=True)
+order = client.place_maker_order(
+    symbol="BTC-EUR",
+    side=OrderSide.BUY,
+    quote_size="50.00",
+    offset="0.10",
+)
+print(f"Order ID: {order['venue_order_id']}")
+```
+
+---
+
+## Running Tests
+
+```bash
+pytest tests
+```
+
+---
+
+## Academic Reference
+
+This library was written as part of a **master's thesis** at **VŠB – Technical
+University of Ostrava**, Faculty of Electrical Engineering and Computer Science.
+
+- **Author**: Bc. Jan Přikryl
+- **University**: VŠB – Technical University of Ostrava
+- **Faculty**: Faculty of Electrical Engineering and Computer Science (FEI)
+
+---
+
+## Changelog
+
+See [CHANGELOG.md](https://github.com/janprikryl1/revolut-x-python/blob/main/CHANGELOG.md).
+
+---
+
+## License
+
+This project is licensed under the MIT License — see the
+[LICENSE](https://github.com/janprikryl1/revolut-x-python/blob/main/LICENSE)
+file for details.

revolut_x_python-1.0.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+revolut_x/__init__.py,sha256=gDLqthrI3-aQPQOYN6dthLric5wV8UGPf79vjf2nC4w,2250
+revolut_x/_auth.py,sha256=Lor9eIas57Jzf1_FOwHtF_0O3XYhJRye04wfb1aUWm0,4457
+revolut_x/_http.py,sha256=La5hi9BfN5ydA23wbNyC5jCC5oMKM9B5FeVn4VSKo2M,11879
+revolut_x/_version.py,sha256=YZsBI4L0nwpRJN96Pp1wo8rndjGF2nQ8PjiWBXOUHZI,394
+revolut_x/account.py,sha256=ucUYwL3DoFG0qW91DRHFT-D6ftYiyULix7nB8-76YIw,6800
+revolut_x/client.py,sha256=5n7yIsyyKqToSgdEkolj2BzxpdqFaQVro5hpJGTb18o,6311
+revolut_x/exceptions.py,sha256=oaTzLbC7IL-aA8DmavMOWcSubgA-YMWWaZaa5KpG4So,4899
+revolut_x/helpers.py,sha256=3nF7QFtUDRijqrQlcg4IVwx2kiD7OeBz_rSlqMvc_Pk,20265
+revolut_x/market.py,sha256=n2AHNuoHuv9ElpwX1A9lc8F3iQ154c8KmplDa4nnYpQ,17135
+revolut_x/orders.py,sha256=OFjjJ9d6FIkl9HvBZwIidwGaxZm3Ezh1utjsi_OFD30,19409
+revolut_x/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+revolut_x/types.py,sha256=EAkizOaqccBVlr3OFwaOUiPjAx9XB8SagXEQLNq0YUk,10745
+revolut_x_python-1.0.0.dist-info/licenses/LICENSE,sha256=uZU5frhpA6kIvdHIJhmtkbsI6ddIlmA00Scbrd_lpBc,1069
+revolut_x_python-1.0.0.dist-info/METADATA,sha256=4o2y6GK6J4bKySHaRkzGV58qfJth53SNiq-S0Ppj2h8,5157
+revolut_x_python-1.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+revolut_x_python-1.0.0.dist-info/top_level.txt,sha256=qqp3klKfMJt3nKxLMzSMzzetP2MgoZArAio3alBrwiE,10
+revolut_x_python-1.0.0.dist-info/RECORD,,

revolut_x_python-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

revolut_x_python-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jan Přikryl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

revolut_x_python-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+revolut_x