> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lfg.rich/llms.txt
> Use this file to discover all available pages before exploring further.

# Trading Bot

> Use the LFG.RICH community trading bot to automate buy and sell strategies for LFG.RICH tokens.

The LFG.RICH Community Trading Bot is a Python trading bot example for BNB Smart Chain that trades **official LFG.RICH launchpad tokens** through the official LFG.RICH protocol contracts.

<CardGroup cols={2}>
  <Card title="Self-hosted" icon="server">
    Run the bot on your own machine or VPS with your own wallet and configuration.
  </Card>

  <Card title="V5-aware" icon="route">
    The bot resolves Hook/Router context and uses the official V5 interaction flow.
  </Card>

  <Card title="Dashboard" icon="chart-pie">
    Review positions, lots, trades, realized/unrealized PnL, and strategy state locally.
  </Card>

  <Card title="Dry run first" icon="shield-halved">
    Start in `dry_run` and use smoke tests before allowing live transactions.
  </Card>
</CardGroup>

This version is compatible with **LFG.RICH only**:

* buys through the LFG.RICH **Swap Router**;
* sells through the LFG.RICH **Swap Router**;
* builds candles from LFG.RICH Uniswap V4 Hook `Buy` and `Sell` events;
* uses the LFG.RICH **Uniswap V4 Hook** for price and quote estimates;
* does **not** use PancakeSwap V2;
* does **not** use PancakeSwap V3;
* does **not** borrow, borrow more, or repay.

<Warning>
  This is community trading software. Use a dedicated wallet, start with small amounts, and test everything before running with real funds.
</Warning>

## How the bot works

The bot monitors one or more LFG.RICH tokens from `config.yaml`.

For each configured token, it:

<Steps>
  <Step title="Resolve the token pool through the Hook">
    The bot uses V5 pool context instead of guessing an old pair or pool.
  </Step>

  <Step title="Scan Hook Buy and Sell events">
    Event data is used to build local market history.
  </Step>

  <Step title="Build internal price candles">
    Candles power the strategy indicators and dashboard.
  </Step>

  <Step title="Calculate strategy indicators">
    EMA, RSI, trend, pump, dump, and bleed conditions are evaluated locally.
  </Step>

  <Step title="Decide BUY, SELL, or HOLD">
    The strategy makes a decision from configured rules and current state.
  </Step>

  <Step title="Execute through the Swap Router unless dry_run is enabled">
    Live trades use the official LFG.RICH Swap Router.
  </Step>

  <Step title="Record trades and lots in SQLite">
    Confirmed fills are persisted for accounting, dashboard, and later sells.
  </Step>
</Steps>

The bot must resolve and use the token's LFG.RICH pool data. It should not assume a legacy pair address or a PancakeSwap-style pool.

## Requirements

### Tested environment

The bot has been tested with:

```text theme={null}
Ubuntu 20.04 / Debian-style server
Python 3.8
SQLite state database
BNB Smart Chain RPC with eth_getLogs support
```

Recommended Python versions for new users:

```text theme={null}
Python 3.10 or Python 3.11
```

Python 3.8 is still supported by the pinned dependency versions included in the bot package.

Do **not** run the bot with Python 2. If you see an error path like this:

```text theme={null}
/usr/lib/python2.7/...
```

you are using the wrong Python version.

### Required system components

The bot needs:

* Python 3;
* Python virtual environment support;
* `pip`;
* SQLite;
* a BNB Smart Chain RPC endpoint with `eth_getLogs` support;
* a wallet private key for live trading.

### Python dependencies

Runtime dependencies are pinned in:

```text theme={null}
requirements.txt
```

Dashboard dependencies are pinned separately in:

```text theme={null}
requirements-dashboard.txt
```

Important compatibility notes:

* `aiohappyeyeballs==2.6.1` is intentionally **not** used because it does not work with Python 3.8.
* `streamlit==1.40.1` is used because `1.40.2` was not installable in the tested Python 3.8 environment.
* The dashboard uses `use_container_width=True`, not newer Streamlit `width="stretch"` syntax.
* The code includes Python 3.8 compatibility fixes where needed.

## Installation on Linux / VPS

Use these steps on Ubuntu/Debian-style servers.

### 1. Install system packages

For Python 3.8:

```bash theme={null}
apt update
apt install -y python3.8-venv python3-pip python3-dev build-essential sqlite3
```

If your server uses another Python 3 version, install the generic venv package instead:

```bash theme={null}
apt update
apt install -y python3-venv python3-pip python3-dev build-essential sqlite3
```

### 2. Download or clone the project

Example:

```bash theme={null}
cd /var/www
git clone https://github.com/lfgdotrich/LFG.RICH-Trading-Bot.git
cd LFG.RICH-Trading-Bot
```

If you are using a ZIP instead, upload/unzip it and then enter the project directory.

### 3. Create a clean virtual environment

```bash theme={null}
rm -rf .venv
python3 -m venv .venv
source .venv/bin/activate
```

Your terminal should now show `(.venv)`.

### 4. Upgrade packaging tools

```bash theme={null}
python -m pip install --upgrade pip setuptools wheel
```

### 5. Install bot dependencies

```bash theme={null}
python -m pip install -r requirements.txt
```

### 6. Create local configuration files

```bash theme={null}
cp .env.example .env
cp config.yaml.example config.yaml
```

### 7. Confirm the environment

```bash theme={null}
which python
python --version
python -m pip show web3
```

Expected `which python` should point inside this project:

```text theme={null}
/var/www/LFG.RICH-Trading-Bot/.venv/bin/python
```

## Installation on Windows

Windows is supported for local testing, development, and community usage. Linux/VPS is recommended for long-running 24/7 operation.

Use PowerShell.

### 1. Install Python

Install Python 3.10 or 3.11 from the official Python website.

During installation, enable:

```text theme={null}
Add Python to PATH
```

### 2. Open PowerShell and enter the project folder

Example:

```powershell theme={null}
cd C:\path\to\LFG.RICH-Trading-Bot
```

### 3. Create and activate a virtual environment

```powershell theme={null}
py -3 -m venv .venv
.\.venv\Scripts\Activate.ps1
```

If PowerShell blocks activation, run:

```powershell theme={null}
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
```

Then activate again:

```powershell theme={null}
.\.venv\Scripts\Activate.ps1
```

### 4. Install dependencies

```powershell theme={null}
python -m pip install --upgrade pip setuptools wheel
python -m pip install -r requirements.txt
```

### 5. Create local config files

```powershell theme={null}
copy .env.example .env
copy config.yaml.example config.yaml
```

## Environment configuration

Create a `.env` file in the project root.

Example:

```env theme={null}
# Tested with NowNodes, Quicknode and publicnode. Other RPCs should work as well
BSC_RPC_URL="https://bsc-rpc.publicnode.com"
#BSC_RPC_URL="https://bsc.nownodes.io/some-api-key"
#BSC_RPC_URL="https://fittest-few-fog.bsc.quiknode.pro/some-api-key/"
PRIVATE_KEY="0xSecret"
WALLET_ADDRESS="0xWalletAddress"
```

### `.env` settings

| Setting          |                  Required | Description                                                                                                      |
| ---------------- | ------------------------: | ---------------------------------------------------------------------------------------------------------------- |
| `BSC_RPC_URL`    |                       Yes | BNB Smart Chain RPC URL. The bot needs normal contract calls and `eth_getLogs` for LFG Hook events.              |
| `PRIVATE_KEY`    | Required for live trading | Wallet private key used to sign buy, sell, and approval transactions. Not required for pure dry-run observation. |
| `WALLET_ADDRESS` |               Recommended | Public wallet address used for logs and dashboard context.                                                       |

Never commit `.env` to GitHub and never share your private key.

## Bot configuration

The bot is configured through:

```text theme={null}
config.yaml
```

Start by copying the example:

```bash theme={null}
cp config.yaml.example config.yaml
```

The default example token is LFGBULL:

```yaml theme={null}
watchlist:
  tokens:
    - symbol: "LFGBULL"
      address: "0x29Ede1E1254419Fe5a3c803fC2b015042075A49A"
      dex: "lfg"
```

If you created your own token on LFG.RICH, replace the symbol and token address in `watchlist.tokens[]`.

### LFG.RICH protocol contracts

The default configuration uses the official LFG.RICH BSC contracts:

```yaml theme={null}
lfg:
  factory: "0xaf6d6F359a630Ec6eb2BaFDc338b86d3E84CaF66"
  hook: "0xCA8D8D8d3d97cfac290a3850d32c2E8330CCe888"
  swap_router: "0x092043364f39f7f57C4E1D32116f453BfaE37440"
  pool_manager: "0x28e2Ea090877bF75740558f6BFB36A5ffeE9e9dF"
```

Do not change these unless LFG.RICH officially deploys new protocol contracts.

## Smoke test

Run the smoke test before running the full bot:

```bash theme={null}
source .venv/bin/activate
python -m bot.smoke_test_lfg
```

On Windows PowerShell:

```powershell theme={null}
.\.venv\Scripts\Activate.ps1
python -m bot.smoke_test_lfg
```

A successful smoke test should print values similar to:

```text theme={null}
token: 0x...
pool_id: 0x...
initialized: True
totalFeeBps: ...
effective price BNB/token: ...
estimate buy 0.001 BNB:
  tokensOut: ...
  platformFee: ...
  floorBoostFee: ...
  totalFee: ...
```

The quote values come from the LFG.RICH Hook. Token amounts and BNB amounts use 18 decimals.

## Running the bot

### 1. Start with dry-run mode

Before live trading, keep this enabled:

```yaml theme={null}
bot:
  dry_run: true
```

Run the bot:

```bash theme={null}
source .venv/bin/activate
python -m bot.main
```

In dry-run mode, the bot scans events, builds candles, calculates signals, and logs intended trades, but it does not send transactions.

### 2. Test a small live buy

After dry-run logs look correct, use a dedicated wallet with a small amount of BNB.

Enable test mode:

```yaml theme={null}
bot:
  dry_run: false
  test_mode: true
  test_action: "BUY"
  test_amount_bnb: 0.005
  test_once: true
```

Run:

```bash theme={null}
python -m bot.main
```

After the test buy succeeds, check the dashboard and verify that the lot was created.

### 3. Disable test mode for normal strategy trading

```yaml theme={null}
bot:
  test_mode: false
```

Then run:

```bash theme={null}
python -m bot.main
```

### 4. Keep the bot running with PM2

Optional Linux example:

```bash theme={null}
pm2 start "./.venv/bin/python -m bot.main" --name LFG-TradingBot
pm2 save
```

Check logs:

```bash theme={null}
pm2 logs LFG-TradingBot --lines 100
```

## Running the dashboard

The dashboard is optional, but useful for checking open lots, PnL, trades, balances, and bot state.

### 1. Install dashboard dependencies

```bash theme={null}
source .venv/bin/activate
python -m pip install -r requirements-dashboard.txt
```

On Windows:

```powershell theme={null}
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements-dashboard.txt
```

### 2. Run the dashboard

Run this from the project root, not from inside the `bot/` folder:

```bash theme={null}
python -m streamlit run bot/dashboard.py --server.address 0.0.0.0 --server.port 8501
```

On Windows local usage:

```powershell theme={null}
python -m streamlit run bot/dashboard.py --server.port 8501
```

Open in the browser:

```text theme={null}
http://YOUR_SERVER_IP:8501
```

For local usage:

```text theme={null}
http://localhost:8501
```

### 3. SSH tunnel option

If you do not want to expose port `8501` publicly:

```bash theme={null}
ssh -L 8501:127.0.0.1:8501 root@YOUR_SERVER_IP
```

Then open:

```text theme={null}
http://localhost:8501
```

### 4. Keep the dashboard running with PM2

Optional Linux example:

```bash theme={null}
pm2 start "./.venv/bin/python -m streamlit run bot/dashboard.py --server.address 0.0.0.0 --server.port 8501" --name LFG-TradingBot-Dashboard
pm2 save
```

## SQLite database and lots

The bot uses a local SQLite database:

```text theme={null}
state.db
```

It is created automatically in the project root when the bot runs.

### Dashboard dependency on the bot

The dashboard reads `state.db`.

The dashboard does not trade by itself and does not create positions by itself. It depends on the bot to create and update trades, positions, and lots.

If the bot has not confirmed any buy transactions yet, the dashboard may have no open lots to display.

### What are lots?

A **lot** is the bot's local record of a buy position.

When the bot confirms a successful buy transaction, it records a lot with:

```text theme={null}
symbol
buy transaction
quantity opened
cost in BNB
average entry price
remaining open quantity
```

The dashboard uses open lots to calculate:

* current position value;
* unrealized PnL;
* realized PnL after sells;
* average entry price;
* open exposure per token.

For LFG tokens, the dashboard prices open lots using this priority:

<Steps>
  <Step title="Use the latest valid candle close">
    This is the preferred current price source when candle data is available.
  </Step>

  <Step title="Fallback to LFG Hook getEffectivePrice(poolId)">
    If candle data is unavailable, the dashboard reads the protocol effective price.
  </Step>

  <Step title="Use zero only when both sources are unavailable">
    A zero price means the dashboard could not find a safe current price source.
  </Step>
</Steps>

### Useful SQLite commands

```bash theme={null}
sqlite3 state.db ".tables"
sqlite3 state.db "SELECT * FROM trades ORDER BY id DESC LIMIT 10;"
sqlite3 state.db "SELECT * FROM lots ORDER BY id DESC LIMIT 10;"
```

Do not delete `state.db` unless you intentionally want to reset local trade history, lots, cooldowns, and candle cache.

## Configuration reference

This section documents the settings in `config.yaml`.

### `chain`

| Setting          | Description                                     |
| ---------------- | ----------------------------------------------- |
| `chain.name`     | Human-readable chain name. Keep as `bsc`.       |
| `chain.chain_id` | BNB Smart Chain mainnet chain ID. Keep as `56`. |

### `rpc`

| Setting                   | Description                                                                               |
| ------------------------- | ----------------------------------------------------------------------------------------- |
| `rpc.request_timeout_sec` | Timeout in seconds for individual RPC requests.                                           |
| `rpc.max_retries`         | Number of retry attempts when RPC calls fail.                                             |
| `rpc.backoff_sec`         | Initial delay between retries. The retry helper increases the delay on repeated failures. |

### `lfg`

| Setting            | Description                                                                       |
| ------------------ | --------------------------------------------------------------------------------- |
| `lfg.factory`      | LFG.RICH Factory contract. Used for protocol metadata and fee receiver reference. |
| `lfg.hook`         | LFG.RICH Uniswap V4 Hook. Used for events, token state, prices, and estimates.    |
| `lfg.swap_router`  | LFG.RICH Swap Router. Used to execute buys and sells.                             |
| `lfg.pool_manager` | Uniswap V4 Pool Manager used by the LFG.RICH protocol.                            |

### `bot` execution settings

| Setting                    | Description                                                                             |
| -------------------------- | --------------------------------------------------------------------------------------- |
| `bot.polling_interval_sec` | Seconds between each bot loop.                                                          |
| `bot.trade_cooldown_sec`   | Seconds to wait after a trade before trading the same token again.                      |
| `bot.min_hold_minutes`     | Minimum minutes to hold a lot before normal sell logic can sell it.                     |
| `bot.dry_run`              | If `true`, the bot logs intended trades but does not send transactions.                 |
| `bot.warmup_approve`       | If `true`, the bot checks token allowance for the LFG Swap Router on startup.           |
| `bot.approve_wait_sec`     | Seconds to wait for approval transaction confirmation before continuing sell execution. |

### `bot` risk and trade sizing

| Setting                   | Description                                                                                    |
| ------------------------- | ---------------------------------------------------------------------------------------------- |
| `bot.profit_gate_enabled` | If `true`, normal sells require `min_profit_pct` unless stop-loss triggers.                    |
| `bot.min_profit_pct`      | Minimum profit percentage required for normal sells when profit gate is enabled.               |
| `bot.max_loss_pct`        | Stop-loss percentage. Example: `10` means sell if the lot is at `-10%` or worse.               |
| `bot.max_hold_minutes`    | Optional forced-exit timer in minutes. `0` disables forced exit.                               |
| `bot.slippage_bps`        | Slippage tolerance in basis points. `1200` means 12%. It must cover token fees and volatility. |
| `bot.gas_limit`           | Gas limit used for LFG buy/sell transactions.                                                  |
| `bot.min_bnb_for_gas`     | BNB to keep untouched for gas. The bot will not spend below this amount.                       |
| `bot.min_trade_bnb`       | Minimum BNB value for a buy/sell action.                                                       |
| `bot.max_trade_bnb`       | Maximum BNB value for a single buy/sell action.                                                |

### `bot` event scanner and candles

| Setting                      | Description                                                                                                           |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `bot.blocks_per_candle`      | Number of BSC blocks per internal price candle.                                                                       |
| `bot.confirmations`          | Blocks to wait before treating events as safe/final enough to process.                                                |
| `bot.log_chunk_blocks`       | `eth_getLogs` chunk size. Lower this if public/free RPCs rate-limit or fail.                                          |
| `bot.warmup_lookback_blocks` | Blocks scanned on first run to build historical candles for older tokens. Increase if the bot says `not enough data`. |
| `bot.max_history_candles`    | Maximum candles kept in memory/cache per token.                                                                       |

### `bot` strategy settings

| Setting                      | Description                                                                        |
| ---------------------------- | ---------------------------------------------------------------------------------- |
| `bot.fast_down_enabled`      | Enables fast downtrend sell protection.                                            |
| `bot.fast_down_candles`      | Number of recent real-volume candles used for fast downtrend detection.            |
| `bot.fast_down_min_drop_pct` | Minimum percentage drop across `fast_down_candles` to flag fast downtrend.         |
| `bot.fast_down_min_steps`    | Minimum number of red/down candle steps required to flag fast downtrend.           |
| `bot.trend_confirm_candles`  | Number of candles used to confirm trend direction.                                 |
| `bot.ema_deadband_pct`       | EMA deadband percentage. Helps avoid noisy trend flips when EMAs are very close.   |
| `bot.dump_lookback`          | Number of candles used to detect a quick dump.                                     |
| `bot.dump_drop_pct`          | Percentage drop over `dump_lookback` candles that flags a dump.                    |
| `bot.pump_lookback`          | Number of candles used to detect a quick pump.                                     |
| `bot.pump_rise_pct`          | Percentage rise over `pump_lookback` candles that flags a pump.                    |
| `bot.bleed_lookback`         | Number of candles used to detect slow bleeding/downtrend.                          |
| `bot.bleed_drop_pct`         | Percentage drop over `bleed_lookback` candles that contributes to bleed detection. |
| `bot.bleed_rise_pct`         | Percentage rise threshold used to distinguish recovery from bleeding.              |
| `bot.bleed_min_steps`        | Minimum number of down steps required for bleed detection.                         |

### `bot` test mode

| Setting               | Description                                                                                             |
| --------------------- | ------------------------------------------------------------------------------------------------------- |
| `bot.test_mode`       | If `true`, forces `test_action` instead of using the strategy signal. Useful for live buy/sell testing. |
| `bot.test_action`     | `BUY` or `SELL`. Only used when `test_mode` is true.                                                    |
| `bot.test_amount_bnb` | BNB trade size for test-mode actions.                                                                   |
| `bot.test_once`       | If `true`, performs one test action and exits.                                                          |

### `watchlist.tokens[]`

Each token entry defines one LFG.RICH token to monitor and trade.

| Setting         | Description                                                                                 |
| --------------- | ------------------------------------------------------------------------------------------- |
| `symbol`        | Token symbol/ticker.                                                                        |
| `address`       | LFG.RICH token contract address.                                                            |
| `max_alloc_bnb` | Maximum total BNB allocation allowed for this token.                                        |
| `add_step_bnb`  | BNB amount to add when the strategy decides to buy/increase position.                       |
| `timeframe_sec` | Intended strategy timeframe in seconds. Kept for compatibility with strategy settings/logs. |
| `ema_fast`      | Fast EMA period used by the strategy.                                                       |
| `ema_slow`      | Slow EMA period used by the strategy.                                                       |
| `rsi_period`    | RSI period used by the strategy.                                                            |
| `dust_size`     | Token quantity below this amount is treated as dust/closed in local lot accounting.         |
| `dex`           | Trading venue. Keep as `lfg`.                                                               |

## Troubleshooting

### `SyntaxError` showing `/usr/lib/python2.7/...`

You are running Python 2.

Activate the venv and use Python 3:

```bash theme={null}
source .venv/bin/activate
python --version
python -m bot.main
```

### `ModuleNotFoundError: No module named 'web3'`

Dependencies are not installed in the active environment:

```bash theme={null}
source .venv/bin/activate
python -m pip install -r requirements.txt
```

### `ensurepip is not available`

Install the venv package:

```bash theme={null}
apt install -y python3.8-venv python3-pip
```

Then recreate the venv:

```bash theme={null}
rm -rf .venv
python3 -m venv .venv
source .venv/bin/activate
```

### `pip: command not found`

Install pip:

```bash theme={null}
apt install -y python3-pip
```

### `No matching distribution found for aiohappyeyeballs==2.6.1`

You are using an old/frozen dependency list from a newer Python environment.

Use the `requirements.txt` included in this LFG.RICH bot package.

### `No matching distribution found for streamlit==1.40.2`

Use the included `requirements-dashboard.txt`, which pins:

```text theme={null}
streamlit==1.40.1
```

### `invalid argument 0: hex string without 0x prefix`

Use the latest LFG.RICH bot package. The LFG pool id and event topic handling were updated to normalize values with the required `0x` prefix.

### Dashboard shows `lot_pnl_pct` as empty or `None`

The dashboard needs a valid current price.

For LFG tokens, the dashboard now uses:

<Steps>
  <Step title="Use the latest valid candle close">
    This is the preferred current price source when candle data is available.
  </Step>

  <Step title="Fallback to LFG Hook getEffectivePrice(poolId)">
    If candle data is unavailable, the dashboard reads the protocol effective price.
  </Step>

  <Step title="Use zero only when both sources are unavailable">
    A zero price means the dashboard could not find a safe current price source.
  </Step>
</Steps>

If the value is still empty, confirm the bot and dashboard are using the same `state.db` and `config.yaml`.

## Safe operating checklist

Before running live:

<Steps>
  <Step title="Use a dedicated wallet">
    Do not run an automated bot from your main wallet.
  </Step>

  <Step title="Keep only a small amount of BNB in that wallet">
    Limit exposure while testing and operating the bot.
  </Step>

  <Step title="Start with dry_run enabled">
    Use `dry_run: true` before allowing live transactions.
  </Step>

  <Step title="Run the smoke test">
    Execute `python -m bot.smoke_test_lfg` before running the bot.
  </Step>

  <Step title="Confirm candles and signals look correct">
    Let the bot run and verify that market data and decisions make sense.
  </Step>

  <Step title="Test one tiny BUY in test mode">
    Use `test_mode: true`, `test_action: "BUY"`, and a tiny `test_amount_bnb`.
  </Step>

  <Step title="Confirm the dashboard shows the lot">
    Make sure the local database and dashboard match the expected result.
  </Step>

  <Step title="Only then disable test_mode">
    Move to live operation only after the small test is confirmed.
  </Step>
</Steps>

## Community note

This bot was built as a contribution to the LFG.RICH community and to support developers, builders, and traders exploring the LFG.RICH launchpad and protocol.

You are free to use, modify, improve, and share this project. Before running live trades, review the configuration, test with small amounts, and adjust the strategy to your own needs.

The goal of this project is to help increase adoption, experimentation, and community-driven development around LFG.RICH.