arke_logo

Arke guide

Arke is a trading bot for creating liquidity and market depth on exchanges that built with the use of Openware stack. That bot has a set of strategies that implement different business logic. 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 a separate Arke instance for each set of strategies. If you overload Arke instance with lots of strategies it will cause troubles and errors in strategy executions.

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

Prerequisites

  • Ruby 2.x
  • UNIX/Linux or OS X environment

Keywords

  • 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 a buy-back strategy.
  • Strategy: It's a set of rules that define Arke behavior 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 the desired directory on your VM (PC), open the terminal, and run the next command to copy the source code:

git clone git@github.com: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 the execution was successful, run the next command to start the Arke:

bundle exec ./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 than one strategy in the file and can set a connection 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 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 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 block 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.

Example of account configuration

log_level: DEBUG

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 set up will be account Arke of your platform (the target exchange), which 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 an 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 the 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. An account that is using third-party source exchange does not require host or ws parameters as they are predefined, key and secret are required only if you are going to use a 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.
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 log information. That parameter supports the next valid values: true or false.
finex That parameter is defining if arke will use Finex API to create and delete orders true or Peatio API false. Set it according to the trading engine that is used by the platform
host It is a base URL of the target exchange that is used for API calls.
ws It is a WebSocket URL of the target exchange.
key It is a public key of the API key pair.
secret It is a private key (secret key) of the API key pair.
delay That parameter specifies minimum delay to respect between requests to corresponding exchange, in second (delay between creat/delete orders calls). You can set up less than a second delay.

Example of account configuration

accounts:
- id: demo
  driver: rubykube
  debug: false
  finex: true
  host: "https://demo.openware.com"
  ws: "wss://demo.openware.com"
  key: ""
  secret: ""
  delay: 0.1

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

# If you need you can add more accounts.

Strategies

Strategies module consists of the main configuration, parameter, and other sub-modules. Arke supports the next strategies: Copy, Orderback, Fixedprice, Microtrades and Microtrades-copy. Strategies can be tuned for different markets with the use of configuration. Below you can find a description of the 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, microtrades and microtrades-copy.
debug That parameter used to extend log 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 the delay in accounts and the rate limit in Peatio/Finex. 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 a Forex conversion rate that can be applied to the price of orders generated by the strategy. Below you can find a 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 the required parameters for static conversion rate.

Field Value Description
type "static" That parameter used to specify the type of conversion rate. To apply a 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.

Example of static conversion configuration

  fx:
    type: static
    rate: 123

Dynamic conversion

In the case, you want the conversion rate, to be dynamic you must use additional parameters. For dynamic conversion rate you will need to create an 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 the conversion rate type. To apply a 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.

Example of dynamic conversion configuration

  fx:
    type: fixer
    api_key: ""
    currency_from: EUR
    currency_to: USD

Configuration of target and source sub-modules

Those sub-modules define 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.

Example of target configuration*

  target:
    account_id: demo
    market_id: btcusdt

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.

Example of source configuration*

  sources:
  - account_id: binance
    market_id: BTCUSDT

Circuitbreaker sub-modules

These 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 has 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 to 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 used to 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 only manages the order book of the target exchange.

The Copy strategy parameters are generic for the rest of the 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 the 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 the trading (and withdrawal) fee if you want to use the 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 the 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 the trading (and withdrawal) fee if you want to use the 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 than 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 than 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 to fulfill the required liquidity at a certain price level.
side Defines a side/sides of the order book to populate it with orders. That parameter supports three 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

strategies:
- id: copy
  type: copy
  debug: false
  enabled: true
  period: 30
  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

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 exchange fee the P&L will be positive. Remember to add generic parameters (parameters that were specified in the Copy strategy description) to the Orderback strategy. Orderback performs with a 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 buyback order/s on the source exchange. For the same price trades, Arke creates one buyback order. If the price of trades were different Arke creates a 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 the 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.

Below is an example of the Orderback strategy

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

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 The minimum amount of order
max_amount The 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

strategies:
- id: microtrades-ETHUSD
  type: microtrades
  debug: true
  enabled: true
  period: 50
  period_random_delay: 10
  params:
    linked_strategy_id: copy-ETHUSD
    min_amount: 0.05
    max_amount: 0.30

Microtrades-copy strategy

This strategy creates random trades on a market with random amounts following the price of one or several sources. It is commonly used to create candles on a market with low activity.

Field Description
min_amount The minimum amount of order (defaults to market minimum order amount)
max_amount The maximum amount of order (defaults to 10 times the market minimum order amount)
maker_taker_orders_delay The time between maker and taker orders (defaults 0.02 sec)
matching_timeout Time in seconds to wait before canceling microtrades orders (defaults 1 sec)

Example of Microtrades-copy strategy configuration

strategies:
- id: microtrades-copy-ETHUSD
  type: microtrades-copy
  debug: false
  enabled: true
  period: 30
  period_random_delay: 10
  params:
    min_amount: 0.0001
    max_amount: 0.009
    maker_taker_orders_delay: 0.02
    matching_timeout: 1

Candle-Sampling strategy

This strategy copy trades from sources every sampling_ratio trade events. It will trigger a market order with the same amount as the trade being copied. The parameter max_slippage can protect against price slippage, it will consider the target order book and reduce the amount of the order accordingly to avoid price slippage. A random of 10% is applied to the sampling_ratio to make the strategy not deterministic. The period parameter doesn't affect this strategy since it only reacts to sources of trade events.

Field Description
sampling_ratio Number of trades to wait before copying one
max_slippage Maximum price slippage percent that allowed on a single trade triggered by the strategy

Example of Candle-Sampling strategy configuration

- id: BTCUSDT-candle
  type: candle-sampling
  debug: false
  enabled: true
  period: 1000
  params:
    sampling_ratio: 100000
    max_slippage: 0.001

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 The 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

- id: fixedprice-BTCUSDT
  type: fixedprice
  debug: false
  enabled: false
  period: 30
  params:
    price: 17131
    random_delta: 1000
    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

An example of strategies.yml file

Below you can find an example configuration with two strategies and two accounts.

log_level: INFO

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

- id: demo-2
  driver: rubykube
  debug: false
  host: "https://demo.openware.com"
  ws: "wss://demo.openware.com"
  key: ""
  secret: ""
  delay: 0.1

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

- id: bitfinex
  driver: bitfinex
  debug: false
  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-1
    market_id: ethjpy

  sources:
  - account_id: bitfinex
    market_id: ETHUSD    

#---------------------------{ Microtrades-copy strategy with a fixer for ETHJPY }-----------------------------
- id: microtrades-copy-ETHJPY
  type: microtrades-copy
  debug: false
  enabled: true
  period: 80
  period_random_delay: 5
  params: 
    min_amount: 0.000001
    max_amount: 0.00009
  fx:
    type: fixer
    api_key: ""
    currency_from: USD 
    currency_to: JPY
    period: 3600

  sources:
  - account_id: bitfinex
    market_id: ETHUSD

  target:
    account_id: demo-2
    market_id: ethjpy

#-------------------------{ Orderback strategy for BTCUSDT }-----------------#
- 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-1
    market_id: btcusdt

  sources:
  - account_id: binance
    market_id: BTCUSDT

#---------------------------{ Microtrade strategy for BTCUSDT }-----------------------------
- id: microtrades-BTCUSDT
  type: microtrades
  debug: false
  enabled: true
  period: 80
  period_random_delay: 5
  params: 
    linked_strategy_id: orderback-BTCUSDT
    min_amount: 0.000001
    max_amount: 0.0019
  sources:
  - account_id: binance
    market_id: BTCUSDT
  target:
    account_id: demo-2
    market_id: btcusdt

#---------------------------{ Copy strategy for BTCUSDT }-----------------------------
strategies:
- id: copy-BTCUSDT
  type: copy
  debug: false
  enabled: true
  period: 20
  params:
    spread_bids: 0.02
    spread_asks: 0.02
    limit_asks_base: 0.05
    limit_bids_base: 0.05
    max_amount_per_order: 0.00025
    levels_size: 2
    levels_count: 10
    side: both

  target:
    account_id: demo-1
    market_id: btcusdt

  sources:
  - account_id: binance
    market_id: BTCUSDT

#----------------------------------{ Fixedprice strategy for BTCUSDT }---------------------------------#     
- id: fixedprice-BTCUSDT
  type: fixedprice
  debug: false
  enabled: true
  period: 30
  params:
    price: 17131
    random_delta: 1000
    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: demo-2
    market_id: btcusdt

#---------------------------{ Candle strategy for BTCUSDT }-----------------------------------
- id: BTCUSDT-candle
  type: candle-sampling
  debug: false
  enabled: true
  period: 1000
  params:
    sampling_ratio: 100000
    max_slippage: 0.0
  target:
    account_id: demo-2
    market_id: btcusdt
  sources:
  - account_id: binance
    market_id: BTCUSDT