Documentation

API Docs Technical Docs User Guides Changelogs

Versions

arke_logo

# Arke guide

Arke is a trading bot for creating liquidity and market depth on exchanges that built with a use of Openware stack. That bot has a set of strategies that implement different business logics. Arke uses API keys to connect to the exchange. Anyone who has an account on the exchange can create API keys and start Arke to provide liquidity.

One strategy instance can work only with one market pair. To market make more than one market pair you will need to create a strategy per a market pair. If you want, you can apply a few strategies to a one market pair. Every strategy should use separate Arke instance for each set of strategies. If you overload Arke instance with lots of strategies it will cause troubles and errors in strategies executions.

Note: You should know that if you stopping Arke, orders that were created remaining in the order book until they will be cancelled manually or executed.

Prerequisites

Ruby 2.x
UNIX/Linux or OS X environment

Key words

Target exchange: It's an exchange that we connect to create liquidity.
Source exchange: It's an exchange from which we get price feed and can implement buy-back strategy.
Strategy: It's a set of rules that define Arke behaviour on a target exchange or/and source exchange based on the market conditions.
Bid-Ask spread: It's a difference between the price of the best bid (a buy order with the highest price) and the price of the best ask (a sell order with the lowest price).

#How to clone Arke

Go to a desired directory on your VM (PC), open terminal and run the next command to copy the source code:

git clone [email protected]:openware/arke.git

#How to start Arke

Open a terminal in the Arke folder and to run the next command to install all dependencies:

bundle install      #Once per Arke clone

If execution was successful, run the next command to start the Arke:

./bin/arke start    #To start Arke

Note: To successfully start Arke you will need to configure a strategy.

# How to configure an Arke strategy

Strategy can be configured in the strategies.yml file that is located in /arke/config/ directory. You can configure more then one strategy in the file and can set a connect with target and source exchanges. Below you can find descriptions of major sections and parameters specification of the configuration file.

#Log level configuration

That parameter used to show logs of Arke's activities. Depends on the details of the log you want to get from Arke, you can use one of the few parameter's values. Each next log level contains details of the previous log level as you can see below.

FATAL > ERROR > WARN > INFO > DEBUG

FATAL - includes only fatal error messages that cause of Arke suspension.
ERROR - includes messages about Arke's incapability to perform planned actions due to an error or lack of environment.
WARN - includes messages about important events that can influence Arke's work or events that blocks the execution of some actions.
INFO - includes short readable messages that show Arke's decision and action as a result of the decision.
DEBUG - includes WebSocket messages, full API response for every performed request and actions that Arke performs with the received information.

Under log_level parameter you need to configure accounts that will be used by Arke to execute different strategies.

#Account configurations

Module accounts used to configure connections with exchanges that you need for your strategies. The first account you would want to setup will be account Arke of your platform (the target exchange), that will connect to Peatio and Barong Api using rubykube driver. To configure a connection with the target exchange you need to create an API key pair. The key and secret should be created on your platform by creating an account for Arke, enabling 2FA and creating API key from a Profile tab if use BaseApp frontend or with Barong REST-API.

Note: Save a secret in a safe place because it displays only once. Disabling 2FA or sealing Vault (secure store) leads to inactivation of API key pairs.

Arke supports the next trading platforms binance, bitfinex, kraken. Those platforms can be used as a source exchange for your strategy. Account that is using third-party source exchange do not require host or ws parameters as they are predefined, key and secret are required only if you are going to user strategy that interacts with account balance on the target exchange (e.i., the Orderback strategy). To configure the Orderback strategy, you will need to create an API key pair on the source exchange.

Field	Description
`id`	That parameter is used to identify an exchange account. That parameter must be unique for the `strategies.yml` file. What symbols we support?
`driver`	That parameter is defining an exchange driver that allows Arke to communicate with an exchange. Arke supports the next values: `rubykube`, `binance`, `bitfinex`, `kraken`. The `rubykube` driver requires additionally two parameters to specify the target exchange: `host` and `ws`.
`debug`	That parameter used to extend logs information. That parameter supports the next valid values: `true` or `false`.
`host`	It is a base URL of the target exchange that used for API calls.
`ws`	It is a WebSocket URL of the target exchange.
`key`	It is a public key of API key pair.
`secret`	It is a private key (secret key) of API key pair.
`delay`	That parameter specify minimum delay to respect between requests to corresponding exchange (in second). You can set up less than a second delay.

Example of account settings

log_level: INFO

#--------------------------{ Accounts that Arke going to use }---------------------------#
accounts:
- id: demo
  driver: rubykube
  debug: false
  host: "https://demo.openware.com"
  ws: "wss://demo.openware.com"
  key: ""
  secret: ""
  delay: 1

- id: binance 
  driver: binance
  debug: true
  key: ""
  secret: ""
  delay: 1

# If you need you can add more accounts.

#Strategies

Strategies module consist of main configuration parameter and other sub-modules. Arke supports the next strategies: Copy, Orderback, Fixedprice and Microtrades. Strategies can be tune for different markets with a use of configuration. Below you can find description of main configuration parameters.

Field	Description
`id`	It is an identifier of a strategy. This parameter must be unique.
`type`	That parameter specifies a strategy type. Arke supports the next strategies: `copy`, `orderback`, `fixedprice` and `microtrades`.
`debug`	That parameter used to extend logs information. That parameter supports the next valid values: `true` or `false`.
`enabled`	That parameter used to enable or disable a strategy. Use the `true` value to enable strategy or the `false` value to disable it.
`period`	That parameter used to set a delay between the strategy iterations. Copy strategy gets order book of target exchange, compare with a current order book on the source exchange, applies required changes by deleting old orders and creating new orders, then wait specified `Period` and repeat the process. Microtrades strategy use `Period` as a delay between performed trades. Remember about delay in accounts and the rate limit in Peatio. Value specified in seconds.
`period_random_delay`	That parameter adds a random delay to `period` parameter. It helps to make it more difficult to recognize the pattern for malicious users. Value specified in seconds.
`fx`	That is a sub-module that provides Forex conversion rate that can be applied to the price of orders that generated by the strategy. Below you can find description of `fx` sub-module parameters.

# Configuration of the `fx` sub-module

This module mostly used with Copy strategies. When the source exchange has a marker pair with the same base currency but with the different quote currency as on the target exchange, the fx sub-module allows doing a quote conversion. So, that sub-module helps to create liquidity on market pairs of the target exchange that does not exist on other supported platforms.

#Static conversion

The fx sub-module can be used with the static conversion rate. In that case, a currency that should be converted will always have the same conversion rate. Below you can find required parameters for static conversion rate.

Field	Value	Description
`type`	"static"	That parameter used to specify the type of conversion rate. To apply static conversion rate in the `fx` sub-module use the next value: "static".
`rate`	float	That parameter used to specify the rate of conversion. The rate value applies to the prices of the strategy.

#Dynamic conversion

In the case, you want conversion rate to be dynamic you must use additional parameters. For dynamic conversion rate you will need to create API key on the Fixer. Below you can find required parameters for dynamic conversion rate.

Field	Value	Description
`type`	"fixer"	That parameter used to specify conversion rate type. To apply dynamic conversion rate in the `fx` sub-module use the next value: "fixer".
`api_key`	string	That parameter used to set your Fixer API key.
`currency_from`	string	The currency to which exchange rates are relative to. (If 1 USD = X EUR, USD is the base currency).
`currency_to`	string	The currency an amount is converted to. (If 1 USD = X EUR, EUR is the target currency)
`period`	seconds	That parameter used to specify refresh rate in seconds (how often you pull a conversion rate from the Fixer. The default value is 3600 if this parameter is not set.

# Configuration of `target` and `source` sub-modules

Those sub-modules defines which account will be used as a target exchange and which will be used as a source exchange. If you are setting rubykube driver as a target or source you should type market_id in lowercase. For other drivers market id must be uppercase.

#Target configuration

Field	Description
`account_id`	It is an ID of an account that was configured by you in the `accounts` module. Arke will use that account as a target exchange and will place orders on it.
`market_id`	It is an ID of the market on the target exchange on which we apply the strategy.

#Sources configuration

Field	Description
`account_id`	It is an ID of an account that was configured by you in the `accounts` module. Arke will use that account as a source exchange and will fetch the data from it.
`market_id`	It is an ID of the market on the source exchange from which we will fetch data.

# Circuitbreaker sub-modules

This sub-modules monitors orders on an account, compare prices with a source exchange and cancel those which are too far from current orderbook offers on the source.

It is a security in case the strategy which creates the market crash or have a defect.

Field	Description
`spread_bids`	Spread to apply on bids side (in percentage)
`spread_asks`	Spread to apply on asks side (in percentage)

The spread applied on circuitbreaker sub-modules should be lower than the spread used by the strategy creating the order book.

# Configuration of the `parameters` sub-module

Parameters sub-module contains parameters that used do define a certain strategy configuration.

# Copy strategy

This strategy uses the order book data from a source exchange, processed the data with strategy configurations and populates the order book of a target exchange with orders. Copy strategy doesn't do trades it's only manage order book of the target exchange.

The Copy strategy parameters are generic for the rest of strategies. Other strategies use the same parameters plus custom ones.

Field	Description
`spread_bids`	Defines a spread to be applied to the best bid from the target exchange. It means that a price of the best bid on the target exchange will be lower than the price of the best bid on the source exchange. You can use that parameter to include trading (and withdrawal) fee if you want to use Orderback strategy. Spread must be set in a decimal format
`spread_asks`	Defines a spread to be applied to the best ask from the target exchange. It means that a price of the best ask on the target exchange will be higher than the price of the best ask on the source exchange. You can use that parameter to include trading (and withdrawal) fee if you want to use Orderback strategy. Spread must be set in a decimal format
`limit_asks_base`	Defines the max amount of base currency that Arke can place for sale in the order book. For example, for BTC/USD pair if you set 10 it means that amount of all orders for sale will be equal/less then 10 BTC.
`limit_bids_base`	Defines the max amount in a base currency equivalent that can be placed for buy in the order book by Arke. For example, for BTC/USD pair if you set 10 it means that equivalent of all orders to be created equal/less then 10 BTC.
`levels_size`	Defines a minimum price difference between orders. Arke process orders from the source exchange and populate orders with applied parameter on the target exchange.
`levels_count`	Defines price levels quantity to be created on the asks and bids sides. For example, if you set 10, Arke will create 10 price levels on the bid side and 10 price levels on the ask side. This parameter must be an integer.
`max_amount_per_order`	Defines a maximum amount (in base currency) to be placed in a buy/sell order. If the current market situation requires more liquidity at a certain price level, Arke creates additional orders with a max amount value to fulfil required liquidity at a certain price level.
`side`	Defines a side/sides of the order book to populate it with orders. That parameter supports tree valid values: `asks`, `bids`, `both`. If you choose `asks` or `bids`, Arke will populate only one side of the order book. To populate the order book with asks and bids use the value `both`.

Below is an example of Copy strategy with static price conversion from USD to KRW by the rate of 1158 KRW per USD

#------------------------------------{ static-ETHKRW }-----------------------------------# 
strategies:
- id: static-ETHKRW
  type: copy
  debug: false
  enabled: true
  period: 30
  fx:
    type: static
    rate: 1158
  params:
    spread_bids: 0.003
    spread_asks: 0.003
    limit_asks_base: 40
    limit_bids_base: 40
    max_amount_per_order: 10
    levels_size: 1
    levels_count: 10
    side: both
  target:
    account_id: demo
    market_id: ethkrw

  sources:
  - account_id: bitfinex
    market_id: ETHUSD

# Orderback strategy

This strategy behaves like the Copy strategy and provides the ability to order back an amount on the source exchange market. Orderback strategy takes place in the case Arke order on the target exchange was matched with a user order. As soon as an order is matched, the strategy creates an order on the source exchange with the matched amount and the same price without the spread. This way if the spread configured is higher than the exchanges fee the P&L will be positive. Remember to add generic parameters (parameters that was specified in Copy strategy description) to the Orderback strategy. Orderback performs with 1-sec delay this parameter is not configurable (but it can be changed in the source code of Arke). During the 1-sec delay, Arke accumulates trades and after 1 sec Arke creates buy back order/s on the source exchange. For the same price trades, Arke creates one buy back order. If the price of trades were different Arke creates corresponding amount of orders on the source exchange.

Field	Description
`enable_orderback`	That parameter used to enable or disable order-back feature. Use the `true` value to enable order-back feature or the `false` value to disable it.
`min_order_back_amount`	The amount of the trade must be higher than this value for the order back to be created, otherwise the trade will be ignored.

#---------------------------------{ orderback-BTCUSDT }----------------------------------#
strategies:
- id: orderback-BTCUSDT
  type: orderback
  debug: false
  enabled: true
  period: 90
  params:
    spread_bids: 0.005
    spread_asks: 0.005
    limit_asks_base: 10
    limit_bids_base: 10
    max_amount_per_order: 0.5
    levels_size: 0.5
    levels_count: 5
    side: both
    enable_orderback: true
    min_order_back_amount: 0.002

  target:
    account_id: demo
    market_id: BTCUSDT

  sources:
  - account_id: binance
    market_id: BTCUSDT

# Microtrades strategy

This strategy can be used to create random auto trades with a certain periodicity. Microtreades strategy employs a market order, it means that a microtrade executes against the best bid or the best ask.

Field	Description
`linked_strategy_id`	OPTIONAL. ID of strategy which will be referred (using for calculating price)
`price_difference`	OPTIONAL. Change of calculated price (using if `linked_strategy_id` exist)
`min_amount`	Minimum amount of order
`max_amount`	Maximum amount of order
`min_price`	OPTIONAL. Price for ask orders (using if `linked_strategy_id` doesn't exist)
`max_price`	OPTIONAL. Price for bid orders (using if `linked_strategy_id` doesn't exist)

Example of Microtrades strategy configuration

#----------------------------------{ microtrades-ETHUSD }--------------------------------#
strategies:
- id: microtrades-ETHUSD
  type: microtrades
  debug: true
  enabled: false
  period: 5
  period_random_delay: 10
  params:
    linked_strategy_id: copy-ETHUSD
    min_amount: 0.05
    max_amount: 0.30

  target:
      account_id: demo
      market_id: ethusd

# Fixedprice strategy

This strategy is used to provide liquidity for a market of a stable currency. It creates buy and sell orders with a specified price range without using any source market.

Field	Description
`price`	Reference price for the strategy to create orderbook
`random_delta`	Random value for deviation of the reference price (maximum deviation = random_delta / 2)

Example of Fixedprice strategy configuration

#----------------------------------{ fixedprice-BTCKRW }---------------------------------#     
- id: fixedprice-BTCKRW
  type: fixedprice
  debug: false
  enabled: false
  period: 30
  params:
    price: 11154108
    random_delta: 50000
    spread_bids: 0.003
    spread_asks: 0.003
    limit_asks_base: 40
    limit_bids_base: 40
    max_amount_per_order: 4
    levels_size: 1
    levels_count: 10
    side: both
  target:
    account_id: APRO
    market_id: btckrw

#An example of `strategies.yml` file

Below you can find an example configuration with two strategies and two accounts. Be sure to not overload the configuration file with lots of strategies because it can cause lagging and incorrect work.

log_level: INFO

#-----------------------------{ Accounts that Arke going to use }------------------------#
accounts:
- id: demo
  driver: rubykube
  debug: false
  host: "https://demo.openware.com"
  ws: "wss://demo.openware.com"
  key: ""
  secret: ""
  delay: 1

- id: binance
  driver: binance
  debug: true
  key: ""
  secret: ""
  delay: 1

#--------------------------{ Copy strategy with a fixer for ETHJPY }---------------------# 
strategies:
- id: fixer-ETHJPY
  type: copy
  debug: false
  enabled: true
  period: 30
  fx:
    type: fixer
    api_key: ""
    currency_from: USD 
    currency_to: JPY
    period: 3600
  params:
    spread_bids: 0.003
    spread_asks: 0.003
    limit_asks_base: 40
    limit_bids_base: 40
    max_amount_per_order: 10
    levels_size: 1
    levels_count: 10
    side: both
  
  target:
    account_id: demo
    market_id: ethjpy

  sources:
  - account_id: binance
    market_id: ETHUSD    

#-------------------------{ Orderback strategy with a fixer for ETHJPY }-----------------#
- id: orderback-BTCUSDT
  type: orderback
  debug: false
  enabled: true
  period: 90
  params:
    spread_bids: 0.005
    spread_asks: 0.005
    limit_asks_base: 10
    limit_bids_base: 10
    max_amount_per_order: 0.5
    levels_size: 0.5
    levels_count: 5
    side: both
    enable_orderback: true
    min_order_back_amount: 0.002

  target:
    account_id: demo
    market_id: ethjpy

  sources:
  - account_id: binance
    market_id: ETHUSD