{"id":13538927,"url":"https://github.com/jkbrzt/cointrol","last_synced_at":"2025-04-08T11:08:41.200Z","repository":{"id":49704701,"uuid":"32533684","full_name":"jkbrzt/cointrol","owner":"jkbrzt","description":"฿ Bitcoin trading bot with a real-time dashboard for Bitstamp.","archived":false,"fork":false,"pushed_at":"2023-08-26T13:18:05.000Z","size":658,"stargazers_count":1455,"open_issues_count":20,"forks_count":291,"subscribers_count":116,"default_branch":"master","last_synced_at":"2024-11-08T07:03:30.501Z","etag":null,"topics":["automation","bitcoin","bitstamp","bot","cryptocurrencies","jakubroztocil","python","speculation","trade","trading","trading-bot","transaction"],"latest_commit_sha":null,"homepage":"https://twitter.com/jakubroztocil","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jkbrzt.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null},"funding":{"github":"jakubroztocil"}},"created_at":"2015-03-19T16:36:47.000Z","updated_at":"2024-10-31T09:34:30.000Z","dependencies_parsed_at":"2024-01-18T04:51:40.809Z","dependency_job_id":"44e27d2b-43d9-4fd9-bc09-0af8168c059c","html_url":"https://github.com/jkbrzt/cointrol","commit_stats":null,"previous_names":["jkbrzt/cointrol","jakubroztocil/cointrol"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jkbrzt%2Fcointrol","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jkbrzt%2Fcointrol/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jkbrzt%2Fcointrol/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jkbrzt%2Fcointrol/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jkbrzt","download_url":"https://codeload.github.com/jkbrzt/cointrol/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247829491,"owners_count":21002995,"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":["automation","bitcoin","bitstamp","bot","cryptocurrencies","jakubroztocil","python","speculation","trade","trading","trading-bot","transaction"],"created_at":"2024-08-01T09:01:17.789Z","updated_at":"2025-04-08T11:08:41.182Z","avatar_url":"https://github.com/jkbrzt.png","language":"Python","funding_links":["https://github.com/sponsors/jakubroztocil"],"categories":["Python","📦 Legacy \u0026 Inactive Projects"],"sub_categories":[],"readme":"# Cointrol\n\nCointrol is a Bitcoin trading bot and real-time dashboard for [Bitstamp](https://bitstamp.net) created by [@jkbrzt](https://twitter.com/jkbrzt).\n\n![Dashboard in the browser](_/browser.png \"Dashboard in the browser\")\n\n\n![cointrol-server and cointrol-trader running in the terminal](_/running-server-and-trader.png \"cointrol-server and cointrol-trader running in the terminal\")\n\n**Cointrol was created to automate Bitcoin speculation.** Besides automated trading based on price change triggers and various trading strategies, it also provides a **real-time updated dashboard for your Bitstamp account** where you can see all your orders and transactions real-time updated (something Bitstamp lacks). The dashboard  for a real-time updated overview can also be used standalone without letting Cointrol make any transactions.\n\nEven though the original idea was to perhaps provide a fully-fledged hosted service, the system remained quite basic as it has only been used by its creator for a period of time in the winter of '13/'14 (when BTC price fluctuations were pretty insane). Some of the obvious limitations—all of which could easily be addressed—are:\n\n* Only basic trading strategies are implemented\n* Single user/Bitstamp account is supported\n* Only one active trading session at a time\n* The **whole account value is used** when trading\n* Django admin is used for auth and trading strategy/session manipulations\n\nEven though Cointrol has been used for real transactions, no guarantees are provided in terms of security, correctness, etc. (see `LICENCE`).\n\n\n## Architecture\n\nThe system consists of the following components:\n\n![](_/architecture.png)\n\n\n### `cointrol-trader`\n\n* Polls various Bitstamp API endpoints\n* Writes changes to DB\n* Publishes changes to Redis pub/sub\n* Opens orders, when suitable\n\n\n### `cointrol-server`\n\n* Serves Webapp static files\n* Exposes DB for Webapp via a REST API\n* Forwards Redis pub/sub messages from Trader to Webapp via WebSocket\n* Exposes Django administration that is currently used for managing trading sessions\n\n\n### `webapp`\n\n* REST/WebSocket API-powered Single Page App\n* Real-time updated overview on orders, transactions, and trading sessions\n\n\n## Technology\n\n**The server-side parts** (`cointrol-server` + `cointrol-trader`) are written in **Python 3** (3.3+ is required) and use a mixture of **Django** (models, admin) and **Tornado** (WebSockets, async IO). Other libraries that are used include sockjs-tornado, Django REST framework.\n\n**The single-page webapp** is written in CoffeeScript, Sass, Handlebars and uses Backbone.js, Brunch, socksjs-client, Bootstrap.\n\n\n\n## Installation\n\n\n### 0. Prerequisites\n\nMake sure you have the following software installed on your system:\n\n* Python 3.3+\n* Redis\n* npm\n\n\n### 1. Install Cointrol\n\n#### 1.1 Install `cointrol-server` \u0026 `cointrol-trader`\n```bash\nmkdir Cointrol \u0026\u0026 cd Cointrol\n\n# Create an isolated Python virtual environment\npip install virtualenv\nvirtualenv ./virtualenv --python=$(which python3)\n\n# Activate the virtualenv\n# IMPORTANT: it needs to be activated every time before you run\n#            a manage.py or cointrol-* command.\n. virtualenv/bin/activate\n\n# Get the code\ngit clone https://github.com/jkbrzt/cointrol\n\n# Create a local settings file\necho 'from .settings_dev import *' \u003e cointrol/cointrol/conf/settings_local.py\n\n# Install Python requirements\npip install -r cointrol/cointrol/conf/requirements.txt\n\n# Initialize the database\ncointrol/manage.py migrate\n\n# Install cointrol-*\npip install -e ./cointrol\n\n```\n\n#### 1.2 Build the single-page app web client and install its dependencies\n\n\n```bash\n# Install dependencies\nsudo npm -g install bower\ncd cointrol/webapp\nnpm install\nbower install\n\n# Build the app\nbrunch build\n\n# Use `brunch watch` during development\n```\n\n### 2. Create a Django user\n\n```bash\n. virtualenv/bin/activate\ncointrol/manage.py createsuperuser\n```\n\n\n### 3. Configure Bitstamp API access\n\n#### 3.1 Get API key and secret\n\nGo to [https://www.bitstamp.net/account/security/api](https://www.bitstamp.net/account/security/api). Create a new key and configure permissions for it. Cointrol needs at least the following permissions:\n\n * `Account balance`\n * `User transactions`\n * `Open orders`\n \nIf you want Cointrol make transactions for you, select two following permissions as well:\n\n  * `Buy limit order`\n  * `Sell limit order`\n\nDon't forget to activate the key by clicking \"Activate\" and confirming the email you receive from Bitstamp. \n\n\n#### 3.2 Configure Cointrol with the API credentials\n1. Activate the virtualenv and run `cointrol-server`\n2. Go to [http://localhost:8000/admin/core/account/1/](http://localhost:8000/admin/core/account/1/) and enter your Bitstamp username as well as the API key and secret to the form there.\n\n## Usage\n\n\n### Start `cointrol-server`\n\n\n```bash\n. virtualenv/bin/activate\ncointrol-server\n```\n\n\nBy default, it will run on [http://localhost:8000](http://localhost:8000). You can change the port with `--port=\u003cport\u003e`. \n\nUse this convenient link to log in: [http://localhost:8000/admin/login/?next=/](http://localhost:8000/admin/login/?next=/) — the Django admin interface is used for authentication, and this link ensures redirection back to the app after signing you in.\n\n**Connection indicator colors explained:**\n\n![green](_/connection-green.png)\n\nGreen: The web app has a WebSocket connection to `cointrol-server`, and *have* recently heard from `cointrol-trader`. \n\n![amber](_/connection-amber.png)\n\n\nAmber: The web app has a WeSocket connection to `cointrol-server`, but \n*have not* heard from `cointrol-trader` in a while.\n\n![red](_/connection-red.png)\n\nRed: The web app couldn't establish WebSocket connection to `cointrol-server`.\n\n\n\n\n### Start `cointrol-trader`\n\n```bash\n. virtualenv/bin/activate\ncointrol-trader\n```\n\nNote, until trading is configured  and the `COINTROL_DO_TRADE` settings set to `True` (covered in a later step), the trader won't make any transactions. It only pulls your data from Bitstamp to populate the dashboard view.\n\n### Trading\n\nUntil the following steps are completed and trading is explicitly enabled, Cointrol doesn't attempt to make any transaction on your behalf:\n\n1. Through the admin ([http://localhost:8000/admin/](http://localhost:8000/admin/)) you can create a trading strategy profile. It can be for the *fixed* (fixed price points in USD are used as buy/sell triggers) or the *relative* (percentage of the initial BTC price are used) strategy.\n2. Create a trading session (also in the admin interface).\n3. To perform actual transactions, you'll have to enable them in the settings (we used the `settings_dev` module which disables them). Add `COINTROL_DO_TRADE = True` to your `cointrol/cointrol/conf/settings_local.py`.\n\n\n## Settings\n\nThe settings is resolved in this order: \n\n1. `settings_local.py`\n2. `settings_(prod|dev).py` \n3. `settings_defaults.py`\n4.  Django defaults\n\nDuring the installation process, you've created `cointrol/cointrol/conf/settings_local.py` which imports settings from the `settings_dev.py` file. All the settings are [Django settings](https://docs.djangoproject.com/en/1.7/ref/settings/). The only non-Django settings is `COINTROL_DO_TRADE` (`False` in `dev`, `True` in `prod`). You can override any of the default settings in the `settings_local.py` file.\n\nBesides `settings_dev.py`, the `conf` directory also has `settings_prod.py`, which is more suitable for production use. It defines logging configuration which makes messages of a level `\u003e=` `WARNING` logged by the trader to be sent to you via email (e.g. when the trader places an order or there is an error). If you decide to use this settings file (by changing the import in `settings_local.py` to `from .settings_prod import *`, you'll have to configure at least [`DATABASES`](https://docs.djangoproject.com/en/1.7/ref/settings/#databases), [`ADMINS`](https://docs.djangoproject.com/en/1.7/ref/settings/#admins) and [`SECRET_KEY`](https://docs.djangoproject.com/en/1.7/ref/settings/#secret-key) as well in your in `settings_local.py`.\n\n\n## Contact\n\nJakub Roztocil\n\n* [https://github.com/jkbrzt](https://github.com/jkbrzt)\n* [https://twitter.com/jkbrzt](https://twitter.com/jkbrzt)\n* [http://roztocil.co](http://roztocil.co)\n* `3NVcdcoXrBV7jKv7T3st6kQz7XdsPNUn34`\n\n## Licence\n\nMIT. See [LICENCE](./LICENCE).\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjkbrzt%2Fcointrol","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjkbrzt%2Fcointrol","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjkbrzt%2Fcointrol/lists"}