Created wiki documentation

catalyst/__main__.py

@@ -196,13 +196,13 @@ def ipython_only(option):
 @click.option(
     '-x',
     '--exchange-name',
-    type=click.Choice({'bitfinex'}),
-    help='The name of the exchange (supported: bitfinex).',
+    type=click.Choice({'bitfinex', 'bittrex'}),
+    help='The name of the targeted exchange (supported: bitfinex, bittrex).',
 )
 @click.option(
     '-n',
     '--algo-namespace',
-    help='A label assigned to the algorithm for tracking purposes. '
+    help='A label assigned to the algorithm for data storage purposes.'
 )
 @click.option(
     '-c',

catalyst/examples/buy_low_sell_high_live.py

@@ -47,7 +47,7 @@ def _handle_data(context, data):
         buy_increment = 50
     elif rsi <= 40:
         buy_increment = 20
-    elif rsi <= 90:
+    elif rsi <= 70:
         buy_increment = 5
     else:
         buy_increment = None
@@ -72,14 +72,6 @@ def _handle_data(context, data):
     cost_basis = None
     if context.asset in context.portfolio.positions:
         position = context.portfolio.positions[context.asset]
-        # TODO: temp test
-        if position.amount > 0:
-            order_target_percent(
-                asset=context.asset,
-                target=0,
-                limit_price=price * (1 - context.SLIPPAGE_ALLOWED),
-            )
-            return
 
         cost_basis = position.cost_basis
         log.info(

docs/live-trading-wiki.md

@@ -0,0 +1,105 @@
+<h1>Live Trading</h1>
+This document explains how to get started with live trading.
+
+<h2>Supported Exchanges</h2>
+Catalyst can trade against these exchanges:
+
+* Bitfinex, id=`bitfinex`
+* Bittrex, id=`bittrex`
+
+<h3>Authentication</h3>
+Most exchanges require key/token combination for authentication. By
+convention, Catalyst uses an "auth.json" file to hold this data.
+
+This example illustrates the convention using the Bitfinex exchange.
+Here is how to generate key and secret values for bitfinex:
+https://docs.bitfinex.com/v1/docs/api-access. Most exchanges follow
+a similar process.
+
+The auth.json file:
+```json
+{
+  "name": "bitfinex",
+  "key": "my-key",
+  "secret": "my-secret"
+}
+```
+
+The file goes here:
+```
+~/.catalyst/data/exchanges/bitfinex/auth.json
+```
+
+Note that the 'bitfinex' directory corresponds to the id of the Bitfinex
+exchange as defined in the "Supported Exchanges" section above.
+Attempting to run an algorithm where the targeted exchange is missing
+its "auth.json" file will create the directory structure but result
+in an error.
+
+<h3>Currency Symbols</h3>
+Catalyst introduces a universal convention to reference
+trading pairs and individual currencies. This
+is required to ensure that the `symbol()` api predictably
+returns the correct asset regardless of the targeted exchange.
+
+Exchanges tend to use their own convention to represent currencies
+(e.g. XBT and BTC both represent Bitcoin on different exchanges).
+Trading pairs are also inconsistent. For example, Bitfinex
+puts the market currency before the base currency without a
+separator, Bittrex puts the base currency first and uses a dash
+seperator.
+
+Here is the Catalyst convention:
+
+*[Market Currency]_[Base Currency]* all lowercase.
+
+Currency symbols (e.g. btc, eth, ltc) follow the Bittrex convention.
+
+Here are some examples:
+```python
+# With Bitfinex
+bitcoin_usd_asset = symbol('btc_usd')
+ethereum_bitcoin_asset = symbol('eth_btc')
+
+# With Bittrex
+ethereum_bitcoin_asset = symbol('eth_btc')
+neo_ethereum_asset = symbol('neo_eth)
+```
+
+Note that the trading pairs are always referenced in the same manner.
+However, not all trading pairs are available on all exchanges. An
+error will occur if the specified trading pair is not trading
+on the exchange.
+
+<h2>Trading an Algorithm</h2>
+There are no special convention to follow when writing an
+algorithm for live trading. The same algorithm should work in
+backtest and live execution mode without modification.
+
+What differs are the arguments provided to the catalyst client or
+`run_algorithm()` interface. Here is example:
+
+```python
+run_algorithm(
+    initialize=initialize,
+    handle_data=handle_data,
+    analyze=analyze,
+    exchange_name='bitfinex',
+    live=True,
+    algo_namespace='my_algo_trading_xrp',
+    base_currency='btc'
+)
+```
+
+Here is the breakdown of the new arguments:
+* live: Boolean flag which enables live trading.
+* exchange_name: The name of the targeted exchange
+    (supported values: *bitfinex*, *bittrex*).
+* algo_namespace: A arbitrary label assigned to your algorithm for
+    data storage purposes.
+* base_currency: The reference currency used to calculate the
+    statistics of your algorithm. Currently, the base currency of all
+    trading pairs of your algorithm must match this value.
+
+Here is a complete algorithm for reference:
+[Buy Low and Sell High](../catalyst/examples/buy_low_sell_high_live.py)