diff --git a/README.md b/README.md index f480b5e..bf3cb72 100644 --- a/README.md +++ b/README.md @@ -1,241 +1,63 @@ # CryptoStrategies - +[Chinese README](README.zh-CN.md) -> ⚠️ 投资有风险，不构成投资建议，仅供学习交流用途。 > ⚠️ Investing involves risk. This project does not provide investment advice and is for educational and research purposes only. -## Open-source overview / 开源项目入口 +## What this project does -| Item | Description | -| --- | --- | -| Project type | strategy package | -| What it does | Shared crypto strategy implementations and metadata for QuantStrategyLab crypto runtimes. | -| 中文说明 | 加密资产策略实现与元数据包，供 Binance 等 crypto runtime 加载。 | -| Current status | Strategy package; execution happens in platform repositories such as BinancePlatform. | +CryptoStrategies is a **Strategy package** in the QuantStrategyLab ecosystem. It contains shared crypto strategy implementations and execution components for QuantStrategyLab platforms, including leader-rotation modules and loader metadata. -### Quick start +## Who this is for -- `python -m pip install -e '.[test]'` -- `python -m pytest -q` +- Engineers and researchers who want to inspect, reproduce, or extend this part of the QuantStrategyLab stack. +- Operators who need a clear entry point before reading the deeper runbooks or workflow files. +- Reviewers who need to understand the repository purpose, safety boundary, and evidence requirements before enabling automation. -### Deploy / operate safely +## Current status -Do not deploy from this repo directly. Update downstream runtime configs and run platform dry-runs first. +Strategy package. Live use requires reproducible research evidence and platform-level risk controls. -### Strategy performance / evidence boundary +## Repository layout -Performance and backtest evidence should be reviewed in the strategy docs or CryptoSnapshotPipelines artifacts before runtime enablement. +- `src/`: main library and runtime code. +- `tests/`: unit and contract tests. +- `docs/`: detailed design notes, runbooks, and evidence docs. +- `.github/workflows/`: CI, scheduled jobs, and deployment workflows. -> Detailed runbooks, migration notes, workflow internals, and historical decisions are kept below. Start with this overview before using the lower-level operational sections. +## Quick start - +From a fresh clone: -> ⚠️ 投资有风险，不构成投资建议，仅供学习交流用途。 +```bash +python -m pip install -e . +python -m pytest -q +``` -[English](#english) | [中文](#中文) +If a command requires credentials, run it only after reading the relevant workflow or runbook and configuring secrets outside Git. ---- +## Deployment and operation - -## English +Install the package into a crypto execution platform, configure runtime settings there, and validate generated targets/orders in dry-run before live execution. -Standalone crypto strategy repository for QuantStrategyLab platforms. +Prefer manual or dry-run execution first. Enable schedules or live execution only after logs, artifacts, permissions, and rollback steps are reviewed. -This repository owns pure strategy logic and strategy metadata. The downstream execution repo still owns exchange access, market-data fetches, runtime state, circuit breakers, Flexible Earn handling, notifications, and order placement. +## Strategy performance and evidence -Monthly report review, AI audit, and automated remediation workflows belong to snapshot artifact repositories such as `CryptoSnapshotPipelines`. This repository does not run monthly report audit automation directly. +Evaluate crypto strategies with reproducible backtests and snapshot artifacts across multiple market regimes. Strategies that do not beat their benchmark after drawdown and turnover costs should remain research-only. -Recommended entry docs: +README files are intentionally not a source of dated performance promises. Re-run the relevant tests, backtests, or pipeline jobs before relying on any result. -- `docs/crypto_cross_platform_strategy_spec.md` -- `docs/crypto_strategy_template.md` -- `docs/crypto_portability_checklist.md` +## Safety notes -### Contract boundary +- Never commit API keys, broker credentials, OAuth tokens, cookies, or account identifiers. +- Run new strategies and platform changes in dry-run or paper mode before any live execution. +- Review generated orders, artifacts, and logs manually before enabling schedules. -The supported downstream surface is now the manifest-backed unified entrypoint for each live profile. +## Contributing -- `CryptoStrategies` owns pure decision logic and manifest metadata -- `BinancePlatform` loads that entrypoint through `QuantPlatformKit` -- shared outputs stay inside `StrategyDecision` -- exchange-specific safety checks, order sequencing, and artifact freshness handling stay in the execution repo -- monthly report audit and remediation workflows stay in snapshot artifact repositories +Keep changes small, reproducible, and covered by the narrowest useful tests. For strategy-facing changes, include the evidence artifact or command used to validate behavior. -Legacy `core` / `rotation` modules may still exist as internal implementation details, but downstream runtimes should not bind to those component names anymore. +## License -### Strategy index - -| Profile | Downstream runtime today | Core idea | -| --- | --- | --- | -| `crypto_leader_rotation` | `BinancePlatform` | BTC core budget plus monthly altcoin leader rotation | - -These strategies are consumed by platform repositories through `QuantPlatformKit` strategy contracts and component loaders. - -### crypto_leader_rotation - -**Objective** -- Keep BTC as the core asset while giving the non-BTC sleeve to a selective trend-following rotation. -- Avoid holding a broad alt basket all the time; only deploy into names that are strong both absolutely and versus BTC. - -**Repository boundary** -- This repository owns: - - BTC target-ratio and base-order budgeting helpers - - trend-pool ranking and monthly refresh / lock logic - - candidate selection, inverse-vol weighting, and sell-reason rules -- `BinancePlatform` currently owns: - - AHR999 and Z-Score data fetches - - DCA buy / trim execution - - exchange safety checks, balance handling, and circuit breaker behavior - - Flexible Earn subscribe / redeem flow and Telegram notifications - -**BTC core budget logic** -- Target BTC weight grows with equity: - - `btc_target_ratio = 0.14 + 0.16 * ln(1 + total_equity / 10000)` - - capped at `65%` -- Base daily BTC order size is: - - `max(15 USDT, total_equity × 0.0012)` -- `compute_allocation_budgets(...)` splits available USDT between: - - the trend sleeve (`trend_usdt_pool`) - - the BTC accumulation sleeve (`dca_usdt_pool`) -- This lets the downstream executor size BTC accumulation and trend allocation from one equity-aware budget framework. - -**Current live BTC execution rules in BinancePlatform** -- `AHR999 < 0.45` → buy multiplier `5x` -- `0.45 <= AHR999 < 0.8` → buy multiplier `2x` -- `0.8 <= AHR999 < 1.2` → buy multiplier `1x` -- `AHR999 >= 1.2` → no scheduled BTC buy -- If `Z-Score > sell_trigger`, the runtime trims BTC. -- Trim size is currently `10%`, `30%`, or `50%` as the overvaluation rises (`trigger`, `>4`, `>5`). - -**Trend-pool construction** -- The live stack prefers an upstream published monthly pool, but this repository also contains the internal ranking logic used to rebuild or validate that pool. -- Current live Binance defaults: - - pool size `5` - - minimum history `365` days - - minimum `180d` average quote volume `8,000,000` - - existing-pool membership bonus `0.10` -- Ranking factors include: - - trend quality (`price vs SMA20 / 60 / 200`) - - persistence - - liquidity and liquidity stability - - relative strength vs BTC - - risk-adjusted momentum -- The pool score is a weighted sum of normalized ranks, with a small bonus for names already in the previous pool. - -**Rotation-entry rules** -- The BTC regime gate must be on. -- A candidate must be above `SMA20`, `SMA60`, and `SMA200`. -- Relative strength vs BTC must be positive. -- Absolute momentum (`0.5×ROC20 + 0.3×ROC60 + 0.2×ROC120`) must also be positive. -- The top `2` candidates are selected by relative score. -- Default weighting is inverse volatility, so lower-vol winners receive slightly more capital. - -**Exit and defense rules** -- A held symbol can be sold for three reasons: - - it rotated out of the selected top names - - price fell below `SMA60` - - price broke the ATR trailing stop: `highest_price - ATR_MULTIPLIER × ATR14` -- The current live Binance profile uses `ATR_MULTIPLIER = 2.5`. -- Pool membership is locked by upstream `version` / `as_of_date` state so the live pool does not churn mid-month unless a refresh is intended. - ---- - - -## 中文 - -这是 `QuantStrategyLab` 的独立加密货币策略仓。 - -这个仓库负责纯策略逻辑和策略元数据。下游执行仓库继续负责交易所接入、行情获取、运行时状态、熔断、Flexible Earn、通知和实际下单。 - -建议先读这些文档： - -- `docs/crypto_cross_platform_strategy_spec.zh-CN.md` -- `docs/crypto_strategy_template.zh-CN.md` -- `docs/crypto_portability_checklist.zh-CN.md` - -### 契约边界 - -当前正式对下游开放的是每个 live profile 的 manifest 驱动统一 entrypoint。 - -- `CryptoStrategies` 负责纯决策逻辑和 manifest 元数据 -- `BinancePlatform` 通过 `QuantPlatformKit` 加载这个 entrypoint -- 共享输出保持在 `StrategyDecision` 契约内 -- 交易所专属安全检查、下单顺序和 artifact 新鲜度校验继续放在执行仓库 - -旧的 `core` / `rotation` 模块可以继续作为仓库内部实现细节存在，但下游运行时不应再绑定这些组件名。 - -### 策略索引 - -| 策略档位 | 当前下游运行仓库 | 核心思路 | -| --- | --- | --- | -| `crypto_leader_rotation` | `BinancePlatform` | 以 BTC 为核心仓，再叠加月度山寨币强者轮动 | - -这些策略通过 `QuantPlatformKit` 提供的策略契约和组件加载接口，被各个平台仓库引用。 - -### crypto_leader_rotation - -**策略目标** -- 让 BTC 继续作为核心资产，同时把非 BTC 仓位交给一套有筛选的趋势轮动。 -- 不长期被动持有一篮子山寨币，只把资金部署到绝对趋势和相对 BTC 强度都过关的标的上。 - -**仓库边界** -- 这个仓库负责： - - BTC 目标仓位和基础下单预算的计算 - - 趋势池打分、月度刷新和锁定逻辑 - - 候选币筛选、逆波动率权重、卖出原因判断 -- 当前 `BinancePlatform` 负责： - - `AHR999` 和 `Z-Score` 数据获取 - - BTC 定投 / 分档止盈执行 - - 交易所安全检查、余额处理和熔断 - - Flexible Earn 申购 / 赎回，以及 Telegram 通知 - -**BTC 核心仓预算逻辑** -- BTC 目标权重会随总权益增长： - - `btc_target_ratio = 0.14 + 0.16 * ln(1 + total_equity / 10000)` - - 上限 `65%` -- BTC 每日基础下单额是： - - `max(15 USDT, total_equity × 0.0012)` -- `compute_allocation_budgets(...)` 会把可用 USDT 拆成： - - 趋势层预算 `trend_usdt_pool` - - BTC 累积预算 `dca_usdt_pool` -- 这样下游执行层就能在同一个按权益变化的预算框架里，同时管理 BTC 核心仓和趋势层。 - -**当前 Binance live 执行层里的 BTC 规则** -- `AHR999 < 0.45` → 买入倍率 `5x` -- `0.45 <= AHR999 < 0.8` → 买入倍率 `2x` -- `0.8 <= AHR999 < 1.2` → 买入倍率 `1x` -- `AHR999 >= 1.2` → 当轮不做计划内 BTC 买入 -- 当 `Z-Score > sell_trigger` 时，运行层会触发 BTC 分档止盈。 -- 当前止盈比例是 `10% / 30% / 50%` 三档，对应高估程度继续抬升（`trigger`、`>4`、`>5`）。 - -**趋势池构建** -- live 链路优先消费上游发布的月度池，但这个仓库也保留了内部打分逻辑，用于重建或校验该池。 -- 当前 Binance live 默认参数： - - 池大小 `5` - - 最少历史数据 `365` 天 - - `180 日`平均成交额下限 `8,000,000` - - 上月已入池标的加分 `0.10` -- 打分因子包括： - - 趋势质量（`price vs SMA20 / 60 / 200`） - - 趋势持续性 - - 流动性和流动性稳定度 - - 相对 BTC 强度 - - 风险调整后动量 -- 最终分数是各个归一化 rank 的加权和，再叠加一小段旧池成员加分。 - -**趋势层入场规则** -- 必须先满足 BTC 闸门开启。 -- 候选币必须站上 `SMA20`、`SMA60`、`SMA200`。 -- 相对 BTC 强度必须为正。 -- 绝对动量 `0.5×ROC20 + 0.3×ROC60 + 0.2×ROC120` 也必须为正。 -- 按相对得分选出前 `2` 名。 -- 默认用逆波动率分配权重，所以波动更低的赢家会拿到略高一点的资金。 - -**退出和防守规则** -- 已持有的币会因为 3 类原因卖出： - - 已经轮出当前 Top 名单 - - 价格跌破 `SMA60` - - 价格跌破 ATR 跟踪止损：`highest_price - ATR_MULTIPLIER × ATR14` -- 当前 Binance live profile 使用 `ATR_MULTIPLIER = 2.5`。 -- 趋势池会按上游 `version / as_of_date` 做锁定，避免在月中因为偶发刷新造成 live 池频繁抖动。 +See [LICENSE](LICENSE) if present in this repository. diff --git a/README.zh-CN.md b/README.zh-CN.md new file mode 100644 index 0000000..28fd200 --- /dev/null +++ b/README.zh-CN.md @@ -0,0 +1,63 @@ +# CryptoStrategies + +[English README](README.md) + +> ⚠️ 投资有风险，不构成投资建议，仅供学习交流用途。 + +## 这个项目做什么 + +CryptoStrategies 是 QuantStrategyLab 体系中的**策略包**。提供 QuantStrategyLab 平台共用的加密货币策略实现和执行组件，包括 leader-rotation 模块和加载元数据。 + +## 适合谁使用 + +- 希望阅读、复现或扩展 QuantStrategyLab 相关模块的工程师和研究人员。 +- 在阅读详细 runbook 或 workflow 前，需要先理解项目入口的运维人员。 +- 在启用自动化前，需要确认项目职责、安全边界和证据要求的 reviewer。 + +## 当前状态 + +策略包。live 使用需要可复现研究证据和平台侧风控。 + +## 仓库结构 + +- `src/`：主要库代码和运行时代码。 +- `tests/`：单元测试和契约测试。 +- `docs/`：详细设计说明、运行手册和证据文档。 +- `.github/workflows/`：CI、定时任务和部署 workflow。 + +## 快速开始 + +从全新 clone 开始： + +```bash +python -m pip install -e . +python -m pytest -q +``` + +如果命令需要凭据，请先阅读相关 workflow 或 runbook，并把密钥配置在 Git 之外。 + +## 部署和运行 + +在加密货币执行平台中安装本包，在平台侧配置运行参数，并先用 dry-run 验证生成的目标和订单。 + +建议先手工运行或 dry-run。只有在日志、产物、权限和回滚步骤都检查过之后，才启用定时任务或 live 执行。 + +## 策略表现与证据边界 + +加密货币策略应通过可复现回测和快照产物，在多种市场环境下评估。考虑回撤和换手成本后无法跑赢基准的策略，应保留为研究策略。 + +README 不应该承诺固定收益或过期指标。实际使用前，请重新运行对应测试、回测或流水线任务。 + +## 安全注意事项 + +- 不要把 API key、券商凭据、OAuth token、Cookie 或账户标识提交到 Git。 +- 新策略或平台变更在 live 前必须先跑 dry-run 或 paper 流程。 +- 启用定时任务前，需要人工检查生成的订单、产物和日志。 + +## 参与贡献 + +请保持改动小、可复现，并用最小必要测试覆盖。涉及策略的改动，需要附上验证行为的证据产物或命令。 + +## 许可证 + +如仓库包含 [LICENSE](LICENSE)，请以该文件为准。