Skip to content

About

πŸ“ˆ Learn Python by building an AI-assisted stock-market research, strategy backtesting, and paper-trading platform - one issue at a time.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Wallstreet

Tests License: MIT Python 3.12+ GitHub issues

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.

Start here

  1. Read How to learn with this repository.
  2. Look through the roadmap.
  3. Open Issue #1: Set up Python and run the project.
  4. 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.

What you will eventually build

Wallstreet learning pipeline: collect and store market data, analyze and backtest with risk checks, then simulate paper trades and review reports.

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.

Planned hourly market data

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.

Advanced research (after the foundations)

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:

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.

Prerequisites

  • 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.

First local run (macOS/Linux)

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 pytest

On 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.

Repository layout

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

Our rules

  1. Paper first. Never implement or activate real trading as part of an early learning task.
  2. Proof before prediction. Compare any strategy with a simple buy-and-hold benchmark, including fees and bad outcomes.
  3. Show your work. Preserve source URLs, timestamps, and reasons for decisions.
  4. Free infrastructure is a constraint, not a guarantee of free investing. Real trades require capital and may incur fees, taxes, and exchange costs.
  5. No hidden spending. Scheduled jobs and inference must stop at free quotas.
  6. Keep your identity private. Never commit home addresses, account numbers, credentials, or statements.
  7. Learn in small steps. Simple, correct code beats elaborate architecture.

Technologies (introduced when you need them)

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

International investing and payments

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.

A note on financial risk

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.

Community and contributing

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.

License

Licensed under the MIT License. See the license file for copyright and licensing details.

About

πŸ“ˆ Learn Python by building an AI-assisted stock-market research, strategy backtesting, and paper-trading platform - one issue at a time.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages