CryptoCandyFarm Automation

Public-safe multi-session automation runner for the Telegram mini app behind @cryptocandyfarm_bot.

This repository is based on a real working VPS runner and keeps the core behavior intact while removing local runtime artifacts, private credentials, and environment-specific state.

Why this repo exists

This repo is meant to show a practical automation architecture, not just dump code. It preserves the useful parts of the real runner:

• Telethon-based bootstrap from Telegram sessions
• authenticated game/task execution
• on-demand Turnstile solving only when the API asks for it
• per-session state, logs, retry, alerting, and scheduler patterns

Current status

Current maturity: public-safe showcase of a production-style runner

What that means:

• core multi-session runner logic is present
• dynamic scheduling, retry/backoff, and optional alerting are preserved
• public examples are sanitized
• live sessions, cookies, and secrets are intentionally excluded

Highlights

• multi-session runner with isolated failures and retry backoff
• scheduler-aware looping based on per-session next due time
• Turnstile solving only when the upstream API explicitly requires it
• optional Telegram alerting for failures, recoveries, and periodic summaries
• public-safe packaging with runtime state, cookies, logs, and secrets excluded from the repository

Features

• Retrieves tgWebAppData from a Telegram Mini App via Telethon session files
• Authenticates against the CryptoCandyFarm API
• Stores per-session HTTP cookies for reuse
• Reads game state and harvests plants that are ready
• Fetches tasks and completes pending ones
• Optional free gift claiming from game_state.gifts
• Optional auto-heal for sick plants via fertilizer usage
• Optional auto-buy fertilizer flow with session allowlists and default-off policy
• Uses a Turnstile solver only when the API explicitly reports needsCaptcha=true
• Supports multi-session execution
• Uses a dynamic per-session scheduler instead of relying only on a fixed global sweep
• Writes structured logs and machine-readable status files
• Includes per-session retry and backoff so one failure does not stop the full runner
• Optional Telegram alerts for runner lifecycle, solver health, repeated failures, recoveries, and periodic summaries

Use cases

• studying a practical Telegram Mini App automation runner
• learning how to combine session bootstrap, HTTP execution, optional captcha solving, and scheduler-driven looping
• using a public-safe reference for multi-session worker design with logs, status files, and alerts
• adapting the architecture to a private runner with your own credentials and deployment setup

Architecture overview

Detailed flow diagrams live in docs/FLOWS.md.

Feature matrix

Area	Component	Execution model	Current status
Bootstrap	Telethon session -> Mini App launch	Telegram client automation	Included
Game loop	harvest + tasks + auth reuse	HTTP runner	Included
Captcha	Turnstile solver only when needed	External solver integration	Included
Multi-session	all sessions with spacing/backoff	Runner orchestration	Included
Scheduler	next due based wake-up	Internal runner logic	Included
Observability	logs + per-session status files	Local runtime outputs	Included
Alerting	runner lifecycle / failure / summaries	Optional Telegram notifier	Included

Demo preview

Screenshots / samples

Status sample

Alert summary sample

Sanitized file examples:

• examples/sample-status.json
• examples/sample-run.log

Tech stack

• Python 3.10+
• Telethon for Telegram session access
• Requests for HTTP/API interaction
• JSON file state for lightweight runtime persistence
• Optional Telegram Bot API notifications

Repository layout

• cryptocandyfarm_auto.py - main runner
• telegram_alerts.py - Telegram alerting helper
• start_cryptocandyfarm.sh - long-running launcher for screen, tmux, or systemd-style wrappers
• requirements.txt - Python dependencies
• .env.example - required and optional environment variables
• config/alerting.example.json - example Telegram alert configuration
• docs/ - quickstart, deployment guidance, FAQ, flow notes, and visuals
• examples/ - sanitized sample status and log outputs
• sessions/ - optional local Telethon session directory, intentionally gitignored
• logs/ - runtime logs, intentionally gitignored
• state/ - cookies, status, and alert state, intentionally gitignored

Compatibility

• Tested for repository CI on Python 3.10, 3.11, and 3.12
• Intended for Linux or other environments where Telethon session files are available locally
• Best suited for VPS or long-running terminal sessions when used in loop mode

Requirements

• Python 3.10+
• A Telegram API ID and API hash from your own Telegram developer app
• At least one authorized Telethon .session file
• Optional Turnstile solver endpoint compatible with the configured API shape

Quick start

Install dependencies:

git clone https://github.com/IndraLawliet13/cryptocandyfarm-automation.git
cd cryptocandyfarm-automation
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
chmod +x start_cryptocandyfarm.sh

Prepare config:

cp .env.example .env
cp config/alerting.example.json config/alerting.local.json

Run a quick smoke test:

set -a
source .env
set +a
python3 cryptocandyfarm_auto.py --list-sessions
python3 cryptocandyfarm_auto.py --all-sessions --auto-captcha --verbose

Run the full looping launcher:

./start_cryptocandyfarm.sh

Docs map

• docs/QUICKSTART.md
• docs/DEPLOYMENT.md
• docs/FLOWS.md
• docs/FAQ.md

Configuration

Copy .env.example and provide your own values:

cp .env.example .env

Required variables:

• CRYPTOCANDYFARM_TELEGRAM_API_ID
• CRYPTOCANDYFARM_TELEGRAM_API_HASH

Useful optional variables:

• CRYPTOCANDYFARM_BOT_USERNAME default: cryptocandyfarm_bot
• CRYPTOCANDYFARM_BASE_URL default: https://cryptocandyfarm.xyz
• CRYPTOCANDYFARM_SESSIONS_DIR default behavior: use ./sessions

To expose the variables in your shell:

set -a
source .env
set +a

Telegram alerting

Alerting is optional.

Example local config:

cp config/alerting.example.json config/alerting.local.json

Supported settings:

• telegram_enabled
• telegram_bot_token
• telegram_chat_id
• summary_interval_seconds
• failure_alert_thresholds
• solver_healthcheck_path

Environment variables can override the JSON config:

• CRYPTOCANDYFARM_TELEGRAM_ENABLED
• CRYPTOCANDYFARM_TELEGRAM_BOT_TOKEN
• CRYPTOCANDYFARM_TELEGRAM_CHAT_ID
• CRYPTOCANDYFARM_SUMMARY_INTERVAL_SECONDS
• CRYPTOCANDYFARM_FAILURE_ALERT_THRESHOLDS

Send a test alert:

python3 cryptocandyfarm_auto.py --test-telegram

Usage

List discovered sessions:

python3 cryptocandyfarm_auto.py --list-sessions

Run one session once:

python3 cryptocandyfarm_auto.py --session your_session_name --auto-captcha --verbose

Run one session with gifts + auto-heal:

python3 cryptocandyfarm_auto.py --session your_session_name --auto-captcha --claim-gifts --auto-heal --verbose

Run all discovered sessions once:

python3 cryptocandyfarm_auto.py --all-sessions --auto-captcha

Run continuously:

./start_cryptocandyfarm.sh

Enable auto-buy fertilizer only for selected sessions:

python3 cryptocandyfarm_auto.py --all-sessions --loop --auto-captcha --claim-gifts --auto-heal --auto-buy-fertilizer --auto-buy-fertilizer-sessions your_session_name

Print saved status files:

python3 cryptocandyfarm_auto.py --status

Output / behavior

Runtime data is intentionally local-only and is written under:

• logs/runner.log
• logs/sessions/<session>.log
• state/status/<session>.json
• state/cookies/
• state/alerts/

Default runner behavior:

• discovers sessions from --sessions-dir, then CRYPTOCANDYFARM_SESSIONS_DIR, then ./sessions
• authenticates each account first
• reads game state
• can claim free gifts when --claim-gifts is enabled
• can auto-heal sick plants when --auto-heal is enabled
• can auto-buy fertilizer when --auto-buy-fertilizer is enabled, but only for sessions allowed by --auto-buy-fertilizer-sessions
• harvests every plant in ready state
• fetches tasks
• completes up to 2 pending tasks per cycle per account by default
• schedules each session from plant/task state so the next due account wakes first
• keeps other sessions running even if one session fails
• applies escalating retry backoff for failing sessions

FAQ / caveats

Does this repo include real sessions or cookies? No. Session files, cookies, logs, and live runtime state are intentionally excluded.

When does the Turnstile solver run? Only when the API reports needsCaptcha=true and you run with --auto-captcha.

Can I use this as-is on my VPS? Treat it as a public-safe reference implementation. You still need your own Telegram API credentials, your own authorized Telethon sessions, and your own solver/runtime setup.

Operational notes

• Runtime cookies and status are stored under state/
• Per-session logs are stored under logs/sessions/
• Status files include scheduling hints like next_delay_seconds, next_due_at, and next_reason
• Auto-buy fertilizer is intentionally a default-off policy because it spends in-game balance; enable it only with clear allowlists
• The script expects valid Telethon session files and will fail authentication if they are not authorized
• External changes in Telegram, the target API, network quality, or captcha handling can still break automation temporarily

Scope and limitations

• This repository focuses on the automation runner itself, not on shipping ready-to-run account data
• Success still depends on valid Telegram sessions, upstream API stability, and a working captcha solver when needed
• External platform changes can break task flows without any code changes in this repository
• Auto-buy fertilizer is intentionally guarded because it spends in-game balance

Public roadmap

• add a dedicated operations/runbook doc for common manual recovery flows
• add more sanitized visuals for alerting and per-session state transitions
• document safer patterns for longer unattended deployment and log rotation review
• add a small architecture decision log for notable implementation choices

Security and publishing notes

This repository intentionally does not include:

• private Telethon session files
• cookies or saved runtime state
• local runner logs
• Telegram bot tokens or chat IDs used in production
• hardcoded Telegram API credentials from the original host

You must provide your own credentials and local runtime files before running it.

License status

This repository now includes a LICENSE file that explicitly states no open-source license has been granted yet. That is intentional. It removes ambiguity without guessing a permissive or copyleft license choice on behalf of the owner.