BBGO
A crypto trading bot framework written in Go. The name bbgo comes from the BB8 bot in the Star Wars movie.
Current Status
Community
What You Can Do With BBGO
💁♀️ 💁♂️
Trading Bot Users You can use BBGO to run the built-in strategies.
🥷
Strategy Developers You can use BBGO's trading unit and back-test unit to implement your own strategies.
🧑💻
Trading Unit Developers You can use BBGO's underlying common exchange API, currently it supports 4+ major exchanges, so you don't have to repeat the implementation.
Features
- Exchange abstraction interface.
- Stream integration (user data websocket, market data websocket).
- Real-time orderBook integration through websocket.
- TWAP order execution support. See TWAP Order Execution
- PnL calculation.
- Slack/Telegram notification.
- Back-testing: KLine-based back-testing engine. See Back-testing
- Built-in parameter optimization tool.
- Built-in Grid strategy and many other built-in strategies.
- Multi-exchange session support: you can connect to more than 2 exchanges with different accounts or subaccounts.
- Indicators with interface similar
to
pandas.Series
(series)(usage):- Accumulation/Distribution Indicator
- Arnaud Legoux Moving Average
- Average True Range
- Bollinger Bands
- Commodity Channel Index
- Cumulative Moving Average
- Double Exponential Moving Average
- Directional Movement Index
- Brownian Motion's Drift Factor
- Ease of Movement
- Exponentially Weighted Moving Average
- Hull Moving Average
- Trend Line (Tool)
- Moving Average Convergence Divergence Indicator
- On-Balance Volume
- Pivot
- Running Moving Average
- Relative Strength Index
- Simple Moving Average
- Ehler's Super Smoother Filter
- Stochastic Oscillator
- SuperTrend
- Triple Exponential Moving Average
- Tillson T3 Moving Average
- Triangular Moving Average
- Variable Index Dynamic Average
- Volatility Indicator
- Volume Weighted Average Price
- Zero Lag Exponential Moving Average
- And more...
- HeikinAshi OHLC / Normal OHLC (check this config)
- React-powered Web Dashboard.
- Docker image ready.
- Kubernetes support.
- Helm chart ready.
- High precision float point (up to 16 digits, run with
-tags dnum
).
Screenshots
Supported Exchanges
- Binance Spot Exchange (and binance.us)
- FTX Spot Exchange
- OKEx Spot Exchange
- Kucoin Spot Exchange
- MAX Spot Exchange (located in Taiwan)
Documentation and General Topics
- Check the documentation index
Requirements
Get your exchange API key and secret after you register the accounts (you can choose one or more exchanges):
- MAX: https://max.maicoin.com/signup?r=c7982718
- Binance: https://accounts.binance.com/en/register?ref=38192708
- FTX: https://ftx.com/#a=7710474
- OKEx: https://www.okex.com/join/2412712?src=from:ios-share
- Kucoin: https://www.kucoin.com/ucenter/signup?rcode=r3KX2D4
This project is maintained and supported by a small group of team. If you would like to support this project, please register on the exchanges using the provided links with referral codes above.
Installation
Install from binary
The following script will help you set up a config file and a dotenv file:
# grid trading strategy for binance exchange
bash <(curl -s https://raw.githubusercontent.com/c9s/bbgo/main/scripts/setup-grid.sh) binance
# grid trading strategy for max exchange
bash <(curl -s https://raw.githubusercontent.com/c9s/bbgo/main/scripts/setup-grid.sh) max
# bollinger grid trading strategy for binance exchange
bash <(curl -s https://raw.githubusercontent.com/c9s/bbgo/main/scripts/setup-bollgrid.sh) binance
# bollinger grid trading strategy for max exchange
bash <(curl -s https://raw.githubusercontent.com/c9s/bbgo/main/scripts/setup-bollgrid.sh) max
If you already have configuration somewhere, a download-only script might be suitable for you:
bash <(curl -s https://raw.githubusercontent.com/c9s/bbgo/main/scripts/download.sh)
Or refer to the Release Page and download manually.
Since v2, we've added new float point implementation from dnum to support decimals with higher precision. To download & setup, please refer to Dnum Installation
One-click Linode StackScript
StackScript allows you to one-click deploy a lightweight instance with bbgo.
- BBGO grid on Binance https://cloud.linode.com/stackscripts/950715
- BBGO grid USDT/TWD on MAX https://cloud.linode.com/stackscripts/793380
- BBGO grid USDC/TWD on MAX https://cloud.linode.com/stackscripts/797776
- BBGO grid LINK/TWD on MAX https://cloud.linode.com/stackscripts/797774
- BBGO grid USDC/USDT on MAX https://cloud.linode.com/stackscripts/797777
- BBGO grid on MAX https://cloud.linode.com/stackscripts/795788
- BBGO bollmaker on Binance https://cloud.linode.com/stackscripts/1002384
Build from source
Configuration
Add your dotenv file:
# for Binance Exchange, if you have one
BINANCE_API_KEY=
BINANCE_API_SECRET=
# if you want to use binance.us, change this to 1
BINANCE_US=0
# for MAX exchange, if you have one
MAX_API_KEY=
MAX_API_SECRET=
# for FTX exchange, if you have one
FTX_API_KEY=
FTX_API_SECRET=
# specify it if credentials are for subaccount
FTX_SUBACCOUNT=
# for OKEx exchange, if you have one
OKEX_API_KEY=
OKEX_API_SECRET=
OKEX_API_PASSPHRASE
# for kucoin exchange, if you have one
KUCOIN_API_KEY=
KUCOIN_API_SECRET=
KUCOIN_API_PASSPHRASE=
KUCOIN_API_KEY_VERSION=2
Prepare your dotenv file .env.local
and BBGO yaml config file bbgo.yaml
.
To check the available environment variables, please see Environment Variables
The minimal bbgo.yaml could be generated by:
curl -o bbgo.yaml https://raw.githubusercontent.com/c9s/bbgo/main/config/minimal.yaml
To run strategy:
bbgo run
To start bbgo with the frontend dashboard:
bbgo run --enable-webserver
If you want to switch to other dotenv file, you can add an --dotenv
option or --config
:
bbgo sync --dotenv .env.dev --config config/grid.yaml --session binance
To query transfer history:
bbgo transfer-history --session max --asset USDT --since "2019-01-01"
Advanced Configuration
Testnet (Paper Trading)
Currently only supports binance testnet. To run bbgo in testnet, apply new API keys from Binance Test Network, and set the following env before you start bbgo:
export PAPER_TRADE=1
export DISABLE_MARKET_CACHE=1 # the symbols supported in testnet is far less than the mainnet
Notification
Synchronizing Trading Data
By default, BBGO does not sync your trading data from the exchange sessions, so it's hard to calculate your profit and loss correctly.
By synchronizing trades and orders to the local database, you can earn some benefits like PnL calculations, backtesting and asset calculation.
You can only use one database driver MySQL or SQLite to store your trading data.
Notice: SQLite is not fully supported, we recommend you use MySQL instead of SQLite.
Configure MySQL Database
To use MySQL database for data syncing, first you need to install your mysql server:
# For Ubuntu Linux
sudo apt-get install -y mysql-server
# For newer Ubuntu Linux
sudo apt install -y mysql-server
Create your mysql database:
mysql -uroot -e "CREATE DATABASE bbgo CHARSET utf8"
Then put these environment variables in your .env.local
file:
DB_DRIVER=mysql
DB_DSN="user:password@tcp(127.0.0.1:3306)/bbgo"
Configure Sqlite3 Database
To use SQLite3 instead of MySQL, simply put these environment variables in your .env.local
file:
DB_DRIVER=sqlite3
DB_DSN=bbgo.sqlite3
Synchronizing your own trading data
Once you have your database configured, you can sync your own trading data from the exchange.
See Configure Sync For Private Trading Data
Using Redis to keep persistence between BBGO sessions
To use Redis, first you need to install your Redis server:
# For Ubuntu/Debian Linux
sudo apt-get install -y redis
# For newer Ubuntu/Debian Linux
sudo apt install -y redis
Set the following environment variables in your bbgo.yaml
:
persistence:
redis:
host: 127.0.0.1 # The IP address or the hostname to your Redis server, 127.0.0.1 if same as BBGO
port: 6379 # Port to Redis server, default 6379
db: 0 # DB number to use. You can set to another DB to avoid conflict if other applications are using Redis too.
Built-in Strategies
Check out the strategy directory strategy for all built-in strategies:
pricealert
strategy demonstrates how to use the notification system pricealert. See document.xpuremaker
strategy demonstrates how to maintain the orderbook and submit maker orders xpuremakerbuyandhold
strategy demonstrates how to subscribe kline events and submit market order buyandholdbollgrid
strategy implements a basic grid strategy with the built-in bollinger indicator bollgridgrid
strategy implements the fixed price band grid strategy grid. See document.supertrend
strategy uses Supertrend indicator as trend, and DEMA indicator as noise filter supertrend. See document.support
strategy uses K-lines with high volume as support support. See document.flashcrash
strategy implements a strategy that catches the flashcrash flashcrashmarketcap
strategy implements a strategy that rebalances the portfolio based on the market capitalization marketcap. See document.
To run these built-in strategies, just modify the config file to make the configuration suitable for you, for example if
you want to run
buyandhold
strategy:
vim config/buyandhold.yaml
# run bbgo with the config
bbgo run --config config/buyandhold.yaml
Back-testing
See Back-testing
Adding Strategy
Write your own private strategy
Create your go package, and initialize the repository with go mod
and add bbgo as a dependency:
go mod init
go get github.com/c9s/bbgo@main
Write your own strategy in the strategy file:
vim strategy.go
You can grab the skeleton strategy from https://github.com/c9s/bbgo/blob/main/pkg/strategy/skeleton/strategy.go
Now add your config:
mkdir config
(cd config && curl -o bbgo.yaml https://raw.githubusercontent.com/c9s/bbgo/main/config/minimal.yaml)
Add your strategy package path to the config file config/bbgo.yaml
---
build:
dir: build
imports:
- github.com/your_id/your_swing
targets:
- name: swing-amd64-linux
os: linux
arch: amd64
- name: swing-amd64-darwin
os: darwin
arch: amd64
Run bbgo run
command, bbgo will compile a wrapper binary that imports your strategy:
dotenv -f .env.local -- bbgo run --config config/bbgo.yaml
Or you can build your own wrapper binary via:
bbgo build --config config/bbgo.yaml
See also:
- https://github.com/narumiruna/bbgo-template
- https://github.com/narumiruna/bbgo-marketcap
- https://github.com/austin362667/shadow
- https://github.com/jnlin/bbgo-strategy-infinite-grid
Command Usages
Submitting Orders to a specific exchagne session
bbgo submit-order --session=okex --symbol=OKBUSDT --side=buy --price=10.0 --quantity=1
Listing Open Orders of a specific exchange session
bbgo list-orders open --session=okex --symbol=OKBUSDT
bbgo list-orders open --session=ftx --symbol=FTTUSDT
bbgo list-orders open --session=max --symbol=MAXUSDT
bbgo list-orders open --session=binance --symbol=BNBUSDT
Canceling an open order
# both order id and symbol is required for okex
bbgo cancel-order --session=okex --order-id=318223238325248000 --symbol=OKBUSDT
# for max, you can just give your order id
bbgo cancel-order --session=max --order-id=1234566
Debugging user data stream
bbgo userdatastream --session okex
bbgo userdatastream --session max
bbgo userdatastream --session binance
Dynamic Injection
In order to minimize the strategy code, bbgo supports dynamic dependency injection.
Before executing your strategy, bbgo injects the components into your strategy object if it found the embedded field that is using bbgo component. for example:
type Strategy struct {
Symbol string `json:"symbol"
Market types.Market
}
Supported components (single exchange strategy only for now):
*bbgo.ExchangeSession
bbgo.OrderExecutor
If you have Symbol string
field in your strategy, your strategy will be detected as a symbol-based strategy, then the
following types could be injected automatically:
types.Market
Strategy Execution Phases
- Load config from the config file.
- Allocate and initialize exchange sessions.
- Add exchange sessions to the environment (the data layer).
- Use the given environment to initialize the trader object (the logic layer).
- The trader initializes the environment and start the exchange connections.
- Call strategy.Run() method sequentially.
Exchange API Examples
Please check out the example directory: examples
Initialize MAX API:
key := os.Getenv("MAX_API_KEY")
secret := os.Getenv("MAX_API_SECRET")
maxRest := maxapi.NewRestClient(maxapi.ProductionAPIURL)
maxRest.Auth(key, secret)
Creating user data stream to get the orderbook (depth):
stream := max.NewStream(key, secret)
stream.Subscribe(types.BookChannel, symbol, types.SubscribeOptions{})
streambook := types.NewStreamBook(symbol)
streambook.BindStream(stream)
Deployment
- Helm Chart
- Baremetal machine or a VPS
Development
Setting up your local repository
- Click the "Fork" button from the GitHub repository.
- Clone your forked repository into
$GOPATH/github.com/c9s/bbgo
. - Change directory into
$GOPATH/github.com/c9s/bbgo
. - Create a branch and start your development.
- Test your changes.
- Push your changes to your fork.
- Send a pull request.
Testing Desktop App
for webview
make embed && go run -tags web ./cmd/bbgo-webview
for lorca
make embed && go run -tags web ./cmd/bbgo-lorca
FAQ
What's Position?
- Base Currency & Quote Currency https://www.ig.com/au/glossary-trading-terms/base-currency-definition
- How to calculate average cost? https://www.janushenderson.com/en-us/investor/planning/calculate-average-cost/
Looking For A New Strategy?
You can write an article about BBGO in any topic, in 750-1500 words for exchange, and I can implement the strategy for you (depends on the complexity and efforts). If you're interested in, DM me in telegram https://t.me/c123456789s or twitter https://twitter.com/c9s, we can discuss.
Adding New Crypto Exchange support?
If you want BBGO to support a new crypto exchange that is not included in the current BBGO, we can implement it for you. The cost is 10 ETH. If you're interested in it, DM me in telegram https://t.me/c123456789s.
Community
- Telegram Group https://t.me/bbgo_intl
- Telegram Group (Taiwan) https://t.me/bbgocrypto
- Twitter https://twitter.com/bbgotrading
Contributing
See Contributing
Financial Contributors
BBGO Tokenomics
To support the development of BBGO, we have created a bounty pool to support contributors by giving away $BBG tokens. Check the details in $BBG Contract Page and our official website
Supporter
- GitBook
License
AGPL License