k-lottery

# Tool List     This is a tool that simulates purchasing lottery tickets for k-lottery 6/45, reports balances, and checks for wins. ## Table of Contents - [What can it do?](#what-can-it-do) - [Requirements](#requirements) - [Quick Start](#quick-start) - [MCP Server Setup](#mcp-server-setup) - [Safety Features](#safety-features) - [CLI Usage](#cli-usage) - [Environment Variables](#environment-variables) - [Exit Codes](#exit-codes) - [Automation Example (cron)](#automation-example-cron) - [Notes](#notes) - [Development](#development) - [Contributions](#contributions) · [Disclaimer](#disclaimer) · [License](#license) ## What can it do? | CLI | Function | | --- | --- | | `scripts/balance.py` | Balance, purchase limit, and validity | | `scripts/check.py` | Purchase history and winning results (rank calculated by server) | | `scripts/deposit.py` | Issue virtual account for deposit (transfer directly) | | `scripts/buy.py` | Automatic number purchase (default dry-run) | | MCP Tool | Parameters | Exposure | Function | | --- | --- | --- | --- | | `lotto_status` | — | Always | Balance, limit, validity, virtual account (**last 4 digits only**) | | `lotto_results` | `days=14`, `round_no?` | Always | Purchase history + winning results | | `lotto_draw` | `round_no` | Always | Public draw results (no login required) | | `lotto_buy_precheck` | `games=5` | Always | Pre-purchase check only. **Does not buy** | | `lotto_buy` | `games=5` | Gate | Actual purchase (approval required) | | `lotto_deposit` | `amount` | Gate | Virtual account issuance (approval required) | ## Requirements | | | | --- | --- | | [uv](https://docs.astral.sh/uv/getting-started/installation/) | Required. Python 3.13 will automatically install uv based on `.python-version` | | k-lottery account | Login credentials | | Promise of responsible purchase | Must be done **directly** on the website. If expired, purchase will be blocked (exit code 3) | | Deposit | Bank transfer required for charging, so full automation is not possible | ## Quick Start ```bash git clone https://github.com/rajephon/k-lottery.git cd k-lottery uv sync cp .env.example .env # Fill in ID and password (.env is not committed) uv run scripts/balance.py ``` ## MCP Server Setup CLI and MCP server share the same core. FastMCP (stdio) server is set up on top of it. ### Register with Claude Code ```bash # Read-only (default). Only visible in this repository directory claude mcp add klottery -- uv run --directory /absolute/path/k-lottery scripts/mcp_server.py # For use in any directory, register with user scope claude mcp add klottery -s user -- uv run --directory /absolute/path/k-lottery scripts/mcp_server.py # To allow purchase and deposit, pass environment variables claude mcp add klottery -s user \ -e KLOTTERY_MCP_ALLOW_BUY=1 -e KLOTTERY_MCP_ALLOW_DEPOSIT=1 -- \ uv run --directory /absolute/path/k-lottery scripts/mcp_server.py ``` ### Register with Claude Desktop Open the configuration file. - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` - Windows: `%APPDATA%\Claude\claude_desktop_config.json` ```json { "mcpServers": { "klottery": { "command": "/opt/homebrew/bin/uv", "args": ["run", "--directory", "/absolute/path/k-lottery", "scripts/mcp_server.py"], "env": { "KLOTTERY_MCP_ALLOW_BUY": "1" } } } } ``` ## Safety Features **CLI** has dry-run by default for purchase and deposit, and requires `--execute` to actually execute. **MCP** does not have tty or `--execute`, so a different approach is needed. 1. **Exposure** — Purchase and deposit are only listed if `KLOTTERY_MCP_ALLOW_*` is present in the server process environment. 2. **Approval** — Human input required for payment amount before execution. 3. **Blocking** — If the client does not support approval prompts, it will fail. 4. **Cooldown** — If a purchase or deposit request is rejected or canceled, it will not be prompted again for 10 minutes. ## CLI Usage All scripts accept `--json` (output JSON to stdout), `-v` (DEBUG logs to stderr), and `--env-file <path>`. ### Balance Check ```bash uv run scripts/balance.py uv run scripts/balance.py --json ``` ### Winning Check ```bash uv run scripts/check.py # Recent 14 days uv run scripts/check.py --days 30 uv run scripts/check.py --round 1234 ``` ### Deposit ```bash uv run scripts/deposit.py --amount 5000 # dry-run uv run scripts/deposit.py --amount 5000 --execute ``` ### Purchase ```bash uv run scripts/buy.py # dry-run (default 5 games) uv run scripts/buy.py --games 5 --execute uv run scripts/buy.py --execute --yes # for cron ``` ## Environment Variables Account information is stored in `.env` (cp `.env.example .env`). This file is not committed. | Environment Variable | Description | Default Value | | --- | --- | --- | | `LOTTO_USER_ID` | k-lottery ID | (required) | | `LOTTO_PASSWORD` | k-lottery password | (required) | | `LOTTO_DATA_DIR` | Cookie and history storage location | `./data` | | `LOTTO_TIMEOUT` | HTTP timeout (seconds) | `10` | | `LOTTO_REQUEST_INTERVAL` | Minimum interval between requests (seconds) | `0.3` | | `LOTTO_USER_AGENT` | User-Agent | Chrome | MCP tool switches are read from the server process environment. | Environment Variable | Description | Default Value | | --- | --- | --- | | `KLOTTERY_MCP_ALLOW_BUY` | Allow `lotto_buy` exposure (`1`/`true`/`yes`/`on`) | (not exposed) | | `KLOTTERY_MCP_ALLOW_DEPOSIT` | Allow `lotto_deposit` exposure | (not exposed) | ## Exit Codes | Code | Meaning | Code | Meaning | | --- | --- | --- | --- | | 0 | Success | 7 | Automation blocked (`isAllowed=N`) | | 1 | General error | 8 | Already purchased round | | 2 | Incorrect argument/value | 9 | Not during sales hours/maintenance | | 3 | Settings/credentials | 10 | Waiting in queue | | 4 | Authentication failure | 11 | User rejected | | 5 | Server response abnormal | 130 | Interrupted | | 6 | Insufficient balance | | | ## Automation Example (cron) ```cron # uv requires absolute path. cron's PATH is different from shell (`which uv` result can be used) # Buy every Monday at 19:00, check wins every Sunday at 09:00 0 19 * * 1 cd /absolute/path/k-lottery && /opt/homebrew/bin/uv run scripts/buy.py --execute --yes >> data/cron.log 2>&1 0 9 * * 0 cd /absolute/path/k-lottery && /opt/homebrew/bin/uv run scripts/check.py --days 7 >> data/cron.log 2>&1 ``` ## Notes - The site was **revamped in 2026**. Existing bot codes (`common.do?method=...`, `userSsl.do?method=login`) found online are all dead endpoints. - There is **automated detection** for purchase requests (`isAllowed=="N"`). Although I haven't been caught yet, if caught, it will definitely fail with exit code 7. - Mobile purchases are blocked on Saturdays and Sundays. This tool uses the PC path. - When the sales time is over, the site returns a normal page with an HTTP 200 status, but only the purchase form is missing. This case is distinguished as `[CLOSED]`. ## Development ```bash uv run pre-commit install # Install hooks (initially 1 time) uv run ruff check --fix . # Lint uv run ruff format . # Format uv run ty check # Type check uv run pytest # Test (no network access) ``` Tests do not access the actual network. httpx calls are mocked with `respx`, and socket guards enforce this protocol. Tests that miss mocking are considered failures. ``` src/klottery/ ├── endpoints.py URL·field name·constants — only this needs to be fixed when the site changes ├── dhlottery.py Site client ├── models.py Response parsing ├── flows.py Purchase·charge·inquiry assembly (shared by CLI·MCP) ├── payloads.py JSON builder (single contract for CLI --json and MCP output) ├── purchase.py Pre-purchase check (pure function) ├── session.py httpx session + cookie persistence ├── crypto.py Login RSA ├── clock.py KST time·date calculation ├── cli.py Common arguments·exit code (CLI only) ├── config.py Settings ├── errors.py Domain exceptions ├── log.py Logging·sensitive value masking ├── storage.py Atomic write to data/ └── mcp/ MCP server wiring — no domain logic here ├── server.py Assembly + exposure gate ├── tools.py Tool definitions ├── confirm.py Approval·cool-down (only contact point) ├── runtime.py Lock·error conversion·audit log └── errors.py Domain exceptions → ToolError code table scripts/ 5 entry points (4 CLI + mcp_server.py) tests/ pytest (respx mocking) data/ Cookies·history (gitignore) ``` - Work conventions: [CLAUDE.md](./CLAUDE.md) - Site API measured spec: [docs/dhlottery-api-spec.md](./docs/dhlottery-api-spec.md) - Design: [docs/2026-07-26_dhlottery-cli.md](./docs/2026-07-26_dhlottery-cli.md) · [docs/2026-07-26_klottery-mcp-server.md](./docs/2026-07-26_klottery-mcp-server.md) ## Contribution This is a personal tool, so I don't accept feature requests. If the site changes and something breaks, feel free to open an issue or PR. However, when doing so, please include actual captured requests and responses in `docs/dhlottery-api-spec.md`. Endpoints written based on guesses will not be merged. ## Disclaimer - This is a **personal tool** created for my own account. It's not intended for use with someone else's account. - It's up to the user to determine whether using this tool complies with the Donghaeng Lottery's terms of service and automation policies. Purchase responses include automated detection (`isAllowed=="N"`), and **your account may be suspended**. - **Real money is involved**. If you make a mistake when purchasing or charging, the resulting losses are your responsibility. - Lottery tickets are a **gaming product**. Automating purchases can lead to an increased number of tickets bought without your awareness. I recommend setting a limit on the number of tickets you can buy through the Donghaeng Lottery and this tool. If you're struggling with gambling issues, please call **1336** for support. - The site may change at any time, and this tool may stop working. **No guarantees are made** (AS-IS). ## License [MIT](./LICENSE)