anti-gambling-trader-tw: a local statistics tool for checking whether your trading is an edge or luck
免費開源的投資反詐、交易統計與自動化交易程式工具：預設 PaperBroker，提供 14 種券商／交易所選項；交易紀錄分析在本機執行。
At a glance
- What is it?
- A free MIT Python project that analyzes trade records, broker exports and LINE chats to separate measurable expectancy from survivorship bias. The core runs on the standard library; the scaffolder can generate paper-trading projects from 14 broker and exchange templates.
- Who is it for?
- Adopt it if you already have a CSV or broker export of your own trades and want a defensible answer to whether the numbers are repeatable, or if you are trying to talk a relative out of a LINE investment group and need a printable report.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 58 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 17, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The question this tool answers, and the people asking it
Most retail trading losses come from mistaking a lucky streak for skill, and the README argues scam operators exploit exactly that gap with fake VIP groups, curated screenshots and guaranteed-profit scripts. The project is aimed at that moment: you have a trade history, or a LINE conversation, or a guru's claimed monthly return, and you want a statistical answer rather than an opinion. It supports Taiwan stocks, Taiwan ETFs, Taiwan index futures and options, US stocks, crypto and forex, and imports CSV, JSON or Excel. The audience is explicitly broad enough to include people who have never opened a terminal; docs/quickstart.md starts from installing Python. That is an unusual editorial choice for a statistics tool, and it tells you who the maintainers think the real user is: not a quant, but someone about to wire money to a stranger.
Expectancy, bootstrap tests and the five verdict levels
The mechanism is a pipeline, not a black box. Records are normalized through core.ingest, which auto-detects Chinese and English column names, then core.metrics computes win rate, profit factor, expectancy, maximum drawdown, Sharpe and Sortino. core.verdict applies a t-test plus a centered bootstrap to ask whether the sample mean is distinguishable from zero, and the output lands in one of five levels: gambling, insufficient, luck_suspected, fragile_edge, or statistical_edge. Only the last one skips the discouragement message. The design is deliberately conservative in one direction: a negative sample expectancy is treated as gambling even before significance is settled. The README is candid that a green verdict is not a guarantee, and that per-strategy results are descriptive statistics only. That restraint matters, because the temptation with a tool like this is to certify each strategy separately, which uncorrected multiple comparisons would turn into a luck detector.
Install anti-gambling-trader-tw and run a first analysis
The core engine depends only on the Python standard library, so installation is short. Requires Python 3.10 or newer, and every command must run from the project root, the directory containing core/. On macOS or Linux, if python points at Python 2, use python3. Clone the repository and install it in editable mode; the pip install -e . step is what puts the anti-gambling-trader entry point on your PATH, and until then every command is spelled python -m core.cli.
git clone https://github.com/mars-tw/anti-gambling-trader-tw.git
cd anti-gambling-trader-tw
pip install -e . # 安裝本體（之後可用 anti-gambling-trader 指令）
# 以下為可選依賴：
# pip install openpyxl # 只有要讀 Excel (.xlsx) 才需要
# pip install -e ".[screenshot]" # 圖片 OCR；另需安裝 Tesseract 與繁中字庫
# pip install backtrader # 只有要實際跑回測骨架才需要（或 vectorbt）With no data of your own, demo generates a sample so you can see the output shape before committing a real file. The --edge variant swaps in a positively skewed example, which is useful for comparing what the two verdict levels look like side by side.
python -m core.cli demo # 看「賭博型」範例
python -m core.cli demo --edge # 看「具優勢」範例
python -m core.cli init-template # 產生 trades_template.csvPoint analyze at your export. Market type is inferred, and if column detection fails you can map fields by hand rather than renaming columns in the spreadsheet. The --json and --strategy flags write a machine-readable result and a backtestable skeleton respectively.
python -m core.cli analyze 你的交易.csv
python -m core.cli analyze 你的交易.csv --field symbol=代號 --field entry_price=買價
python -m core.cli analyze --example us --json result.json --strategy my_strategy.pyExpect a verdict banner plus a metrics table, not a single number. If your file lacks usable exit timestamps, the tool refuses to treat row order as chronology and will not claim out-of-sample validation; that refusal is the feature, not a bug. Screenshot OCR is a separate path and the README is blunt that it extracts candidate fields only, may misread signs, decimal points and buy/sell direction, and never writes into your trade log automatically.
Fail-closed input handling is the most opinionated part
Where the documentation is unusually specific is the data-integrity rules. Missing, invalid or uniform exit times disable time-ordering claims. Mixed or unknown P&L currencies are not summed. When contract multiplier, notional or the entry basis for a direct P&L figure is unreliable, return and drawdown percentages are switched off entirely. Ambiguous gross/net columns such as 盈虧, 已實現損益 or realized_pnl are rejected unless you rename them to something that says net, or confirm with --field pnl=你的欄名. A gross column like profit loads only if the same row carries a credible total_fee or 交易成本. This is a deliberate trade-off: the tool will refuse to produce a number rather than produce a plausible wrong one, which is the opposite of what most retail analytics dashboards do. The cost is friction on messy exports, and the README points to docs/user-guide.md for the full fail-closed rules rather than pretending they are self-evident.
Scam scanning, forensics and the guru-claim checker
Alongside the statistics there is a second family of commands aimed at evidence rather than your own P&L. scan-text reads pasted group messages or an exported LINE file, understands cross-message phrasing and LINE export headers, and shows speaker, timestamp, the original sentence and the reason it was flagged, with a risk level instead of a fake percentage. guru-check takes a claimed win rate, trade count and monthly return and reports how likely that result is under pure chance. forensics looks for suspicious signatures in a claimed return series, such as excessive smoothness or an implausibly high Sharpe. survivorship estimates how easily a ten-win streak appears by luck alone. scam-check is interactive. The README is careful to say this is statistical assistance, not forensic or judicial proof, and routes people to Taiwan's 165 anti-fraud hotline and the official regulator and investor-protection bodies instead.
Where it is the wrong tool
Three boundaries are worth stating plainly. First, this is not a backtesting engine: it generates skeletons for backtrader, vectorbt or a generic target, and you need one of those installed to run them. Second, it is not a broker integration. The scaffolder emits a self-contained project with strategy, risk controls, broker interface, data source and charts, with PaperBroker runnable out of the box and 13 real broker or exchange templates alongside it, but the README states the generated historical runner does not send real orders and that a live adapter can only send orders after you supply keys, finish a live runner and explicitly unlock it. Third, sample size is a hard limit. The insufficient verdict exists precisely because small samples cannot separate skill from luck, and no amount of report formatting fixes that. If you trade once a quarter, this tool will mostly tell you it does not know, and that is the honest answer.
How it differs from a backtesting framework
The nearest thing to a comparison in the documentation is backtrader and vectorbt, which the project treats as optional extras rather than rivals. The difference in approach is the direction of inference. A backtesting framework takes a rule and asks what it would have returned on historical bars, which is a forward simulation you control. This tool takes what you already did and asks whether the result is distinguishable from noise, using centered bootstrap and out-of-sample checks, and it is willing to answer "no". Those are complementary: the README's own workflow is to analyze real trades first, then let the scaffolder turn the logic into something backtrader can run. If you want parameter sweeps and walk-forward optimization, install backtrader or vectorbt; if you want to know whether your last two years of fills mean anything, that is the question this project was built around.
Maintenance, licence and what a fork costs you
The repository is not archived and the last push was on 2026-07-22, so the code has moved within the last two months, though the README does not document a release cadence and no releases were retrieved. pyproject.toml pins version 0.1.0, which is worth reading as an honest signal: this is early software with a single-version history. The licence is MIT, declared both in the LICENSE file and in the classifier, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained; the project also ships CITATION.cff and DISCLAIMER.md, and the README states the tool is statistical assistance rather than judicial proof. Upgrade cost is low by construction. Dependencies are empty, with openpyxl, Pillow plus pytesseract, backtrader or vectorbt, and pytest all behind optional extras, so a version bump cannot break your analysis environment through a transitive dependency. The real cost of forking is the input contract: any change to how pnl, pnl_currency or fees are interpreted will silently change verdicts, and the fail-closed rules in docs/user-guide.md are the specification you would be diverging from.
Editorial conclusion
Adopt it if you already have a CSV or broker export of your own trades and want a defensible answer to whether the numbers are repeatable, or if you are trying to talk a relative out of a LINE investment group and need a printable report. Skip it if you want a backtesting framework, an execution engine, or a signal generator: the scaffolder produces skeletons, and the README states the generated historical runner does not send real orders, so live trading requires you to write the live runner and unlock the adapter yourself. Before trusting any verdict, verify three things in your own data: that your pnl column is net of all fees as the standard field contract requires, that your exit timestamps are real rather than row order, and that you filled the tag column, because the per-strategy breakdown is where the tool actually earns its keep.
Frequently asked questions
Is trading 100% gambling?
The project's framing is that a sample with negative expectancy is treated as gambling by conservative default, because a negative true expectancy means a losing expectation over the long run by definition. A positive sample can still be labelled luck_suspected or insufficient, and only statistical_edge passes the significance test. So the tool does not call all trading gambling; it calls it gambling when the numbers cannot show otherwise.
What is the 90% rule in gambling?
The documentation does not describe a 90% rule. What it does address is the claim of a 90% win rate: guru-check takes --win-rate and --trades and reports how likely that result is to appear by chance alone, and the README warns that a high win rate can coexist with a losing expectancy when losses are large.
What is the difference between a trader and a gambler, according to anti-gambling-trader-tw?
The README draws the line at expectancy and significance: a trader has a positive expectancy that survives a t-test plus centered bootstrap and out-of-sample validation, while a gambler has a negative expectancy or a result statistically indistinguishable from luck. The five verdict levels exist to place a specific record on that spectrum rather than to define the person.
Community notes