Need help with kelp?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

stellar
595 Stars 135 Forks Other 805 Commits 139 Opened issues

Description

Kelp is a free and open-source trading bot for the Stellar DEX and 100+ centralized exchanges

Services available

!
?

Need anything else?

Contributors list

Kelp

Kelp logo

GitHub last commit Github All Releases license

Godoc Go Report Card Build Status Contributors

Kelp is a free and open-source trading bot for the Stellar universal marketplace and for centralized exchanges such as Binance, Kraken, CoinbasePro, etc.

Kelp includes several configurable trading strategies and exchange integrations. You can define your own parameters or use the sample configurations to quickly get up and running with a trading bot in a matter of minutes. The modular design allows you to easily create new trading strategies, exchange integrations, and assets to give you full control over the bot.

Kelp is built to:

  • Make spreads and make markets
  • Create liquidity and facilitate price-discovery for ICOs
  • Price and trade custom stablecoins
  • Mimic orderbooks from other exchanges

To learn more about the Stellar protocol check out Stellar Videos on Coinbase Earn, or this video about the Stellar DEX created by Lumenauts, or read more about it on the Stellar Website.

Be Smart and Go Slow

Important Disclaimer: Be Smart and Go Slow. Whenever you trade on Stellar, you are trading with volatile assets, in volatile markets, and you risk losing money. Kelp is an experimental software that contains bugs. Use Kelp at your own risk. There is no guarantee you'll make a profit from using our bots or strategies. In fact, if you set bad parameters or market conditions change, Kelp might help you lose money very fast. So be smart and go slow.

Your use of Kelp is governed by the Apache 2.0 open-source license. Please note that SDF’s interactions with you are governed by the SDF Terms of Service and Privacy Policy.

Kelp GUI screenshot

Table of Contents

Getting Started

How To Get Kelp

To get started with Kelp, either download the pre-compiled binary for your platform from the Github Releases Page or compile Kelp from source.

There is one binary associated with this project:

kelp
. Once the binary is downloaded, run the bot by following the instructions in Running Kelp.

Download Kelp Binary

You can find the pre-compiled binary for your platform from the Github Releases Page.

GUI

Here is a list of binaries for the most recent release v1.0.0-rc2 (v1.11.0):

| Platform | Architecture | Binary File Name | | -------------- | ------------ | ---------------- | | MacOS (Darwin) | 64-bit | kelp-v1.11.0-darwin-amd64.tar | | Windows | 64-bit | kelp-v1.11.0-windows-amd64.tar | | Linux | 64-bit | kelp-v1.11.0-linux-amd64.tar |

CLI

Here is a list of binaries for the most recent release v1.11.0:

| Platform | Architecture | Binary File Name | | -------------- | ------------ | ---------------- | | MacOS (Darwin) | 64-bit | kelp-v1.11.0-darwin-amd64.tar | | Windows | 64-bit | kelp-v1.11.0-windows-amd64.tar | | Linux | 64-bit | kelp-v1.11.0-linux-amd64.tar | | Linux | 64-bit arm | kelp-v1.11.0-linux-arm64.tar | | Linux | 32-bit arm5 | kelp-v1.11.0-linux-arm5.tar | | Linux | 32-bit arm6 | kelp-v1.11.0-linux-arm6.tar | | Linux | 32-bit arm7 | kelp-v1.11.0-linux-arm7.tar |

After you untar the downloaded file, change to the generated directory (

kelp-v1.11.0
) and invoke the
kelp
binary.

Here's an example to get you started (replace

filename
with the name of the file that you download):
tar xvf filename
cd kelp-v1.11.0
./kelp

To run the bot in simulation mode, try this command:

./kelp trade -c sample_trader.cfg -s buysell -f sample_buysell.cfg --sim

Compile from Source

Note for Windows Users: You should use a Bash Shell to follow the steps below. This will give you a UNIX environment in which to run your commands and will enable the

./scripts/build.sh
bash script to work correctly.

To compile Kelp from source:

  1. Download and setup Golang v1.13 or later.
    • Confirm that
      $GOPATH
      is set, and that
      GOBIN=$GOPATH/bin
    • Confirm that
      $PATH
      includes the full filepath of
      $GOBIN
  2. Install Glide for dependency management
    • curl https://glide.sh/get | sh
  3. Install Yarn and NodeJs to build the Kelp GUI
  4. Clone the repo into
    $GOPATH/src/github.com/stellar/kelp
    :
    • git clone [email protected]:stellar/kelp.git
    • Change to
      kelp
      directory for all following commands:
      cd $GOPATH/src/github.com/stellar/kelp
  5. Install the dependencies:
    • glide install
  6. Install the astilectron-bundler binary into
    $GOBIN
    • go get -u github.com/asticode/go-astilectron-bundler/...
    • go install github.com/asticode/go-astilectron-bundler/astilectron-bundler
  7. Build the binaries using the provided build script (the go install command will produce a faulty binary):
    • ./scripts/build.sh
  8. Confirm one new binary file exists with version information.
    • ./bin/kelp version
  9. Set up CCXT to use an expanded set of priceFeeds and orderbooks (see the Using CCXT section for details)
    • sudo docker run -p 3000:3000 -d franzsee/ccxt-rest:v0.0.4

Running Kelp

Kelp places orders on the Stellar marketplace based on the selected strategy. Configuration files specify the Stellar account and strategy details.

These are the following commands available from the

kelp
binary: -
trade
: Trades with a specific strategy against the Stellar universal marketplace -
exchanges
: Lists the available exchange integrations along with capabilities -
strategies
: Lists the available strategies along with details -
version
: Version and build information -
help
: Help about any command

The

trade
command has three required parameters which are:
  • botConf: full path to the .cfg file with the account details, sample file here.
  • strategy: the strategy you want to run (sell, selltwap, _buysell, balanced, pendulum, mirror, delete).
  • stratConf: full path to the .cfg file specific to your chosen strategy, sample files here.

Kelp sets the

X-App-Name
and
X-App-Version
headers on requests made to Horizon. These headers help us track overall Kelp usage, so that we can learn about general usage patterns and adapt Kelp to be more useful in the future. Kelp also uses Amplitude for metric tracking. These can be turned off using the
--no-headers
flag. See
kelp trade --help
for more information.

Here's an example of how to start the trading bot with the buysell strategy:

kelp trade --botConf ./path/trader.cfg --strategy buysell --stratConf ./path/buysell.cfg

If you are ever stuck, just run

kelp help
to bring up the help section or type
kelp help [command]
for help with a specific command.

Using CCXT

You can use the CCXT library via the CCXT REST API Wrapper to fetch prices and orderbooks from a larger number of exchanges. You will need to run the CCXT REST server on

localhost:3000
so Kelp can connect to it.

The CCXT-REST server must be running on port

3000
before you start up the Kelp bot. You can list the exchanges (
./kelp exchanges
) to get the full list of supported exchanges via CCXT.

Note: this integration is still experimental and is also incomplete. Please use at your own risk.

CCXT-rest can be run in any one of the following ways.

Download CCXT Binary

We have compiled the ccxt-rest v0.0.4 server as a binary for all x86 platforms (linux, darwin, windows). This is the version that Kelp currently uses.

You can find these pre-compiled binaries of the CCXT-rest server in the releases tab here.

Run CCXT using Docker

Install docker (linux:

sudo apt install -y docker.io
) and run the CCXT-REST docker image configured to port
3000
(linux:
sudo docker run -p 3000:3000 -d franzsee/ccxt-rest:v0.0.4
). You can find more details on the CCXT_REST github page.

Using Postgres

Postgres v12.1 or later must be installed for Kelp to automatically write trades to a sql database along with updating the trader config file.

Examples

It's easier to learn with examples! Take a look at the walkthrough guides and sample configuration files below.

Walkthrough Guides

Configuration Files

Each strategy you implement needs a configuration file. The format of the configuration file is specific to the selected strategy. You can use these files to customize parameters for your chosen strategy.

The following reference config files are in the examples folder:

Winning Educational Content from StellarBattle

SDF sponsored a Kelp StellarBattle in August/September 2020, here were the winning results (announcement):

Components

Kelp includes an assortment of strategies, price feeds, and plugins you can use to customize your bot. Kelp also enables you to create your own trading strategies.

click to expand Components section

Strategies

Strategies are at the core of Kelp. Without them it's just lazy, capable of nothing, thinking of nothing, doing nothing, like our friend [scooter][scooter video] here. The strategies give your bot purpose. Each approaches the market in a different way and is designed to achieve a particular goal.

The following strategies are available out of the box with Kelp:

  • sell (source):

    • What: creates sell offers based on a reference price with a pre-specified liquidity depth
    • Why: To sell tokens at a fixed price or at a price that changes based on an external reference price
    • Who: An issuer could use Sell to distribute tokens from an ICO pre-sale
  • sell_twap (source):

    • What: creates sell offers based on a reference price spread over the day for a given daily sale amount
    • Why: To sell tokens consistently using the time-weighted-average-price (TWAP) metric
    • Who: An issuer could use SellTwap to distribute tokens from an ICO pre-sale in a consistent manner
  • buysell (source):

    • What: creates buy and sell offers based on a specific reference price and a pre-specified liquidity depth while maintaining a [spread][spread].
    • Why: To make the market for tokens based on a fixed or external reference price.
    • Who: Anyone who wants to create liquidity for a stablecoin or [fiat][fiat] token
  • balanced (source):

    • What: dynamically prices two tokens based on their relative demand (like AMMs). For example, if more traders buy token A from the bot (the traders are therefore selling token B), the bot will automatically raise the price for token A and drop the price for token B. This strategy does not allow you to configure the order size but can run out of assets. This is a mean-reversion strategy.
    • Why: To let the market surface the true price for one token in terms of another.
    • Who: Market makers and traders for tokens that have a neutral view on the market
  • pendulum (source):

    • What: dynamically prices two tokens based on their relative demand (like AMMs). For example, if more traders buy token A from the bot (the traders are therefore selling token B), the bot will automatically raise the price for token A and drop the price for token B. This strategy allows you to configure the order size but runs the risk of running out of one of the two assets. This is a mean-reversion strategy.
    • Why: To let the market surface the true price for one token in terms of another.
    • Who: Market makers and traders for tokens that have a neutral view on the market
  • mirror (source):

    • What: mirrors an orderbook from another exchange by placing the same orders on Stellar after including a [spread][spread].
    • Why: To [hedge][hedge] your position on another exchange whenever a trade is executed to reduce inventory risk while keeping a spread
    • Who: Anyone who wants to reduce inventory risk and also has the capacity to take on a higher operational overhead in maintaining the bot system.
  • delete (source):

    • What: deletes your offers from both sides of the specified orderbook. Note: does not need a strategy-specific config file.
    • Why: To kill the offers placed by the bot. This is not a trading strategy but is used for operational purposes only.
    • Who: Anyone managing the operations of the bot who wants to stop all activity by the bot.

Refer to this [Pull Request][pr-template-new-strategy] to see an example template of a new trading strategy.

Price Feeds

Price Feeds fetch the price of an asset from an external source. The following price feeds are available out of the box with Kelp:

  • crypto: fetches the price of tokens from [CoinMarketCap][cmc]
  • fiat: fetches the price of a [fiat][fiat] currency from the [CurrencyLayer API][currencylayer]
  • exchange: fetches the price from an exchange you specify, such as Kraken or Poloniex. You can also use the [CCXT][ccxt] integration to fetch prices from a wider range of exchanges (see the Using CCXT section for details)
  • fixed: sets the price to a constant
  • function: uses a pre-defined function to combine the above price feed types into a single feed. We currently support only two types
    • max - max(exchange/ccxt-binance/XLM/USDT/mid,exchange/ccxt-coinbasepro/XLM/USD/mid)
    • invert - invert(exchange/ccxt-binance/XLM/USDT/mid)

Exchanges

Exchange integrations provide data to trading strategies and allow you to [hedge][hedge] your positions on different exchanges. The following exchange integrations are available out of the box with Kelp:

  • sdex ("sdex") (source): The [Stellar Decentralized Exchange][sdex]
  • kraken ("kraken") (source): [Kraken][kraken] - recommended to use ccxt-kraken instead
  • kraken (via CCXT) ("ccxt-kraken") (source): Kraken via CCXT - full two-way integration (tested)
  • binance (via CCXT) ("ccxt-binance") (source): Binance via CCXT - full two-way integration (tested)
  • coinbasepro (via CCXT) ("ccxt-coinbasepro") (source): Coinbase Pro via CCXT - full two-way integration (tested)
  • poloniex (via CCXT) ("ccxt-poloniex") (source): Poloniex via CCXT - only tested on priceFeeds and one-way mirroring
  • bittrex (via CCXT) ("ccxt-bittrex") (source): Bittrex via CCXT - only tested on priceFeeds and onw-way mirroring

Plugins

Kelp can easily be extended because of its modular plugin based architecture. You can create new flavors of the following components: Strategies, PriceFeeds, and Exchanges.

These interfaces make it easy to create plugins:

  • Strategy (source) - API for a strategy
  • PriceFeed (source) - API for price of an asset
  • Exchange (source) - API for crypto exchanges

Directory Structure

The folders are organized to make it easy to find code and streamline development flow. Each folder is its own package without any sub-packages.

github.com/stellar/kelp
├── api/            # API interfaces live here (strategy, exchange, price feeds, etc.)
├── cmd/            # Cobra commands (trade, exchanges, strategies, etc.)
├── examples/       # Sample config files and walkthroughs
├── model/          # Low-level structs (dates, orderbook, etc.)
├── plugins/        # Implementations of API interfaces (sell strategy, kraken, etc.)
├── support/        # Helper functions and utils
├── trader/         # Trader bot logic; uses other top-level packages like api, plugins, etc.
├── glide.yaml      # Glide dependencies
├── main.go         # main function for our kelp binary
└── ...

Accounting

You can use [Stellar-Downloader][stellar-downloader] to download trade and payment data from your Stellar account as a CSV file.

Community

click to expand Community section

Contributing

See the Contribution Guide and then please [sign the Contributor License Agreement][cla].

Changelog

See the Changelog.

Code of Conduct

See the Code of Conduct.

Project Improvements

  • [Submit a Bug Report][github-bug-report]
  • [Submit a Feature Request][github-feature-request]
  • [Raise an issue][github-new-issue] that is not a bug report or a feature request
  • [Contribute a PR][github-pulls]

Public Assets

click to expand Public Assets section

TEST1 and TEST2 issued by the GCL4KBYTRA3QYI4JTN4FWVYVYNI67W2M6XMDUB2V6ZLWFASIYHWEJPHU account are test assets used to test Kelp on the production Stellar Network. These assets have no value and are marked as auth_required with the intent to close them off from the rest of the Stellar ecosystem. No trustlines will be accepted against these assets. As part of our testing process, you may observe a market and trades between these two tokens. It is not intended for any of these assets to represent any meaningful volume on the Stellar Network.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.