Learn Python by building an honest, AI-assisted stock-market research and paper-trading app, one GitHub issue at a time.
Wallstreet is an open-source Python learning project. It is not a ready-made trading bot, an investment recommendation service, or a promise of passive income. The goal is to understand the data, write the Python yourself, test every decision, and eventually simulate an entire portfolio safely.
Current status: learning scaffold only. No live brokerage connection, real-money order placement, or withdrawals are implemented. Paper trading comes after research, backtesting, and risk controls.
- Read How to learn with this repository.
- Look through the roadmap.
- Open Issue #1: Set up Python and run the project.
- Finish one issue, run its tests, and leave yourself notes before starting the next.
Each issue explains why the feature exists, what Python concepts you will practice, which files to change, a small example, tests to write, and how to know you are done. You are supposed to write the feature code yourself. Ask an AI assistant for explanations, examples, and code reviewsβnot a complete solution unless you change your mind. The roadmap links to every lesson.
The diagram is also available as an editable SVG. The PNG is used here because GitHub's mobile app does not consistently render Mermaid diagrams.
The pipeline always allows HOLD: the safest system often makes no trade. Models make uncertain forecasts, not guarantees.
Wallstreet's existing price collector lesson (#6) now teaches hourly (1Hour) and daily (1Day) stock-price bars from Alpaca's free IEX feed. The API connection is not implemented yetβthis is a guided Python exercise. Issue #5 covers authenticated requests, #9 validates incomplete/stale bars, and #10 schedules best-effort hourly collection through GitHub Actions. The IEX feed represents one exchange, not all US market trades; hourly polling does not provide continuous streaming prices.
The advanced learning tracks extend Wallstreet into a market movement analyzer, a regime-aware strategy laboratory, and an AI research agent that proposes algorithm improvements. Start these only after the prerequisites in their issues:
- Market movement analyzer β Issues #23β27: explain trend, volatility, abnormal volume, regime changes, sector breadth, and the effects of published news.
- Adaptive strategy lab β Issues #28β33: evaluate next-session probabilities, regime-specific rules, position sizing, honest walk-forward tests, and competing paper strategies.
- AI-guided improvement β Issues #34β39: produce evidence packs, let AI propose configuration or code changes on a branch, test them independently, and create pull requests for human review.
Read the adaptive-strategy policy before implementing any automated AI changes. The agent may propose and test changes; it may not self-approve, merge, bypass risk checks, activate live trading, or withdraw money.
- A Mac, Linux, or Windows computer with Python 3.12 or newer.
- A text editor such as VS Code.
- Git and a GitHub account.
- Curiosity and patience. Prior Python experience is not required.
git clone https://github.com/Thavarshan/wallstreet.git
cd wallstreet
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e '.[dev]'
python -m wallstreet
python -m pytestOn Windows, activate with .venv\Scripts\activate. If python is not found, try python3. The package currently prints a welcome message and runs a tiny starter test; subsequent issues turn it into a real app.
| Path | Purpose |
|---|---|
src/wallstreet/ |
Python package you will develop |
tests/ |
Small, repeatable automated tests |
docs/ |
Learning guide, roadmap, glossary, architecture |
issues/ |
Markdown copies of the planned learning issues |
.github/workflows/ |
Continuous-integration checks, later scheduled jobs |
.env.example |
Placeholder names for configuration, never actual secrets |
CONTRIBUTING.md |
How to help without taking away the learning experience |
SECURITY.md |
How to report vulnerabilities privately |
- Paper first. Never implement or activate real trading as part of an early learning task.
- Proof before prediction. Compare any strategy with a simple buy-and-hold benchmark, including fees and bad outcomes.
- Show your work. Preserve source URLs, timestamps, and reasons for decisions.
- Free infrastructure is a constraint, not a guarantee of free investing. Real trades require capital and may incur fees, taxes, and exchange costs.
- No hidden spending. Scheduled jobs and inference must stop at free quotas.
- Keep your identity private. Never commit home addresses, account numbers, credentials, or statements.
- Learn in small steps. Simple, correct code beats elaborate architecture.
| Stage | Technology | Reason |
|---|---|---|
| Foundations | Python, venv, pytest |
Understand code and tests |
| Storage | sqlite3 |
A free database built into Python |
| Data collection | HTTP requests, RSS, official APIs | Repeatable datasets |
| Analysis | pandas and simple statistics |
Examine price patterns |
| AI (optional) | Free inference or local baseline | Classify news; don't trust it to decide trades |
| Automation | GitHub Actions | Run tasks without your laptop on |
| Paper brokerage | Official paper-trading API | Test behavior without real money |
| Web view | Cloudflare Workers/D1 when warranted | Low-cost read-only dashboards |
Future broker research should verify the applicable residency, tax, account-eligibility, deposit, and withdrawal rules for each jurisdiction. Payment services are not stock brokers and cannot place securities orders. No integration should bypass identity checks or account restrictions.
See the later broker-readiness issue before connecting anything live.
No strategy is risk-free. A forecast can be wrong, a stop can execute at a worse price, and a paper account can look better than real trading. Use money you can afford to lose only after separate research and authorization. This repository is educational, not financial advice.
Wallstreet is open source and welcomes bug reports, documentation improvements, constructive reviews, and Python learning questions. Please read the contribution guide, Code of Conduct, and support guide. Use the issue templates to make your question or proposal easy to understand.
This repository is designed for hands-on learning: contributors and AI agents should help explain and review, not silently complete every lesson. See AGENTS.md for the expectations placed on coding assistants. Significant changes are recorded in the changelog.
For vulnerabilities or accidental secret exposure, follow the security policy rather than opening a public issue.
Licensed under the MIT License. See the license file for copyright and licensing details.
