{"id":19208708,"url":"https://github.com/ozgen/binance-telegram-bot","last_synced_at":"2026-01-24T16:35:18.921Z","repository":{"id":212168220,"uuid":"730861852","full_name":"ozgen/binance-telegram-bot","owner":"ozgen","description":"Binance Telegram Bot is an automated trading bot that integrates Binance's trading capabilities with signals received from Telegram channels. ","archived":false,"fork":false,"pushed_at":"2025-05-09T06:06:45.000Z","size":313,"stargazers_count":9,"open_issues_count":1,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-09T07:21:45.468Z","etag":null,"topics":["binance","binance-api","binance-trading-bot","btc","java","telegram-bot","trade-bot"],"latest_commit_sha":null,"homepage":"","language":"Java","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/ozgen.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-12-12T20:49:06.000Z","updated_at":"2025-05-09T06:06:49.000Z","dependencies_parsed_at":"2023-12-12T22:22:09.959Z","dependency_job_id":"b1babdb2-509e-4184-b70f-ed8e3935d0de","html_url":"https://github.com/ozgen/binance-telegram-bot","commit_stats":null,"previous_names":["ozgen/binance-telegram-bot"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ozgen%2Fbinance-telegram-bot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ozgen%2Fbinance-telegram-bot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ozgen%2Fbinance-telegram-bot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ozgen%2Fbinance-telegram-bot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ozgen","download_url":"https://codeload.github.com/ozgen/binance-telegram-bot/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253804372,"owners_count":21967046,"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":["binance","binance-api","binance-trading-bot","btc","java","telegram-bot","trade-bot"],"created_at":"2024-11-09T13:27:31.362Z","updated_at":"2026-01-24T16:35:18.916Z","avatar_url":"https://github.com/ozgen.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"![CI](https://github.com/ozgen/binance-telegram-bot/actions/workflows/ci.yml/badge.svg)\n![Coverage](https://codecov.io/gh/ozgen/binance-telegram-bot/branch/main/graph/badge.svg)\n\n# Binance Telegram Bot\n\n## Introduction\nBinance Telegram Bot is an automated trading bot that integrates Binance's trading capabilities with signals received from Telegram channels.\nIt executes trades on Binance based on signals from Telegram, ensuring automated and timely responses to market changes.\n\n## Features\n- Signal Processing\n- Trade Execution\n- Configurable Settings\n- Detailed Logging and Monitoring\n- Robust Error Handling\n\n## Getting Started\n\n### Prerequisites\n- Java 21\n- Maven\n- Binance account\n- Telegram account\n\n### Installation\n1. Clone the repo: `git clone https://github.com/ozgen/binance-telegram-bot.git`\n2. Navigate to the directory: `cd binance-telegram-bot`\n3. Build with Maven: `mvn clean install`\n\n### Configuration\nConfigure the application using environment variables or a `.env` file. Here are the key variables you need to set:\n\n#### Database Configuration\n- `spring.datasource.url`: URL to the Azure database\n- `spring.datasource.username`: Azure database username\n- `spring.datasource.password`: Azure database password\n\n#### Azure Keyvault Configuration\n- `azure.keyvault.uri`: Azure keyvault URI\n- `azure.keyvault.client-id`: Azure keyvault client ID\n- `azure.keyvault.client-key`: Azure keyvault client key\n- `azure.keyvault.tenant-id`: Azure keyvault tenant ID\n\n#### Telegram Bot Configuration\n- `bot.telegram.token`: Telegram bot token\n- `bot.telegram.enabled`: Enable Telegram bot (`true` or `false`)\n\n#### JPA and Hibernate Configuration\n- `spring.jpa.properties.hibernate.jdbc.lob.non_contextual_creation`: Hibernate setting for LOB creation\n- `spring.jpa.hibernate.ddl-auto`: Hibernate DDL auto strategy (`create`, `create-drop`, `validate`, `update`)\n\n#### Bot Investment Configuration\n- `app.bot.investment.currency`: Investment currency (e.g., `BTC`)\n- `app.bot.investment.amount`: Total investment amount\n- `app.bot.investment.perAmount`: Amount per trade\n- `app.bot.investment.currencyRate`: Currency rate for conversion (e.g., `BTCUSD`)\n- `app.bot.investment.percentageInc`: Percentage increase for buying\n- `app.bot.investment.profitPercentage`: Profit percentage target\n\n#### Bot Schedule Configuration\n- `app.bot.schedule.buyError`: Schedule interval for buy error in ms\n- `app.bot.schedule.sellError`: Schedule interval for sell error in ms\n- `app.bot.schedule.insufficient`: Schedule interval for insufficient balance in ms\n- `app.bot.schedule.notInRange`: Schedule interval for not in range status in ms\n- `app.bot.schedule.tradingSignal`: Schedule interval for trading signals in ms\n- `app.bot.schedule.openSellOrder`: Schedule interval for open sell orders in ms\n- `app.bot.schedule.openBuyOrder`: Schedule interval for open buy orders in ms\n- `app.bot.schedule.sellLater`: Schedule interval for sell later orders in ms\n- `app.bot.schedule.monthBefore`: Number of months before for date calculations\n\n#### New Configuration for Telegram Error Reporting\n- `bot.telegram.error.enabled`: Set to `true` to enable error reporting on Telegram.\n\n### Running the Bot\nStart the bot with:\n```bash\njava -jar target/binance-telegram-bot-0.0.1-SNAPSHOT.jar\n```\n## Setup Instructions\n\nTo ensure the system functions correctly, follow these setup requirements:\n\n### Telegram Bot Setup\n1. **Create a Telegram Bot**: Follow the instructions on [Telegram's official documentation](https://core.telegram.org/bots#creating-a-new-bot) to create a new bot.\n2. **Generate a Bot Token**: Use this [guide](https://medium.com/geekculture/generate-telegram-token-for-bot-api-d26faf9bf064) to generate a token for your Telegram bot.\n\n### Error Reporting with Telegram\n- Create a new bot for error reporting following the steps above.\n- Create a troubleshooting channel on Telegram and add the error bot as an admin.\n- Start the system, then send a message to the troubleshooting channel to initialize the error bot correctly.\n\n### Telegram Channel Listener\n- Make sure the bot is an admin of the Telegram channel you want to monitor.\n\n### Database Configuration\n- This setup uses Azure Key Vault and Azure SQL Database. For local or alternative databases, update the `application.properties` file accordingly.\n\n### Azure Key Vault\n1. **Create an Azure Key Vault**: Follow the steps outlined [here](https://azure.github.io/cloud-scale-data-for-devs-guide/get-started-with-java-and-key-vault.html).\n2. **Connect to Azure Key Vault**: Use the instructions provided [here](https://learn.microsoft.com/en-us/azure/azure-app-configuration/use-key-vault-references-spring-boot?tabs=yaml) to connect.\n\n### Azure SQL Database\n1. **Create an Azure SQL Database**: Detailed instructions can be found [here](https://learn.microsoft.com/en-us/azure/azure-sql/database/single-database-create-quickstart?tabs=azure-portal). Opting for a serverless configuration is cost-effective.\n2. **Connect to Azure SQL Database**: Follow these [steps](https://learn.microsoft.com/en-us/azure/developer/java/spring-framework/configure-spring-data-jdbc-with-azure-sql-server?tabs=passwordless) to connect.\n\n### Environment Variables\nSet up the following environment variables for your application:\n```\nAZURE_DB_PASSWORD=\u003cdb-password\u003e\nAZURE_DB_URL=\u003cazure-db-url\u003e\nAZURE_DB_USERNAME=\u003cdb-user-name\u003e\nAZURE_KEYVAULT_CLIENT_ID=\u003cazure-keyvault-client-id\u003e\nAZURE_KEYVAULT_CLIENT_KEY=\u003cazure-keyvault-client-key\u003e\nAZURE_KEYVAULT_TENANT_ID=\u003cazure-keyvault-tenant-id\u003e\nAZURE_KEYVAULT_URL=\u003ckeyvault-url\u003e\nTELEGRAM_ERROR_TOKEN=\u003ctelegram-error-token\u003e\nTELEGRAM_TOKEN=\u003ctelegram-channel-token\u003e\nTELEGRAM_USERNAME=\u003ctelegram-bot-username\u003e\nTELEGRAM_ERROR_USERNAME=\u003ctelegram-error-bot-username\u003e\n```\nReplace the placeholder values with your actual configuration details.\n\nEnsure all prerequisites are met for the system to run smoothly.\n\n### Running the Bot (Local Profile with Dockerized PostgreSQL)\n\nFor local development, you can run the **PostgreSQL database via Docker** and run the **Spring Boot application** locally with the `local` profile.\n\n#### Step 1: Start PostgreSQL via Docker Compose\n\nFrom the project root, run:\n\n```bash\ndocker-compose -f docker/docker-compose.yml up -d\n```\n\nMake sure your `docker-compose.yml` exposes the correct PostgreSQL port (`5432`) and includes environment variables like:\n\n```yaml\nenvironment:\n  POSTGRES_DB: binancebot\n  POSTGRES_USER: myuser\n  POSTGRES_PASSWORD: mypass\n```\n\n#### Step 2: Set Local Environment Variables\n\nExport these variables in your terminal session (or place them in a `.env` file if your tooling supports it):\n\n```env\n# Database\nSPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/binancebot\nSPRING_DATASOURCE_USERNAME=myuser\nSPRING_DATASOURCE_PASSWORD=mypass\n\n# Telegram Bot\nBOT_TELEGRAM_TOKEN=\u003cyour-telegram-token\u003e\nBOT_TELEGRAM_ENABLED=true\n\n# Binance API\nBINANCE_API_KEY=\u003cyour-binance-api-key\u003e\nBINANCE_API_SECRET=\u003cyour-binance-api-secret\u003e\n```\nExample env file can be found in [here](/sample-local.env) \n\n#### Step 3: Run the Spring Boot App with `local` Profile\n\nBuild and run the app:\n\n```bash\nmvn clean install\njava -Dspring.profiles.active=local -jar target/binance-telegram-bot-0.0.1-SNAPSHOT.jar\n```\n\nThis setup:\n- Connects to the PostgreSQL instance running in Docker\n- Loads credentials from local environment variables\n- Avoids any cloud integrations not enabled in the `local` profile\n\n---\n\n## Usage\nThe bot monitors specified Telegram channels for trading signals and executes corresponding trades on Binance. Here's an example of a trading signal the bot can process:\n\n```\nTrading Signal Example:\nNKNBTC\n\nENTRY: 0.00000260 - 0.00000290\n\nTP1: 0.00000315\nTP2: 0.00000360\nTP3: 0.00000432\nTP4: 0.00000486\nTP5: 0.00000550\nTP6: 0.00000666\nTP7: 0.00000741\n\nSTOP: Close weekly below 0.00000240\n```\n\n\n## **Optional Parameters: Invest Amount \u0026 Sell Later Strategy**\nThe bot allows **two optional parameters** in trading signals:\n- **INVEST** → Specifies how much to invest in the trade.\n- **STRATEGY: SELL_LATER** → Delays selling until a future condition is met.\n\n###  How It Works\n| Parameter  | Description                                                                                                                                       |\n|------------|---------------------------------------------------------------------------------------------------------------------------------------------------|\n| `INVEST`   | Defines the amount allocated for the trade (e.g., `\"0.0001 BTC\"`). If omitted, the bot will use the default investment settings.                  |\n| `STRATEGY` | If set to `SELL_LATER`, the bot will **not** immediately create sell order. Instead, It creates sell order when profit targets (TPs) are reached. |\n\n### **Example Signal with Optional Parameters**\n```\nTrading Signal Example:\nNKNBTC\n\nENTRY: 0.00000260 - 0.00000290\n\nTP1: 0.00000315\nTP2: 0.00000360\nTP3: 0.00000432\nTP4: 0.00000486\nTP5: 0.00000550\nTP6: 0.00000666\nTP7: 0.00000741\n\nSTOP: Close weekly below 0.00000240\n\n# Optional Parameters\nINVEST: 0.001  \nSTRATEGY: SELL_LATER\n```\n\n### **Behavior of `SELL_LATER` Strategy**\n- Normally, the bot **automatically sells** when a TP level is reached.\n- If `SELL_LATER` is set:\n    1. The bot **holds the asset** instead of selling at TP levels.\n    2. The sell order will be **triggered later** based on other conditions (e.g., price spikes, custom alerts).\n\n### How to Use These Parameters\n| Scenario | Expected Bot Behavior                           |\n|------------|-------------------------------------------------|\n| **No `INVEST` value** | Uses the default investment configuration.      |\n| **INVEST set** | Overrides the default investment amount.        |\n| **No `SELL_LATER`** | The bot sells at the defined profit percentage. |\n| **`SELL_LATER` enabled** | The bot holds the asset and delays selling.     |\n\n---\n\n### **Why Use These Options?**\n- **INVEST** → Gives you flexibility to **change investment size per trade**.\n- **SELL_LATER** → Useful for **longer-term holds** instead of auto-selling.\n---\n\n## Chunked Buy and Sell Orders\n\nThe bot now supports placing buy and sell orders in smaller parts (called \"chunks\"). This helps avoid problems like sudden price changes when trading large amounts.\n\n### How to Enable\n\nTo turn on chunked order execution, add the following to your `application.properties` or environment variables:\n\n```properties\n# app execution strategy: CHUNKED or DEFAULT\napp.bot.execution.strategy=CHUNKED\n```\n\n### How It Works\n\nWhen you use the `CHUNKED` setting:\n\n* The bot checks the average trading volume for the coin.\n* Based on the volume, it decides how many small orders (chunks) to place.\n* Your total investment is divided across these small buy orders.\n* Each buy order is tracked separately.\n* When the price target is reached, the bot creates separate sell orders for each chunk.\n\n### Advantages\n\n* Helps avoid moving the market price by placing smaller orders.\n* Adapts to how actively a coin is being traded.\n* Makes it easier to manage and track each trade.\n\n---\n\n### CHUNKED_PROGRESSIVE Strategy\n\nThis advanced execution strategy builds upon `CHUNKED` by reacting dynamically to real-time market conditions. It also supports multiple entries, margin-split investments, calculated leverage, and multiple take-profit levels.\n\nTo enable:\n\n```properties\napp.bot.execution.strategy=CHUNKED_PROGRESSIVE\n```\n\n#### How It Works\n\n* The bot calculates **average quote volume** using recent 5-minute candlesticks.\n* Based on this liquidity, it dynamically sets the **number of chunks**:\n\n  * Higher liquidity → more chunks.\n  * Lower liquidity → fewer chunks.\n* Before placing each chunk, the bot ensures:\n\n  * The **price is within the signal's entry range**.\n  * The market shows a **short-term bullish trend** (based on recent price movements).\n* For each chunk:\n\n  * It uses a **fixed portion of the total margin** (e.g., 5% of portfolio split evenly).\n\n  * It calculates **leverage** using the formula:\n\n    ```\n    leverage = entryPrice / (entryPrice - stopLoss)\n    ```\n\n  * It assigns a specific **take-profit level** based on chunk index.\n* Each chunk is sold **independently** once its target profit price is reached.\n\n#### Signal Example\n\n```\nNKNBTC\nENTRY: 0.00000260 - 0.00000290\nTP1: 0.00000315\nTP2: 0.00000360\nTP3: 0.00000432\nTP4: 0.00000486\nTP5: 0.00000550\nTP6: 0.00000666\nTP7: 0.00000741\nSTOP: Close weekly below 0.00000240\n```\n\nIn this case:\n\n* The bot averages the entry range (e.g., midpoint of 0.00000260 and 0.00000290).\n* Calculates leverage using that midpoint and the stop price (e.g., 0.00000275 / (0.00000275 - 0.00000240)).\n* Distributes investment and assigns a corresponding take-profit (TP1–TP7) per chunk.\n\n#### Advantages\n\n* Reacts to live market signals for smarter trade timing.\n* Dynamically adjusts chunking based on market liquidity.\n* Calculates leverage based on real risk (entry vs. stop).\n* Supports multiple TP levels for staggered profit-taking.\n\n---\n\n### Switch Back to Default\n\nIf you want the bot to place just one buy and one sell order per signal, change the setting back to:\n\n```properties\napp.bot.execution.strategy=DEFAULT\n```\n\n---\n\n## Test Coverage\n\n### Running Tests\nExecute the test suite using Maven:\n```bash\nmvn test\n```\n\n### Coverage Reporting\nAfter running the tests, generate a coverage report using JaCoCo (Java Code Coverage Library):\n```bash\nmvn jacoco:report\n```\nThe coverage report can be found in `target/site/jacoco/index.html`. Open it in a web browser to view detailed coverage statistics.\n\n## License\nThis project is licensed under the MIT License\n\n## Acknowledgments\n- Binance API\n- Telegram API\n\n---\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fozgen%2Fbinance-telegram-bot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fozgen%2Fbinance-telegram-bot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fozgen%2Fbinance-telegram-bot/lists"}