valr-py 0.3.0

Python SDK for the VALR REST API

A Python SDK for VALR cryptocurrency exchange APIs.

Installation

pip install valr-python

You can also install the in-development version with:

pip install https://github.com/jonathanelscpt/valr-python/archive/master.zip

Authentication

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 = w.data['id']
...    print(order_id)
... except Exception as e:
...    print(e)
"558f5e0a-ffd1-46dd-8fae-763d93fa2f25"

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'],
...                     ws_type=WebSocketType.TRADE.name,
...                     trade_subscriptions=[TradeEvent.MARKET_SUMMARY_UPDATE.name],
...                     hooks={TradeEvent.MARKET_SUMMARY_UPDATE.name: pretty_hook})
>>> loop = asyncio.get_event_loop()
>>> loop.run_until_complete(c.run())
{'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'},
 'type': 'MARKET_SUMMARY_UPDATE'}

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.

Development

To execute all tests run:

tox

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

Windows	set PYTEST_ADDOPTS=--cov-append tox
Other	PYTEST_ADDOPTS=--cov-append tox

Donate

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

Changelog

0.3.0 (2023-04-20)

• Added new API features:

• Add fiat bank accounts APIs

• Add VALR Pay APIs

• Added formatting of balances as a convenience function

0.2.7 (2021-12-06)

• Enum support for SOLZAR

0.2.6 (2021-11-15)

• added subaccount support

• added all rest api endpoint changes for 2021

• api renaming to align with VALR api docs

• unit tests extended to support endpoint changes and subaccount feature

0.2.5 (2021-11-02)

• bank fast withdrawal support

0.2.4 (2020-09-27)

• build stability bugfixes

0.2.3 (2020-09-27)

• replaced json with simplejson for speed improvements

0.2.2 (2020-05-25)

• renamed several sdk methods for API standardization

• added enums for REST API

• added support for simple enum str printing

• added type support for enums

• added XRPZAR support in currency enum

0.2.1 (2020-05-25)

• Decimal support and JSON serialization handling

• added typing support for all API calls

• async support for VALR’s beta websocket API

• additional api documentation

• build automation extensions

0.1.7 (2020-01-11)

• Standardised api attribute naming in Client

• Updated doctest and readme for more detailed SDK description

0.1.6 (2020-01-11)

• Added custom warning IncompleteOrderWarning on receiving 202 Accepted response to support custom handling of incomplete orders

• Added custom warning TooManyRequestsWarning during 429 handling

• Added class flag for enabling or disabling 429 handler

0.1.5 (2020-01-11)

• Expanded test suites to unit, functional and live integration testing

• Internal class refactoring

• Added optional HTTP 429 handling by honouring the “Retry-After” header value sent in VALR responses

0.1.4 (2020-01-04)

• Streamlined ordering api calls with decorators

• Added typing support

• Re-worked class design internals to support later async expansion

• Fixed bugs with str ‘None’ insertion with f-strings

• Expanded unit tests to cover all api endpoints for synchronous client

0.1.3 (2020-01-02)

• Fixed defect with empty body signed signatures

• Updated class importing

• Added additional docstrings and unit tests

0.1.2 (2019-12-31)

• Updated readme and documentation

0.1.1 (2019-12-31)

• corrected build error issue in setup.py

0.1.0 (2019-12-29)

• Initial PyPi release

0.0.0 (2019-12-27)

• Alpha-only. Not released on PyPI.