LotteryCN

A Python library for enjoyable analysis of Chinese welfare & sports lotteries — official draw data, combinatorial odds & expected value, number-picking strategies with backtesting, and winning checks.

Documentation · 中文文档

English | 简体中文

Table of Contents

• Why LotteryCN
• Supported Games, Strategies & Data Sources
• Installation
• Quickstart
• Command Line
• License
• Disclaimer

Why LotteryCN

• Official data only — winning numbers and draw details (sales, prize pools, per-level results, province distribution) come straight from official channels; no third-party scrapers.
• Combinatorial math for probabilities & expectations — exact prize-tier counts; current prize tiers, conditions and amounts in one auditable config with source URLs; probabilities, expected values and return rates derived from official prize tables, plus instant ticket checking.
• Number-picking strategies & backtesting (core) — 11 strategies + a composable shrink engine + built-in rolling backtest; the backtest keeps proving every strategy matches the random baseline in expected value.
• Full pipeline — collect (cached incrementally) → analyze → predict → backtest → check.

Supported Games, Strategies & Data Sources

Games

Strategies

lotterycn.predict ships eleven number-generation strategies plus a composable filter engine. None of them has any predictive power — draws are independent random events, so every strategy has exactly the same expected value as the random baseline. Full details: the Strategies page.

Honest disclaimer: historical statistics cannot predict future draws — play rationally.

Data Sources

All rules and draw data come from official channels only:

• China Welfare Lottery: cwl.gov.cn
• China Sports Lottery: lottery.gov.cn

Rule and data sources exclude all company-operated portals (see CONTRIBUTING.md); the rule versions currently implemented are cited with URLs in lotterycn/config.py.

Installation

pip install --upgrade lotterycn

conda install -c conda-forge lotterycn

Requires Python 3.10 – 3.15.

Quickstart

One full pipeline — collect (cached & refreshed incrementally) → analyze → predict → backtest → check:

import lotterycn

df_ssq = lotterycn.load_history_data(lottery_name='ssq', if_cached=True, sleep_seconds=0.1)
stats = lotterycn.load_number_statistics(lottery_name='ssq', history=df_ssq)
print(lotterycn.load_prize_expectation(lottery_name='ssq'))

picks = lotterycn.load_predict_numbers(lottery_name='ssq', method='hot', amount=5)
results = lotterycn.backtest(lottery_name='ssq', methods=('random', 'hot'), window=10)
print(lotterycn.backtest_summary(results=results))

print(lotterycn.load_check_result(lottery_name='ssq', my_number='01,05,12,18,27,33|08', if_cached=True))

Every strategy matches random in expected value — the backtest above reproduces this conclusion every time; any "significantly better than random" observation is overfitting or noise. Ticket formats follow the published draw results; per-game play types (kl8 pick=1..10, dlt if_pool_over_800m / if_add_bet, compound bets) and all other parameters are documented in the API Reference.

Command Line

The package installs a lotterycn console script (also available as python -m lotterycn.cli):

lotterycn odds ssq
lotterycn expect dlt --pool-over-800m
lotterycn predict ssq --method hot --amount 5 --cached
lotterycn check ssq \
  --number '01,05,12,18,27,33|08' \
  --draw '01,05,12,18,27,33|08'

--cached reads the local cache and refreshes it incrementally (first run requires network).

Contributions are welcome — see CONTRIBUTING.md. For local checks: pip install pytest ruff && pytest (offline; network tests via pytest -m network).

License

MIT

Disclaimer

This project is for data analysis and educational purposes only. It is not affiliated with any lottery operator. Lottery data and rules may change at any time; always refer to official announcements. Play rationally — lotteries are for adults (18+) and should never be treated as an investment.