.. _api:

Usage
=====

.. _currencies:

Currency values
----------------

.. index::
   single: currency

Currently *cexiopy* supports the following currencies:

::

    'BTC' 'GHS' 'LTC' 'NMC'

You may want to avoid the hassle with hardcoded strings, mostly because of
their error-prone nature, and use the following helper class instead:

.. code-block:: python

    >>> from cexio.helpers import Currency
    >>> Currency.bitcoin # 'BTC'
    >>> Currency.gigahash # 'GHS'
    >>> Currency.litecoin # 'LTC'
    >>> Currency.namecoin # 'NMC'


Public functions
----------------

.. index::
   single: Public functions

.. note::
   This type of fucntions does not require authentication (HTTP GET method).


.. index::
   single: order book

.. _f_order_book:

order book
~~~~~~~~~~~~~~~~~~~~

    def order_book(pair):
        *Gets the 'bids' and 'asks' for the currrencies pair*

        **Parameters:**

        * ``pair`` is a list containing two currencies

        Returns a Python dictionary of recent 'bids' and 'asks' for the given currencies along with the timestamp:

        * **ask** a list containing the asked sell price and the amount
        * **bid** a list containing the asked buy price and the amount
        * **timestamp** UNIX timestamp

.. code-block:: python

    >>> cexio.order_book(['BTC', 'NMC'])

.. :ref:`currencies <currencies>`


.. index::
   single: ticker

.. _f_ticker:

ticker
~~~~~~~~~~~~~~~~~~~~

    def ticker(pair):
        *Gets the 'ticker' values for the past 24 hours*

        **Parameters:**

        * ``pair`` is a list containing two currencies

        Returns a Python dictionary of 'ticker' values for the past 24 hours:

            * **ask** value
            * **bid** value
            * **high** value
            * **last** value
            * **low** value
            * **timestamp** value
            * **volume** value

.. code-block:: python

    >>> cexio.ticker(['BTC', 'GHS'])


.. index::
   single: trade history

.. _f_trade_history:

trade history
~~~~~~~~~~~~~~~~~~~~

    def trade_history(pair):
        *Gets the recent trade history for the currrencies pair*

        **Parameters:**

        * ``pair`` is a list containing two currencies

        Returns a Python list of recent trades, where each trade is a Python dictionary:

.. code-block:: python

    >>> cexio.trade_history(['BTC', 'NMC'])

.. attention::
   *cexiopy* still does not support the optional *since* parameter (TBA).


Private functions
-----------------

.. note::
   This type of fucntions requires authentication.


.. index::
   single: login

.. _f_login:

login
~~~~~

    def login(username, api_key, api_secret):
        *Performs a 'lazy' login*

        **Parameters:**

        * ``username`` (*required*) your CEX.IO username
        * ``api_key`` (*required*) your CEX.IO API key
        * ``api_secret`` (*required*) your CEX.IO API secret

        Returns *None*

.. attention::
   The *login* function is required once -- before the
   execution of any private function.


.. index::
   single: open orders

.. _f_open_orders:

open orders
~~~~~~~~~~~~~~~~~~~~~~~~~~~

    def open_orders(pair)
        *Gets current orders*

        **Parameters:**

        * ``pair`` (*required*) the currencies pair

        Returns an empty Python list if no orders, otherwise a Python
        list where each element contains the following information:

            * **amount** the asked amount
            * **id** the order ID
            * **pending** the pending amount (if partially executed)
            * **price** the asked price
            * **time** UNIX timestamp
            * **type** the order type, could be either 'buy' or 'sell'

.. code-block:: python

    >>> from cexio.helpers import Currency

    >>> pair = [Currency.gigahash, Currency.namecoin]
    >>> cexio.open_orders(pair)


.. index::
   single: open orders

.. _f_cancel_order:

cancel order
~~~~~~~~~~~~~~~~~~~~~~~~~~~

    def cancel_order(id=order_id)
        *Cancel the given order*

        **Parameters:**

        * ``id`` (*required, named argument*) the order id

        Returns True upon success, otherwise a Python
        dictionary with the CEX.IO error

.. code-block:: python

    >>> pair = [Currency.gigahash, Currency.namecoin]
    >>> cexio.open_orders(id=1235813)
    True


.. index::
   single: buy Gigahashes with Bitcoins

.. _f_buy_gigahash_with_bitcoin:

buy Gigahashes with BTC
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    def buy_gigahash_with_bitcoin(amount, price):
        *Buy Gigahashes with Bitcoins*

        **Parameters:**

        * ``amount`` (*required*) the amount of asked Gigahashes
        * ``price`` (*required*) the price per Gigahash in Bitcoins

        Returns a Python dictionary with the order details:

            * **amount** the asked amount
            * **id** the order ID
            * **pending** the pending amount (if partially executed)
            * **price** the asked price
            * **time** UNIX timestamp
            * **type** the order type, could be either 'buy' or 'sell'

.. code-block:: python

    >>> cexio.buy_gigahash_with_bitcoin(amount=1, price=0.001) # highly unlikly


.. index::
   single: sell Gigahashes for Bitcoins

.. _f_sell_gigahash_for_bitcoin:

sell Gigahashes for BTC
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    def sell_gigahash_for_bitcoin(amount, price):
        *Sell Gigahashes for Bitcoins*

        **Parameters:**

        * ``amount`` (*required*) the amount of asked Bitcoins
        * ``price`` (*required*) the price per Gigahash in Bitcoins

        Returns a Python dictionary with the order details:

            * **amount** the asked amount
            * **id** the order ID
            * **pending** the pending amount (if partially executed)
            * **price** the asked price
            * **time** UNIX timestamp
            * **type** the order type, could be either 'buy' or 'sell'

.. code-block:: python

    >>> cexio.sell_gigahash_with_bitcoin(amount=1, price=100) # highly unlikly


.. index::
   single: buy Gigahashes with Namecoins

.. _f_buy_gigahash_with_namecoin:

buy Gigahashes with NMC
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    def buy_gigahash_with_namecoin(amount, price):
        *Buy Gigahashes with Namecoins*

        **Parameters:**

        * ``amount`` (*required*) the amount of asked Gigahashes
        * ``price`` (*required*) the price per Gigahash in Namecoins

        Returns a Python dictionary with the order details:

            * **amount** the asked amount
            * **id** the order ID
            * **pending** the pending amount (if partially executed)
            * **price** the asked price
            * **time** UNIX timestamp
            * **type** the order type, could be either 'buy' or 'sell'

.. code-block:: python

    >>> cexio.buy_gigahash_with_namecoin(amount=1, price=0.001) # highly unlikly


.. index::
   single: sell Gigahashes for NMC

.. _f_sell_gigahash_for_namecoin:

sell Gigahashes for NMC
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    def sell_gigahash_for_namecoin(amount, price):
        *Sell Gigahashes for Namecoins*

        **Parameters:**

        * ``amount`` (*required*) the amount of asked Namecoins
        * ``price`` (*required*) the price per Gigahash in Namecoins

        Returns a Python dictionary with the order details:

            * **amount** the asked amount
            * **id** the order ID
            * **pending** the pending amount (if partially executed)
            * **price** the asked price
            * **time** UNIX timestamp
            * **type** the order type, could be either 'buy' or 'sell'

.. code-block:: python

    >>> cexio.sell_gigahash_for_namecoin(amount=1, price=100) # highly unlikly


.. index::
   single: buy Litecoins with Bitcoins

.. _f_buy_litecoin_with_bitcoin:

buy LTC with BTC
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    def buy_litecoin_with_bitcoin(amount, price):
        *Buys Litecoins with Bitcoins*

        **Parameters:**

        * ``amount`` (*required*) the amount of asked Namecoins
        * ``price`` (*required*) the price per Namecoin in Bitcoins

        Returns a Python dictionary with the order details:

            * **amount** the asked amount
            * **id** the order ID
            * **pending** the pending amount (if partially executed)
            * **price** the asked price
            * **time** UNIX timestamp
            * **type** the order type, could be either 'buy' or 'sell'

.. code-block:: python

    >>> cexio.buy_litecoin_with_bitcoin(amount=1, price=0.001) # highly unlikly


.. index::
   single: sell Litecoins for Bitcoins

.. _f_sell_litecoin_for_bitcoin:

sell LTC for BTC
~~~~~~~~~~~~~~~~~~~~~~~~~~~

    def sell_litecoin_for_bitcoin(amount, price)
        *Sells Litecoins for Bitcoins*

        **Parameters:**

        * ``amount`` (*required*) the amount of asked Bitcoins
        * ``price`` (*required*) the price per Namecoin in Bitcoins

        Returns a Python dictionary with the order details:

            * **amount** the asked amount
            * **id** the order ID
            * **pending** the pending amount (if partially executed)
            * **price** the asked price
            * **time** UNIX timestamp
            * **type** the order type, could be either 'buy' or 'sell'

.. code-block:: python

    >>> cexio.sell_litecoin_for_bitcoin(amount=1, price=100) # highly unlikly


.. index::
   single: buy Namecoins with Bitcoins

.. _f_buy_namecoin_with_bitcoin:

buy NMC with BTC
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    def buy_namecoin_with_bitcoin(amount, price):
        *Buys Namecoins with Bitcoins*

        **Parameters:**

        * ``amount`` (*required*) the amount of asked Namecoins
        * ``price`` (*required*) the price per Namecoin in Bitcoins

        Returns a Python dictionary with the order details:

            * **amount** the asked amount
            * **id** the order ID
            * **pending** the pending amount (if partially executed)
            * **price** the asked price
            * **time** UNIX timestamp
            * **type** the order type, could be either 'buy' or 'sell'

.. code-block:: python

    >>> cexio.buy_namecoin_with_bitcoin(amount=1, price=0.001) # highly unlikly


.. index::
   single: sell Namecoins for Bitcoins

.. _f_sell_namecoin_for_bitcoin:

sell NMC for BTC
~~~~~~~~~~~~~~~~~~~~~~~~~~~

    def sell_namecoin_for_bitcoin(amount, price)
        *Sells Namecoins for Bitcoins*

        **Parameters:**

        * ``amount`` (*required*) the amount of asked Bitcoins
        * ``price`` (*required*) the price per Namecoin in Bitcoins

        Returns a Python dictionary with the order details:

            * **amount** the asked amount
            * **id** the order ID
            * **pending** the pending amount (if partially executed)
            * **price** the asked price
            * **time** UNIX timestamp
            * **type** the order type, could be either 'buy' or 'sell'

.. code-block:: python

    >>> cexio.sell_namecoin_for_bitcoin(amount=1, price=100) # highly unlikly