valr-py 0.3.1
Python SDK for the VALR REST API
License: MIT
Requires Python: >=3.6
Keywords: VALR,REST,API,Bitcoin,Ethereum,stream,websocket

========
Overview
========




A Python SDK for VALR cryptocurrency exchange APIs.


Installation
============

::

    pip install valr-py

You can also install the in-development version with::

    pip install https://github.com/Quirky-Fox/valr-py/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_py import Client
    >>> from valr_py.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_py import WebSocketClient
    >>> from valr_py.enum import TradeEvent
    >>> from valr_py.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.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.