{"id":30454456,"url":"https://github.com/didac-crst/mockexchange","last_synced_at":"2026-05-02T17:32:06.957Z","repository":{"id":308896396,"uuid":"1034479913","full_name":"didac-crst/mockexchange","owner":"didac-crst","description":"Stateless, deterministic, no-risk spot-exchange emulator for testing and debugging trading bots — fake losses, real skills.","archived":false,"fork":false,"pushed_at":"2025-08-18T10:24:48.000Z","size":1793,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-18T10:26:53.863Z","etag":null,"topics":["api","backtesting","ccxt","crypto","cryptocurrency","docker","market-data","paper-trading","redis","rest-api","streamlit","trading-bot","trading-platform","trading-simulator","valkey"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/didac-crst.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-08T13:06:29.000Z","updated_at":"2025-08-18T10:19:46.000Z","dependencies_parsed_at":"2025-08-08T15:27:06.751Z","dependency_job_id":"c526b56e-b80b-454f-ac59-e6b9057a748b","html_url":"https://github.com/didac-crst/mockexchange","commit_stats":null,"previous_names":["didac-crst/mockexchange"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/didac-crst/mockexchange","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/didac-crst%2Fmockexchange","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/didac-crst%2Fmockexchange/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/didac-crst%2Fmockexchange/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/didac-crst%2Fmockexchange/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/didac-crst","download_url":"https://codeload.github.com/didac-crst/mockexchange/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/didac-crst%2Fmockexchange/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271755400,"owners_count":24815396,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-23T02:00:09.327Z","response_time":69,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","backtesting","ccxt","crypto","cryptocurrency","docker","market-data","paper-trading","redis","rest-api","streamlit","trading-bot","trading-platform","trading-simulator","valkey"],"created_at":"2025-08-23T16:01:42.730Z","updated_at":"2026-05-02T17:32:06.919Z","avatar_url":"https://github.com/didac-crst.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MockExchange Suite \u003c!-- omit in toc --\u003e\n\n[![Python](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Docker](https://img.shields.io/badge/docker-available-blue.svg)](https://www.docker.com/)\n[![Poetry](https://img.shields.io/badge/poetry-managed-orange.svg)](https://python-poetry.org/)\n[![Tests](https://img.shields.io/badge/tests-available-green.svg)](https://github.com/didac-crst/mockexchange)\n[![Status](https://img.shields.io/badge/status-active-success.svg)](https://github.com/didac-crst/mockexchange)\n[![Code Quality](https://img.shields.io/badge/code%20quality-maintained-blue.svg)](https://github.com/didac-crst/mockexchange)\n[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-red.svg)](https://github.com/astral-sh/ruff)\n[![Type checking: mypy](https://img.shields.io/badge/type%20checking-mypy-blue.svg)](https://mypy-lang.org/)\n![CodeRabbit Pull Request Reviews](https://img.shields.io/coderabbit/prs/github/didac-crst/mockexchange)\n\n**_Trade without fear, greed, or actual money — because every fake loss is a real step up._**\n\nThis repository contains the full **MockExchange** paper-trading platform:\n- **MockX Engine** – Matching engine, portfolio tracking, and API layer.\n- **MockX Periscope** – Streamlit-based dashboard for visualizing portfolio and orders.\n- **MockX Oracle** – Price feed service (e.g., Binance via CCXT → Valkey).\n- [*MockX Gateway** (external repo)](https://github.com/didac-crst/mockexchange-gateway) – Lightweight Python wrapper for the MockX Engine API, providing a ccxt-style interface for bots and scripts.\n\n---\n\n## Table of Contents \u003c!-- omit in toc --\u003e\n\n- [TL;DR](#tldr)\n- [📜 Story](#-story)\n- [✨ Core Features](#-core-features)\n- [🗺 Architecture \u0026 Ecosystem](#-architecture--ecosystem)\n- [📦 Packages in this Monorepo](#-packages-in-this-monorepo)\n- [🚀 Quick Start](#-quick-start)\n  - [Prerequisites](#prerequisites)\n  - [1. Clone and Setup](#1-clone-and-setup)\n  - [2. Start All Services](#2-start-all-services)\n  - [3. Access Your Services](#3-access-your-services)\n  - [Alternative: Manual Service Management](#alternative-manual-service-management)\n  - [Development Setup](#development-setup)\n- [🚀 How we ship](#-how-we-ship)\n  - [Standard Workflow (Recommended)](#standard-workflow-recommended)\n  - [Release Branch Workflow (For Complex Releases)](#release-branch-workflow-for-complex-releases)\n  - [Release Branch Script Features](#release-branch-script-features)\n  - [When to use Release Branches](#when-to-use-release-branches)\n- [📦 Install from GitHub tags](#-install-from-github-tags)\n  - [Oracle](#oracle)\n  - [Engine](#engine)\n  - [Periscope](#periscope)\n- [📚 Examples](#-examples)\n  - [Common Use Cases](#common-use-cases)\n  - [Order Generator](#order-generator)\n- [🔧 Environment Configuration](#-environment-configuration)\n  - [Quick Setup](#quick-setup)\n  - [Key Configuration Sections](#key-configuration-sections)\n    - [**Valkey (Database)**](#valkey-database)\n    - [**Oracle (Price Feeds)**](#oracle-price-feeds)\n    - [**Engine (API)**](#engine-api)\n    - [**Periscope (Dashboard)**](#periscope-dashboard)\n  - [Benefits of Centralized Configuration](#benefits-of-centralized-configuration)\n- [🗂 Monorepo Structure](#-monorepo-structure)\n- [📚 Documentation](#-documentation)\n  - [**Core Documentation**](#core-documentation)\n  - [**Project Documentation**](#project-documentation)\n  - [**External Resources**](#external-resources)\n- [🪪 License](#-license)\n\n---\n\n## TL;DR\n\n- Stateless, deterministic, no-risk spot-exchange emulator.\n- ccxt-compatible API — test bots without touching live markets.\n- Externalized price feed (MockX Oracle) so you can swap sources.\n- Companion Streamlit dashboard (MockX Periscope) for monitoring.\n- Full CLI + REST API + Docker support.\n\n---\n\n## 📜 Story\n\n\u003e It was **2013**, and Bitcoin had just hit a jaw-dropping **$300**.\n\u003e Someone in our old engineering WhatsApp group brought it up.\n\u003e I asked innocently, *“What’s that?”*\n\u003e\n\u003e The response came instantly, dripping with confidence:\n\u003e *“You’re too late — this bubble is about to burst…”*\n\u003e\n\u003e Which, in hindsight, was probably the most confidently\n\u003e wrong (and overly cautious) financial advice I’ve ever received.\n\nBut something about it intrigued me. I didn’t fully understand it.\nI didn’t even think it would work — and yet, I bought in.\nJust **2/3 of a BTC**, about **180 €**, which, at the time, I mentally wrote off as *“money I’ll never see again.”*\nSpoiler: it was the **best terrible financial decision** I’ve ever made.\n\nI held.\nAnd held.\nAnd held some more.\n\nThen came **2017** — the year of Lambos, moon memes, and FOMO-induced insomnia.\nI began checking prices at night before bed, and again first thing in the morning —\nnot for fun, but to confirm whether I was now rich… or still stuck working 9 to 5.\n\nThis, of course, led me to the **classic rookie move**: diversification.\nI dove into altcoins with names like **LTC**, **TROY**, and others I’ve repressed like a bad haircut from high school.\nLet’s just say: they didn’t go to the moon — they dug a tunnel.\n\nDecision after decision, I watched my gains **evaporate in slow motion**.\nEventually, I realized I needed support — not from a financial advisor (they’d only\nremind me of my poor decisions), but from something more aligned with my goals — not theirs.\n\n**Something logical**.\nEmotionless.\nFree from fear and greed.\nUnimpressed by sudden price spikes or Twitter hype.\nA system that won’t panic sell or chase pumps.\n\nI wanted an intelligent system that could make decisions based on **data**, not **dopamine**.\nSomething that would just execute the plan, no matter how boring or unsexy that plan was.\nSomething more disciplined than I’d ever been — able to stay locked on a single task for hours, without fatigue, distraction, or the urge to check the news.\n\nIn short, I wanted to build a **trader with no feelings** —\nlike a **psychopath**, but helpful.\n\nSo in **2020**, full of optimism and free time, I enrolled in an **AI-for-trading** program.\nI was ready to automate the pain away.\n\nThen… I became a dad.\n\nSuddenly, my trading ambitions were replaced with diapers, sleep deprivation,\nand learning the fine art of **negotiating with toddlers**.\nNeedless to say, the bot went on standby — alongside my hobbies, ambitions, and most adult-level reasoning.\n\nFast forward to **2024**. The kids sleep (sometimes), and my curiosity roared back to life.\nI decided it was time to build — **for real**.\nNot to get rich — but because this is what I do for fun:\nconnect dots, explore computer science, study markets, and challenge my past self\nwith fewer emotional trades and more intelligent systems.\n\nBut ideas need hardware.\nSo I bought my first Raspberry Pi.\nBecause if I was going to burn time, I wasn’t about to burn kilowatts.\nI needed something that could run 24/7 without turning my electricity bill into a second mortgage.\nResilient, quiet, efficient — like a monk with a TPU, ready to meditate on market patterns in silence for as long as it takes.\nIt wasn’t much, but it was enough to get started.\n\nFrom there, the system began to grow — and spiral.\nScraping prices in real time, keeping databases efficient, aggregating data, archiving old data,\nwriting little scripts that somehow become immortal zombie processes needing to be killed by hand...\nI genuinely didn’t expect it to be so much.\n\nAnd yet — I like it.\nThis is how I relax: designing systems no one asked for, solving problems I created myself,\nand picking up strange new skills in the process — the kind you never set out to learn, but somehow end up mastering.\n\nWhich brings us to **2025**, and **MockExchange**:\na stateless, deterministic, no-risk spot-exchange emulator that speaks fluent **ccxt**,\npretends it’s real, and stores the last price-tick, balance and order in **Valkey** (aka Redis) —\ninstead of touching live markets — so you can test, dry-run, and debug your bot\nwithout risking a single satoshi.\n\nNo more fear.\nNo more “should I have bought?” or “why did I sell?”\nJust logic, fake orders, and enough tooling to safely build the thing\nthat trades smarter than I did.\n\n---\n\n## ✨ Core Features\n\n- 🧩 **Modular architecture** — Engine, Periscope, Oracle, and Gateway can run independently or together.\n- 🔌 **Pluggable components** — swap price feeds, dashboards, or clients without touching the core.\n- 🌐 **ccxt-inspired interface** — follows familiar trading API patterns to simplify bot integration.\n- 📊 **Full visibility** — Periscope dashboard for live monitoring of balances, orders, and performance metrics.\n- 🔮 **Realistic market simulation** — Oracle injects live exchange prices into a safe, risk-free trading environment.\n- 🚀 **Ready for production** — Dockerized services with pinned versions, path-filtered CI, and clear interface boundaries.\n- 🛠 **Developer-friendly** — One-command setup, pre-commit hooks, comprehensive testing, and linting.\n\n---\n\n## 🗺 Architecture \u0026 Ecosystem\n\n```mermaid\nflowchart TB\n    subgraph Clients\n        periscope[\"MockX Periscope\u003cbr/\u003e(Streamlit UI)\"]\n        bot[\"Trading Bot / Script\"]\n    end\n\n    subgraph Infra\n        redis[(\"Valkey / Redis\")]\n        engine[\"MockX Engine 📈\"]\n    end\n\n    subgraph External\n        binance[\"Binance (Live Market Data)\"]\n    end\n\n    bot --\u003e|ccxt-like wrapper| gateway[\"MockX Gateway 🛡 (external)\"]\n    periscope --\u003e|HTTP/REST| engine\n    gateway --\u003e|HTTP/REST| engine\n\n    engine --\u003e redis\n\n    oracle[\"MockX Oracle 🔮\u003cbr/\u003e(ccxt → Redis)\"] --\u003e redis\n    binance --\u003e|ccxt| oracle\n\n    %% Color styling for important components\n    style engine fill:#1976d2,color:#ffffff\n    style periscope fill:#7b1fa2,color:#ffffff\n    style oracle fill:#388e3c,color:#ffffff\n    style redis fill:#f57c00,color:#ffffff\n    style gateway fill:#d32f2f,color:#ffffff\n```\n\n---\n\n## 📦 Packages in this Monorepo\n\n| Package             | Path                  | Description                                       | README                                           |\n| ------------------- | --------------------- | ------------------------------------------------- | ------------------------------------------------ |\n| **MockX Valkey**    | `packages/valkey/`    | Redis-compatible database for data persistence.   | [Valkey README](packages/valkey/README.md)       |\n| **MockX Oracle**    | `packages/oracle/`    | Market data feeder (ccxt → Valkey/Redis).         | [Oracle README](packages/oracle/README.md)       |\n| **MockX Engine**    | `packages/engine/`    | Core engine (core/), API layer (api/), CLI tools. | [Engine README](packages/engine/README.md)       |\n| **MockX Periscope** | `packages/periscope/` | Streamlit dashboard for portfolio and orders.     | [Periscope README](packages/periscope/README.md) |\n\nRelated (external):\n- **MockX Gateway** – https://github.com/didac-crst/mockexchange-gateway\n    Minimal ccxt-style Python client to interact with the Engine API (install via `pip` or `poetry`).\n\n---\n\n## 🚀 Quick Start\n\n### Prerequisites\n- **Docker** and **Docker Compose** installed\n- **Git** for cloning the repository\n\n### 1. Clone and Setup\n```bash\n# Clone the repository\ngit clone https://github.com/your-username/mockexchange.git\ncd mockexchange\n\n# Setup environment (first time only)\ncp .env.example .env\n# Edit .env if needed (defaults work for most cases)\n```\n\n### 2. Start All Services\n```bash\n# Start all services in parallel (default)\nmake start\n\n# Or start services in dependency order (recommended for first-time setup)\nmake start-sequential\n```\n\n**What this launches:**\n- **MockX Valkey** (Redis-compatible database) on port 6379\n- **MockX Oracle** (price feed service)\n- **MockX Engine** (trading API) on port 8000\n- **MockX Periscope** (dashboard) on port 8501\n\n### 3. Access Your Services\n- **📊 Dashboard**: http://localhost:8501\n- **🔌 API**: http://localhost:8000\n- **📖 API Docs**: http://localhost:8000/docs\n- **📋 Logs**: `make logs`\n\n### Alternative: Manual Service Management\nIf you prefer to start services individually or connect to external services:\n\n```bash\n# Start services in order (recommended)\nmake start-valkey      # Database first\nmake start-oracle      # Price feed\nmake start-engine      # Trading API\nmake start-periscope   # Dashboard\n\n# Or stop/restart individual services\nmake stop-engine       # Stop only the API\nmake restart-oracle    # Restart price feed\nmake logs-periscope    # View dashboard logs\n\n# Connect to external services (update .env first)\n# VALKEY_HOST=192.168.1.100\n# API_URL=http://192.168.1.101:8000\nmake start-engine      # Engine connects to external Valkey\nmake start-periscope   # Periscope connects to external Engine\n```\n\n### Development Setup\nFor contributors and developers:\n\n```bash\n# 🚀 Complete Development Cycle (Recommended)\nmake dev              # Install deps + format + lint + type-check + test\n\n# 🧪 Testing\nmake test             # Run all unit tests\nmake test-integration # Run integration tests (requires running services)\nmake integration      # Fresh restart + integration tests (no cache)\nmake integration-full # Full dev cycle + integration tests\n\n# 🔧 Code Quality\nmake format           # Format code with Ruff\nmake lint             # Run linting with Ruff\nmake type-check       # Run type checking with MyPy (smart filtering)\n\n# 🐳 Service Management\nmake start            # Start all services\nmake stop             # Stop all services\nmake restart          # Restart all services\nmake restart-no-cache # Restart with fresh builds (no cache)\nmake status           # Show service status\n\n# 📊 Logs\nmake logs             # All service logs\nmake logs-engine      # Engine logs only\nmake logs-oracle      # Oracle logs only\nmake logs-periscope   # Dashboard logs only\nmake logs-valkey      # Database logs only\n\n# 🏷️ Release Management\nmake release-branch   # Create release branch (interactive)\nmake version          # Show current version and tags\n\n# 🔗 GitHub PR Tools\nmake export-pr-comments PR=123  # Export PR comments to JSON for LLM analysis\nmake analyze-pr-comments PR=123 # Analyze all comments and generate LLM prompt\nmake analyze-pr-comments-latest PR=123 # Analyze only latest review (recommended)\nmake export-and-analyze-pr PR=123 # Export and analyze all comments in one command\nmake export-and-analyze-pr-latest PR=123 # Export and analyze latest review only (recommended)\n```\nmake logs-valkey       # Database logs only\nmake logs-engine       # Engine logs only\nmake logs-oracle       # Oracle logs only\nmake logs-periscope    # Dashboard logs only\n\n# Check service status\nmake status            # Show all service statuses\n\n### 🎯 Enhanced Development Workflow\n\nThe MockExchange development workflow has been enhanced with comprehensive automation:\n\n#### **🚀 One-Command Development Cycle**\n```bash\nmake dev  # Does everything: install → format → lint → type-check → test\n```\n- **Installs dependencies** (Poetry + pre-commit)\n- **Formats code** (Ruff)\n- **Runs linting** (Ruff)\n- **Type checking** (MyPy with smart filtering)\n- **Runs tests** (All unit tests)\n\n#### **🧪 Comprehensive Testing**\n```bash\nmake integration      # Fresh restart + integration tests\nmake integration-full # Full dev cycle + integration tests\n```\n- **Fresh environment**: No cached artifacts\n- **Real integration**: Tests against running services\n- **Complete validation**: Perfect for pre-release testing\n\n#### **🔧 Smart Type Checking**\n```bash\nmake type-check  # MyPy with smart filtering\n```\n- **Focuses on business logic** (ignores framework limitations)\n- **Zero false positives** (no framework noise)\n- **Catches real type issues** in your code\n\n#### **🐳 Service Management**\n```bash\nmake restart-no-cache  # Fresh builds for debugging\nmake logs-engine       # Service-specific logs\n```\n- **Individual service control**\n- **Fresh rebuilds when needed**\n- **Easy log access**\n\n#### **🔗 GitHub PR Tools**\n```bash\nmake export-and-analyze-pr-latest PR=123  # One-shot latest review analysis (recommended)\nmake export-and-analyze-pr PR=123         # One-shot all reviews analysis\nmake export-pr-comments PR=123            # Export PR comments to JSON\nmake analyze-pr-comments-latest PR=123    # Analyze only latest review\nmake analyze-pr-comments PR=123           # Analyze all reviews\n```\n- **Export CodeRabbit comments** for AI analysis\n- **Latest review focus** - Avoid LLM confusion from multiple reviews\n- **Organized structure** in `scripts/github-pr-tools/`\n- **Cursor integration** ready for LLM analysis\n- **One-shot workflow** for quick analysis\n- **Requires GitHub token** (set in `scripts/github-pr-tools/.env`)\n\n**Setup:**\n```bash\n# Create scripts/github-pr-tools/.env with your GitHub token\necho \"GITHUB_TOKEN=your_github_token_here\" \u003e scripts/github-pr-tools/.env\n\n# One-shot latest review analysis (recommended - less confusion for LLM)\nmake export-and-analyze-pr-latest PR=123\n\n# Use with Cursor\n# Open scripts/github-pr-tools/output/pr_123_comments_latest_review_llm_prompt.txt in Cursor\n# Or copy-paste the content into Cursor's chat\n```\n\n## 🚀 How we ship\n\n### Standard Workflow (Recommended)\n1. Create a feature branch, implement changes.\n2. Open a Pull Request (PR). CI runs tests and lint.\n3. When green, merge into `main`.\n4. **Create a release**:\n   - **GitHub UI** (Recommended): **Releases** → *Draft a new release* → Tag `vX.Y.Z` → Publish\n   - **CLI**:\n     ```bash\n     git checkout main \u0026\u0026 git pull --ff-only\n     git tag -a vX.Y.Z -m \"MockExchange vX.Y.Z\"\n     git push origin vX.Y.Z\n     ```\n\nCI will run on the tag to validate the release commit.\n\n### Release Branch Workflow (For Complex Releases)\nFor more control or when you need to freeze changes for QA/testing:\n\n1. Create feature branch → implement changes\n2. Open PR → CI runs tests\n3. **Create release branch** (automated):\n   ```bash\n   # Interactive mode (recommended)\n   make release-branch\n\n   # Direct mode\n   ./scripts/create-release-branch.sh patch    # 0.1.0 → 0.1.1\n   ./scripts/create-release-branch.sh minor    # 0.1.0 → 0.2.0\n   ./scripts/create-release-branch.sh major    # 0.1.0 → 1.0.0\n\n       # Preview what would happen\n    ./scripts/create-release-branch.sh patch --dry-run\n    ```\n4. **Push the release branch**: `git push -u origin release/vX.Y.Z`\n5. **Tag the release branch**: `git tag -a vX.Y.Z -m \"Release vX.Y.Z\"`\n6. **Push tag**: `git push origin vX.Y.Z`\n7. **Merge to main** after release is validated\n\n### Release Branch Script Features\n\nThe `scripts/create-release-branch.sh` script provides:\n\n- **🔄 Automatic version calculation** - Fetches latest tags and calculates next version\n- **✅ Git validation** - Checks branch, working directory, and remote sync\n- **🛡️ Safety features** - Dry-run mode, confirmations, error handling\n- **🎨 User-friendly** - Colored output, clear instructions, help text\n- **📋 Next steps** - Shows what to do after branch creation\n\n**Requirements:**\n- Must be on `main` branch (or confirm override)\n- Working directory must be clean\n- Remote tags must be up to date\n\n**Examples:**\n```bash\n# See what would happen\n./scripts/create-release-branch.sh patch --dry-run\n\n# Create a patch release branch\n./scripts/create-release-branch.sh patch\n\n# Interactive mode with menu\nmake release-branch\n```\n\n### Quick Reference: Common Release Commands\n\n```bash\n# Check current version and tags\nmake version\n\n# Create release branch (interactive)\nmake release-branch\n\n# Create release branch (direct)\n./scripts/create-release-branch.sh patch\n\n# Create and push a tag\ngit tag -a v0.1.1 -m \"Release v0.1.1\"\ngit push origin v0.1.1\n\n# Deploy specific version\nVERSION=v0.1.1 docker-compose up -d\n```\n\n### When to use Release Branches\n\nUse a release branch when you need to:\n- **Freeze changes** for QA/testing while `main` continues development\n- **Cherry-pick hotfixes** onto a stable release candidate\n- **Maintain multiple release lines** (e.g., v1.x and v2.x simultaneously)\n\n**Default workflow**: Tag directly on `main` for simplicity.\n\n## 📦 Install from GitHub tags\n\nYou can install any service directly from a Git tag:\n\n#### Oracle\n```bash\npip install \"git+https://github.com/didac-crst/mockexchange.git@vX.Y.Z#subdirectory=packages/oracle\"\n```\n\n#### Engine\n```bash\npip install \"git+https://github.com/didac-crst/mockexchange.git@vX.Y.Z#subdirectory=packages/engine\"\n```\n\n#### Periscope\n```bash\npip install \"git+https://github.com/didac-crst/mockexchange.git@vX.Y.Z#subdirectory=packages/periscope\"\n```\n\nAlternatively, clone at a tag and install with Poetry inside each package:\n\n```bash\ngit clone --depth 1 --branch vX.Y.Z git@github.com:didac-crst/mockexchange.git\ncd mockexchange/packages/engine \u0026\u0026 poetry install\n```\n\n### Common Use Cases\n\n```bash\n# Development workflow\nmake start-valkey      # Start database first\nmake start-oracle      # Start price feed\nmake start-engine      # Then start the API\nmake logs-engine       # Monitor engine logs\nmake restart-engine    # Restart after code changes\n\n# Debugging specific services\nmake logs-valkey       # Check database connectivity\nmake logs-oracle       # Check if price feed is working\nmake restart-periscope # Restart dashboard if UI is stuck\nmake status            # See which services are running\n\n# Selective deployment\nmake start-valkey make start-engine make start-periscope  # Skip oracle if using external data\n```\n\n---\n\n## 📚 Examples\n\nThe `examples/` directory contains tools and examples that demonstrate how to use the MockExchange platform.\n\n### Order Generator\n\nA Dockerized tool that generates random orders to test your MockExchange instance:\n\n```bash\n# Show available examples\nmake examples\n\n# Show order generator help\nmake order-generator\n\n# Start the order generator (fresh start with reset)\nmake order-generator-start-reset\n\n# Start the order generator (start without reset)\nmake order-generator-start\n\n# Continue without reset\nmake order-generator-restart\n\n# Continue with reset\nmake order-generator-restart-reset\n\n# View logs\nmake order-generator-logs\n\n# Stop the generator\nmake order-generator-stop\n\n# Check status\nmake order-generator-status\n```\n\n**Manual usage:**\n```bash\n# Ensure MockExchange stack is running\nmake start\n\n# Start the order generator\ncd examples/order-generator\ncp .env.example .env\n# Edit .env with your API settings\n./manage.sh start --reset\n```\n\nFor more details, see [examples/README.md](examples/README.md).\n\n---\n\n## 🔧 Environment Configuration\n\nAll environment variables are centralized in the root `.env` file. This eliminates duplication and makes configuration management much easier.\n\n### Quick Setup\n```bash\n# Copy the template and customize if needed\ncp .env.example .env\n\n# For external Valkey server, update VALKEY_HOST in .env:\n# VALKEY_HOST=192.168.1.100  # Replace with your Valkey server IP\n```\n\n**Note**: The `.env.example` is configured for Docker Compose. For external services, update:\n- `VALKEY_HOST` - Point to external Valkey/Redis server\n- `ENGINE_HOST` - Point to external Engine API server\n- `PERISCOPE_HOST` - Point to external Periscope dashboard server\n\n### Key Configuration Sections\n\n#### **Global Configuration**\n- `VERSION` - MockExchange version\n- `TEST_ENV` - Test environment flag (enables API docs, disables auth)\n- `DEBUG` - Development mode flag\n\n#### **Valkey (Database)**\n- `VALKEY_HOST` - Database host (default: `valkey` for Docker, use IP for external)\n- `VALKEY_PASSWORD` - Database authentication\n- `VALKEY_PORT` - Database port (default: 6379)\n\n#### **Oracle (Price Feeds)**\n- `EXCHANGE` - Source exchange (binance, coinbase, etc.)\n- `SYMBOLS` - Trading pairs to monitor\n- `INTERVAL_SEC` - Price update frequency\n- `QUOTES` - Quote assets for discovery (comma-separated, e.g., \"USDT,EUR\")\n- `QUOTE` - Fallback quote asset if QUOTES is empty (default: USDT)\n- `DISCOVER_QUOTES` - Enable automatic market discovery (true/false)\n- `DISCOVER_LIMIT` - Maximum markets per quote asset (0 = unlimited)\n\n#### **Engine (API)**\n- `ENGINE_HOST` - API server host (default: `engine` for Docker, use IP for external)\n- `ENGINE_PORT` - API server port (default: 8000)\n- `COMMISSION` - Trading commission rate\n- `API_KEY` - Authentication key\n- `CASH_ASSET` - Default cash/quote asset for the system (default: USDT)\n- `TICK_LOOP_SEC` - Price-tick scanning interval in seconds (default: 10)\n- `PRUNE_EVERY_MIN` - How often to prune old data in minutes (default: 60)\n- `STALE_AFTER_H` - Data considered stale after hours (default: 24)\n- `EXPIRE_AFTER_H` - Data expires after hours (default: 2)\n- `SANITY_CHECK_EVERY_MIN` - Sanity check interval in minutes (default: 10)\n- `API_TIMEOUT_SEC` - API request timeout for CLI in seconds (default: 10)\n\n#### **Engine Order Processing**\n- `MIN_TIME_ANSWER_ORDER_MARKET` - Minimum delay before processing market orders in seconds (default: 1)\n- `MAX_TIME_ANSWER_ORDER_MARKET` - Maximum delay before processing market orders in seconds (default: 5)\n- `SIGMA_FILL_MARKET_ORDER` - Slippage simulation for market order fills (default: 0.1)\n\n#### **Periscope (Dashboard)**\n- `ENGINE_HOST` - Engine host for API URL construction (default: `engine` for Docker, use IP for external)\n- `ENGINE_PORT` - Engine port for API URL construction (default: 8000)\n- `PERISCOPE_HOST` - Dashboard host for UI URL construction (default: `localhost`)\n- `PERISCOPE_PORT` - Dashboard port for UI URL construction (default: 8501)\n- `APP_TITLE` - Dashboard title\n- `REFRESH_SECONDS` - Auto-refresh interval\n- `QUOTE_ASSET` - Quote asset for portfolio valuation (default: USDT)\n- `FRESH_WINDOW_S` - Fresh window for highlighting in seconds (default: 60)\n- `N_VISUAL_DEGRADATIONS` - Number of fade-out levels for visual feedback (default: 60)\n- `SLIDER_MIN` - Minimum value for order count slider (default: 10)\n- `SLIDER_MAX` - Maximum value for order count slider (default: 1000)\n- `SLIDER_STEP` - Step size for order count slider (default: 10)\n- `SLIDER_DEFAULT` - Default value for order count slider (default: 50)\n- `LOCAL_TZ` - Timezone for timestamps (default: Europe/Berlin)\n- `LOGO_FILE` - Logo file for dashboard (optional)\n\n### Benefits of Centralized Configuration\n- ✅ **Single source of truth** - All config in one place\n- ✅ **No duplication** - Eliminates scattered `.env` files\n- ✅ **Easy customization** - Change once, applies everywhere\n- ✅ **Better security** - Centralized password management\n- ✅ **Simplified deployment** - One config file to manage\n\n- ✅ **Automatic URL construction** - API_URL and UI_URL built from HOST:PORT variables\n\n### URL Construction\nThe system automatically constructs URLs from HOST and PORT variables:\n- `API_URL = http://${ENGINE_HOST}:${ENGINE_PORT}` (for Periscope to connect to Engine)\n- `UI_URL = http://${PERISCOPE_HOST}:${PERISCOPE_PORT}` (for dashboard links)\n\nThis means you only need to configure the individual HOST and PORT variables, not the full URLs.\n\n---\n\n## 🗂 Monorepo Structure\n```text\nmockexchange/\n├── packages/\n│   ├── valkey/        # MockX Valkey (Redis database)\n│   ├── engine/        # MockX Engine (core/ + api/)\n│   ├── periscope/     # MockX Periscope (dashboard)\n│   └── oracle/        # MockX Oracle (price feeds)\n├── examples/          # Examples and tools\n│   ├── order-generator/ # Random order generator\n│   └── README.md      # Examples overview\n├── .github/workflows/ # CI/CD pipelines\n├── docker-compose.yml # Full stack orchestration\n├── .env.example       # Environment configuration template\n├── Makefile          # Development commands\n├── pyproject.toml    # Root workspace config\n├── .pre-commit-config.yaml # Code quality hooks\n├── scripts/          # Development and release scripts\n│   └── create-release-branch.sh # Automated release branch creation\n├── CHANGELOG.md      # Version history and release notes\n├── DOCKER_VERSIONS.md # Docker version pinning documentation\n└── README.md         # This file\n```\n\n---\n\n## 📚 Documentation\n\n### **Core Documentation**\n- [Valkey README](packages/valkey/README.md) - Database layer and data structures\n- [Oracle README](packages/oracle/README.md) - Price feed service and configuration\n- [Engine README](packages/engine/README.md) - Trading engine and API reference\n- [Periscope README](packages/periscope/README.md) - Dashboard features and usage\n\n### **Project Documentation**\n- [CHANGELOG.md](CHANGELOG.md) - Version history and release notes\n- [Docker Version Pinning](DOCKER_VERSIONS.md) - Reproducible Docker builds\n- [Examples README](examples/README.md) - Usage examples and tools\n\n### **External Resources**\n- [MockX Gateway](https://github.com/didac-crst/mockexchange-gateway) - ccxt-style Python client\n\n---\n\n## 🪪 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n\u003e **Don’t risk real money.**\n\u003e Spin up MockExchange, hammer it with tests, then hit live markets only when your algos are solid.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdidac-crst%2Fmockexchange","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdidac-crst%2Fmockexchange","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdidac-crst%2Fmockexchange/lists"}