{"id":49921157,"url":"https://github.com/jango-blockchained/hoox-setup","last_synced_at":"2026-05-16T20:03:22.571Z","repository":{"id":284437924,"uuid":"954940790","full_name":"jango-blockchained/hoox-setup","owner":"jango-blockchained","description":"⚡ Hoox is a modular, high-performance algorithmic trading and automation framework built entirely on Cloudflare Edge Workers. It uses distributed microservices to process signals, execute trades, and manage state with near-zero latency worldwide.","archived":false,"fork":false,"pushed_at":"2026-05-10T11:31:38.000Z","size":8015,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-10T11:33:17.226Z","etag":null,"topics":["ai-agent","algorithmic-trading","bun","cloudflare","cloudflare-workers","crypto-trading-bot","edge-computing","microservices","tradingsignal","tradingview-webhooks","typescript","zero-latency"],"latest_commit_sha":null,"homepage":"https://hoox-dashboard.pages.dev","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jango-blockchained.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-03-25T21:17:34.000Z","updated_at":"2026-05-10T11:31:43.000Z","dependencies_parsed_at":"2025-04-14T23:28:08.203Z","dependency_job_id":"b0611e6f-2ac1-4410-967f-7dbb34fb9a97","html_url":"https://github.com/jango-blockchained/hoox-setup","commit_stats":null,"previous_names":["jango-blockchained/hoox-cf-edge-worker","jango-blockchained/hoox-setup"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/jango-blockchained/hoox-setup","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jango-blockchained%2Fhoox-setup","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jango-blockchained%2Fhoox-setup/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jango-blockchained%2Fhoox-setup/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jango-blockchained%2Fhoox-setup/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jango-blockchained","download_url":"https://codeload.github.com/jango-blockchained/hoox-setup/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jango-blockchained%2Fhoox-setup/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33117350,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-16T18:38:32.183Z","status":"ssl_error","status_checked_at":"2026-05-16T18:38:29.903Z","response_time":115,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["ai-agent","algorithmic-trading","bun","cloudflare","cloudflare-workers","crypto-trading-bot","edge-computing","microservices","tradingsignal","tradingview-webhooks","typescript","zero-latency"],"created_at":"2026-05-16T20:03:21.598Z","updated_at":"2026-05-16T20:03:22.552Z","avatar_url":"https://github.com/jango-blockchained.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🚀 Hoox - The Zero-Latency Edge Trading Ecosystem\n\n\u003cdiv align=\"center\"\u003e\n\n[![Language](https://img.shields.io/badge/Language-TypeScript-blue.svg?style=for-the-badge\u0026logo=typescript)](https://www.typescriptlang.org/)\n[![Runtime](https://img.shields.io/badge/Runtime-Bun-black?style=for-the-badge\u0026logo=bun)](https://bun.sh)\n[![Platform](https://img.shields.io/badge/Platform-Cloudflare®%20Edge%20Workers-orange?style=for-the-badge\u0026logo=cloudflare)](https://workers.cloudflare.com/)\n[![Coverage](https://img.shields.io/badge/Coverage-80%25-brightgreen.svg?style=for-the-badge)](docs/development/testing.md)\n[![License](https://img.shields.io/badge/License-CC%20BY%204.0-lightgrey.svg?style=for-the-badge)](https://creativecommons.org/licenses/by/4.0/)\n[![Main Repo](https://img.shields.io/badge/Main%20Repo-hoox--setup-blue?style=for-the-badge\u0026logo=github)](https://github.com/jango-blockchained/hoox-setup)\n\n**Comprehensive Docs:** **[Documentation Home](docs/home.md)** · **[Report a Bug](https://github.com/jango-blockchained/hoox-setup/issues)**\n\n\u003c/div\u003e\n\n\u003e **Low-latency edge trading.** Hoox is a free and open-source algorithmic trading and automation framework. Built on **Cloudflare® Workers**, Hoox utilizes a globally distributed, microservice edge architecture. Process signals, execute trades, and manage state with **low latency**, directly from the network edge closest to the exchange.\n\n---\n\n## 🔁 Required clone mode\n\nThis repository uses Git submodules for worker repositories. You must clone it recursively:\n\n```bash\ngit clone --recursive https://github.com/jango-blockchained/hoox-setup.git hoox-trading\n```\n\n## 🌟 Why Hoox?\n\nHoox provides a modern approach to algorithmic trading infrastructure deployment.\n\n- 💸 **Cost-Effective \u0026 Open Source:** Hoox leverages Cloudflare®'s free tiers, allowing you to run your trading infrastructure with minimal or no server costs.\n- ⚡ **Edge Execution:** Your code runs on Cloudflare®'s Edge, geographically close to exchange API servers (like Binance, Bybit, and MEXC). When a signal fires, Hoox executes with minimal network latency.\n- 🛡️ **Built-in Security:** Hoox inherits Cloudflare®'s security features. With a Zero Trust architecture, strict IP Allow-listing, and encrypted internal Service Bindings, your API keys and trading strategies are well-protected.\n- 🧠 **Automated Management:** Featuring an embedded risk manager (`agent-worker`), Hoox can monitor your portfolio, manage trailing stops, trigger kill-switches, and send system health summaries.\n\n---\n\n## ⚠️ Disclaimer\n\nHoox is provided \"as-is\" for educational and research purposes only. The authors, contributors, and copyright holders make no warranties regarding the software and disclaim all liability for any financial losses resulting from its use.\n\n**No Financial Advice.** Nothing in this repository constitutes financial, investment, or trading advice. Users are solely responsible for their own trading decisions and must evaluate all risks independently.\n\n**Risk of Loss.** Algorithmic trading on centralized and decentralized exchanges involves substantial risk. Past performance is not indicative of future results. You may lose some or all of your invested capital.\n\n**Regulatory Compliance.** Users are responsible for ensuring compliance with applicable laws and regulations in their jurisdiction. Trading activities may be subject to licensing requirements, reporting obligations, or restrictions depending on your location.\n\n**No Warranties.** The software is provided under CC BY 4.0 without warranties of any kind, express or implied, including but not limited to merchantability, fitness for a particular purpose, or non-infringement. See the [LICENSE](LICENSE) and [DISCLAIMER](DISCLAIMER.md) for full details.\n\n---\n\n## ✨ Enterprise-Grade Features\n\n### Core Platform\n\n| Feature                          | Description                                                                                                                                                                                       |\n| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🔗 **Service Bindings**          | Microsecond inter-worker communication—no public internet routing, no TLS overhead, no DNS resolution. Workers call each other via internal V8 isolates.                                          |\n| 📨 **Async Queues**              | Cloudflare® Queues with exponential backoff retry policy (30s → 15min). Guaranteed delivery survives exchange downtime, API rate limits, and network partitions.                                  |\n| 🛡️ **Idempotent Execution**      | Durable Objects with SQLite-backed state prevent duplicate trades on network retries. Every webhook gets a unique trace ID for end-to-end signal tracking.                                        |\n| 🤖 **Multi-Provider AI Gateway** | 5 AI providers (Workers AI, OpenAI, Anthropic, Google AI, Azure OpenAI) with automatic fallback chain, health checks, SSE streaming, vision analysis, reasoning models, and usage tracking.       |\n| 🧠 **AI Risk Manager**           | `agent-worker` runs on a 5-minute cron: monitors open positions, moves trailing stops, scales out of profitable trades, flips the Global Kill Switch on max drawdown, and sends health summaries. |\n| ⚡ **Smart Placement**           | Zero-config latency optimization — Workers automatically run on the edge node closest to exchange API servers. 30-60% latency reduction, $0 cost (free on all plans).                             |\n| 🔄 **Real DO Idempotency**       | Durable Object with SQLite-backed persistence, TTL-based dedup, and automatic alarm cleanup. Prevents duplicate trades on network retries across cold starts.                                     |\n\n### Data \u0026 Storage\n\n| Feature                    | Description                                                                                                                                                   |\n| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🗄️ **D1 Edge Database**    | Globally distributed SQLite at the edge. Persistent, atomic storage for trade history, positions, and balances. Preserved write limits via R2 log offloading. |\n| 📦 **R2 Object Storage**   | Zero-egress, S3-compatible storage for trade reports, system logs, and user uploads. No bandwidth charges on retrieval.                                       |\n| 🔐 **KV Configuration**    | Sub-millisecond global key-value store for dynamic routing, IP allowlists, session state, kill-switch toggles, and live settings—no redeployment required.    |\n| 🔎 **Vectorize RAG Index** | Embedded vector database for retrieval-augmented generation. Powers context-aware AI responses and intelligent Telegram bot conversations.                    |\n| 📊 **Analytics Engine**    | Time-series analytics dataset for tracking API call latency, error rates, and trade execution metrics across all workers. Free on all plans.                  |\n\n### Trading Infrastructure\n\n| Feature                      | Description                                                                                                                                                |\n| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 📈 **Multi-Exchange Engine** | Execute across Binance, Bybit, and MEXC with dynamic routing via `CONFIG_KV`. Redirect symbols to different exchanges instantly without code deployment.   |\n| 🌐 **DeFi Execution**        | On-chain swap execution via `web3-wallet-worker` with secure mnemonic management and browser rendering for DApp interactions.                              |\n| 📧 **Email Signal Parsing**  | Trigger trades from raw email parsing via `email-worker`. Ancillary input channel alongside TradingView webhooks and Telegram commands.                    |\n| ⚡ **Rate Limiting**         | KV-backed rate limiter (10 trades/min) survives cold starts. Falls back to in-memory when KV unavailable. Prevents API bans and accidental trade spamming. |\n| 📄 **Automated PDF Reports** | Twice-daily PDF portfolio reports via Cloudflare Browser Rendering. Styled HTML → PDF, stored in R2, delivered via Telegram. Free 10 min/day on all plans. |\n\n### Developer Experience\n\n| Feature                | Description                                                                                                                                                                                                                                                          |\n| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 📊 **Command Center**  | Next.js 16 dashboard deployed to Cloudflare Workers via OpenNext. Real-time portfolio monitoring, win rates, live positions, and risk settings—no redeployment to change configuration.                                                                              |\n| 🖥️ **Interactive TUI** | Terminal-based process manager (`./hoox-tui`) for local development. Hot-reload all 9 workers simultaneously with one command.                                                                                                                                       |\n| 🛠️ **CLI Workspaces**  | Bun workspace monorepo managed via `hoox` CLI (15 command groups, 50+ subcommands, 381 tests). Interactive setup wizard, env config, KV sync, D1 ops, health monitoring, repair, and more.                                                                           |\n| 🐳 **Docker Support**  | Full local dev environment with Docker Compose. `hoox dev start` prompts for Native vs Docker runtime, offers `--runtime` flag override. Profiles: `workers`, `dashboard`, `full`.                                                                                   |\n| 🔗 **Shared Package**  | `@jango-blockchained/hoox-shared` provides a custom router with `:param` path parameter support, `Errors.*` response factories, generic exchange provider factory (`ExchangeRouter`), middleware stack (auth, CORS, logging, rate-limit, validation), and utilities. |\n\n### Security\n\n| Feature                        | Description                                                                                                                                           |\n| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🔒 **Zero Trust Architecture** | Internal workers (`trade-worker`, `d1-worker`) have zero public endpoints—accessible only via Cloudflare® Service Bindings.                           |\n| 🛡️ **WAF Integration**         | IP allowlisting and rate limiting at the Cloudflare edge. Malicious traffic dropped before hitting the gateway worker.                                |\n| 🔑 **Secret Injection**        | API keys injected directly into the V8 isolate at runtime. Never stored in plaintext, never logged. Local `.dev.vars` excluded from version control.  |\n| 🏴 **Global Kill Switch**      | Instant trading halt via KV toggle. No redeployment, no downtime—immediate effect across all workers on next request cycle.                           |\n| 🔐 **Security Headers**        | Full CSP, HSTS, X-Frame-Options, X-Content-Type-Options, Referrer-Policy, and Permissions-Policy on every response. CORS disabled (same-origin only). |\n\n---\n\n## 🚀 Quick Start (Deploy in 5 Minutes)\n\n### Option A: Install from Source (Recommended)\n\n1. **Clone the repository:**\n\n   ```bash\n   git clone --recursive https://github.com/jango-blockchained/hoox-setup.git hoox-trading\n   cd hoox-trading\n   ```\n\n2. **Install dependencies and bootstrap:**\n\n   ```bash\n   bun install\n   hoox init\n   ```\n\n### Deploy\n\n**Deploy your entire trading empire to the Cloudflare® Edge!**\n\n```bash\n# Deploy all workers + dashboard (correct dependency order)\nhoox deploy all --auto\n\n# Post-deploy: set Telegram webhook\nhoox deploy telegram-webhook\n\n# Post-deploy: update dashboard service URLs\nhoox deploy update-internal-urls\n\n# Post-deploy: apply KV manifest defaults\nhoox deploy kv-config\n```\n\n\u003e **Local Development:** Want to test before going live? Run `hoox dev start` to launch all workers — choose between Native (wrangler) or Docker (compose) runtime. Use `./hoox-tui` for the interactive terminal UI!\n\n---\n\n## 📦 Worker Submodules\n\nHoox uses Git submodules for each worker, allowing independent development and deployment. All workers are part of the [hoox-setup](https://github.com/jango-blockchained/hoox-setup) monorepo.\n\n| Worker                    | Description                                 | Repository                                                                                        |\n| ------------------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------- |\n| 🔐 **hoox** (Gateway)     | Webhook entrypoint \u0026 firewall               | [jango-blockchained/hoox](https://github.com/jango-blockchained/hoox)                             |\n| 📈 **trade-worker**       | Multi-exchange execution engine             | [jango-blockchained/trade-worker](https://github.com/jango-blockchained/trade-worker)             |\n| 🧠 **agent-worker**       | AI risk manager \u0026 cron jobs                 | [jango-blockchained/agent-worker](https://github.com/jango-blockchained/agent-worker)             |\n| 💬 **telegram-worker**    | Telegram notifications \u0026 commands           | [jango-blockchained/telegram-worker](https://github.com/jango-blockchained/telegram-worker)       |\n| 🗄️ **d1-worker**          | D1 database operations                      | [jango-blockchained/d1-worker](https://github.com/jango-blockchained/d1-worker)                   |\n| 🌐 **web3-wallet-worker** | DeFi \u0026 on-chain execution                   | [jango-blockchained/web3-wallet-worker](https://github.com/jango-blockchained/web3-wallet-worker) |\n| 📧 **email-worker**       | Email signal parsing                        | [jango-blockchained/email-worker](https://github.com/jango-blockchained/email-worker)             |\n| 📊 **analytics-worker**   | Analytics \u0026 reporting                       | [jango-blockchained/analytics-worker](https://github.com/jango-blockchained/analytics-worker)     |\n| 📄 **report-worker**      | Automated PDF reports via Browser Rendering | [jango-blockchained/report-worker](https://github.com/jango-blockchained/report-worker)           |\n\n\u003e **Note:** Clone with `git clone --recursive` to get all submodules, or run `git submodule update --init --recursive` after cloning.\n\n---\n\n## 🛠️ The `@jango-blockchained/hoox-cli` \u0026 Workspaces\n\nThe Hoox setup is managed via a dedicated, locally linked CLI tool at `packages/cli` (15 command groups, 50+ subcommands, 381 tests). By utilizing Bun Workspaces, all management commands are available via the `hoox` binary.\n\n### Complete Command Tree\n\n```\nhoox                                 Interactive TUI (no args)\n├── init                             Setup wizard with AI provider support\n├── clone                            Clone worker repos as submodules\n├── dev                              Local development (native/docker)\n├── deploy                           Deploy workers, dashboard, webhook, KV\n├── infra                            Manage D1, KV, R2, Queues, Vectorize, Analytics\n├── config                           Config, env vars, KV keys, secrets\n│   ├── env                          Declarative 31-key env matrix\n│   └── kv                           16-key manifest + apply-manifest\n├── check                            Prerequisites, setup, health\n├── db                               D1 schema, migrate, query, export, reset\n├── monitor                          Health, trades, logs, kill-switch, backup\n├── repair                           System check, repair, guided rebuild\n├── logs                             Tail worker logs\n├── test                             CI pipeline\n├── waf                              WAF rules\n└── dashboard                        Dashboard operations\n```\n\n### Key Workflows\n\n| Workflow    | Commands                                                                                            |\n| ----------- | --------------------------------------------------------------------------------------------------- |\n| **Setup**   | `hoox init` → `hoox check prerequisites` → `hoox config env init` → `hoox config kv apply-manifest` |\n| **Deploy**  | `hoox deploy all --auto` → `hoox deploy telegram-webhook` → `hoox deploy update-internal-urls`      |\n| **Operate** | `hoox monitor status` → `hoox monitor trades` → `hoox monitor kill-switch`                          |\n| **Repair**  | `hoox repair check` → `hoox repair infra` → `hoox repair secrets` → `hoox repair rebuild`           |\n| **Infra**   | `hoox infra d1 list` → `hoox infra vectorize list` → `hoox infra queues list`                       |\n\n### Features\n\n- **Interactive Setup**: Guided wizard with AI provider integration (OpenAI, Anthropic, Google AI, Home Assistant)\n- **Toolchain Validation**: 7 prerequisites checks (bun, git, node, wrangler, Cloudflare auth, Docker, repository)\n- **Declarative Env Config**: 31 environment variables across 8 sections with init/show/validate/generate-dev-vars\n- **KV Manifest Sync**: 16-key manifest with one-command apply for CONFIG_KV namespace\n- **Database Operations**: Schema apply, tracking migrations, read-only queries, export, reset with --remote support\n- **Infrastructure as Code**: Provision D1, KV, R2, Queues, Vectorize, Analytics via `hoox infra`\n- **Post-Deploy Automation**: Telegram webhook setup, internal URL updates, KV config sync\n- **Operational Monitoring**: Worker health probes, recent trades, system logs, queue depth, D1 backup, kill switch\n- **Guided Repair**: 5-step system check, per-component repair, interactive full rebuild\n- **Health Checks**: Worker /health endpoint probing for all enabled workers\n- **Secret Management**: Sync, check, and rotate Cloudflare secrets\n- **All commands** support `--json` (machine output) and `--quiet` (minimal output) global flags\n\n---\n\n## 🧅 Performance \u0026 Tooling: Powered by Bun\n\nHoox relies on **Bun** as its primary JavaScript runtime and package manager. Bun is designed as a drop-in replacement for Node.js, providing significantly faster execution, immediate startup times, and built-in tooling for testing, running scripts, and managing dependencies.\n\n- **Super Fast Execution**: Native implementations and the JavaScriptCore engine make script execution near instantaneous.\n- **Lightning Fast Installs**: Dependency resolution and installation are optimized for speed, caching, and concurrent fetching.\n- **Built-in Test Runner**: Hoox uses `bun test`, giving you natively integrated testing without heavy additional dependencies like Jest or Mocha.\n- **TypeScript Out-of-the-Box**: Bun compiles TypeScript on the fly, eliminating the need for slow build steps during development.\n\n---\n\n## 🏗️ The Microservice Architecture\n\nHoox is split into distinct, highly specialized micro-workers. If one fails, the others keep running.\n\n```mermaid\ngraph TB\n    %% ── Styling ──────────────────────────────────────────────────────\n    classDef external fill:#f5f5f5,stroke:#999,stroke-width:2,color:#333\n    classDef waf fill:#fff8e1,stroke:#f9a825,stroke-width:2\n    classDef worker fill:#e8f5e9,stroke:#43a047,stroke-width:2,color:#1b5e20\n    classDef storage fill:#e3f2fd,stroke:#1e88e5,stroke-width:2,color:#0d47a1\n    classDef compute fill:#f3e5f5,stroke:#8e24aa,stroke-width:2,color:#4a148c\n    classDef cli fill:#fafafa,stroke:#bdbdbd,stroke-width:1,stroke-dasharray: 4\n    classDef dash fill:#fff3e0,stroke:#ef6c00,stroke-width:2,color:#bf360c\n\n    %% ── Layers ───────────────────────────────────────────────────────\n\n    subgraph \"🌐 External World\"\n        TV[\"📊 TradingView Webhooks\"]\n        TG[\"💬 Telegram Bot Commands\"]\n        EM[\"📧 Email Signals\"]\n        subgraph \"💱 Exchanges\"\n            BINANCE[\"Binance API\"]\n            BYBIT[\"Bybit API\"]\n            MEXC[\"MEXC API\"]\n        end\n    end\n\n    subgraph \"🛡️ Cloudflare® WAF\"\n        WAF[\"IP Allowlisting \u0026 Rate Limiting\"]\n    end\n\n    subgraph \"⚡ Cloudflare® Edge Network — Workers\"\n        GW[\"🔐 hoox\u003cbr/\u003eGateway \u0026 Firewall\"]\n        TW[\"📈 trade-worker\u003cbr/\u003eExecution Engine\"]\n        AW[\"🧠 agent-worker\u003cbr/\u003eAI Risk Manager\"]\n        D1W[\"🗄️ d1-worker\u003cbr/\u003eSQL Operations\"]\n        TGW[\"💬 telegram-worker\u003cbr/\u003eNotifications\"]\n        W3W[\"🌐 web3-wallet\u003cbr/\u003eDeFi Execution\"]\n        EMW[\"📧 email-worker\u003cbr/\u003eEmail Parser\"]\n        ANW[\"📊 analytics-worker\u003cbr/\u003eObservability\"]\n        RPW[\"📄 report-worker\u003cbr/\u003ePDF Reports\"]\n        DASH[\"🖥️ Dashboard\u003cbr/\u003eNext.js Command Center\"]:::dash\n    end\n\n    subgraph \"💾 Cloudflare® Storage Layer\"\n        KV[(\"KV · Config \u0026 Kill-Switch\u003cbr/\u003eSub-millisecond reads\")]\n        DB[(\"D1 · Trade Database\u003cbr/\u003eGlobal SQLite\")]\n        R2[(\"R2 · Object Storage\u003cbr/\u003eReports \u0026 Logs\")]\n        VEC[(\"Vectorize · RAG Index\u003cbr/\u003eAI Embeddings\")]\n    end\n\n    subgraph \"🧮 Cloudflare® Compute Layer\"\n        AI{{\"🤖 Workers AI\u003cbr/\u003eLLaMA 3 Inference\"}}\n        DO{{\"🔒 Durable Objects\u003cbr/\u003eIdempotency Locks\"}}\n        Q{{\"📨 Queues\u003cbr/\u003eAsync Delivery · Retry\"}}\n        BROWSER{{\"🌐 Browser Rendering\u003cbr/\u003ePDF Generation\"}}\n        AE{{\"📈 Analytics Engine\u003cbr/\u003eTime-Series Metrics\"}}\n    end\n\n    subgraph \"🔧 Management Plane — hoox CLI\"\n        CLI[\"hoox deploy · hoox infra · hoox config\u003cbr/\u003ehoox db · hoox monitor · hoox repair\u003cbr/\u003ehoox check · hoox logs · hoox waf\"]\n    end\n\n    %% ── External → WAF → Gateway ─────────────────────────────────────\n\n    TV --\u003e|\"HTTPS + API Key\"| WAF\n    TG --\u003e|\"HTTPS + Bot Token\"| TGW\n    EM --\u003e|\"SMTP/IMAP\"| EMW\n    WAF --\u003e|\"Validated Signals\"| GW\n\n    %% ── Dashboard ────────────────────────────────────────────────────\n\n    DASH --\u003e|\"Service Binding\"| GW\n    DASH -.-\u003e|\"Read Config\"| KV\n\n    %% ── hoox Gateway Routing ─────────────────────────────────────────\n\n    GW --\u003e|\"⚡ Fast Path · Service Binding\"| TW\n    GW --\u003e|\"📨 Fallback · Queue\"| Q\n    GW --\u003e|\"🔒 Idempotency\"| DO\n    GW --\u003e|\"💬 Notifications\"| TGW\n    GW -.-\u003e|\"Config + Rate Limit\"| KV\n    GW -.-\u003e|\"Track API Calls\"| AE\n\n    %% ── agent-worker (Cron: every 5 min) ─────────────────────────────\n\n    AW --\u003e|\"Cron */5 · Evaluate Positions\"| TW\n    AW --\u003e|\"Send Summaries\"| TGW\n    AW --\u003e|\"Query History\"| D1W\n    AW --\u003e|\"Risk Analysis\"| AI\n    AW -.-\u003e|\"Portfolio State\"| DB\n    AW -.-\u003e|\"Market Data\u003cbr/\u003ePrice Checks\"| BINANCE\n    AW -.-\u003e|\"Market Data\u003cbr/\u003ePrice Checks\"| BYBIT\n    AW -.-\u003e|\"Market Data\u003cbr/\u003ePrice Checks\"| MEXC\n\n    %% ── trade-worker Execution ───────────────────────────────────────\n\n    TW --\u003e|\"Service Binding\"| D1W\n    TW --\u003e|\"Service Binding\"| TGW\n    TW --\u003e|\"Service Binding\"| ANW\n    TW --\u003e|\"DeFi Execution\"| W3W\n    TW -.-\u003e|\"Read/Write Trades\"| DB\n    TW -.-\u003e|\"Read Config\"| KV\n    TW -.-\u003e|\"RAG Context\"| VEC\n    TW -.-\u003e|\"Offload Logs\"| R2\n    TW -.-\u003e|\"Enqueue Retry\"| Q\n    TW -.-\u003e|\"AI Analysis\"| AI\n    TW -.-\u003e|\"Render Reports\"| BROWSER\n    TW ==\u003e|\"REST · REST\u003cbr/\u003eSigned Requests\"| BINANCE\n    TW ==\u003e|\"REST · WebSocket\u003cbr/\u003eSigned Requests\"| BYBIT\n    TW ==\u003e|\"REST\u003cbr/\u003eSigned Requests\"| MEXC\n\n    %% ── telegram-worker ──────────────────────────────────────────────\n\n    TGW --\u003e|\"Track Events\"| ANW\n    TGW -.-\u003e|\"AI Chat Responses\"| AI\n    TGW -.-\u003e|\"Read Config\"| KV\n\n    %% ── email-worker ─────────────────────────────────────────────────\n\n    EMW --\u003e|\"Track Events\"| ANW\n    EMW -.-\u003e|\"Read Config\"| KV\n\n    %% ── report-worker (Cron: 06:00 + 18:00) ──────────────────────────\n\n    RPW --\u003e|\"Cron · Store PDFs\"| R2\n    RPW --\u003e|\"Send Report Links\"| TGW\n    RPW -.-\u003e|\"REST · Render HTML→PDF\"| BROWSER\n\n    %% ── CLI Management Plane (dashed to all managed resources) ───────\n\n    CLI -.-\u003e|\"hoox deploy · hoox check\"| GW\n    CLI -.-\u003e|\"hoox deploy · hoox repair\"| TW\n    CLI -.-\u003e|\"hoox deploy · hoox repair\"| AW\n    CLI -.-\u003e|\"hoox deploy\"| D1W\n    CLI -.-\u003e|\"hoox deploy · telegram-webhook\"| TGW\n    CLI -.-\u003e|\"hoox deploy\"| W3W\n    CLI -.-\u003e|\"hoox deploy\"| EMW\n    CLI -.-\u003e|\"hoox deploy\"| ANW\n    CLI -.-\u003e|\"hoox deploy\"| RPW\n    CLI -.-\u003e|\"hoox deploy\"| DASH\n    CLI -.-\u003e|\"hoox db · hoox repair db\"| DB\n    CLI -.-\u003e|\"hoox config kv · hoox repair kv\"| KV\n    CLI -.-\u003e|\"hoox infra r2\"| R2\n    CLI -.-\u003e|\"hoox infra queues\"| Q\n    CLI -.-\u003e|\"hoox infra vectorize\"| VEC\n    CLI -.-\u003e|\"hoox infra analytics\"| AE\n    CLI -.-\u003e|\"hoox infra d1 · hoox repair\"| DO\n\n    %% ── Apply styles ─────────────────────────────────────────────────\n\n    class TV,TG,EM,BINANCE,BYBIT,MEXC external\n    class WAF waf\n    class GW,TW,AW,D1W,TGW,W3W,EMW,ANW,RPW worker\n    class KV,DB,R2,VEC storage\n    class AI,DO,Q,BROWSER,AE compute\n    class CLI cli\n```\n\n---\n\n## 📋 The 9 Pillars of Hoox (Workers)\n\n### 🔐 hoox (The Gateway)\n\nThe main entry point. It validates incoming TradingView webhooks, verifies API keys, and routes valid signals to the execution engine.\n\n- **WAF Integration**: IP allowlisting and rate limiting are handled via Cloudflare WAF to drop malicious traffic before it hits the worker.\n- **Fast Path Execution**: Attempts to execute trades instantly via direct Service Bindings, falling back to queues if necessary.\n- **Real DO Idempotency**: Prevents duplicate trades using SQLite-backed Durable Objects with TTL-based dedup and automatic alarm cleanup.\n- **KV-backed Rate Limiting**: Rate limiter persists across cold starts using CONFIG_KV, with transparent in-memory fallback.\n- **Smart Placement**: Worker runs on edge node closest to exchange API servers — 30-60% latency reduction.\n- **Analytics Tracking**: Every API call is tracked via analytics-worker for real-time observability.\n- **Trace IDs**: Generates distributed trace IDs for end-to-end signal tracking.\n\n### 📈 trade-worker (The Execution Engine)\n\nThe execution module. Routes and executes orders across MEXC, Binance, and Bybit. Handles leverage calculation and size mapping.\n\n- **Dynamic Routing**: Uses an `ExchangeRouter` with `CONFIG_KV` to instantly redirect symbols to different exchanges without code deployment. The `ExchangeRouter` and `IExchangeProvider` types live in the shared package for reusability.\n- **Standardized Error Handling**: All error responses use the `Errors.*` factory from `@jango-blockchained/hoox-shared` for consistent JSON error format across every worker.\n- **Smart Placement**: Automatically executes on the Cloudflare edge node closest to the exchange's API servers.\n- **R2 Log Offloading**: Verbose request and response logs are saved to R2 (`hoox-system-logs`), preserving D1 write limits for critical financial data.\n\n### 🧠 agent-worker (The AI Risk Manager \u0026 Multi-Provider AI Gateway)\n\nRuns silently on a 5-minute Cron schedule. It observes open positions, moves trailing stops, scales out of profitable trades, and flips the Global Kill Switch if maximum daily drawdown is reached.\n\n**Enhanced with Multi-Provider AI (Tasks 18-30):**\n\n- **5 AI Providers**: Workers AI, OpenAI, Anthropic, Google AI, Azure OpenAI\n- **Automatic Fallback Chain**: Seamless switching between providers on failure\n- **Health Checks**: Providers self-report health status for intelligent routing\n- **SSE Streaming**: Real-time streaming responses for chat and reasoning\n- **Vision Analysis**: Image analysis with URL or base64 input\n- **Reasoning Models**: Extended thinking support (OpenAI o1, etc.)\n- **Prompt Templates**: Pre-built templates (trading-analyst, risk-assessor, market-scanner)\n- **Usage Tracking**: Monitor API usage across all providers\n\n**New Endpoints:**\n\n- `POST /agent/chat` - AI chat with streaming support\n- `POST /agent/vision` - Image analysis\n- `POST /agent/reasoning` - Extended thinking queries\n- `GET /agent/usage` - Usage statistics\n- `GET /agent/prompts` - List prompt templates\n\n### 📊 dashboard (The Command Center)\n\nA secure, Cloudflare Workers-powered React dashboard using Next.js 16 + OpenNext. Monitor Win Rates, view live positions, and adjust risk settings on the fly without ever needing to redeploy code.\n\n### 💬 telegram-worker (The Communicator)\n\nSends instant trade confirmations and AI-generated market summaries straight to your phone.\n\n### 🗄️ d1-worker (The Memory)\n\nHandles all heavy SQL operations, aggregating trade histories and system logs to keep the execution workers incredibly lightweight.\n\n### 🌐 web3-wallet-worker (The On-Chain Bridge)\n\nReady for DeFi execution. Securely manages mnemonic phrases to execute swaps on decentralized exchanges.\n\n### 📧 email-worker\n\nAncillary plugin allowing you to trigger trades via raw email parsing.\n\n### 📄 report-worker (The Reporter)\n\nAutomated PDF portfolio report generation via Cloudflare Browser Rendering.\n\n- **Cron-Triggered**: Generates reports twice daily (06:00 + 18:00 UTC).\n- **Styled HTML→PDF**: Converts portfolio metrics, P\u0026L, win rates, and position data into professional PDF reports.\n- **R2 Storage**: Stores all generated PDFs in the `trade-reports` R2 bucket with date-based keys.\n- **Telegram Delivery**: Sends report links directly via `telegram-worker` service binding.\n- **Free Tier**: Browser Rendering is free at 10 min/day on all Cloudflare plans.\n\n---\n\n## 🔐 Security Architecture\n\nSecurity is a foundational aspect of the Hoox system.\n\n### Implemented Security Features\n\n| Feature                       | Description                                                 |\n| ----------------------------- | ----------------------------------------------------------- |\n| **CORS**                      | Disabled - same-origin only                                 |\n| **X-Frame-Options**           | DENY - prevents iframe embedding                            |\n| **X-Content-Type-Options**    | nosniff - prevents MIME sniffing                            |\n| **X-XSS-Protection**          | 1; mode=block                                               |\n| **Referrer-Policy**           | strict-origin-when-cross-origin                             |\n| **Permissions-Policy**        | Blocks accelerometer, camera, geolocation, microphone, etc. |\n| **Strict-Transport-Security** | max-age=31536000; includeSubDomains                         |\n| **Content-Security-Policy**   | default-src 'self'                                          |\n| **Idempotent Execution**      | Durable Objects prevent duplicate trades                    |\n| **Rate Limiting**             | 10 trades/minute protection                                 |\n| **IP Allow-listing**          | Optional IP filtering via KV                                |\n| **API Key Auth**              | Secret binding validation                                   |\n| **Kill Switch**               | Global trading pause via KV                                 |\n\n### Security Layers\n\n1. **Edge-Level**: Cloudflare's DDoS protection, firewall, and WAF\n2. **Worker-Level**: IP allow-listing, API key validation, rate limiting\n3. **Execution-Level**: Idempotency keys prevent duplicates, kill switches halt trading\n4. **Response-Level**: All responses include security headers\n\n- **No Public APIs:** The `trade-worker` and `d1-worker` literally do not exist on the public internet. They can _only_ be accessed internally by the `hoox` gateway via Cloudflare® Service Bindings.\n- **Zero Trust Dashboard:** Your UI is secured with authentication and deployed to Cloudflare Workers using the OpenNext adapter for full Next.js feature support.\n- **Hardware-Level Secret Injection:** API keys are injected directly into the V8 isolate at runtime. They are never stored in plaintext or logged.\n- **Idempotent Execution:** Durable Objects prevent duplicate trades on network retries—no lost ETH from double-spending.\n- **Rate Limiting:** Built-in throttling prevents accidental trade spamming.\n\n---\n\n## 🎯 Async Trade Execution (Queues)\n\nHoox uses Cloudflare® Queues for guaranteed trade delivery:\n\n| Mode                       | Description                                  |\n| -------------------------- | -------------------------------------------- |\n| `queue_failover` (default) | Try direct execution first, queue on failure |\n| `queue_everywhere`         | Always queue trades asynchronously           |\n\n### Configuration\n\n```bash\n# Set mode in KV\nwrangler kv key put webhooks:queue_mode queue_failover --binding CONFIG_KV --remote\n```\n\n### Retry Behavior\n\n- **Attempt 1**: Immediate\n- **Attempt 2**: 30 seconds\n- **Attempt 3**: 1 minute\n- **Attempt 4**: 5 minutes\n- **Attempt 5**: 15 minutes\n- After max retries: Trade logged to D1 as failed\n\n---\n\n## 💸 Free Tier Costs (Everything is Free!)\n\nHoox runs entirely on Cloudflare® Workers Free tier:\n\n| Service                | Free Limit                    | Notes                               |\n| ---------------------- | ----------------------------- | ----------------------------------- |\n| 🟠 Workers             | 100k req/day                  | ~3k trades/day                      |\n| 🟠 D1                  | 5M rows read, 100k writes/day | 5GB storage                         |\n| 🟠 KV                  | 1GB, 1k ops/day               | Config + rate limiter state         |\n| 🟠 R2                  | 10GB/month                    | Trade reports, logs, PDFs           |\n| 🟠 Queues              | 10k ops/day                   | ~3k trades/day                      |\n| 🟠 Durable Objects     | SQLite-backed only            | Idempotency locks                   |\n| 🟠 Workers AI          | 10k neurons/day               | AI summaries, risk analysis         |\n| 🟠 Vectorize           | 100 indexes                   | RAG-powered AI responses            |\n| 🟠 Browser Rendering   | 10 min/day                    | PDF portfolio reports               |\n| 🟠 Analytics Engine    | Unlimited datasets            | Real-time API + trade observability |\n| 🟠 Smart Placement     | Unlimited                     | 30-60% latency reduction            |\n| 🟠 WAF + Rate Limiting | 1 free rate limit rule        | API protection                      |\n\n---\n\n## 🧪 Testing \u0026 Reliability\n\nWith money on the line, we test everything.\n\n```bash\n# Run the massive test suite powered by Bun\nbun test --coverage\n```\n\n**Current Test Coverage:**\n\n- **packages/cli**: 381 tests across 26 files — 0 failures (100% pass rate)\n- **workers/hoox**: test suite in progress\n- **workers/trade-worker**: test suite in progress\n- **workers/agent-worker**: test suite in progress\n\nBuilt natively on Bun, Hoox features TypeScript type safety with strict mode enabled.\n\n\u003e **Note**: Coverage targets \u003e80% for all critical execution paths. See [Testing Documentation](docs/development/testing.md) for detailed coverage reports.\n\n### 🌐 Live Integration Tests\n\nA full live test suite against **real Cloudflare infrastructure** (no mocks) is available at [`tests/live/`](tests/live/). Covers all services used by hoox:\n\n```bash\n# Run all live tests (requires credentials in tests/live/.env)\nbun test:live\n\n# Run tests for a specific service\nbun test tests/live/d1.test.ts              # D1 SQL database\nbun test tests/live/kv.test.ts              # KV namespace\nbun test tests/live/r2.test.ts              # R2 object storage\nbun test tests/live/queues.test.ts          # Queue messaging\nbun test tests/live/ai.test.ts              # Workers AI inference\nbun test tests/live/api.test.ts             # Cloudflare REST API\nbun test tests/live/secrets.test.ts         # Secret management\nbun test tests/live/durable-objects.test.ts # Durable Objects\n```\n\n\u003e ⚠ **Warning:** These tests create and destroy real resources. Use a development/staging account, NOT production. Copy [`tests/live/env.template`](tests/live/env.template) to `tests/live/.env` to configure.\n\n---\n\n## 🐳 Local Development (Docker)\n\nHoox supports local development using Docker. While production deployment targets Cloudflare Workers, Docker allows you to run and test the worker logic locally.\n\n### Prerequisites\n\n- [Docker](https://www.docker.com/) \u0026 Docker Compose\n- Bun runtime (included in our Docker images)\n\n### Development (Hot-Reload)\n\nSpin up all workers locally with hot-reloading enabled. Changes to your code are reflected instantly without rebuilding the container.\n\n```bash\n# Build and start the dev environment\nbun run docker:dev\n\n# Optional: validate compose file before boot\ndocker compose config\n```\n\nThis launches all workers on the following ports:\n\n| Service         | Port |\n| --------------- | ---- |\n| Gateway (hoox)  | 8787 |\n| Trade Worker    | 8789 |\n| Telegram Worker | 8791 |\n| D1 Worker       | 8792 |\n| Web3 Wallet     | 8793 |\n| Dashboard       | 8794 |\n| Agent           | 8795 |\n| Email           | 8796 |\n| Report          | 8797 |\n\nTo stop local dev cleanly:\n\n```bash\nbun run docker:down\n```\n\n### Production Build\n\nBuild the optimized production image for local testing.\n\n```bash\n# Build the production image\nbun run docker:prod\n```\n\n**Configuration:**\nEnsure your `.env.local` or environment variables are set with your Cloudflare API Token and Account ID:\n\n```bash\nCLOUDFLARE_API_TOKEN=your_token_here\nCLOUDFLARE_ACCOUNT_ID=your_account_id\n```\n\n---\n\n## 🤝 Contribute\n\nTraditional algorithmic trading is often complex and difficult to deploy. Hoox aims to simplify this.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/new-strategy`)\n3. Commit your changes (`git commit -m 'Add new strategy'`)\n4. Push to the branch (`git push origin feature/new-strategy`)\n5. Open a Pull Request\n\n---\n\n## ✅ Integrated Cloudflare Services\n\nAll Cloudflare service integrations are **live** across hoox workers (May 2026):\n\n| Service                     |                   Integration                   |        CLI Mgmt        |             Workers              | Cost |\n| --------------------------- | :---------------------------------------------: | :--------------------: | :------------------------------: | :--: |\n| **Smart Placement**         |          `placement { mode: \"smart\" }`          |           —            | hoox, trade, agent, d1, telegram | Free |\n| **Durable Objects**         | Real IdempotencyStore w/ SQLite + alarm cleanup |           —            |               hoox               | Free |\n| **KV-backed Rate Limiting** |    Survives cold starts, in-memory fallback     |    `hoox config kv`    |               hoox               | Free |\n| **Browser Rendering**       |         Automated PDF portfolio reports         |           —            |          report-worker           | Free |\n| **Analytics Engine**        |    Time-series tracking via analytics-worker    | `hoox infra analytics` |           all workers            | Free |\n| **Workers AI**              |        LLaMA 3 risk analysis \u0026 summaries        |           —            |      agent, telegram, hoox       | Free |\n| **Vectorize**               |            RAG-powered AI responses             | `hoox infra vectorize` |          telegram, hoox          | Free |\n| **D1 Database**             |            Global SQLite at the edge            |       `hoox db`        |         trade, d1, agent         | Free |\n| **KV Config**               |          Sub-millisecond config store           |    `hoox config kv`    |           all workers            | Free |\n| **Queues**                  |             Async message delivery              |  `hoox infra queues`   |           hoox, trade            | Free |\n| **R2 Storage**              |           Zero-egress object storage            |    `hoox infra r2`     |          trade, report           | Free |\n| **WAF + Rate Limiting**     |    CLI-managed IP allowlisting + rate rules     |       `hoox waf`       |            zone-level            | Free |\n\nAll services run on Cloudflare's **Free plan** — no monthly costs.\n\n---\n\n## 📄 License\n\nLicensed under [Creative Commons Attribution 4.0 International](https://creativecommons.org/licenses/by/4.0/). See [LICENSE](LICENSE) for the full license text and [DISCLAIMER](DISCLAIMER.md) for legal terms.\n\n---\n\n\u003cdiv align=\"center\"\u003e\nBuilt with 🔥 on the Cloudflare® Edge.\n\u003c/div\u003e\n\n---\n\n_Cloudflare® and the Cloudflare logo are trademarks and/or registered trademarks of Cloudflare, Inc. in the United States and other jurisdictions._\n_Pine Script™ and TradingView® are trademarks of TradingView, Inc. This project is an independent effort and is not affiliated with or endorsed by TradingView, Inc._\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjango-blockchained%2Fhoox-setup","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjango-blockchained%2Fhoox-setup","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjango-blockchained%2Fhoox-setup/lists"}