Published July 2026 · last updated 17 November 2026 · by @qrak

A trading bot that reads charts, keeps a memory of its trades, and learns from the closed ones

The engineering history of an open-source, vision-capable crypto bot — first commit 21 December 2025.


1. Origin — a stateless calculator

The first commit is dated 21 December 2025; the project has been written outside working hours since then. Every date and number below is checked against the repository.

The first version did what the common tutorial prescribes. Pull RSI, MACD and Bollinger Bands in Python, write a prompt template, put the floats into an LLM API. The answers came back confident and articulate — "RSI is at 28, oversold. BUY." — and the paper portfolio went the other way.

The model was not the limitation. The architecture was: a stateless calculator, sent to work as a reasoning engine. Every cycle started from zero, and no closed trade could change the next decision.

2. The timeline, taken from git log

Every date below is the date a file first appeared in the repository or a commit landed. You can check all of them with git log --date=short --diff-filter=A.

Phase 1 — December 2025: the stateless calculator

First commit 21 Dec 2025, with OpenRouter already present in that commit's config as a provider option. The candle_limit = 999 value has been in config/config.ini since that very first commit, the order book is fetched at 50 levels, and the bot had no memory of anything it did.

Phase 2 — January 2026: the bot gets eyes

The dashboard server lands 6 Jan. Chart rendering is older than this phase: chart_generator.py and the ChartGenerator class are in the repository from 22 Dec 2025. On 16 Jan the chart image becomes the AI-optimized PNG the model actually looks at, with the image-export retry logic that Plotly/Kaleido makes necessary; the 1920×1080 frame arrives in July. The bot stops reading floats and starts reading a chart.

Phase 3 — May 2026: the brain

16 May: the vector-memory era. brain_experience, brain_context and brain_reflection arrive — closed trades become 768D embeddings in ChromaDB, retrievable before the next decision, with a reflection pass that writes rules in plain language. A few days earlier (12 May) came the blunt commit message "make bot profitable with Gemini Flash 3 Preview". The claim did not hold, and the commit stays in the history.

Phase 4 — July 2026: the bot starts maintaining itself

26–27 Jul: the .ai/ directory appears — a supervisor plus seven specialist agent profiles (Bolt, Palette, Sentinel, Refactor, Concise, Bugfixer, Smoke Tests) with their own journals. 30 Jul: Reddit/RSS sentiment lands, and with it the public landing page.

Phase 5 — August 2026: the executor and the verdict journal

14 Aug: executor integration. The engine stops assuming what happened to its orders and starts reading a verdict journal — one line per decision, written by the executor service, keyed by the bot's own order_id. Orders that cannot be confirmed go to a dead-letter queue instead of vanishing.

Phase 6 — September 2026: providers and tests

12 Sep: provider transport consolidation and the official DeepSeek API added next to Google AI. 19 Sep: the test suite is reorganised into domain modules and the entry gate is reduced to expected value alone — the fixed R/R floor is gone, and the brain earns its own floor from its own expectancy. 1,549 collected at that point, 1,532 passing, 17 skipped.

3. The mathematics and the engineering

The Numba JIT indicator engine

Indicators are written in NumPy and decorated with Numba's @njit(cache=True), so they compile to machine code on first call and cache the result. src/indicators/ contains 65 Numba-compiled functions (107 across the whole src/ tree) with zero external technical-analysis dependencies. Real code, not a screenshot:

@njit(cache=True)
def supertrend_numba(high: np.ndarray, low: np.ndarray, close: np.ndarray,
                     length: int = 10, multiplier: float = 3.0) -> tuple[np.ndarray, np.ndarray]:

    n = len(close)
    atr = atr_numba(high, low, close, length)

    hl2 = (high + low) / 2
    upperband = hl2 + multiplier * atr
    lowerband = hl2 - multiplier * atr

    trend = np.full(n, np.nan)
    direction = np.full(n, 1)

    for i in range(1, n):
        upperband[i], lowerband[i] = calculate_band_adjustments(close, upperband, lowerband, i)

        if close[i] > upperband[i - 1]:
            direction[i] = 1
        elif close[i] < lowerband[i - 1]:
            direction[i] = -1
        # ... the rest of the loop is in the file

src/indicators/trend/trend_indicators.py — trimmed at the loop; the full function is in the repo. No docstrings: this project keeps prose out of the code and in these pages.

Chart vision

Plotly renders a 1920×1080 candlestick chart (SMA, RSI, CMF, OBV, swing annotations) to PNG and it is sent to a multimodal model alongside the numeric stack. Images arrive from an export pipeline that hangs often enough that the code carries timeouts and exponential-backoff retries around it — src/analyzer/pattern_engine/chart_generator.py.

The Surprise Ratio

A support break that won because of a random news spike should not become a rule. Every closed trade gets a surprise score:

Surprise Ratio = |Realized P&L − Expected P&L| / max(|Expected P&L|, 0.01)

A rule whose group average exceeds 1.5 carries a ⚠️ high surprise annotation, so the model can discount the lucky outcomes behind it (src/trading/brain_reflection.py). The bot learns from what it understood, not from what it got lucky on.

What constrains an entry

The project prompts the model to discuss expected value, but the repository does not currently enforce a deterministic expected-value gate. Deterministic checks concern the symbol whitelist, position caps and validated stop/target values. The optional min_rr_entry setting is currently 0.0, so this page does not present it as an active entry gate.

What is not in here

  • No Kelly criterion. An earlier version of this page claimed Kelly-sized positions. There is no Kelly code in the repository. Position size is the model's proposal, clamped to a 10% of capital cap, with 1% / 2% / 3% fallbacks by conviction level.
  • No track record. The closed trades are an anecdote; the ledger is on the results page with its caveats, and this page does not present a win rate as a result.
  • No backtest-to-live claim. Simulated fills have no slippage, no partial fills and no liquidity limits. Paper numbers are not live numbers.

Corrections, 3 November 2026

  • The about page and the footer said the author works in a warehouse and is in Wrocław. That is personal information, not a property of the project, and it is removed from the public copy. The contact and privacy pages still show the operator's location because they state who is responsible for the site.
  • The cycle description said "every four hours" as if it were a fixed property. The cadence follows the configured timeframe; 4h is the public deployment's value.
  • The sizing and memory lines are now stated as the code does them: fallback sizes come from the config (1–3% by confidence), and the claim checks cover trend strength and pattern quality, not every number a model writes.
  • The commit count on the public pages was 556 on 1 November (607 on master when this correction was written). Counts and ledger figures now come from claims.json and the ledger JSON, so this page no longer types them.

Corrections, 16 November 2026

  • The status section claimed a browser test suite run after playwright install chromium. No test opens a browser: Playwright appears only as the chart-export fallback in src/analyzer/pattern_engine/chart_generator.py, and the old test that drove the live dashboard is gone. The sentence is removed.
  • The page said the live provider was DeepSeek. The deployment runs provider = opencode with deepseek-v4.1-flash on the OpenCode Go endpoint; DeepSeek is one provider in the all chain.
  • The printed supertrend_numba excerpt carried a docstring the file does not have. This project has no docstrings; the excerpt is now the real function, trimmed at the loop.
  • The surprise ratio now shows the denominator the code uses, max(|expected|, 0.01).
  • Test figures on the home page are rendered from claims.json instead of a typed "~119 s", and the About page no longer implies this website lives in the LLM_trader repository.

4. Status — November 2026

  • Trading: simulated capital only (a 10,000 USDC paper book). No real funds are involved anywhere in this project.
  • Tests: 2,804 collected, every one passing except the MCP history test, which skips unless the optional mcp package is installed. python -m pytest tests -q, measured 17 November 2026 — 2,804 collected, 132 s.
  • Executor: implemented as a separate service and wired to an exchange testnet (ENABLE_TESTNET=true, sandbox endpoints). It has placed test orders and journals their verdicts; live trading with real money is not enabled.
  • Profitability: unproven. Development has had losing stretches and the code comments admit it. If that ever changes, this page changes with it.
  • Source: the whole thing is at github.com/qrak/LLM_trader. The repository, not this page, is the source of truth.

5. Quick start

git clone https://github.com/qrak/LLM_trader.git && cd LLM_trader
python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt -c constraints.txt
cp keys.env.example keys.env    # add GOOGLE_STUDIO_API_KEY, DEEPSEEK_API_KEY or OPENROUTER_API_KEY
python start.py                 # dashboard at http://localhost:8000

Paper trading is the default. The executor only sees decisions when you enable it — and it defaults to testnet.