Skip to content

update for docs #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
evanlewis-hub wants to merge 4 commits into
base: main
Choose a base branch
from
Open

update for docs #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
c50f8f3
update for docs
Mar 19, 2026
a43bab9
removed old sdk
Mar 19, 2026
e78830f
added notes about autogeneration
Mar 19, 2026
68543ef
changed to official
Mar 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
95 changes: 95 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,95 @@
# Contributing to WhiteBit Python SDK

Thank you for your interest in contributing!

---

## Important: Auto-generated Core

The core SDK (`src/whitebit/`) is **automatically generated** from the WhiteBit API definition using [Fern](https://buildwithfern.com). This means:

- **Do not open PRs that modify files inside `src/whitebit/`** — changes will be overwritten on the next generation run.
- To request a new endpoint or fix an incorrect API definition, open an issue instead (see [Reporting Bugs](#reporting-bugs) and [Requesting Features](#requesting-features)).

---

## What you CAN contribute

| Area | How |
|---|---|
| **Bug reports** | Open an issue with reproduction steps |
| **Feature requests** | Open an issue describing the use case |
| **Examples** | Add or improve files in `examples/` |
| **Tests** | Add test cases in `tests/` |
| **Use cases & guides** | Real-world usage patterns, strategies, bots |
| **Documentation** | Fixes and improvements to `README.md` |

---

## Reporting Bugs

Before opening an issue, search existing ones to avoid duplicates.

Include:

- Python version (`python --version`)
- SDK version (`pip show whitebit-python-sdk`)
- Minimal code snippet that reproduces the problem
- Full error traceback
- Expected vs actual behaviour

---

## Requesting Features

Open an issue with the label **enhancement** and describe:

- The use case you are trying to solve
- The API endpoint involved (link to the [WhiteBit API docs](https://docs.whitebit.com/) if applicable)
- Any alternative approaches you considered

---

## Contributing Examples and Tests

Examples and tests are the best place to contribute code directly.

**Examples** live in `examples/` — feel free to add:
- New usage patterns for existing clients
- Real-world trading strategies or bots
- Integration patterns (e.g. asyncio, frameworks)

**Tests** live in `tests/test.py`. All tests use the `responses` library to mock HTTP calls — no real API credentials are needed.

```bash
# Setup
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -e .

# Run tests
python -m pytest tests/ -v
```

When adding a test:
1. Mock the HTTP call with `@responses.activate`
2. Cover both a success case and an error/missing-credentials case
3. Assert the request URL, method, body, and response

---

## Submitting a Pull Request

1. Fork the repo and create a branch: `git checkout -b feature/my-feature`
2. Make sure all existing tests pass
3. Keep commits focused — one logical change per commit
4. Reference any related issue in the PR description (e.g. `Closes #42`)

---

## Code Style

- Follow [PEP 8](https://peps.python.org/pep-0008/)
- Use type hints where possible
- Do not commit API keys, secrets, or any credentials
230 changes: 138 additions & 92 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,123 +1,169 @@
## A Python SDK for [whitebit](https://www.whitebit.com)
# WhiteBit Python SDK

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![PyPI version](https://badge.fury.io/py/whitebit-python-sdk.svg)](https://badge.fury.io/py/whitebit-python-sdk)
[![Python Version](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org/downloads/)

Please read [whitebit API document](https://whitebit-exchange.github.io/api-docs/) before continuing.
An official Python SDK for the [WhiteBit](https://www.whitebit.com) cryptocurrency exchange API.

## API List
> Please read the [WhiteBit API documentation](https://docs.whitebit.com/) before using this SDK.

- [Private API](https://whitebit-exchange.github.io/api-docs/private/http-trade-v4/)
- [Public API](https://whitebit-exchange.github.io/api-docs/public/http-v4/)
- [Private WS](https://whitebit-exchange.github.io/api-docs/private/websocket/)
- [Public WS](https://whitebit-exchange.github.io/api-docs/public/websocket/)
---

v4 is the preferred one to use
## Installation

## Disclaimer
“You acknowledge that the software is provided “as is”. Author makes no representations or warranties with respect to
the software whether express or implied, including but not limited to, implied warranties of merchantability and fitness
for a particular purpose. author makes no representation or warranty that: (i) the use and distribution of the software
will be uninterrupted or error free, and (ii) any use and distribution of the software is free from infringement of any
third party intellectual property rights. It shall be your sole responsibility to make such determination before the use
of software. Author disclaims any liability in case any such use and distribution infringe any third party’s
intellectual property rights. Author hereby disclaims any warranty and liability whatsoever for any development created
by or for you with respect to your customers. You acknowledge that you have relied on no warranties and that no
warranties are made by author or granted by law whenever it is permitted by law.”
```bash
pip install whitebit-python-sdk
```

## REST API
Python 3.9 or higher is required.

### Setup
---

#### Install the Python module:
## Quick Start

```bash
python3 -m pip install python-whitebit-sdk
### Sync client

```python
from whitebit import WhitebitApi

client = WhitebitApi(txc_apikey="YOUR_API_KEY", token="YOUR_TOKEN")

# Market data (public)
print(client.public_api_v4.get_tickers())

# Spot trading
print(client.spot_trading.get_trade_account_balance(ticker="BTC"))
print(client.spot_trading.create_limit_order(market="BTC_USDT", side="buy", amount="0.001", price="30000"))

# Collateral
print(client.collateral_trading.get_open_positions(market="BTC_USDT"))
```

Init client for API services. Get APIKey/SecretKey from your whitebit account.
### Async client

```python
from whitebit import MainAccountClient
import asyncio
from whitebit import AsyncWhitebitApi

async def main():
client = AsyncWhitebitApi(txc_apikey="YOUR_API_KEY", token="YOUR_TOKEN")

# Market data (public)
tickers = await client.public_api_v4.get_tickers()
print(tickers)

# Spot trading
balance = await client.spot_trading.get_trade_account_balance(ticker="BTC")
print(balance)

order = await client.spot_trading.create_limit_order(
market="BTC_USDT", side="buy", amount="0.001", price="30000"
)
print(order)

account = MainAccountClient(api_key="", api_secret=""))
asyncio.run(main())
```

Following are some simple examples.
Get your API key from your [WhiteBit account settings](https://whitebit.com/settings/api).

See the **examples** folder for full references.
---

#### Create Spot Limit Order
> **Note:** The SDK client (`WhitebitApi` / `AsyncWhitebitApi`) is auto-generated from the WhiteBit API definition using [Fern](https://buildwithfern.com). To report issues or request new endpoints, open an issue — see [Contributing](CONTRIBUTING.md).

```python
# Create order/spot client
order = OrderClient(api_key="",
api_secret="")
## Clients

# Call SDK function put_limit
print(order.put_limit("BTC_USDT", "sell", "0.1", "40000", True))
```
The SDK exposes two top-level clients — `WhitebitApi` (sync) and `AsyncWhitebitApi` (async). Both share the same sub-client structure:

## Websocket API
| Sub-client | Auth | Description |
|---|---|---|
| `client.public_api_v4` | No | Tickers, order books, klines, assets, trades |
| `client.spot_trading` | Yes | Place/cancel spot orders, balance, order history |
| `client.collateral_trading` | Yes | Margin/futures orders, positions, OCO |
| `client.main_account` | Yes | Main balance, deposit/withdraw history |
| `client.deposit` | Yes | Deposit addresses, fiat deposit URLs |
| `client.withdraw` | Yes | Withdrawals |
| `client.transfer` | Yes | Transfer between balances |
| `client.codes` | Yes | Transfer codes (create, apply, history) |
| `client.fees` | Yes | Fee information |
| `client.market_fee` | Yes | Market-specific fees |
| `client.jwt` | Yes | WebSocket JWT token |
| `client.authentication` | Yes | OAuth2 token management |
| `client.sub_account` | Yes | Sub-account management |
| `client.sub_account_api_keys` | Yes | Sub-account API key management |
| `client.crypto_lending_fixed` | Yes | Fixed crypto lending |
| `client.crypto_lending_flex` | Yes | Flex crypto lending |
| `client.credit_line` | Yes | Credit line |
| `client.mining_pool` | Yes | Mining pool stats and management |

### Setup
---

Init bot class and "on_message" method for work with ws responses. Get APIKey/SecretKey from your whitebit account.
## Examples

```python
class Bot(WhitebitWsClient):
def __init__(self):
super().__init__(key="", secret="")
Full working examples are in the [`examples/`](examples/) directory:

async def on_message(self, event) -> None:
logging.info(event)

```
### [trade_examples.py](examples/trade_examples.py)

Following are some simple examples.
Covers `TradeMarketClient`, `TradeAccountClient`, and `TradeOrderClient`:
- Get tickers, order books, klines, assets
- Get spot balance, order history, unexecuted orders
- Place limit, market, stop-limit, stop-market orders
- Bulk limit orders, kill switch

See the **examples** folder for full references.
### [main_examples.py](examples/main_examples.py)

#### Subscribe on deals topic
Covers `MainAccountClient`:
- Main account balance and fee info
- Transaction history
- Create and apply transfer codes

```python
class Bot(WhitebitWsClient):
'''Can be used to create a custom trading strategy/bot'''

def __init__(self):
super().__init__(key="", secret="")

async def on_message(self, event) -> None:
'''receives the websocket events'''
if 'result' in event:
result = event['result']
match result:
case 'pong': return
logging.info(event['result'])
return
else:
method = event['method']
match method:
case WhitebitWsClient.DEALS_UPDATE:
logging.info(event['params'])
return


async def main() -> None:
bot = Bot()
await bot.get_deals("BTC_USDT", 0, 100)
await bot.subscribe_deals(["BTC_USDT"])
while not bot.exception_occur:
await asyncio.sleep(100)
return


if __name__ == '__main__':
logging.basicConfig(level=logging.INFO)
loop = asyncio.new_event_loop()
asyncio.set_event_loop(loop)
try:
asyncio.run(main())
except KeyboardInterrupt:
pass
finally:
loop.close()
### [collateral_examples.py](examples/collateral_examples.py)

Covers `CollateralMarketClient`, `CollateralAccountClient`, `CollateralOrderClient`:
- Futures/collateral market info
- Margin balance, open positions, leverage
- Place and cancel collateral/OCO orders

### [ws_example.py](examples/ws_example.py)

Covers `WhitebitWsClient`:
- Extend the client and implement `on_message` for real-time events
- Subscribe to deals, prices, order book depth, balance, pending orders

---

## WebSocket Topics

| Method | Description |
|---|---|
| `subscribe_kline` / `get_kline` | Candlestick (OHLCV) data |
| `subscribe_last_price` / `get_last_price` | Last price updates |
| `subscribe_market_depth` / `get_market_depth` | Order book depth |
| `subscribe_market_stat` / `get_market_stat` | 24h market statistics |
| `subscribe_market_trades` / `get_market_trades` | Public trades stream |
| `subscribe_deals` / `get_deals` | Deals stream |
| `subscribe_spot_balance` / `get_spot_balance` | Spot account balance |
| `subscribe_margin_balance` / `get_margin_balance` | Margin account balance |
| `subscribe_pending_orders` / `get_pending_orders` | Open orders updates |
| `subscribe_orders_executed` / `get_orders_executed` | Executed orders |

---

## Running Tests

```bash
pip install -r requirements.txt
python -m pytest tests/ -v
```

---

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on reporting bugs, requesting features, and submitting pull requests.

---

## Disclaimer

The software is provided "as is" without warranty of any kind. Use at your own risk.
Loading