bbgo_origin/README.md

556 lines
14 KiB
Markdown
Raw Normal View History

2022-01-05 09:59:29 +00:00
# BBGO
2020-10-08 12:49:05 +00:00
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
2021-12-04 16:39:36 +00:00
[![Go](https://github.com/c9s/bbgo/actions/workflows/go.yml/badge.svg?branch=main)](https://github.com/c9s/bbgo/actions/workflows/go.yml)
2021-12-27 17:53:37 +00:00
[![DockerHub](https://img.shields.io/docker/pulls/yoanlin/bbgo.svg)](https://hub.docker.com/r/yoanlin/bbgo)
2021-12-27 03:59:38 +00:00
<img alt="open collective badge" src="https://opencollective.com/bbgo/tiers/badge.svg">
<img alt="open collective badge" src="https://opencollective.com/bbgo/tiers/backer/badge.svg?label=backer&color=brightgreen" />
2020-10-10 05:19:54 +00:00
2022-01-05 09:59:29 +00:00
## Community
[![Telegram Global](https://img.shields.io/badge/telegram-global-blue.svg)](https://t.me/bbgo_intl)
[![Telegram Taiwan](https://img.shields.io/badge/telegram-tw-blue.svg)](https://t.me/bbgocrypto)
[![Twitter](https://img.shields.io/twitter/follow/bbgotrading?label=Follow&style=social)](https://twitter.com/bbgotrading)
2020-10-08 12:49:05 +00:00
## Features
2021-12-25 15:04:24 +00:00
- 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](./doc/topics/twap.md)
- PnL calculation.
- Slack/Telegram notification.
- Back-testing: KLine-based back-testing engine. See [Back-testing](./doc/topics/back-testing.md)
- Built-in Grid strategy.
- Many built-in strategies.
- Multi-exchange session support: you can connect to more than 2 exchanges with different accounts or subaccounts.
- Standard indicators, e.g., SMA, EMA, BOLL, VMA, MACD...
2021-12-27 15:51:55 +00:00
- React-powered Web Dashboard.
- Docker image ready.
- Kubernetes support.
- Helm chart ready.
2020-10-08 12:49:05 +00:00
2021-12-06 16:40:47 +00:00
## Screenshots
![bbgo dashboard](assets/screenshots/dashboard.jpeg)
2020-10-08 14:31:09 +00:00
## Supported Exchanges
2021-12-30 15:50:53 +00:00
- Binance Spot Exchange (and binance.us)
2021-10-07 08:40:57 +00:00
- FTX Spot Exchange
2021-12-14 10:26:46 +00:00
- OKEx Spot Exchange
2021-12-25 19:25:29 +00:00
- Kucoin Spot Exchange
- MAX Spot Exchange (located in Taiwan)
2020-10-08 14:31:09 +00:00
2020-10-27 12:21:28 +00:00
## Requirements
2021-03-20 02:16:07 +00:00
Get your exchange API key and secret after you register the accounts (you can choose one or more exchanges):
2020-10-27 12:21:28 +00:00
2021-12-09 04:05:50 +00:00
- MAX: <https://max.maicoin.com/signup?r=c7982718>
- Binance: <https://www.binancezh.com/en/register?ref=VGDGLT80>
- FTX: <https://ftx.com/#a=7710474>
- OKEx: <https://www.okex.com/join/2412712?src=from:ios-share>
2021-12-22 18:56:18 +00:00
- Kucoin: <https://www.kucoin.com/ucenter/signup?rcode=r3KX2D4>
2021-03-19 03:07:15 +00:00
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
2020-10-27 12:21:28 +00:00
2020-10-10 05:18:40 +00:00
## Installation
2021-03-13 12:02:05 +00:00
### Install from binary
The following script will help you set up a config file, dotenv file:
2021-03-13 12:02:05 +00:00
2021-03-29 10:38:55 +00:00
```sh
2021-12-30 05:49:51 +00:00
# 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
2021-03-13 12:02:05 +00:00
```
2021-12-06 15:29:46 +00:00
### One-click Linode StackScript:
- BBGO Grid Trading on Binance <https://cloud.linode.com/stackscripts/950715>
- BBGO USDT/TWD Grid Trading on MAX <https://cloud.linode.com/stackscripts/793380>
- BBGO USDC/TWD Grid Trading on MAX <https://cloud.linode.com/stackscripts/797776>
- BBGO LINK/TWD Grid Trading on MAX <https://cloud.linode.com/stackscripts/797774>
- BBGO USDC/USDT Grid Trading on MAX <https://cloud.linode.com/stackscripts/797777>
- BBGO Standard Grid Trading on MAX <https://cloud.linode.com/stackscripts/795788>
2021-12-06 15:29:46 +00:00
### Build from source
2021-03-13 12:02:05 +00:00
2021-12-06 15:29:46 +00:00
See [Build from source](./doc/build-from-source.md)
2021-05-09 17:00:12 +00:00
2021-12-06 15:29:46 +00:00
## Configuration
2020-10-10 05:18:40 +00:00
2020-10-11 08:05:07 +00:00
Add your dotenv file:
2021-03-29 10:38:55 +00:00
```sh
2021-12-22 14:28:10 +00:00
# for Binance Exchange, if you have one
2020-10-11 08:05:07 +00:00
BINANCE_API_KEY=
BINANCE_API_SECRET=
2021-12-30 15:46:43 +00:00
# if you want to use binance.us, change this to 1
BINANCE_US=0
2021-12-22 14:28:10 +00:00
# for MAX exchange, if you have one
2020-10-11 08:05:07 +00:00
MAX_API_KEY=
MAX_API_SECRET=
2021-12-22 14:28:10 +00:00
# for FTX exchange, if you have one
2021-02-05 13:27:29 +00:00
FTX_API_KEY=
FTX_API_SECRET=
# specify it if credentials are for subaccount
2021-03-15 10:52:31 +00:00
FTX_SUBACCOUNT=
2021-12-22 14:28:10 +00:00
# for OKEx exchange, if you have one
OKEX_API_KEY=
OKEX_API_SECRET=
OKEX_API_PASSPHRASE
2021-12-26 08:03:44 +00:00
# for kucoin exchange, if you have one
KUCOIN_API_KEY=
KUCOIN_API_SECRET=
KUCOIN_API_PASSPHRASE=
KUCOIN_API_KEY_VERSION=2
2020-10-11 08:05:07 +00:00
```
2021-02-25 04:49:25 +00:00
Prepare your dotenv file `.env.local` and BBGO yaml config file `bbgo.yaml`.
2020-10-10 10:01:37 +00:00
2022-01-26 15:56:16 +00:00
To check the available environment variables, please see [Environment Variables](./doc/configuration/envvars.md)
The minimal bbgo.yaml could be generated by:
2021-03-19 03:00:20 +00:00
2021-03-29 10:38:55 +00:00
```sh
2021-03-20 02:16:51 +00:00
curl -o bbgo.yaml https://raw.githubusercontent.com/c9s/bbgo/main/config/minimal.yaml
```
2021-12-06 16:02:03 +00:00
To run strategy:
2021-03-29 10:38:55 +00:00
```sh
2021-12-06 16:02:03 +00:00
bbgo run
```
2021-12-06 16:02:03 +00:00
To start bbgo with the frontend dashboard:
2020-11-23 06:50:57 +00:00
```sh
2021-12-06 16:02:03 +00:00
bbgo run --enable-webserver
2020-11-23 06:50:57 +00:00
```
2021-12-06 16:02:03 +00:00
If you want to switch to other dotenv file, you can add an `--dotenv` option or `--config`:
2020-11-23 06:50:57 +00:00
```sh
2021-12-06 16:02:03 +00:00
bbgo sync --dotenv .env.dev --config config/grid.yaml --session binance
2020-11-23 06:50:57 +00:00
```
2021-12-06 16:02:03 +00:00
2020-10-11 12:11:22 +00:00
To query transfer history:
```sh
2021-02-17 06:43:08 +00:00
bbgo transfer-history --session max --asset USDT --since "2019-01-01"
2020-10-11 12:11:22 +00:00
```
To calculate pnl:
```sh
bbgo pnl --exchange binance --asset BTC --since "2019-01-01"
2020-10-11 12:11:22 +00:00
```
2021-12-05 18:03:04 +00:00
## Advanced Configuration
2021-03-19 03:00:20 +00:00
2021-12-09 12:35:14 +00:00
### Notification
- [Setting up Telegram notification](./doc/configuration/telegram.md)
- [Setting up Slack notification](./doc/configuration/slack.md)
2021-03-19 03:00:20 +00:00
### 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.
2021-03-19 03:02:35 +00:00
2021-03-19 03:00:20 +00:00
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:
2021-03-29 10:38:55 +00:00
```sh
2021-03-19 03:00:20 +00:00
# For Ubuntu Linux
sudo apt-get install -y mysql-server
```
2021-03-19 03:52:09 +00:00
Or [run it in docker](https://hub.docker.com/_/mysql)
2021-03-19 03:00:20 +00:00
Create your mysql database:
2021-03-29 10:38:55 +00:00
```sh
2021-03-19 03:00:20 +00:00
mysql -uroot -e "CREATE DATABASE bbgo CHARSET utf8"
```
Then put these environment variables in your `.env.local` file:
2021-03-29 10:38:55 +00:00
```sh
2021-03-19 03:00:20 +00:00
DB_DRIVER=mysql
DB_DSN="user:password@tcp(127.0.0.1:3306)/bbgo"
2021-03-19 03:00:20 +00:00
```
#### Configure Sqlite3 Database
Just put these environment variables in your `.env.local` file:
2021-03-29 10:38:55 +00:00
```sh
2021-03-19 03:00:20 +00:00
DB_DRIVER=sqlite3
DB_DSN=bbgo.sqlite3
```
2021-12-06 16:02:03 +00:00
## Synchronizing your own trading data
Once you have your database configured, you can sync your own trading data from the exchange.
2022-01-26 16:24:31 +00:00
See [Configure Sync For Private Trading Data](./doc/configuration/sync.md)
2021-12-06 16:02:03 +00:00
2021-12-20 03:16:16 +00:00
## Using Redis to keep persistence between BBGO sessions
To use Redis, first you need to install your Redis server:
```sh
# For Ubuntu/Debian Linux
sudo apt-get install -y redis
```
Set the following environment variables in your `bbgo.yaml`:
```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.
```
2020-10-27 11:24:39 +00:00
## Built-in Strategies
Check out the strategy directory [strategy](pkg/strategy) for all built-in strategies:
2021-12-09 12:35:14 +00:00
- `pricealert` strategy demonstrates how to use the notification system [pricealert](pkg/strategy/pricealert). See
[document](./doc/strategy/pricealert.md).
2021-03-19 03:00:20 +00:00
- `xpuremaker` strategy demonstrates how to maintain the orderbook and submit maker
orders [xpuremaker](pkg/strategy/xpuremaker)
- `buyandhold` strategy demonstrates how to subscribe kline events and submit market
2021-10-14 05:10:00 +00:00
order [buyandhold](pkg/strategy/pricedrop)
2021-03-19 03:00:20 +00:00
- `bollgrid` strategy implements a basic grid strategy with the built-in bollinger
indicator [bollgrid](pkg/strategy/bollgrid)
2021-12-27 10:42:42 +00:00
- `grid` strategy implements the fixed price band grid strategy [grid](pkg/strategy/grid). See
[document](./doc/strategy/grid.md).
2021-12-16 10:30:38 +00:00
- `support` strategy implements the fixed price band grid strategy [support](pkg/strategy/support). See
[document](./doc/strategy/support.md).
2020-11-07 04:24:18 +00:00
- `flashcrash` strategy implements a strategy that catches the flashcrash [flashcrash](pkg/strategy/flashcrash)
2021-03-19 03:00:20 +00:00
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
2020-11-07 04:26:08 +00:00
`buyandhold` strategy:
2020-11-07 04:24:18 +00:00
```sh
vim config/buyandhold.yaml
# run bbgo with the config
bbgo run --config config/buyandhold.yaml
2020-11-07 04:24:18 +00:00
```
2020-10-27 11:24:39 +00:00
2021-12-06 16:17:35 +00:00
## Back-testing
See [Back-testing](./doc/topics/back-testing.md)
## 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:
```go
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:
```go
package newstrategy
const ID = "newstrategy"
const stateKey = "state-v1"
var log = logrus.WithField("strategy", ID)
func init() {
2021-05-27 19:05:59 +00:00
bbgo.RegisterStrategy(ID, &Strategy{})
}
```
Implement the strategy methods:
```go
package newstrategy
func (s *Strategy) Subscribe(session *bbgo.ExchangeSession) {
2021-05-27 19:05:59 +00:00
session.Subscribe(types.KLineChannel, s.Symbol, types.SubscribeOptions{Interval: "2m"})
}
func (s *Strategy) Run(ctx context.Context, orderExecutor bbgo.OrderExecutor, session *bbgo.ExchangeSession) error {
2021-05-27 19:05:59 +00:00
// ....
return nil
}
```
Edit `pkg/cmd/builtin.go`, and import the package, like this:
```go
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/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"
)
```
2020-10-27 12:36:20 +00:00
## Write your own strategy
Create your go package, and initialize the repository with `go mod` and add bbgo as a dependency:
2021-03-29 10:38:55 +00:00
```sh
2020-10-27 12:36:20 +00:00
go mod init
2021-01-21 04:32:39 +00:00
go get github.com/c9s/bbgo@main
2020-10-27 12:36:20 +00:00
```
2021-01-21 04:32:39 +00:00
Write your own strategy in the strategy file:
2020-10-27 12:36:20 +00:00
2021-03-29 10:38:55 +00:00
```sh
2021-01-21 04:32:39 +00:00
vim strategy.go
2020-10-27 12:36:20 +00:00
```
You can grab the skeleton strategy from <https://github.com/c9s/bbgo/blob/main/pkg/strategy/skeleton/strategy.go>
Now add your config:
2021-03-29 10:38:55 +00:00
```sh
2020-10-27 12:36:20 +00:00
mkdir config
2020-10-27 12:38:56 +00:00
(cd config && curl -o bbgo.yaml https://raw.githubusercontent.com/c9s/bbgo/main/config/minimal.yaml)
2020-10-27 12:36:20 +00:00
```
Add your strategy package path to the config file `config/bbgo.yaml`
```yaml
2021-01-21 04:32:39 +00:00
---
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
2020-10-27 12:36:20 +00:00
```
Run `bbgo run` command, bbgo will compile a wrapper binary that imports your strategy:
```sh
dotenv -f .env.local -- bbgo run --config config/bbgo.yaml
```
2021-01-21 04:32:39 +00:00
Or you can build your own wrapper binary via:
```shell
bbgo build --config config/bbgo.yaml
```
2021-05-27 19:05:59 +00:00
## Command Usages
### Submitting Orders to a specific exchagne session
```shell
bbgo submit-order --session=okex --symbol=OKBUSDT --side=buy --price=10.0 --quantity=1
```
### Listing Open Orders of a specific exchange session
```sh
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
```shell
# 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
```shell
bbgo userdatastream --session okex
bbgo userdatastream --session max
bbgo userdatastream --session binance
```
2020-10-27 12:36:20 +00:00
## Dynamic Injection
In order to minimize the strategy code, bbgo supports dynamic dependency injection.
2021-03-19 03:00:20 +00:00
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:
2020-10-27 12:36:20 +00:00
```go
type Strategy struct {
2021-03-19 03:00:20 +00:00
*bbgo.Notifiability
2020-10-27 12:36:20 +00:00
}
```
And then, in your code, you can call the methods of Notifiability.
Supported components (single exchange strategy only for now):
- `*bbgo.Notifiability`
- `bbgo.OrderExecutor`
2021-03-19 03:00:20 +00:00
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:
2020-11-07 04:24:18 +00:00
- `*bbgo.ExchangeSession`
- `types.Market`
2021-03-15 09:57:03 +00:00
## Strategy Execution Phases
1. Load config from the config file.
2. Allocate and initialize exchange sessions.
3. Add exchange sessions to the environment (the data layer).
2021-03-15 09:58:10 +00:00
4. Use the given environment to initialize the trader object (the logic layer).
2021-03-15 09:57:03 +00:00
5. The trader initializes the environment and start the exchange connections.
6. Call strategy.Run() method sequentially.
2020-10-18 03:20:44 +00:00
## Exchange API Examples
2020-10-10 04:06:22 +00:00
2020-10-10 04:07:12 +00:00
Please check out the example directory: [examples](examples)
2020-10-10 04:06:22 +00:00
2020-10-10 04:09:23 +00:00
Initialize MAX API:
```go
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):
```go
stream := max.NewStream(key, secret)
stream.Subscribe(types.BookChannel, symbol, types.SubscribeOptions{})
streambook := types.NewStreamBook(symbol)
streambook.BindStream(stream)
```
2021-12-27 16:18:37 +00:00
## Deployment
2021-03-15 09:57:42 +00:00
2021-12-27 16:18:37 +00:00
- [Helm Chart](./doc/deployment/helm-chart.md)
- Baremetal machine or a VPS
2020-12-17 07:31:00 +00:00
2021-02-15 12:30:53 +00:00
## Development
2021-12-27 16:18:37 +00:00
- [Adding New Exchange](./doc/development/adding-new-exchange.md)
- [Migration](./doc/development/migration.md)
2021-03-18 06:57:03 +00:00
### Setting up your local repository
1. Click the "Fork" button from the GitHub repository.
2. Clone your forked repository into `$GOPATH/github.com/c9s/bbgo`.
3. Change directory into `$GOPATH/github.com/c9s/bbgo`.
4. Create a branch and start your development.
2021-03-19 03:00:20 +00:00
5. Test your changes.
2021-03-18 06:57:03 +00:00
6. Push your changes to your fork.
7. Send a pull request.
2021-02-18 01:24:24 +00:00
### Setup frontend development environment
2021-03-29 10:38:55 +00:00
```sh
2021-02-18 01:24:24 +00:00
cd frontend
yarn install
```
### Testing Desktop App
for webview
```sh
make embed && go run -tags web ./cmd/bbgo-webview
```
for lorca
```sh
make embed && go run -tags web ./cmd/bbgo-lorca
```
2021-12-13 06:22:22 +00:00
## 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/>
2020-10-08 14:31:09 +00:00
2021-11-25 18:57:07 +00:00
## Contributing
2020-10-11 08:31:58 +00:00
2021-11-25 18:58:03 +00:00
See [Contributing](./CONTRIBUTING.md)
2020-10-08 14:31:09 +00:00
2021-12-27 03:59:38 +00:00
### Financial Contributors
<object type="image/svg+xml" data="https://opencollective.com/bbgo/tiers/backer.svg?avatarHeight=36&width=600"></object>
2021-12-01 16:52:03 +00:00
## Supporter
- GitBook
2020-10-08 12:49:05 +00:00
## License
MIT License