Metadata-Version: 2.4
Name: ritbit-v4-client
Version: 0.0.3
Author-email: ritbit <support@tyranodex.xyz>
Requires-Python: <3.14,>=3.9
Requires-Dist: bech32<2.0.0,>=1.2.0
Requires-Dist: bip-utils<3.0.0,>=2.9.3
Requires-Dist: coincurve>=20.0.0
Requires-Dist: grpcio<2.0.0,>=1.74.0
Requires-Dist: httpx<0.28.0,>=0.27.0
Requires-Dist: pycryptodome<4.0.0,>=3.20.0
Requires-Dist: ritbit-v4-proto>=0.0.2
Requires-Dist: typing-extensions<5.0.0,>=4.12.2
Requires-Dist: websocket-client<2.0.0,>=1.7.0
Description-Content-Type: text/markdown

<img src="https://ritbit.trade/icon.svg" height="64px" align="right" />

# Python Client (async) for Ritbit (v4 API)
<div align="center">
    <a href='https://pypi.org/project/ritbit-v4-client'>
    <img src='https://img.shields.io/pypi/v/ritbit-v4-client.svg' alt='PyPI'/>
  </a>
  <a href='https://github.com/ritbit/v4-clients/blob/main/LICENSE'>
    <img src='https://img.shields.io/badge/License-AGPL_v3-blue.svg' alt='License' />
  </a>
</div>

## Quick links

<div align="center">

### [Documentation](https://docs.tyranodex.xyz/)
### [Other implementations](https://github.com/ritbit/v4-clients)

</div>

## Install

### Using uv (recommended)

```bash
uv init my-trading-bot
cd my-trading-bot
uv add ritbit-v4-client
```

### Using pip

```bash
pip install ritbit-v4-client
```

### Install from GitHub

```bash
uv add git+https://github.com/ritbit/v4-clients#subdirectory=v4-client-py-v2
```

or with pip:

```bash
pip install "ritbit-v4-client @ git+https://github.com/ritbit/v4-clients#subdirectory=v4-client-py-v2"
```

### Common Installation Issue on Ubuntu

If you encounter the following error:

```
Failed building wheel for ed25519-blake2b
```

Install the required build tools and Rust toolchain:

```bash
sudo apt-get update
sudo apt-get install build-essential python3-dev libssl-dev
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
```

Then retry the installation.

## Getting Started Guide

**Ritbit Python SDK Trading Documentation**: go-to resource for starting trades on Ritbit using the Python SDK. Follow this guide to learn the basics and begin trading.

### Table of Contents

1. [Introduction](./documentation/intro.md)
2. [Network Setup](./documentation/network_setup.md)
3. [Using the Testnet Faucet](./documentation/using_testnet_faucet.md)
4. [Account Details](./documentation/account_details.md)
5. [Getting Price Quotes](./documentation/getting_price_quotes.md)
6. [Placing Orders](./documentation/placing_orders.md)
7. [Placing Native Orders](./documentation/placing_native_orders.md)
8. [Using WebSockets](./documentation/using_websockets.md)

### Quick Start

1. Set up your network connection (see [Network Setup](./documentation/network_setup.md))
2. If using testnet, obtain funds from the faucet (see [Using the Testnet Faucet](./documentation/using_testnet_faucet.md))
3. Check your account details (see [Account Details](./documentation/account_details.md))
4. Get current market prices (see [Getting Price Quotes](./documentation/getting_price_quotes.md))
5. Build and place your order (see [Placing Orders](./documentation/placing_orders.md) or [Placing Native Orders](./documentation/placing_native_orders.md))
6. Optionally, set up WebSocket connections for real-time updates (see [Using WebSockets](./documentation/using_websockets.md))

For more detailed examples, see the [examples directory](/examples). Note that some examples may require installation of additional packages to work.

## Changes

### Migration

If you are transitioning from a previous version of the Python client, please note the following differences:

#### NodeClient

`ValidatorClient` is renamed to `NodeClient`.

All provided methods are asynchronous.

Methods are available directly, no methods `get` or `post` needed, since the client uses inheritance, and consists of three layers:

- `QueryNodeClient`, the basic layer that send queries to a node
- `MutatingNodeClient` - the extension on top of the query client, that support transation simulation and sending
- `NodeClient` the toppest layer that provides methods to control orders

For parameters raw types used.

For construcint order the `Market` builder is provided, that helps to calculate quantums and subticks values.

#### IndexerClient

The `IndexerClient` has the similar structure, but provides
asynchronous methods as well.

#### IndexerSocket

The `SocketClient` is replaced with the `IndexerSocket` that provides separate channels concept and allow to add per-channel processing.

### Key Improvements

The latest version of the Python async client for Ritbit offers notable enhancements over previous iterations. These improvements make it a more efficient tool for trading and integration.

#### Asynchronous Execution

The methods leverage Python's async features, allowing you to fully harness concurrency benefits. This approach optimizes resource usage, minimizes unnecessary threads, and reduces latency.

#### Enhanced Type Hints

Expanded type hint coverage enhances code readability and provides better tooling support. Additionally, it helps detect errors early during development.

#### API Reflection

The client closely mirrors the Ritbit API, enabling seamless access to the exchange's features and parameters. This makes integrating the client with your applications intuitive and straightforward.

#### Lightweight Implementation
The client is built using pure Python libraries and maintains a thin, transparent layer that follows the Principle of Least Astonishment (POLA). This ensures explicit behavior and gives you greater control.

#### MIT License
Licensed under the permissive MIT license, the client can be easily integrated into your software projects without restrictive legal hurdles.

## Development

The project is divided into three main parts:
* node - contains the `NodeClient`, transaction builder and other utilities
* indexer - contains rest api indexer client and websocket indexer client
* faucet - contains faucet client

### Installing from source

The project uses [uv](https://docs.astral.sh/uv/). To install dependencies, run:

```bash
uv sync
```

To include dev and example dependencies:

```bash
uv sync --group dev --group examples
```

### Preparing development environment
Install git hooks:
```bash
uv run pre-commit install
```

### Testing
To run tests use:

```bash
uv run pytest
```

### Linting
```bash
uv run black --check ./ritbit_v4_client ./tests ./examples
```

For more details about the grant see [link](https://tyranodex.xyz).
