Python SDK for VALR exchange APIs

starsStars 4
forksForks 2
watchersWatchers 4
current-versionCurrent version
total-releasesTotal releases 0
open_issues_countOpen issues 3
dateFirst release -
dateLatest release -
updateLast update 2020-12-16



A Python SDK for VALR cryptocurrency exchange APIs.


pip install valr-python

You can also install the in-development version with:

pip install


Authenticating to VALR API private resources requires a valid API Key from the VALR exchange.

Synchronous REST API Client

To use the synchronous REST API client:

>>> from valr_python import Client
>>> from valr_python.exceptions import IncompleteOrderWarning
>>> from decimal import Decimal
>>> c = Client(api_key='api_key', api_secret='api_secret')
>>> c.rate_limiting_support = True # honour HTTP 429 "Retry-After" header values
>>> limit_order = {
...     "side": "SELL",
...     "quantity": Decimal('0.1'),
...     "price": Decimal('10000'),
...     "pair": "BTCZAR",
...     "post_only": True,
... }
>>> try:
...    res = c.post_limit_order(**limit_order)
...    order_id = res['id']
...    print(order_id)
... except IncompleteOrderWarning as w:  # HTTP 202 Accepted handling for incomplete orders
...    order_id =['id']
...    print(order_id)
... except Exception as e:
...    print(e)

Asynchronous REST API Client

The asynchronous REST API client is still in development. Coming soon!

WebSocket API Client

To use the WebSocket API client:

>>> import asyncio
>>> from typing import Dict
>>> from pprint import pprint
>>> from valr_python import WebSocketClient
>>> from valr_python.enum import TradeEvent
>>> from valr_python.enum import WebSocketType
>>> def pretty_hook(data: Dict):
...    pprint(data)
>>> c = WebSocketClient(api_key='api_key', api_secret='api_secret', currency_pairs=['BTCZAR'],
...           ,
...                     trade_subscriptions=[],
...                     hooks={ : pretty_hook})
>>> loop = asyncio.get_event_loop()
>>> loop.run_until_complete(
{'currencyPairSymbol': 'BTCZAR',
 'data': {'askPrice': '151601',
          'baseVolume': '314.7631144',
          'bidPrice': '151600',
          'changeFromPrevious': '2.14',
          'created': '2020-02-06T22:47:03.129Z',
          'currencyPairSymbol': 'BTCZAR',
          'highPrice': '152440',
          'lastTradedPrice': '151600',
          'lowPrice': '146765',
          'previousClosePrice': '148410',
          'quoteVolume': '47167382.04552981'},

This library leverages websockets and asyncio and is thus a coroutine-based API client. Both of VALR's Account WebSocket connection and Trade WebSocket connection API endpoints are included. Furthermore, the SDK fully supports VALR's subscription methods for both Account and Trade endpoints. Please see the VALR API documentation for further information.

For each subscription, a hook must be provided to process the WS responses. Failing to do so raises a HookNotFoundError exception. For ease of use, several Enum classes have been implemented (as showcased above) for client instantiation and hook consumption of API responses. However, client input is accepted in str format.

Although not completely minimalistic, please note that the SDK is implemented as a thin client and parsing of API streams response is left up to the application user.


To execute all tests run:


Note, to combine the coverage data from all the tox environments run:

set PYTEST_ADDOPTS=--cov-append
PYTEST_ADDOPTS=--cov-append tox


If this library has helped you or if you would like to support future development, donations are most welcome:

Cryptocurrency Address
BTC 38c7QWggrB2HLUJZFmhAC2zh4t8C57c1ec
ETH 0x01eD3b58a07c6d005281Db76e6c1AE2bfF2226AD