valr-python

======== Overview

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 <https://www.valr.com/>_.

Synchronous REST API Client

To use the synchronous REST API client:

.. code-block:: python

>>> 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:

.. code-block:: python

>>> 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 :code:websockets and :code: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 :code:Account and :code:Trade endpoints. Please see the VALR API documentation <https://docs.valr.com/>_ for further information.

For each subscription, a hook must be provided to process the WS responses. Failing to do so raises a :code:HookNotFoundError exception. For ease of use, several :code:Enum classes have been implemented (as showcased above) for client instantiation and hook consumption of API responses. However, client input is accepted in :code: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:

.. list-table:: :widths: 10 90 :stub-columns: 1

- - 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.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.