{"id":21661018,"url":"https://github.com/karanpratapsingh/hypertrade","last_synced_at":"2025-04-09T09:11:06.960Z","repository":{"id":40520823,"uuid":"447989812","full_name":"karanpratapsingh/HyperTrade","owner":"karanpratapsingh","description":"Ready to deploy, distributed cryptocurrency trading bot","archived":false,"fork":false,"pushed_at":"2022-05-04T04:33:43.000Z","size":12246,"stargazers_count":282,"open_issues_count":10,"forks_count":66,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-04-02T07:11:18.263Z","etag":null,"topics":["cryptocurrency","digitalocean","distributed-systems","docker","go","kubernetes","python","react","terraform","typescript"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/karanpratapsingh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-01-14T14:10:09.000Z","updated_at":"2025-03-18T15:11:26.000Z","dependencies_parsed_at":"2022-07-25T07:47:08.627Z","dependency_job_id":null,"html_url":"https://github.com/karanpratapsingh/HyperTrade","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/karanpratapsingh%2FHyperTrade","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/karanpratapsingh%2FHyperTrade/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/karanpratapsingh%2FHyperTrade/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/karanpratapsingh%2FHyperTrade/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/karanpratapsingh","download_url":"https://codeload.github.com/karanpratapsingh/HyperTrade/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248008630,"owners_count":21032556,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cryptocurrency","digitalocean","distributed-systems","docker","go","kubernetes","python","react","terraform","typescript"],"created_at":"2024-11-25T09:43:17.265Z","updated_at":"2025-04-09T09:11:06.942Z","avatar_url":"https://github.com/karanpratapsingh.png","language":"Go","funding_links":["https://www.buymeacoffee.com/karanps"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg width=\"100px\" src=\"./assets/logo.png\"\u003e\n  \u003ch1 align=\"center\"\u003eHyperTrade\u003c/h1\u003e\n  \u003cp align=\"center\"\u003eReady to deploy, distributed cryptocurrency trading bot.\u003c/p\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n\u003ca href=\"https://www.buymeacoffee.com/karanps\" target=\"_blank\"\u003e\u003cimg height=\"30px\" src=\"https://www.buymeacoffee.com/assets/img/guidelines/download-assets-sm-1.svg\" alt=\"Buy Me A Coffee\" \u003e\u003c/a\u003e\n\u003cimg src=\"https://img.shields.io/github/workflow/status/karanpratapsingh/HyperTrade/Build?style=for-the-badge\" /\u003e\n\u003cimg src=\"https://img.shields.io/badge/License-GPL-red.svg?style=for-the-badge\" /\u003e\n\u003cimg alt=\"Twitter: karan_6864\" src=\"https://img.shields.io/twitter/follow/karan_6864.svg?style=for-the-badge\u0026logo=TWITTER\u0026logoColor=FFFFFF\u0026labelColor=00aced\u0026logoWidth=20\u0026color=00aced\" target=\"_blank\" /\u003e\n\u003cimg height=\"29px\" src=\"https://web-platforms.sfo2.digitaloceanspaces.com/WWW/Badge%203.svg\" alt=\"DigitalOcean Referral Badge\" /\u003e\n\n\u003cbr /\u003e\n\n\u003cp align=\"center\"\u003e\n\u003cb\u003eUSE THIS SOFTWARE AT YOUR OWN RISK. THE AUTHOR ASSUMES NO LIABILITY FOR YOUR TRADING OUTCOMES.\u003c/b\u003e\n\n\u003cbr /\u003e\n\n\u003cimg width=\"49.5%\" src=\"./assets/screenshots/dashboard/charts.png\" alt=\"charts\" /\u003e \u003cimg width=\"49.5%\" src=\"./assets/screenshots/dashboard/dataframe.png\" alt=\"dataframe\" /\u003e\n\u003cimg width=\"49.5%\" src=\"./assets/screenshots/dashboard/portfolio.png\" alt=\"portfolio\" /\u003e \u003cimg width=\"49.5%\" src=\"./assets/screenshots/dashboard/config.png\" alt=\"config\" /\u003e\n\u003cimg width=\"34%\" src=\"./assets/screenshots/dashboard/config-strategy.png\" alt=\"config-strategy\" /\u003e \u003cimg width=\"34%\" src=\"./assets/screenshots/dashboard/charts-indicators.png\" alt=\"charts-indicators\" /\u003e \u003cimg width=\"30.6%\" src=\"./assets/screenshots/bot/telegram.png\" alt=\"telegram\" /\u003e\n\n## 📖 Contents\n\n- [Overview](#overview)\n- [Motivation](#motivation)\n- [Features](#features)\n- [Technologies](#technologies)\n- [Working](#working)\n- [Architecture](#architecture)\n- [Getting Started](#getting-started)\n- [Customization](#customization)\n- [Usage](#usage)\n  - [Telegram](#telegram)\n  - [Web](#web)\n- [Deployment](#deployment)\n- [Contribute](#contribute)\n- [License](#license)\n\n## 🔍 Overview \u003ca id=\"overview\" /\u003e\n\nHere's a short overview of the project.\n\n[![overview](https://user-images.githubusercontent.com/29705703/160863938-a8350ddd-5bf7-442e-beb9-fe590b28a725.png)](https://youtu.be/jHBlUlIY4AQ)\n\n## 💡 Motivation \u003ca id=\"motivation\" /\u003e\n\nA few months ago I got into the crypto market. It was all new and fascinating to me. The idea of this project originally came from a script I used to automate buying and selling of fiat assets.\n\nI was curious and wanted to scale it into a real system that can execute trades for me. I had a lot of fun building this. I got to play with lots of different technologies while growing my financial knowledge.\n\nFeel free to [reach out](https://karanpratapsingh.com?action=contact) to me if you have any additional questions. There are lots of fixes and features to be done!\n\n_It is important to note that this project is under active development and was developed as an experiment. Currently, only [Binance](https://binance.com/) is supported but contributions are welcome!_\n\n**Please leave a ⭐ as motivation or support by [donating](https://www.buymeacoffee.com/karanps) if you liked the idea 😄**\n\n## ✨ Features \u003ca id=\"features\" /\u003e\n\nThis system has lots of features such as:\n\n- **Web UI**: Real-time access to charts, technical indicators, and portfolio.\n\n- **Configurable**: Supports assets and strategies customization easily without touching any code!\n\n- **Portable**: Export your trades and real-time data frame to CSV.\n\n- **Multiple Assets**: Trade multiple crypto assets simultaneously!\n\n- **Telegram Support**: On the move? Use [Telegram](#telegram) bot to receive real-time notifications and much more.\n\n- **Ready to deploy**: Comes with [Infrastructure as Code](https://dev.to/karanpratapsingh/introduction-to-infrastructure-as-code-with-terraform-4f29) which is ready to deploy to [Digital Ocean](https://www.digitalocean.com/).\n\n- **Easy to upgrade**: Modify the system easily to your needs.\n\n## ⚡️ Technologies \u003ca id=\"technologies\" /\u003e\n\n\u003cimg width=\"98%\" src=\"./assets/diagrams/stack.png\" alt=\"stack\" /\u003e\n\n## ❓ Working \u003ca id=\"working\" /\u003e\n\nHere's a simple diagram illustrating how streams and events are published/subscribed in the system. We use NATS for messaging and streams, more about that in the [architecture](#architecture) section.\n\nBasically, The Exchange service publishes Kline/Candlestick data based on our configuration. Strategy service then subscribes to it and publishes a stream of dataframe which contains the indicators, buy/sell signals, and other metadata. The buy/sell signals are determined using the configuration as well, where we can customize our strategies given that they are supported.\n\nNow, The Exchange service subscribes to the dataframe stream and executes trades on the signal using the Binance API. Any event such as order, trade, error, etc is published and then the Notification service can send a message to the user using the Telegram API.\n\n*_Note: This only represents core events, there are more events for the Web and DB services._*\n\n\u003cimg src=\"./assets/diagrams/working.png\" alt=\"working\" /\u003e\n\n## 🏭 Architecture \u003ca id=\"architecture\" /\u003e\n\nIt's a microservices based architecture with event driven approach for decoupling. It uses distributed streams and messaging which keeps the system simple yet robust to make sure it can grow in the future.\n\n\u003cimg width=\"60%\" src=\"./assets/diagrams/architecture.png\" alt=\"architecture\" /\u003e \u003cimg width=\"37.45%\" src=\"./assets/diagrams/k8s.png\" alt=\"k8s\" /\u003e\n\n_Note: Kubernetes diagram was generated using [Lens - The Kubernetes IDE](https://github.com/nevalla/lens-resource-map-extension/)_\n\n**Why so many technologies?**\n\nThis started as an all Go project, but then I decided to add Python to the mix as it has a really good ecosystem for technical indicators and mathematical use cases.\n\nFor the web, I used React as it's easy and TypeScript provides some sanity to JavaScript projects!\n\nNginx and Postgres fit right in as the use case grew. As always, use what's right for the project!\n\n**Why event driven?**\n\nOriginally I made this using HTTP REST, but systems like this are event driven by nature. Plus this approach helps to decouple services even more.\n\n**How do services communicate?**\n\nAll the messaging infrastructure use cases are handled by [NATS](https://nats.io). Inter-service communications are mainly via publish-subscribe and request-reply patterns. Essentially, NATS acts as our service mesh!\n\nWe also use [JetStream](https://docs.nats.io/nats-concepts/jetstream) for real-time, persisted data streams.\n\n\u003cimg width=\"55%\" src=\"https://user-images.githubusercontent.com/29705703/156038663-61d9c242-de32-41da-9a59-a2452a0ead11.png\" alt=\"publish-subscribe\" /\u003e \u003cimg width=\"43.85%\" src=\"https://user-images.githubusercontent.com/29705703/156039685-bb32987e-a11f-4246-a6fa-1d74f6388119.png\" alt=\"request-reply\" /\u003e\n\n_Read more about [Distributed communication patterns with NATS](https://dev.to/karanpratapsingh/distributed-communication-patterns-with-nats-g17)_\n\n**Why Kubernetes? Isn't it overkill?**\n\nI agree! Kubernetes can be bit overkill, especially for this project. But my goal here was to keep it cloud agnostic, even though it was very tempting to just spin up AWS lambdas with event bridge.\n\n## 🍕 Getting Started \u003ca id=\"getting-started\" /\u003e\n\nHere we will setup our development environment. But first, we will need to install the following tools.\n\n**Tools**\n\n- [Minikube](https://minikube.sigs.k8s.io/docs/start/)\n- [Skaffold](https://skaffold.dev/docs/install/)\n- [Helm](https://helm.sh/docs/intro/install/)\n- [Go \u003e= 1.18](https://go.dev/doc/install)\n- [Node \u003e= 16.14](https://nodejs.org/en/download/)\n- [Python \u003e= 3.10](https://www.python.org/downloads/)\n- [yq](https://github.com/mikefarah/yq)\n- [volta](https://volta.sh/)\n- [doctl](https://github.com/digitalocean/doctl)\n\n**Steps**\n\n- Once all the tools are installed, execute `make prepare` to prepare the local environment.\n- Create a `infrastructure/k8s/env.yaml` to similar structure as `infrastructure/k8s/env.example.yaml` and [follow this guide](./docs/secrets-setup.md).\n- Review the configuration in `services/exchange/config.json`\n- Start development with `make dev` command.\n- Use `make stop` to stop the local minikube cluster.\n\n## 🛠 Customization \u003ca id=\"customization\" /\u003e\n\nWe can customize trading strategies either via web app or `services/exchange/config.json` directly.\n\nCurrently, only few trading strategies like RSI and MACD are supported and I plan to add more soon. \n\n\u003cimg width=\"60%\" src=\"./assets/screenshots/dashboard/config-strategy.png\" alt=\"config-strategy\" /\u003e\n\n## 📚 Usage \u003ca id=\"usage\" /\u003e\n\n### 💬 Telegram \u003ca id=\"telegram\" /\u003e\n\nTelegram bot helps us to interact with the system easily and receive real-time notifications.\n\n**Commands**\n\nThe telegram bot supports the following commands:\n\n\u003cimg src=\"./assets/screenshots/bot/telegram-commands.png\" alt=\"telegram-commands\" /\u003e\n\n- **`/configs`**: Get asset configurations.\n- **`/balance`**: Get current account balance.\n- **`/positions`**: Get actively held positions.\n- **`/stats`**: Get portfolio statistics.\n- **`/enable`**: Enable trading for a symbol.\n- **`/disable`**: Disable trading for a symbol.\n- **`/dump`**: Dump all the positions for a symbol.\n\n_Note: `enable`, `disable` and `dump` commands are symbol specific, and are executed as `/cmd symbol`. Example, `/enable ETHUSDT`_\n\n### 💻 Web \u003ca id=\"web\" /\u003e\n\nSince this application deals with sensitive financial data, it is **not recommended** to expose it via ingress unless we have proper RBAC authorization in place. Hence, it is recommended to connect to it via port-forwarding on your local machine.\n\n**Steps**\n\n- Connect to the application via port-forwarding using `make connect` command.\n\n_Note: Make sure `doctl` is authenticated, and we're using the correct k8s cluster name._\n\n- Open `localhost:8080` to see the web interface.\n\n- Once done, use the `make disconnect` command to remove the kubectl context from your machine.\n\n_Note: It is recommended to use the telegram bot over the user interface on non-secure systems._\n\n## 🚀 Deployment \u003ca id=\"deployment\" /\u003e\n\nDeployments can be done via `deploy.yml` Github actions to our [Digital Ocean](https://www.digitalocean.com/) Kubernetes cluster. But first, we will need to provision our infrastructure.\n\n_Important: Infrastructure we're about to provision has its own cost!_\n\n**Tools**\n\n- [Terraform](https://learn.hashicorp.com/tutorials/terraform/install-cli)\n\n**Steps**\n\n- Create and export a [GITHUB_TOKEN](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry#authenticating-to-the-container-registry) to access our Github container registry.\n\n```\n$ export TF_VAR_GHCR_TOKEN=value-of-your-token\n```\n\n- Get an API token from DigitalOcean [dashboard](https://cloud.digitalocean.com/account/api/tokens) and export it temporarily for terraform.\n\n```\n$ export DIGITALOCEAN_TOKEN=value-of-your-token\n```\n\n- Apply the Terraform configuration.\n\n```\n$ cd infrastructure\n$ terraform init\n$ terraform apply\n```\n\n- Go to Github and add `GHCR_TOKEN` and `DIGITALOCEAN_TOKEN` to your repository secrets for Github actions.\n- Generate `base64` string of your secrets, and add it as `APP_SECRETS` to your repository secrets for Github actions.\n\n```\n$ cat infrastructure/k8s/env.yaml | base64\n```\n\n- Go to the actions tab and run the `Build and Deploy` action.\n\n- Once the deploy is complete, our application will be deployed in the `hypertrade` namespace on Kubernetes.\n\n_Note: If you want to change the name of the project, make sure to update all the associated Kubernetes manifest files, skaffold config, nginx config etc._\n\n## 👏 Contribute \u003ca id=\"contribute\" /\u003e\n\nContributions are welcome as always, before submitting a new PR please make sure to open a new issue so community members can discuss it.\n\nAdditionally, you might find existing open issues which can help with improvements.\n\nThis project follows a standard [code of conduct](./CODE_OF_CONDUCT.md) so that you can understand what actions will and will not be tolerated.\n\n## 📄 License \u003ca id=\"license\" /\u003e\n\nThis project is GPL-3.0 licensed, as found in the [LICENSE](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkaranpratapsingh%2Fhypertrade","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkaranpratapsingh%2Fhypertrade","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkaranpratapsingh%2Fhypertrade/lists"}