bludnic / opentrader

Open-source crypto trading bot

OpenTrader is an advanced cryptocurrency trading bot offering high-frequency, cross-exchange arbitrage and event-based strategies, including technical analysis with indicators. Features a user-friendly management UI, robust backtesting capabilities, and support for 100+ exchanges via CCXT.

Strategies:

• Grid: A grid trading strategy that profits from the price fluctuation of an asset.
• RSI: A Relative Strength Index (RSI) strategy that buys and sells based on the RSI indicator.
• DCA: Dollar-Cost Averaging (DCA) strategy that buys an asset at regular intervals.

Supported exchanges: OKX, BYBIT, BINANCE, KRAKEN, COINBASE, GATEIO

Quick start

Requirements

# NodeJS v20 or higher
$ node -v

# `pnpm` must be installed
$ pnpm -v

# Install Turborepo globally
$ pnpm install turbo --global

# Docker (optional)
$ docker -v

Environment variables

The project uses a single .env file in the root directory. Frameworks such as Next.js require the .env file to be located directly in the project directory. To address this, some apps/packages might include a symlink pointing to the root .env file.

1. Create environment file .env in the root directory

$ cp .env.example .env

2. Replace the DATABASE_URL if your URL is different from the actual one.

Installation

1. Install dependencies

$ pnpm install

2. Build packages

$ turbo run build

3. Run db migrations

$ turbo run prisma:migrate

4. Seed the database

$ turbo run prisma:seed

⚠️ Note: Since the packages do not have a dev server, running the build command is mandatory on the first run.

Basic usage

Connect an exchange

Copy the exchanges.sample.json5 file to exchanges.json5 and add your API keys.

Supported exchanges: OKX, BYBIT, BINANCE, KRAKEN, COINBASE, GATEIO

Choose a strategy

Create the strategy configuration file config.json5. We will use the grid strategy as an example.

{
  // Grid strategy params
  settings: {
    highPrice: 70000, // upper price of the grid
    lowPrice: 60000, // lower price of the grid
    gridLevels: 20, // number of grid levels
    quantityPerGrid: 0.0001, // quantity in base currency per each grid
  },
  pair: "BTC/USDT",
  exchange: "DEFAULT",
}

Currently supported strategies: grid, rsi

Run a backtest

Command: ./bin/cli.sh backtest <strategy> --from <date> --to <date> -t <timeframe>

Example running a grid strategy on 1h timeframe.

$ bin/cli.sh backtest grid --from 2024-03-01 --to 2024-06-01 -t 1h

To get more accurate results, use a smaller timeframe, e.g. 1m, however, it will take more time to download OHLC data from the exchange.

Live trading

Starting the daemon

Before running live trading, you need to start the daemon:

$ bin/cli.sh up

Now the daemon is ready to listen for incoming commands.

Tip: To run the daemon in the background, use: bin/cli.sh up -d

Running a Live Trading

Command: bin/cli.sh trade <strategy>

Example running a live trading with grid strategy.

$ bin/cli.sh trade grid

To stop the live trading, run bin/cli.sh stop

Stop the daemon

To stop the daemon, run the following command:

$ bin/cli.sh down

UI

The user interface allows managing multiple bots and strategies, viewing backtest results, and monitoring live trading.

Currently, the UI is under development. For early access, please email me at [email protected]

After getting the access, run the following command to pull the UI into monorepo:

$ git submodule update --init

Run frontend app:

$ pnpm i
$ turbo run build
$ turbo run dev

• Frontend: http://localhost:3000
• API: http://localhost:4000

Project structure

• Strategies dir: packages/bot-templates
• Indicators: packages/indicators
• Exchange connectors: packages/exchanges

🪪 License

Licensed under the Apache 2.0 License. See the LICENSE file for more information.

opentrader's Issues

Create a `shrinkwrap.json` from `pnpm-lock.yaml` before publishing to NPM

Pre-launch checklist

Documentation

• Project has a LICENSE file with an open source license
• Project has basic documentation (README, CONTRIBUTING, CODE_OF_CONDUCT)
• The name is easy to remember, gives some idea of what the project does, and does not conflict with an existing project or infringe on trademarks
• The issue queue is up-to-date, with issues clearly organized and labeled

Code

• Project uses consistent code conventions and clear function/method/variable names
• The code is clearly commented, documenting intentions and edge cases
• There are no sensitive materials in the revision history, issues, or pull requests (for example, passwords or other non-public information)

Dashboard: Found a bug? Link to the Github Issues

Deploy a demo app

Do it after Paper Trading support #38
Disable all real trading features.
Add a banner at the top of the page indicating that this is a DEMO only.
Separate workflow in Github Actions.

Bot strategy run policy

export function* strategy() {
  // ...
}

strategy.runPolicy = {
  // Option 1: Run every hour
  interval: "1h",
  // Option 2: Run every timeframe interval
  candleClosed: (botConfig) => botConfig.timeframe,
  // Option 3: Run on order status change
  orderStatusChangedTo: "filled",
  // Option 3.1: Run on order status change (list of statuses)
  orderStatusChangedTo: ["filled", "partially-filled"],
  // Option 4: On orderbook change (for arb strategies)
  watchOrderBook: true,
  // Option 5: On public trade happened
  watchTrades: true
}

CLI & Telegram bot

Commands

• opentrader start [strategy]: Start bot
• opentrader stop: Stop bot
• opentrader stats: Get bot statistics
• opentrader orders: Current open orders
• opentrader history: Closed orders
• opentrader trades: Get trades
• opentrader performance: Bot performance
• opentrader profit: Profit statistics
• opentrader new [name] [params=JSON]: Create a bot

Bot started / stopped datetime markers on the Chart

Prettify on lint-staged

• Prettify and Eslint on lint-staged
• Format schema.prisma on lint-staged

Sync `@types/node` version across monorepo

Replace DATABASE_URL with SQLite format

Replace DATABASE_URL with SQLite format file:./dev.db

opentrader/.github/workflows/dev.yml

Line 25 in eb22dc8

--build-arg DATABASE_URL=postgresql://postgres:postgres@localhost:5432/postgres

• Replace DATABASE_URL in docker-compose.yaml
• Replace DATABASE_URL in Github Workflow
• Create a Docker volume and use it for storing dev.db file

Add Paper Trading

Fix: Replace `ccxt.loadMarkets()` with the `IExchange.loadMarkets()` wrapper to cache markets across exchange instances

This will probably not work. The second exchange will load markets from the exchange and not the database.

import { exchanges, cache } from '@opentrader/exchanges'
import { PrismaCacheProvider } from '@opentrader/exchanges/server'

cache.setCacheProvider(new PrismaCacheProvider())

const exchange1 = exchanges.OKX()
await exchange1.loadMarkets() // from cache

const exchange2 = exchanges.OKX()
await exchange2.fetchTicker('BTC/USDT') // will call `ccxt.loadMarkets()`

Missing NextJS dev indicator

It must be enabled by default. Even specifying devIndicators.buildActivity: true in the config doesn't has no effect.

My guess is that @mui/joy styles interfere with NextJS indicator.

Docs: https://nextjs.org/docs/app/api-reference/next-config-js/devIndicators

Validate strategy params before starting the bot

Add funding links (FUNDING.yml)

https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/displaying-a-sponsor-button-in-your-repository#displaying-a-sponsor-button-in-your-repository

Slow dev server with `@mui`

mui/material-ui#35840

https://vercel.com/blog/how-we-optimized-package-imports-in-next-js

Option to use SQLite instead of Postgres in Prisma

• Convert Enums to Strings. Instead define them manually using TS. Cast types in trpc package.
• SQLite introduced recently JSONB type, so wait until Prisma will implement it drizzle-team/drizzle-orm#1977

OKX:1INCH/EUR is not a valid symbolId

Fix regex

EventBus between Processor app and trpc package

• onEchangeAdded: Subscribe to OrdersChannel
• onBotCreated: Subscribe to CandlesChannel
• onExchangeRemoved: Unsubscribe from channel
• onBotRemoved/onBotDisabled: Unsubscribe from channel

Processing different types of SmartTrades

Currently we have two types of SmartTrades:

type SmartTradeType = "SmartTrade" | "DCA"

Entry and TakeProfit may be Order or Ladder.

type EntryType  = "Order" | "Ladder"
type TakeProfitType = "Order" | "Ladder"

Therefore there are 4 possible varieties of SmartTrade:

Buy	Sell
Order	Order
Order	Ladder
Ladder	Order
Ladder	Ladder

Need to create a package for processing every type and variety of SmartTrade. The API may be something like this:

SmartTrade

const entity = prisma.smartTrade.findUnique({ where: { id: 1 } })
const smartTrade = new SmartTradeProcessor(entity)

// must cancel all open orders and mark SmartTrade as closed
await smartTrade.cancel() 

// place the entry order (entryType == "Order")
// or the first order of ladder (entryType == "Ladder")
await smartTrade.entry() 

// OR using hooks
// e.g. using WebSockets and receiving events from the exchange
await smartTrade.handleOrderFilled(orderId) // the processor will decide by itself what to do with that event
await smartTrade.handleOrderCanceled(orderId)

// @internal
// place the next entry buy order if needed (entryType === "Ladder")
// place TP sell order if entry buy order was filled (entryType === "Order")
await smartTrade.publishNext()

DCA

const entity = prisma.smartTrade.findUnique({ where: { id: 2 } })
const dca = new DCATradeProcessor(entity)

await dca.cancel() // same as for SmartTrade
await dca.entry() // same as for SmartTrade

// if TP was filled, then mark DCA as completed
// if SO (Safety Order) was filled, then it must update the TP order limit price
// if SL was filled, the mark DCA as completed
await dca.handleOrderFilled(orderId)

// @internal
await dca.updateTakeProfit()

Rewrite the context to support cross exchange strategy

Current context:

type TBotContext<T extends IBotConfiguration> = {
  control: IBotControl;
  config: T;
  command: "start" | "stop" | "process";
  onStart: boolean;
  onStop: boolean;
  onProcess: boolean;
}

• Add persistent storage ctx.store
• Split ctx.config into ctx.exchanges and ctx.params (botParams)

Exchanges config sample:

{
  OKX: {
    name: "OKX Account",
    apiKey: "your-api-key",
    secretKey: "your-secret",
    password: "your-password",
  },
  BYBIT: {
    name: "ByBit Account",
    apiKey: "your-api-key",
    secretKey: "your-secret",
  },
  BYBIT2: {
    name: "ByBit Account #2",
    apiKey: "your-api-key",
    secretKey: "your-secret",
  },
}

README: Add shields

• Telegram link
• Stars
• License
• Commit activity
• Build: passing
• Donate
• Test coverage (maybe)

GridBot: add Console to track the bot running events

Something like this:

The bot events may be:

• START command received
• Getting the current asset price: $10.25 USDT
• Executing the bot template: template:GridBot
• SmartTrade with ref 0 and status Placed/Idle and { buy: 10, sell: 15 } was queued
• SmartTrade with ref 1 and status Filled/Idle and { buy: 15, sell: 20 } was queued
• Template execution done with no errors
• OrderPublisher: Sell Order of SmartTrade with ref 1 was placed on the exchange orderId: abc123
• OrderPublisher: An error occurred: OKXExchange: { message: "Rate limit exceeded" }

Unify `IGetLimitOrderResponse` and `IWatchOrder`

Upgrade `zod`

Handle gaps in the candles channel

Upgrade ReactQuery to v5

Update dependency @tanstack/react-query from v4 -> v5.
Note: The @trpc/react-query still uses v4 of ReactQuery. Must wait until tRPC will support v5.

README: Add a screenshot/gif of the app

Better authorization

Use NextAuth https://next-auth.js.org/

Dashboard: Add favicon, logo, manifest, meta and other assets

• Add favicon
• Replace logo in the Github organisation
• Add logo in README.md
• Replace logo in frontend app

Add possibility to control the fetch implementation of CCXT

Need a similar solution as controlling the cache strategy:

import { ExchangeCode } from "@opentrader/types";
import { exchanges, cache } from "@opentrader/exchanges";
import { PrismaCacheProvider } from '@opentrader/exchanges/server'

cache.setCacheProvider(new PrismaCacheProvider());

const exchange = exchanges[ExchangeCode.OKX]();
const markets = await exchange.loadMarkets();

Checklist

• Implement cache.setFetchImplementation()
• Test without specifying fetch implementation in browser
• Test without specifying fetch implementation in any Node.js server (e.g. ExpressJS or NestJS)
• Test with NextJS fetch cache.setFetchImplementation(fetch)
• Check if the request are not cached by NextJS (may require to disable the cache)

Add "Check" button on Exchanges page

Must check if exchange credentials work

Failed to used Pino logger in browser

Job failed after importing @opentrader/exchanges -> logger from frontend app.
https://github.com/bludnic/opentrader/actions/runs/9046641961/job/24857683790

Browser logging docs:
https://github.com/pinojs/pino/blob/main/docs/browser.md

Mark exchange account as disabled when the keys are expired or invalid credentials were provided

• Migrate DB. Add disabled column
• Mark exchange account as disabled when starting the bot
• Update seed data

Use single source of ENV variables

Currently using a workaround with a symlink to root .env:

.env ← apps/frontend/.env
.env ← apps/processor/.env
.env ← packages/prisma/.env

About ENV variable in Turbo repo:

• https://turbo.build/repo/docs/core-concepts/caching/environment-variable-inputs
• https://turbo.build/repo/docs/handbook/environment-variables

Add more exchanges (BybBit, Binance, Kraken, Coinbase, Gateio)

Get rid of Prisma env conflict warning

Discussion: prisma/prisma#9726

UI with LineChart for profits

Example on Coinruler

From email.

Major version update: `usehooks-ts`, `RTK`, `date-fns`

Major version available: v2 -> v3
https://www.npmjs.com/package/usehooks-ts

useElementSize was deprecated
https://github.com/bludnic/opentrader-pro/blob/dev/frontend/src/ui/charts/Chart/BaseChart.tsx#L16