NAME

cryp-arbit - Cryptocurrency arbitrage utility

VERSION

This document describes version 0.010 of cryp-arbit (from Perl distribution App-cryp-arbit), released on 2021-05-26.

SYNOPSIS

In ~/.config/cryp-arbit.conf (or ~/.config/cryp.conf as the configuration can be shared between cryp-* family of scripts):

[program=cryp-arbit]
db_name = cryp_arbit
; db_username = youruser         ; optional, will be searched in ~/.my.cnf
; db_password = yourpass         ; optional, will be searched in ~/.my.cnf

[exchange/indodax]
api_key = ...
api_secret = ...<

[exchange/coinbase-pro]
api_key = ...
api_secret = ...
api_passphrase = ...

Collecting orderbooks

To collect orderbooks (for e.g. backtesting data later):

% cryp-arbit collect-orderbooks

Performing arbitrage

Then to test:

% cryp-arbit opportunities
% cryp-arbit arbit --debug --dry-run

To really create sell/buy orders:

% cryp-arbit arbit

To list created order pairs:

% cryp-arbit order-pairs
% cryp-arbit order-pairs --open

To check the status of created orders (and cancel orders that are not being filled for too long):

% cryp-arbit check-orders

To get profit report:

% cryp-arbit profit-report

# Use specified USD spot rates (e.g. USD/IDR=14500, USD/THB=33.25)
% cryp-arbit profit-report --usd-rate IDR=14500 --usd-rate THB=33.25

For other subcommands, use cryp-arbit --help or see the documentation.

DESCRIPTION

SUBCOMMANDS

arbit

Perform arbitrage.

This utility monitors prices of several cryptocurrencies ("base currencies", e.g. LTC) in several cryptoexchanges. The "quote currency" can be fiat (e.g. USD, all other fiat currencies will be converted to USD) or another cryptocurrency (usually BTC).

When it detects a net price difference for a base currency that is large enough (see min_net_profit_margin option), it will perform a buy order on the exchange that has the lower price and sell the exact same amount of base currency on the exchange that has the higher price. For example, if on XCHG1 the buy price of LTC 100.01 USD and on XCHG2 the sell price of LTC is 98.80 USD, then this utility will buy LTC on XCHG2 for 98.80 USD and sell the same amount of LTD on XCHG1 for 100.01 USD. The profit is (100.01 - 98.80 - trading fees) per LTC arbitraged. You have to maintain enough LTC balance on XCHG1 and enough USD balance on XCHG2.

The balances are called inventories or your working capital. You fill and transfer inventories manually to refill balances and/or to collect profits.

check-orders

Check the orders that have been created.

This subcommand will check the orders that have been created previously by arbit subcommand. It will update the order status and filled size (if still open). It will cancel (give up) the orders if deemed too old.

collect-orderbooks

Collect orderbooks into the database.

This utility collect orderbooks from exchanges and put it into the database. The data can be used later e.g. for backtesting.

dump-cryp-config

opportunities

Show arbitrage opportunities.

This subcommand, like the arbit subcommand, checks prices of cryptocurrencies on several exchanges for arbitrage possibility; but does not actually perform the arbitraging.

order-pairs

List created order pairs.

profit-report

Get profit report.

OPTIONS

* marks required options.

Common options

--config-path=s, -c

Set path to configuration file.

--config-profile=s, -P

Set configuration profile to use.

--debug

Shortcut for --log-level=debug.

--format=s

Choose output format, e.g. json, text.

Default value:

undef

--help, -h, -?

Display help message and exit.

--json

Set output format to json.

--log-level=s

Set log level.

--naked-res

When outputing as JSON, strip result envelope.

Default value:

By default, when outputing as JSON, the full enveloped result is returned, e.g.:

[200,"OK",[1,2,3],{"func.extra"=>4}]

The reason is so you can get the status (1st element), status message (2nd element) as well as result metadata/extra result (4th element) instead of just the result (3rd element). However, sometimes you want just the result, e.g. when you want to pipe the result for more post-processing. In this case you can use `--naked-res` so you just get:

[1,2,3]

--no-config, -C

Do not use any configuration file.

--no-env

Do not read environment for default options.

--page-result

Filter output through a pager.

--quiet

Shortcut for --log-level=error.

--subcommands

List available subcommands.

--trace

Shortcut for --log-level=trace.

--verbose

Shortcut for --log-level=info.

--version, -v

Display program's version and exit.

--view-result

View output using a viewer.

Options for subcommand arbit

--accounts-json=s

Cryptoexchange accounts (JSON-encoded).

See --accounts.

--accounts=s@

Cryptoexchange accounts.

There should at least be two accounts, on at least two different cryptoexchanges. If not specified, all accounts listed on the configuration file will be included. Note that it's possible to include two or more accounts on the same cryptoexchange.

Can be specified multiple times.

--base-currencies-json=s

Target (crypto)currencies to arbitrate (JSON-encoded).

See --base-currency.

--base-currency=s@

Target (crypto)currencies to arbitrate.

If not specified, will list all supported pairs on all the exchanges and include the base cryptocurrencies that are listed on at least 2 different exchanges (for arbitrage possibility).

Can be specified multiple times.

--db-name=s*

--db-password=s

--db-username=s

--frequency=s

How many seconds to wait between rounds (in seconds).

Default value:

A round consists of checking prices and then creating arbitraging order pairs.

--loop

Shortcut for --rounds -1.

See --rounds.

--max-order-age=s

How long should we wait for orders to be completed before cancelling them (in seconds).

Default value:

Sometimes because of rapid trading and price movement, our order might not be filled immediately. This setting sets a limit on how long should an order be left open. After this limit is reached, we cancel the order. The imbalance of the arbitrage transaction will be recorded.

--max-order-pairs-per-round=s

Maximum number of order pairs to create per round.

--max-order-quote-size=s

What is the maximum amount of a single order.

Default value:

A single order will be limited to not be above this value (in quote currency, which if fiat will be converted to USD). This is the amount for the buying (because an arbitrage transaction is comprised of a pair of orders, where one order is a selling order at a higher quote currency size than the buying order).

For example if you are arbitraging BTC against USD and IDR, and set this option to 75, then orders will not be above 75 USD. If you are arbitraging LTC against BTC and set this to 0.03 then orders will not be above 0.03 BTC.

Suggestion: If you set this option too high, a few orders can use up your inventory (and you might not be getting optimal profit percentage). Also, large orders can take a while (or too long) to fill. If you set this option too low, you will hit the exchanges' minimum order size and no orders can be created. Since we want smaller risk of orders not getting filled quickly, we want small order sizes. The optimum number range a little above the exchanges' minimum order size.

--min-account-balances-json=s

What are the minimum account balances (JSON-encoded).

See --min-account-balances.

--min-account-balances=s

What are the minimum account balances.

--min-net-profit-margin=s

Minimum net profit margin that will trigger an arbitrage trading, in percentage.

Default value:

Below this percentage number, no order pairs will be sent to the exchanges to do the arbitrage. Note that the net profit margin already takes into account trading fees and forex spread (see Glossary section for more details and illustration).

Suggestion: If you set this option too high, there might not be any order pairs possible. If you set this option too low, you will be getting too thin profits. Run `cryp-arbit opportunities` or `cryp-arbit arbit --dry-run` for a while to see what the average percentage is and then decide at which point you want to perform arbitrage.

--quote-currencies-json=s

The currencies to exchange (buy/sell) the target currencies (JSON-encoded).

See --quote-currency.

--quote-currency=s@

The currencies to exchange (buy/sell) the target currencies.

You can have fiat currencies as the quote currencies, to buy/sell the target (base) currencies during arbitrage. For example, to arbitrage LTC against USD and IDR, `base_currencies` is ['BTC'] and `quote_currencies` is ['USD', 'IDR'].

You can also arbitrage cryptocurrencies against other cryptocurrency (usually BTC, "the USD of cryptocurrencies"). For example, to arbitrage XMR and LTC against BTC, `base_currencies` is ['XMR', 'LTC'] and `quote_currencies` is ['BTC'].

Can be specified multiple times.

--rounds=s

How many rounds.

Default value:

-1 means unlimited.

--strategy=s

Which strategy to use for arbitration.

Default value:

"merge_order_book"

Strategy is implemented in a `App::cryp::arbit::Strategy::*` perl module.

Options for subcommand check-orders

--db-name=s*

--db-password=s

--db-username=s

--max-order-age=s

How long should we wait for orders to be completed before cancelling them (in seconds).

Default value:

Options for subcommand collect-orderbooks

--accounts-json=s

Cryptoexchange accounts (JSON-encoded).

See --accounts.

--accounts=s@

Cryptoexchange accounts.

Can be specified multiple times.

--base-currencies-json=s

Target (crypto)currencies to arbitrate (JSON-encoded).

See --base-currency.

--base-currency=s@

Target (crypto)currencies to arbitrate.

If not specified, will list all supported pairs on all the exchanges and include the base cryptocurrencies that are listed on at least 2 different exchanges (for arbitrage possibility).

Can be specified multiple times.

--db-name=s*

--db-password=s

--db-username=s

--frequency=s

How many seconds to wait between rounds (in seconds).

Default value:

--quote-currencies-json=s

The currencies to exchange (buy/sell) the target currencies (JSON-encoded).

See --quote-currency.

--quote-currency=s@

The currencies to exchange (buy/sell) the target currencies.

Can be specified multiple times.

Options for subcommand opportunities

--accounts-json=s

Cryptoexchange accounts (JSON-encoded).

See --accounts.

--accounts=s@

Cryptoexchange accounts.

Can be specified multiple times.

--base-currencies-json=s

Target (crypto)currencies to arbitrate (JSON-encoded).

See --base-currency.

--base-currency=s@

Target (crypto)currencies to arbitrate.

If not specified, will list all supported pairs on all the exchanges and include the base cryptocurrencies that are listed on at least 2 different exchanges (for arbitrage possibility).

Can be specified multiple times.

--db-name=s*

--db-password=s

--db-username=s

--ignore-balance

Ignore account balances.

--ignore-min-order-size

Ignore minimum order size limitation from exchanges.

--max-order-pairs-per-round=s

Maximum number of order pairs to create per round.

--max-order-quote-size=s

What is the maximum amount of a single order.

Default value:

--min-account-balances-json=s

What are the minimum account balances (JSON-encoded).

See --min-account-balances.

--min-account-balances=s

What are the minimum account balances.

--min-net-profit-margin=s

Minimum net profit margin that will trigger an arbitrage trading, in percentage.

Default value:

--quote-currencies-json=s

The currencies to exchange (buy/sell) the target currencies (JSON-encoded).

See --quote-currency.

--quote-currency=s@

The currencies to exchange (buy/sell) the target currencies.

Can be specified multiple times.

--strategy=s

Which strategy to use for arbitration.

Default value:

"merge_order_book"

Strategy is implemented in a `App::cryp::arbit::Strategy::*` perl module.

Options for subcommand order-pairs

--db-name=s*
--db-password=s
--db-username=s
--open
--time-end=s
--time-start=s

Options for subcommand profit-report

--db-name=s*

--db-password=s

--db-username=s

--detail, -l

--time-end=s

--time-start=s

--usd-rate=s%

Set USD rates.

Example:

--usd-rate IDR=14500 --usd-rate THB=33.25

Each value is a name-value pair, use key=value syntax. Can be specified multiple times.

--usd-rates-json=s

Set USD rates (JSON-encoded).

See --usd-rate.

COMPLETION

This script has shell tab completion capability with support for several shells.

bash

To activate bash completion for this script, put:

complete -C cryp-arbit cryp-arbit

in your bash startup (e.g. ~/.bashrc). Your next shell session will then recognize tab completion for the command. Or, you can also directly execute the line above in your shell to activate immediately.

It is recommended, however, that you install modules using cpanm-shcompgen which can activate shell completion for scripts immediately.

tcsh

To activate tcsh completion for this script, put:

complete cryp-arbit 'p/*/`cryp-arbit`/'

in your tcsh startup (e.g. ~/.tcshrc). Your next shell session will then recognize tab completion for the command. Or, you can also directly execute the line above in your shell to activate immediately.

It is also recommended to install shcompgen (see above).

other shells

For fish and zsh, install shcompgen as described above.

CONFIGURATION FILE

This script can read configuration files. Configuration files are in the format of IOD, which is basically INI with some extra features.

By default, these names are searched for configuration filenames (can be changed using --config-path): ~/.config/cryp.conf, ~/.config/cryp-arbit.conf, ~/cryp.conf, ~/cryp-arbit.conf, /etc/cryp.conf, or /etc/cryp-arbit.conf.

All found files will be read and merged.

To disable searching for configuration files, pass --no-config.

To put configuration for a certain subcommand only, use a section name like [subcommand=NAME] or [SOMESECTION subcommand=NAME].

You can put multiple profiles in a single file by using section names like [profile=SOMENAME] or [SOMESECTION profile=SOMENAME] or [subcommand=SUBCOMMAND_NAME profile=SOMENAME] or [SOMESECTION subcommand=SUBCOMMAND_NAME profile=SOMENAME]. Those sections will only be read if you specify the matching --config-profile SOMENAME.

You can also put configuration for multiple programs inside a single file, and use filter program=NAME in section names, e.g. [program=NAME ...] or [SOMESECTION program=NAME]. The section will then only be used when the reading program matches.

You can also filter a section by environment variable using the filter env=CONDITION in section names. For example if you only want a section to be read if a certain environment variable is true: [env=SOMEVAR ...] or [SOMESECTION env=SOMEVAR ...]. If you only want a section to be read when the value of an environment variable has value equals something: [env=HOSTNAME=blink ...] or [SOMESECTION env=HOSTNAME=blink ...]. If you only want a section to be read when the value of an environment variable does not equal something: [env=HOSTNAME!=blink ...] or [SOMESECTION env=HOSTNAME!=blink ...]. If you only want a section to be read when an environment variable contains something: [env=HOSTNAME*=server ...] or [SOMESECTION env=HOSTNAME*=server ...]. Note that currently due to simplistic parsing, there must not be any whitespace in the value being compared because it marks the beginning of a new section filter or section name.

To load and configure plugins, you can use either the -plugins parameter (e.g. -plugins=DumpArgs or -plugins=DumpArgs@before_validate_args), or use the [plugin=NAME ...] sections, for example:

[plugin=DumpArgs]
-event=before_validate_args
-prio=99

[plugin=Foo]
-event=after_validate_args
arg1=val1
arg2=val2

which is equivalent to setting -plugins=-DumpArgs@before_validate_args@99,-Foo@after_validate_args,arg1,val1,arg2,val2.

List of available configuration parameters:

Common for all subcommands

format (see --format)
log_level (see --log-level)
naked_res (see --naked-res)

Configuration for subcommand arbit

accounts (see --accounts)
base_currencies (see --base-currency)
db_name (see --db-name)
db_password (see --db-password)
db_username (see --db-username)
frequency (see --frequency)
max_order_age (see --max-order-age)
max_order_pairs_per_round (see --max-order-pairs-per-round)
max_order_quote_size (see --max-order-quote-size)
min_account_balances (see --min-account-balances)
min_net_profit_margin (see --min-net-profit-margin)
quote_currencies (see --quote-currency)
rounds (see --rounds)
strategy (see --strategy)

Configuration for subcommand check-orders

db_name (see --db-name)
db_password (see --db-password)
db_username (see --db-username)
max_order_age (see --max-order-age)

Configuration for subcommand collect-orderbooks

accounts (see --accounts)
base_currencies (see --base-currency)
db_name (see --db-name)
db_password (see --db-password)
db_username (see --db-username)
frequency (see --frequency)
quote_currencies (see --quote-currency)

Configuration for subcommand dump-cryp-config

Configuration for subcommand opportunities

accounts (see --accounts)
base_currencies (see --base-currency)
db_name (see --db-name)
db_password (see --db-password)
db_username (see --db-username)
ignore_balance (see --ignore-balance)
ignore_min_order_size (see --ignore-min-order-size)
max_order_pairs_per_round (see --max-order-pairs-per-round)
max_order_quote_size (see --max-order-quote-size)
min_account_balances (see --min-account-balances)
min_net_profit_margin (see --min-net-profit-margin)
quote_currencies (see --quote-currency)
strategy (see --strategy)

Configuration for subcommand order-pairs

db_name (see --db-name)
db_password (see --db-password)
db_username (see --db-username)
open (see --open)
time_end (see --time-end)
time_start (see --time-start)

Configuration for subcommand profit-report

db_name (see --db-name)
db_password (see --db-password)
db_username (see --db-username)
detail (see --detail)
time_end (see --time-end)
time_start (see --time-start)
usd_rates (see --usd-rate)

ENVIRONMENT

CRYP_ARBIT_OPT => str

Specify additional command-line options.

FILES

~/.config/cryp.conf

~/.config/cryp-arbit.conf

~/cryp.conf

~/cryp-arbit.conf

/etc/cryp.conf

/etc/cryp-arbit.conf

HOMEPAGE

Please visit the project's homepage at https://metacpan.org/release/App-cryp-arbit.

SOURCE

Source repository is at https://github.com/perlancar/perl-App-cryp-arbit.

BUGS

Please report any bugs or feature requests on the bugtracker website https://github.com/perlancar/perl-App-cryp-arbit/issues

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

AUTHOR

perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

To install App::cryp::arbit, copy and paste the appropriate command in to your terminal.

cpanm

cpanm App::cryp::arbit

CPAN shell

perl -MCPAN -e shell
install App::cryp::arbit

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

Collecting orderbooks

Performing arbitrage

DESCRIPTION

SUBCOMMANDS

arbit

check-orders

collect-orderbooks

dump-cryp-config

opportunities

order-pairs

profit-report

OPTIONS

Common options

Options for subcommand arbit

Options for subcommand check-orders

Options for subcommand collect-orderbooks

Options for subcommand opportunities

Options for subcommand order-pairs

Options for subcommand profit-report

COMPLETION

bash

tcsh

other shells

CONFIGURATION FILE

Common for all subcommands

Configuration for subcommand arbit

Configuration for subcommand check-orders

Configuration for subcommand collect-orderbooks

Configuration for subcommand dump-cryp-config

Configuration for subcommand opportunities

Configuration for subcommand order-pairs

Configuration for subcommand profit-report

ENVIRONMENT

CRYP_ARBIT_OPT => str

FILES

HOMEPAGE

SOURCE

BUGS

SEE ALSO

AUTHOR

COPYRIGHT AND LICENSE

Module Install Instructions