.. _rst_order:

Order
=============

Overview
*************
Order is part of the backtest system of Nyxar. Although users do not interact directly with :class:`Order`, it is worthwhile to clarify some properties of it and the role it plays behind the scene. 

User's trading algorithms place and query orders in the :class:`BackExchange` through the API therein. :class:`BackExchange` determines whether orders are filled based on the order type and the ticker price. :class:`Transaction` are generated by the :ref:`rst_slippage`  to determine how (amount and price) orders are filled. 


API Reference
****************

.. py:class:: OrderSide(Enum)

	Enumeration of order side. 

	.. attribute:: Buy

	.. attribute:: Sell



.. py:class:: OrderType(Enum)

	Enumeration of order type. 

	.. attribute:: Market

		Market order. Market order will be filled as soon as it is accepted. Market order is also `all-or-none <https://en.wikipedia.org/wiki/All_or_none>`_ order, meaning either the order is filled in full or an :exc:`InsufficientFunds` exception is raised. 

	.. attribute:: Limit

		Limit order. Limit order will only be filled when the ticker price is higher/lower than the limit price for sell/buy orders. Limit order doesn't necessarily need to be filled in full. The filled amount at each time bar is determined the by :ref:`rst_slippage`. 

		Asset in the unfilled part of the order is not available for trading unless the order is cancelled. In order balance can be queried as `used` in :meth::`BackExchange.fetch_balance`. 

	.. attribute:: StopLimit

		Stop limit order. Stop limit order will become a limit order when the ticker price is lower/higher than the stop price for sell/buy orders. Note that whether to open a stop limit order is determined only by the ticker price. Slippage model is only effective in filling the order. 



.. py:class:: OrderStatus(Enum)

	Enumeration of order status. 

	.. attribute:: Submitted

		Orders submitted to the :ref:`order-queue` of :class:`BackExchange`. 

	.. attribute:: Accepted

		Orders accepted by the exchange but is not yet open. It is only applicable to stop limit orders. 

	.. attribute:: Open

		Open orders that are not filled yet. It is applicable to limit and stop limit orders. 

	.. attribute:: Filled

		Orders that are fully filled. 

	.. attribute:: Cancelled

		Orders that are cancelled before fully filled. 



.. py:class:: Order(timestamp, order_type, side, quote_name, base_name, amount, price, stop_price)
   
   .. attribute:: timestamp

      The timestamp when the order is created. 

   .. attribute:: datetime

      A `datetime` object converted from :attr:`Order.timestamp`. 

   .. attribute:: id

      The unique id of the order that is used to query the order in order queue or order books. 

   .. attribute:: status

      An :class:`OrderStatus` object represents the current order status. 

   .. attribute:: type

      An :class:`OrderType` object represents order type. 

   .. attribute:: side

      An :class:`OrderSide` object represents order side. 

   .. attribute:: quote_name

      The name of the quote asset. 

   .. attribute:: base_name

      The name of the quote asset. 

   .. attribute:: symbol

      The name of the trading pair symbol, which is `quote asset name/base asset name`. 

   .. attribute:: amount

      The total amount of the order. 

   .. attribute:: filled

      The filled amount of the order. 

   .. attribute:: remaining

      The remaining amount of the order. The relation `filled + remaining = amount` always holds true. 

   .. attribute:: filled_percentage

      The filled percentage of the order, computed as `100.0 * filled/amount`. 

   .. attribute:: price

      The limit price of the order. Applicable for limit order and stop limit order. For market order, it defaults to `0`. 

   .. attribute:: stop_price

      The stop limit price of the order. Applicable for stop limit order. For other order types, it defaults to `0`. 

   .. attribute:: transactions

      A list of :class:`Transaction` that accounts for the filled amount of the order. 

   .. attribute:: fee

      A dictionary of fees taken by the exchange. 

      ::

         >>> order.fee
         {'FOO': 0.05}

   .. attribute:: info

      A dictionary of order info.

      ::

         >>> order.info
         {'id': 4920631724339456104, 
          'datetime': '2018-02-02 14:26:00', 
          'timestamp': 1517599560000, 
          'status': 'filled', 
          'symbol': 'FOO/BAR', 
          'type': 'limit', 
          'side': 'buy', 
          'price': 0.000954, 
          'stop_price': 0, 
          'amount': 100, 
          'filled': 100, 
          'remaining': 0, 
          'transaction': [{'datetime': '2018-02-02 15:44:00', 'timestamp': 1517604240000, 'price': 0.00095367, 'amount': 100}], 
          'fee': {'FOO': 0.05}}

   .. method:: open()

   .. method:: accept()

   .. method:: cancel()

   .. method:: generate_transaction(amount, price, timestamp)

   .. method:: execute_transaction(transaction)

   .. method:: pay_fee(asset, amount)



.. py:class:: Transaction(quote_name, base_name, price, amount, side, timestamp)

   Attributes of :class:`Transaction` are very similar to those in :class:`Order`. In fact, :class:`Order` is inherited from :class:`Transaction` with more attributes and methods. 

   .. attribute:: timestamp

   .. attribute:: datetime

   .. attribute:: id

   .. attribute:: side

   .. attribute:: quote_name

   .. attribute:: base_name

   .. attribute:: symbol

   .. attribute:: amount

   .. attribute:: price

   .. attribute:: info

      ::

         >>> tx.info
         {'datetime': '2018-02-02 15:44:00', 'timestamp': 1517604240000, 'price': 0.00095367, 'amount': 100}