bbgo
A trading bot framework written in Go. The name bbgo comes from the BB8 bot in the Star Wars movie. aka Buy BitCoin Go!
Current Status
Features
- Exchange abstraction interface
- Stream integration (user data websocket)
- PnL calculation
- Slack notification
- KLine-based backtest
- Built-in strategies
- Multi-session support
- Standard indicators (SMA, EMA, BOLL)
Supported Exchanges
- MAX Exchange (located in Taiwan)
- Binance Exchange
- FTX (working in progress)
Requirements
Get your exchange API key and secret after you register the accounts (you can choose one or more exchanges):
- For MAX: https://max.maicoin.com/signup?r=c7982718
- For Binance: https://www.binancezh.com/en/register?ref=VGDGLT80
- For FTX: https://ftx.com/#a=7710474
Since the exchange implementation and support are done by a small team, if you like the work they've done for you, It would be great if you can use their referral code as your support to them. :-D
Installation
Install from binary
The following script will help you set up a config file, dotenv file:
bash <(curl -s https://raw.githubusercontent.com/c9s/bbgo/main/scripts/setup-grid.sh)
Install and Run from the One-click Linode StackScript:
- BBGO USDT/TWD Market Grid Trading https://cloud.linode.com/stackscripts/793380
- BBGO Standard Grid Trading https://cloud.linode.com/stackscripts/795788
Install from source
Install the bbgo command:
go get -u github.com/c9s/bbgo/cmd/bbgo
Add your dotenv file:
# if you have one
BINANCE_API_KEY=
BINANCE_API_SECRET=
# if you have one
MAX_API_KEY=
MAX_API_SECRET=
# if you have one
FTX_API_KEY=
FTX_API_SECRET=
# specify it if credentials are for subaccount
FTX_SUBACCOUNT=
Prepare your dotenv file .env.local and BBGO yaml config file bbgo.yaml.
The minimal bbgo.yaml could be generated by:
curl -o bbgo.yaml https://raw.githubusercontent.com/c9s/bbgo/main/config/minimal.yaml
To sync your own trade data:
bbgo sync --session max
bbgo sync --session binance
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 sync remote exchange klines data for backtesting:
bbgo backtest --exchange binance -v --sync --sync-only --sync-from 2020-01-01
To run backtest:
bbgo backtest --exchange binance --base-asset-baseline
To query transfer history:
bbgo transfer-history --session max --asset USDT --since "2019-01-01"
To calculate pnl:
bbgo pnl --exchange binance --asset BTC --since "2019-01-01"
To run strategy:
bbgo run
Advanced Setup
Setting up Telegram Bot Notification
Open your Telegram app, and chat with @botFather
Enter /newbot to create a new bot
Enter the bot display name. ex. your_bbgo_bot
Enter the bot username. This should be global unique. e.g., bbgo_bot_711222333
Botfather will response your a bot token. Keep bot token safe
Set TELEGRAM_BOT_TOKEN in the .env.local file, e.g.,
TELEGRAM_BOT_TOKEN=347374838:ABFTjfiweajfiawoejfiaojfeijoaef
For the telegram chat authentication (your bot needs to verify it's you), if you only need a fixed authentication token, you can set TELEGRAM_AUTH_TOKEN in the .env.local file, e.g.,
TELEGRAM_BOT_AUTH_TOKEN=itsme55667788
Run your bbgo,
Open your Telegram app, search your bot bbgo_bot_711222333
Enter /start and /auth {code}
Done! your notifications will be routed to the telegram chat.
Setting up Slack Notification
Put your slack bot token in the .env.local file:
SLACK_TOKEN=xxoox
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.
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
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=root@tcp(127.0.0.1:3306)/bbgo
Configure Sqlite3 Database
Just put these environment variables in your .env.local file:
DB_DRIVER=sqlite3
DB_DSN=bbgo.sqlite3
Built-in Strategies
Check out the strategy directory strategy for all built-in strategies:
pricealertstrategy demonstrates how to use the notification system pricealertxpuremakerstrategy demonstrates how to maintain the orderbook and submit maker orders xpuremakerbuyandholdstrategy demonstrates how to subscribe kline events and submit market order buyandholdbollgridstrategy implements a basic grid strategy with the built-in bollinger indicator bollgridgridstrategy implements the fixed price band grid strategy gridflashcrashstrategy implements a strategy that catches the flashcrash flashcrash
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
Adding New Built-in Strategy
Fork and clone this repository, Create a directory under pkg/strategy/newstrategy, write your strategy at pkg/strategy/newstrategy/strategy.go.
Define a strategy struct:
package newstrategy
import (
"github.com/c9s/bbgo/pkg/fixedpoint"
)
type Strategy struct {
Symbol string `json:"symbol"`
Param1 int `json:"param1"`
Param2 int `json:"param2"`
Param3 fixedpoint.Value `json:"param3"`
}
Register your strategy:
const ID = "newstrategy"
const stateKey = "state-v1"
var log = logrus.WithField("strategy", ID)
func init() {
bbgo.RegisterStrategy(ID, &Strategy{})
}
Implement the strategy methods:
func (s *Strategy) Subscribe(session *bbgo.ExchangeSession) {
session.Subscribe(types.KLineChannel, s.Symbol, types.SubscribeOptions{Interval: "1m"})
}
func (s *Strategy) Run(ctx context.Context, orderExecutor bbgo.OrderExecutor, session *bbgo.ExchangeSession) error {
// ....
return nil
}
Edit pkg/cmd/builtin.go, and import the package, like this:
package cmd
// import built-in strategies
import (
_ "github.com/c9s/bbgo/pkg/strategy/bollgrid"
_ "github.com/c9s/bbgo/pkg/strategy/buyandhold"
_ "github.com/c9s/bbgo/pkg/strategy/flashcrash"
_ "github.com/c9s/bbgo/pkg/strategy/grid"
_ "github.com/c9s/bbgo/pkg/strategy/mirrormaker"
_ "github.com/c9s/bbgo/pkg/strategy/pricealert"
_ "github.com/c9s/bbgo/pkg/strategy/support"
_ "github.com/c9s/bbgo/pkg/strategy/swing"
_ "github.com/c9s/bbgo/pkg/strategy/trailingstop"
_ "github.com/c9s/bbgo/pkg/strategy/xmaker"
_ "github.com/c9s/bbgo/pkg/strategy/xpuremaker"
)
Write your own 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
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 {
*bbgo.Notifiability
}
And then, in your code, you can call the methods of Notifiability.
Supported components (single exchange strategy only for now):
*bbgo.Notifiabilitybbgo.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:
*bbgo.ExchangeSessiontypes.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)
How To Add A New Exchange
(TBD)
Helm Chart
Prepare your docker image locally (you can also use the docker image from docker hub):
make docker DOCKER_TAG=1.16.0
The docker tag version number is from the file Chart.yaml
Prepare your secret:
kubectl create secret generic bbgo-grid --from-env-file .env.local
Configure your config file, the chart defaults to read config/bbgo.yaml to create a configmap:
cp config/grid.yaml config/bbgo.yaml
vim config/bbgo.yaml
Install chart with the preferred release name, the release name maps to the previous secret we just created, that is, bbgo-grid:
helm install bbgo-grid ./charts/bbgo
Delete chart:
helm delete bbgo
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.
Adding new migration
rockhopper --config rockhopper_sqlite.yaml create --type sql add_pnl_column
rockhopper --config rockhopper_mysql.yaml create --type sql add_pnl_column
or
bash utils/generate-new-migration.sh add_pnl_column
Be sure to edit both sqlite3 and mysql migration files.
To test the drivers, you can do:
rockhopper --config rockhopper_sqlite.yaml up
rockhopper --config rockhopper_mysql.yaml up
Setup frontend development environment
cd frontend
yarn install
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
Support
By contributing pull requests
Any pull request is welcome, documentation, format fixing, testing, features.
By registering account with referral ID
You may register your exchange account with my referral ID to support this project.
- For MAX Exchange: https://max.maicoin.com/signup?r=c7982718 (default commission rate to your account)
- For Binance Exchange: https://www.binancezh.com/en/register?ref=VGDGLT80 (5% commission back to your account)
By small amount cryptos
- BTC address
3J6XQJNWT56amqz9Hz2BEVQ7W4aNmb5kiU - USDT ERC20 address
0x63E5805e027548A384c57E20141f6778591Bac6F
Community
You can join our telegram channel https://t.me/bbgocrypto, it's in Chinese, but English is fine as well.
Contribution
BBGO has a token BBG for the ecosystem (contract address: https://etherscan.io/address/0x3afe98235d680e8d7a52e1458a59d60f45f935c0).
Each issue has its BBG label, by completing the issue with a pull request, you can get correspond amount of BBG.
If you have feature request, you can offer your BBG for contributors.
For further request, please contact us: https://t.me/c123456789s
License
MIT License
![strategy: grid2 [part2] -- reverse order and arb profit calculation](https://avatars.githubusercontent.com/u/50894?v=4)
