python-wallex

A lightweight, dependency-light Python SDK for the Wallex cryptocurrency exchange REST API, plus an optional real-time WebSocket depth streamer.

It wraps the most common public (market data) and private (account / trading / wallet) endpoints as small helper functions with built-in retry logic for transient network errors.

Note on symbols: Throughout the SDK, TMN refers to Toman (shown as IRT on some raw endpoints), e.g. the market symbol BTCTMN.

---

Contents

File	Description
wallex.py	The core SDK — REST wrappers for market data, trading and wallet endpoints.
price_streamer_wlx.py	Optional real-time depth streamer over WebSocket, exposing a small local HTTP API.
requirements.txt	Python dependencies.

---

Installation

git clone https://github.com/amirSamanQ/python-wallex.git
cd python-wallex
pip install -r requirements.txt

Core SDK dependency: requests. The streamer additionally needs: websocket-client, fastapi, uvicorn.

---

Quick start

import wallex as wlx

# Required for any private (account / trading) endpoint:
wlx.wallex_api_key = "YOUR_API_KEY"

# --- Public market data (no API key needed) ---
prec = wlx.get_quantity_precision("BTCTMN")
print(prec)                       # {'q': 5, 'p': 0}

book = wlx.get_best_bid_ask("BTCTMN", count=2)
print(book["bid"][0])             # {'price': 63200000000.0, 'vol': 0.012}

# --- Trading (private) ---
order = wlx.new_order(side="buy", quantity=0.001, market="BTCTMN", price=63000000000)
order_id = order["result"]["clientOrderId"]

status = wlx.check_order(order_id)
wlx.cancel_order_wallex(order_id)

# --- Balances ---
usdt_free = wlx.get_balance("USDT", free=True)   # available USDT
tmn_free  = wlx.get_balance("TMN",  free=True)   # available Toman

---

Authentication

Private endpoints authenticate with an API key sent in the X-API-Key header. Set it once after importing the module:

import wallex as wlx
wlx.wallex_api_key = "YOUR_API_KEY"

⚠️ Never hardcode API keys in source control. Load them from environment variables or a secrets file at runtime.

---

API reference

Public market data

get_quantity_precision(market) -> dict

Returns the quantity (stepSize) and price (tickSize) precision for a market.

wlx.get_quantity_precision("BTCTMN")
# {'q': 5, 'p': 0}      # q = quantity decimals, p = price decimals

get_best_bid_ask(market, count=2) -> dict

Returns the top count order-book levels for both sides.

wlx.get_best_bid_ask("USDTTMN", count=1)
# {
#   'bid': [{'price': 68500.0, 'vol': 1200.0}],
#   'ask': [{'price': 68520.0, 'vol':  850.0}]
# }

On repeated network failure returns ('server_error', 'server_error').

A common pattern (from real usage) is to derive top-of-book and mid price:

d = wlx.get_best_bid_ask("USDTTMN", count=1)
bid = float(d['bid'][0]['price'])
ask = float(d['ask'][0]['price'])
mid = (bid + ask) / 2.0

get_trades_list(symbol) -> dict

Returns recent public trades for a market. Retries up to 20 times on error.

---

Trading (private)

new_order(side, quantity, market, price=None, order_type='LIMIT', clientOrderId=None) -> dict

Places an order. Quantity and price are automatically rounded to the market's precision. Returns ('server_error', 'server_error') on repeated failure.

r = wlx.new_order(side="sell", quantity=4, market="TONUSDT", price=5.0)
if r.get("success"):
    order_id = r["result"]["clientOrderId"]

Example response:

{
  'result': {
    'symbol': 'TONUSDT',
    'type': 'LIMIT',
    'side': 'BUY',
    'clientOrderId': 'LIMIT-9cb33fb3-b052-4f9d-a152-f92d5168567a',
    'transactTime': 1722936818,
    'price': '5.0000000000000000',
    'origQty': '4.0000000000000000',
    'executedSum': '0.0000000000000000',
    'executedQty': '0.0000000000000000',
    'executedPrice': '5.0000000000000000',
    'sum': '20.0000000000000000',
    'executedPercent': 0,
    'status': 'NEW',
    'active': True,
    'fills': []
  },
  'message': 'Order placed',
  'success': True
}

new_order_market(side, quantity, market, order_type='MARKET') -> dict

Places a MARKET order (no price).

check_order(orderId) -> dict

Fetches the current status of an order by its clientOrderId. Retries up to 10 times; returns the string 'server error!' on failure.

Useful fields on result: status, active, executedQty, executedSum, executedPercent, price.

st = wlx.check_order(order_id)
res = st["result"]
executed_qty     = float(res["executedQty"])
executed_value   = float(res["executedSum"])
executed_percent = float(res["executedPercent"])
if executed_percent == 100.0:
    print("fully filled")

get_wallex_open_orders(market=None) -> list

Returns all open orders, optionally filtered by market.

open_orders = wlx.get_wallex_open_orders("DOGEUSDT")

cancel_order_wallex(orderId) -> dict

Cancels an order by id, with retries. On a non-final response it retries recursively until the order is confirmed cancelled or reported as not found.

res = wlx.cancel_order_wallex(order_id)
if res.get("success"):
    print("cancelled")

---

Account balances

get_balance(symbol=None, free=True) -> float | dict

• symbol=None → returns the full balances dict.
• symbol="USDT", free=True → returns available amount (value - locked).
• symbol="USDT", free=False → returns total value.

usdt_free  = wlx.get_balance("USDT", free=True)
tmn_total  = wlx.get_balance("TMN",  free=False)
all_bals   = wlx.get_balance()

---

Real-time depth streamer

price_streamer_wlx.py maintains an in-memory cache of best bid / ask / mid for a set of Toman markets over a Wallex WebSocket connection, and serves it via a small local HTTP API (FastAPI + uvicorn on 127.0.0.1:9101).

Run it:

python price_streamer_wlx.py

Query the cache:

curl http://127.0.0.1:9101/depth/BTCTMN

{
  "market": "BTCTMN",
  "bid": 63200000000.0,
  "ask": 63220000000.0,
  "mid": 63210000000.0,
  "ts": 1722936818.42
}

Returns 404 with {"error": "No data for <MARKET>"} if the market has not been received yet. Edit WALLEX_MARKETS in the file to change the subscription list.

---

Disclaimer

This is an unofficial, community SDK and is not affiliated with Wallex. Trading cryptocurrencies carries risk; use at your own responsibility and test carefully before running against a live account.