From 8f3c440bac990c88fceaf1e0364451fa93b21803 Mon Sep 17 00:00:00 2001 From: fredfortier Date: Thu, 31 Aug 2017 14:14:54 -0400 Subject: [PATCH] Created wiki documentation --- catalyst/__main__.py | 6 +- ..._dip_live.py => buy_low_sell_high_live.py} | 10 +- docs/live-trading-wiki.md | 105 ++++++++++++++++++ 3 files changed, 109 insertions(+), 12 deletions(-) rename catalyst/examples/{buy_the_dip_live.py => buy_low_sell_high_live.py} (93%) create mode 100644 docs/live-trading-wiki.md diff --git a/catalyst/__main__.py b/catalyst/__main__.py index 99d03a52..b11e7d04 100644 --- a/catalyst/__main__.py +++ b/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', diff --git a/catalyst/examples/buy_the_dip_live.py b/catalyst/examples/buy_low_sell_high_live.py similarity index 93% rename from catalyst/examples/buy_the_dip_live.py rename to catalyst/examples/buy_low_sell_high_live.py index 7ea58bf9..e3469079 100644 --- a/catalyst/examples/buy_the_dip_live.py +++ b/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( diff --git a/docs/live-trading-wiki.md b/docs/live-trading-wiki.md new file mode 100644 index 00000000..2d127ea2 --- /dev/null +++ b/docs/live-trading-wiki.md @@ -0,0 +1,105 @@ +

Live Trading

+This document explains how to get started with live trading. + +

Supported Exchanges

+Catalyst can trade against these exchanges: + +* Bitfinex, id=`bitfinex` +* Bittrex, id=`bittrex` + +

Authentication

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

Currency Symbols

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

Trading an Algorithm

+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)