PolyTutor Telegram Paper Trading Lab

PolyTutor Phase 1 #8 — clean-room educational project (v0.1.0)

Telegram-style PAPER/DEMO prediction-market learning lab:

deterministic demo markets → synthetic order book → paper orders / fills / positions / PnL → educational UX.

This is NOT live trading. There is no wallet, no private key, no CLOB authenticated client, and no live mode toggle.

What this is

An independent PolyTutor clean-room lab for teaching:

1. How prediction-market order books look (best bid/ask/spread/depth)
2. How paper market and limit orders behave under simple deterministic rules
3. How portfolio cash, positions, and realized/unrealized PnL relate
4. How fail-closed allowlist authorization gates privileged actions

What this is NOT

• Not a fork or sanitized continuation of any rejected live-trading bot
• Not a Polymarket production client
• Not a profitability tool
• Not connected to blockchain wallets or authenticated exchange APIs

Quick start (local simulator — preferred)

cd polymarket-telegram-trading-lab
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
export ALLOWED_DEMO_USER_IDS=1001,1002
export STARTING_PAPER_CASH=10000
python -m polytutor_telegram

Single command:

python -m polytutor_telegram -c "/markets"
python -m polytutor_telegram -c "/buy demo-btc-100k Yes 100" --user 1001

Commands (all PAPER/DEMO labeled)

Command	Purpose
/help	Help
/markets	List synthetic markets
/market <id>	Market detail
/book <id> <outcome>	Demo order book
/portfolio	Paper cash, positions, PnL
/orders	Paper orders
/history	Paper journal
/buy <id> <outcome> <amount>	Paper market buy
/sell <id> <outcome> <shares>	Paper market sell
/limit <id> <outcome> <BUY|SELL> <shares> <price>	Paper limit
/cancel <order_id>	Cancel OPEN paper order

Privileged commands (/buy, /sell, /limit, /cancel) require an allowlisted demo user id (fail-closed).

Network

v0.1.0 uses a local Telegram-like command simulator (no bot token, offline). Real Telegram transport is intentionally absent in this release for safety.

Configuration

See .env.example. Allowed keys:

• STARTING_PAPER_CASH
• ALLOWED_DEMO_USER_IDS

Never set PRIVATE_KEY, MNEMONIC, CLOB secrets, or ENCRYPTION_KEY — they are not supported and must not appear.

Tests, quality & security

python -m compileall -q src tests scripts
ruff check src tests scripts
pytest -q
python scripts/security/check_secrets.py
python scripts/quality/check.py

.github/workflows/quality.yml runs the local quality runner on pull requests. Security gates remain in .github/workflows/security.yml.

Docs

• DISCLAIMER.md
• SECURITY.md
• CLEAN_ROOM.md
• docs/architecture.md
• docs/paper-trading.md
• docs/authorization.md

License

MIT — see LICENSE.