From 50c2333f48dc93cb6c6622f2ce785edcca874898 Mon Sep 17 00:00:00 2001 From: VladKochetov007 Date: Thu, 28 Nov 2024 03:17:18 +0200 Subject: [PATCH] docs --- README.md | 308 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 308 insertions(+) diff --git a/README.md b/README.md index e3bb114..9e4ff60 100644 --- a/README.md +++ b/README.md @@ -6,3 +6,311 @@ A simple, fast, and powerful library for algorithmic trading in Go, **with no dependencies**. +## Table of Contents +- [Features](#features) +- [Installation](#installation) +- [Quick Start](#quick-start) +- [Strategies](#strategies) + - [Bollinger Bands Strategy](#bollinger-bands-strategy) + - [Grid Trading Bot](#grid-trading-bot) + - [Custom Strategy](#custom-strategy) +- [Backtesting](#backtesting) +- [Portfolio Management](#portfolio-management) +- [Exchange Simulation](#exchange-simulation) + +## Features +- Zero external dependencies +- Event-driven architecture +- Built-in strategy implementations +- Backtesting engine with market and limit orders support +- Portfolio management tools +- Exchange simulation for testing +- Support for both spot and margin trading +- Customizable commission rates +- Performance metrics calculation (Sharpe ratio, CARA utility) + +## Installation + +```bash +go get github.com/quick-trade/xoney +``` + +## Quick Start + +```go +package main + +import ( + "github.com/quick-trade/xoney/backtest" + "github.com/quick-trade/xoney/common" + "github.com/quick-trade/xoney/exchange" +) + +func main() { + // Create a portfolio with initial USD balance + currency := data.NewCurrency("USD", "BINANCE") + portfolio := common.NewPortfolio(currency) + portfolio.Set(currency, 10000) + + // Initialize exchange simulator with 0.1% commission + simulator := exchange.NewMarginSimulator(portfolio, 0.001) + + // Create backtester + tester := backtest.NewBacktester(&simulator) + + // Run your strategy + equity, err := tester.Backtest(charts, strategy) + if err != nil { + panic(err) + } +} +``` + +## Strategies + +### Bollinger Bands Strategy + +The Bollinger Bands strategy is a popular technical analysis tool that uses standard deviations to determine overbought or oversold conditions. + +```go +package main + +import ( + "github.com/quick-trade/xoney/strategy" + "github.com/quick-trade/xoney/common/data" +) + +func main() { + // Create BTC/USD instrument with 15-minute timeframe + btcUsd := data.NewSymbol("BTC", "USD", "BINANCE") + timeframe, _ := data.NewTimeFrame(time.Minute*15, "15m") + instrument := data.NewInstrument(*btcUsd, *timeframe) + + // Initialize Bollinger Bands strategy + // Parameters: period=30 days, deviation=2 + strategy := NewBBStrategy(60*24*30, 2, instrument) + + // Run backtest + equity, err := tester.Backtest(charts, &strategy) + if err != nil { + panic(err) + } +} +``` + +### Grid Trading Bot + +Grid trading is a strategy that places multiple orders at regular intervals above and below a set price, aiming to profit from market oscillations. + +```go +package main + +import ( + "github.com/quick-trade/xoney/toolkit" + "github.com/quick-trade/xoney/common/data" +) + +func main() { + // Create auto grid generator + // Parameters: lookback=100 candles, levels=10, deviation=1.5, total_amount=0.5 (in base currency) + generator := NewAutoGrid(100, 10, 1.5, 0.5) + + // Initialize grid bot + bot := toolkit.NewGridBot(generator, instrument) + + // Run backtest + equity, err := tester.Backtest(charts, bot) + if err != nil { + panic(err) + } +} +``` + +### Custom Strategy + +You can create your own strategy by implementing the `Tradable` interface: + +```go +type Tradable interface { + Start(charts data.ChartContainer) error + Next(candle data.InstrumentCandle) (events.Event, error) + MinDurations() Durations +} +``` + +Example of a simple moving average crossover strategy: + +```go +type MACrossStrategy struct { + instrument data.Instrument + shortPeriod int + longPeriod int + shortMA []float64 + longMA []float64 +} + +func (m *MACrossStrategy) Next(candle data.InstrumentCandle) (events.Event, error) { + // Strategy logic here + return event, nil +} +``` + +## Backtesting + +Xoney provides a powerful backtesting engine that supports: +- Market and limit orders +- Custom commission rates +- Portfolio tracking +- Performance metrics + +```go +func runBacktest() { + // Initialize simulator with 0.1% commission + simulator := exchange.NewMarginSimulator(portfolio, 0.001) + tester := backtest.NewBacktester(&simulator) + + // Run backtest + equity, err := tester.Backtest(charts, strategy) + if err != nil { + panic(err) + } + + // Access performance metrics + history := equity.Deposit() + balanceHistory := equity.PortfolioHistory() +} +``` + +## Portfolio Management + +Xoney includes tools for portfolio management and rebalancing. All weights and orders are specified in base currency: + +```go +// Create a rebalancing strategy with weights in base currency +weights := map[data.Currency]float64{ + btc: 0.4, // 0.4 BTC + eth: 0.3, // 0.3 ETH + usdt: 0.3, // 0.3 USDT +} + +rebalancer := toolkit.NewRebalancePortfolio(weights) +``` + +## Exchange Simulation + +Test your strategies with the built-in exchange simulator: + +```go +// Create simulator with 0.1% commission +simulator := exchange.NewMarginSimulator(portfolio, 0.001) + +// Place market order +order, _ := exchange.NewOrder( + symbol, + exchange.Market, + exchange.Buy, + price, + amount, +) +err := simulator.PlaceOrder(order) +``` + +The simulator supports: +- Market and limit orders +- Spot and margin trading +- Custom commission rates +- Portfolio tracking +- Price feeds + +For more examples and detailed documentation, visit our [documentation](https://github.com/quick-trade/xoney/docs). + +## Toolkit + +**Warning**: The toolkit package is currently in experimental stage and should be used with extreme caution. The functionality may be unstable and contain bugs. + +### Grid Trading Bot + +Grid trading is a strategy that places multiple orders at regular intervals above and below a set price, aiming to profit from market oscillations. + +```go +package main + +import ( + "github.com/quick-trade/xoney/toolkit" + "github.com/quick-trade/xoney/common/data" +) + +func main() { + // Create auto grid generator + // Parameters: lookback=100 candles, levels=10, deviation=1.5, total_amount=0.5 (in base currency) + generator := NewAutoGrid(100, 10, 1.5, 0.5) + + // Initialize grid bot + bot := toolkit.NewGridBot(generator, instrument) + + // Run backtest + equity, err := tester.Backtest(charts, bot) + if err != nil { + panic(err) + } +} +``` + +### Portfolio Management + +Xoney includes tools for portfolio management and rebalancing. All weights and orders are specified in base currency: + +```go +// Create a rebalancing strategy with weights in base currency +weights := map[data.Currency]float64{ + btc: 0.4, // 0.4 BTC + eth: 0.3, // 0.3 ETH + usdt: 0.3, // 0.3 USDT +} + +rebalancer := toolkit.NewRebalancePortfolio(weights) +``` + +### Custom Events + +You can create custom events by implementing the Event interface: + +```go +type CustomEvent struct { + timestamp time.Time + data interface{} +} + +func (e *CustomEvent) Occur(connector exchange.Connector) error { + // Implement your event logic here + return nil +} + +// Create sequential events (executed one after another) +sequential := events.NewSequential(event1, event2, event3) + +// Create parallel events (executed simultaneously) +parallel := events.NewParallel(event1, event2, event3) +``` + +Example of a custom order event: + +```go +type OrderEvent struct { + order exchange.Order +} + +func (e *OrderEvent) Occur(connector exchange.Connector) error { + return connector.PlaceOrder(e.order) +} + +// Create and use the event +order, _ := exchange.NewOrder( + symbol, + exchange.Market, + exchange.Buy, + price, // price in base currency + amount, // amount in base currency +) +event := &OrderEvent{order: order} +```