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