diff --git a/docs/crypto-tail-strategy/README.md b/docs/crypto-tail-strategy/README.md new file mode 100644 index 0000000..0d3c267 --- /dev/null +++ b/docs/crypto-tail-strategy/README.md @@ -0,0 +1,32 @@ +# 尾盘策略文档 (Crypto Tail Strategy) + +本目录集中存放与 Polymarket 加密市场尾盘策略相关的文档。 + +## 目录结构 + +``` +crypto-tail-strategy/ +├── README.md # 本说明 +├── crypto-tail-auto-spread-dynamic-coefficient.md # 自动价差动态系数(中英通用) +├── zh/ # 中文文档 +│ ├── crypto-tail-strategy-user-guide.md # 用户配置指南 +│ ├── crypto-tail-strategy-ui-spec.md # UI 规格 +│ ├── crypto-tail-strategy-tasks.md # 任务与验收 +│ ├── crypto-tail-strategy-flow.md # 流程说明 +│ ├── crypto-tail-strategy-min-spread-flow.md # 最小/最大价差流程 +│ └── crypto-tail-strategy-market-data.md # 市场数据与周期 +└── en/ # 英文文档 + └── crypto-tail-strategy-user-guide.md # User configuration guide +``` + +## 文档说明 + +| 文档 | 说明 | +|------|------| +| **user-guide** (zh/en) | 面向用户的策略配置指南与 FAQ | +| **ui-spec** (zh) | 前端列表、表单、时间窗口、触发记录等 UI 规格 | +| **tasks** (zh) | 开发任务与验收项 | +| **flow** (zh) | 策略整体流程 | +| **min-spread-flow** (zh) | 价差过滤(最小/最大价差)流程 | +| **market-data** (zh) | Gamma slug、周期、时间区间、价格判断等市场数据规则 | +| **auto-spread-dynamic-coefficient** | 自动价差模式下动态系数计算说明 | diff --git a/docs/crypto-tail-auto-spread-dynamic-coefficient.md b/docs/crypto-tail-strategy/crypto-tail-auto-spread-dynamic-coefficient.md similarity index 100% rename from docs/crypto-tail-auto-spread-dynamic-coefficient.md rename to docs/crypto-tail-strategy/crypto-tail-auto-spread-dynamic-coefficient.md diff --git a/docs/en/crypto-tail-strategy-user-guide.md b/docs/crypto-tail-strategy/en/crypto-tail-strategy-user-guide.md similarity index 79% rename from docs/en/crypto-tail-strategy-user-guide.md rename to docs/crypto-tail-strategy/en/crypto-tail-strategy-user-guide.md index 08f79c5..afa5ccc 100644 --- a/docs/en/crypto-tail-strategy-user-guide.md +++ b/docs/crypto-tail-strategy/en/crypto-tail-strategy-user-guide.md @@ -120,16 +120,24 @@ Cycle Start → Within Time Window → Price Enters Range → Auto Order - Minimum order amount: At least 1 USDC - If account balance is insufficient, order will fail and record failure reason -### 3.5 Minimum Spread (Advanced Feature) +### 3.5 Spread Filter (Advanced Feature) -The minimum spread feature filters market volatility, only triggering when Binance BTC/USDC price movement reaches a certain magnitude. +The spread filter controls whether to trigger based on Binance BTC/USDC K-line volatility. It supports two directions: **Minimum spread** and **Maximum spread**. | Parameter | Description | Required | Example | |-----------|-------------|----------|---------| -| **Minimum Spread Mode** | Choose spread validation method | ✅ | None / Fixed / Auto | -| **Minimum Spread Value** | Fill when using Fixed mode | Conditionally required | 30 | +| **Spread Mode** | Choose spread validation method | ✅ | None / Fixed / Auto | +| **Spread Direction** | Min spread (trigger when ≥) or Max spread (trigger when ≤) | ✅ | Min spread / Max spread | +| **Spread Value** | Fill when using Fixed mode (unit: USDC) | Conditionally required | 30 | -**Three Mode Explanations**: +**Spread Direction**: + +- **Min spread**: Triggers only when Binance K-line spread **≥** the set value + - Use when you want to trade only when volatility is "large enough" (avoid entering when volatility is too small). +- **Max spread**: Triggers only when Binance K-line spread **≤** the set value + - Use when you want to trade only when volatility is "small enough" (avoid entering when volatility is too high). + +**Three Spread Modes**: **Mode 1: None (NONE)** - No spread validation @@ -137,26 +145,28 @@ The minimum spread feature filters market volatility, only triggering when Binan - **Suitable for**: Not concerned about Binance price volatility, only watching Polymarket price **Mode 2: Fixed (FIXED)** -- Set a fixed minimum spread value (unit: USDC) -- Only triggers when Binance BTC/USDC K-line spread (|close price - open price|) ≥ set value -- **Example**: Set to 30 - - Binance K-line spread ≥ 30 in cycle: Triggered ✅ - - Binance K-line spread < 30 in cycle: Not triggered -- **Suitable for**: You know the expected spread threshold +- Set a fixed spread value (unit: USDC) +- **Min spread**: Triggers when K-line spread ≥ set value + - Example: Set 30, spread ≥ 30 → triggered ✅, spread < 30 → not triggered +- **Max spread**: Triggers when K-line spread ≤ set value + - Example: Set 50, spread ≤ 50 → triggered ✅, spread > 50 → not triggered +- **Suitable for**: You have a clear spread threshold in mind **Mode 3: Auto (AUTO)** -- System automatically calculates minimum spread based on historical 20 K-lines +- System automatically calculates an effective spread from the last 20 K-lines - Calculation logic: 1. Get recent 20 K-lines (matching strategy cycle) 2. Filter by direction (Up direction only looks at rising K-lines, Down direction only looks at falling K-lines) 3. Remove outliers (using IQR method) - 4. Calculate average spread × 0.8 as minimum spread -- **Suitable for**: Want automatic adjustment based on historical data, no manual setup needed + 4. Calculate average spread × 0.8 as effective spread +- **Min spread**: Triggers when K-line spread ≥ effective spread +- **Max spread**: Triggers when K-line spread ≤ effective spread +- **Suitable for**: Want automatic adjustment based on historical data without setting a specific value **Spread Explanation**: -- Spread = |close price - open price| +- Spread = |close price - open price| (Binance BTC/USDC for that K-line) - Example: Open price 50000, close price 50030, spread = 30 -- Larger spread indicates greater price volatility in that cycle +- Larger spread means greater price volatility in that cycle --- @@ -176,7 +186,7 @@ Minimum Price: 0.00 Maximum Price: 0.60 Investment Mode: Fixed Amount Fixed Amount: 10 USDC -Minimum Spread Mode: None +Spread Mode: None Enabled: On ``` @@ -200,7 +210,7 @@ Minimum Price: 0.40 Maximum Price: 0.70 Investment Mode: By Ratio Ratio: 15% -Minimum Spread Mode: None +Spread Mode: None Enabled: On ``` @@ -224,15 +234,16 @@ Minimum Price: 0.50 Maximum Price: 0.80 Investment Mode: Fixed Amount Fixed Amount: 20 USDC -Minimum Spread Mode: Fixed -Minimum Spread Value: 50 +Spread Mode: Fixed +Spread Direction: Min spread +Spread Value: 50 Enabled: On ``` **Explanation**: - 10 ~ 14 minutes after cycle start: Only triggers when both conditions are met: 1. Price is between 0.50 ~ 0.80 ✅ - 2. Binance BTC/USDC spread ≥ 50 ✅ + 2. Spread direction is "Min spread" and Binance spread ≥ 50 ✅ - If spread is only 30, won't trigger even if price condition is met --- @@ -251,15 +262,16 @@ Minimum Price: 0.30 Maximum Price: 0.90 Investment Mode: By Ratio Ratio: 20% -Minimum Spread Mode: Auto +Spread Mode: Auto +Spread Direction: Min spread Enabled: On ``` **Explanation**: -- System automatically calculates minimum spread based on historical 20 K-lines +- System automatically calculates effective spread from the last 20 K-lines - 2 ~ 8 minutes after cycle start: Only triggers when both conditions are met: 1. Price is between 0.30 ~ 0.90 ✅ - 2. Binance BTC/USDC spread ≥ system-calculated minimum spread ✅ + 2. Spread direction is "Min spread" and Binance spread ≥ system-calculated effective spread ✅ --- @@ -271,7 +283,7 @@ Enabled: On 1. ✅ Current time is within the time window 2. ✅ Market price is within [Minimum Price, Maximum Price] range 3. ✅ This cycle hasn't triggered yet (maximum one trigger per cycle) -4. ✅ If minimum spread is set, Binance spread must also meet the condition +4. ✅ If spread filter is set, Binance spread and spread direction must both be satisfied ### Q2: Why didn't my strategy trigger? @@ -279,7 +291,7 @@ Enabled: On 1. **Time window incorrect**: Current time is not within the set time window 2. **Price not in range**: Market price is not within [Minimum Price, Maximum Price] range 3. **Already triggered this cycle**: This cycle has already triggered once, won't trigger again -4. **Spread not met**: If minimum spread is set, Binance spread hasn't reached the requirement +4. **Spread not met**: If spread filter is set, Binance spread or spread direction requirement is not satisfied 5. **Insufficient account balance**: Account balance is less than the set investment amount 6. **Strategy not enabled**: Check if strategy's enabled status is "On" @@ -305,18 +317,22 @@ Enabled: On - Example: Set 10%, when account has 100 USDC, invest 10 USDC, after balance becomes 90 USDC, next trigger invests 9 USDC - Automatically adapts to balance changes -### Q5: What's the use of the minimum spread feature? +### Q5: What's the use of the spread filter feature? -**A**: Minimum spread filters market volatility, only triggering when Binance BTC/USDC price movement reaches a certain magnitude. +**A**: The spread filter decides whether to trigger based on Binance BTC/USDC K-line volatility. It supports two directions. -**Scenario**: -- If market volatility is small (spread < set value), may not be worth trading -- By setting minimum spread, can avoid triggering when volatility is too small +**Min spread** (trigger when spread **≥** set value): +- Avoids triggering when volatility is too small +- Example: Set 30, only triggers when spread ≥ 30 + +**Max spread** (trigger when spread **≤** set value): +- Avoids triggering when volatility is too high (lower risk) +- Example: Set 50, only triggers when spread ≤ 50 **Three mode selection suggestions**: - **None**: Not concerned about Binance price volatility, only watching Polymarket price -- **Fixed**: You know the expected spread threshold (e.g., at least 30 USDC movement is worth trading) -- **Auto**: Want automatic adjustment based on historical data, no manual setup needed +- **Fixed**: You know the expected spread threshold (use with Min or Max spread direction) +- **Auto**: Want effective spread calculated from historical data without setting a specific value ### Q6: Why is it recommended to use a separate wallet? @@ -375,11 +391,12 @@ Enabled: On - ⚠️ Ensure sufficient account balance to avoid order failures - ⚠️ Ratio mode: Note the impact of account balance changes on investment amount -### 6.5 Minimum Spread Settings +### 6.5 Spread Filter Settings -- ⚠️ Fixed mode: Need to fill reasonable spread value (unit: USDC) -- ⚠️ Auto mode: System automatically calculates at cycle start, no manual setup needed -- ⚠️ Setting spread too large may make strategy difficult to trigger +- ⚠️ Spread direction: Min spread means "trigger when ≥"; Max spread means "trigger when ≤". Choose according to your need. +- ⚠️ Fixed mode: Need to fill a reasonable spread value (unit: USDC) +- ⚠️ Auto mode: System calculates effective spread within the window, no manual value needed +- ⚠️ Overly strict spread (min spread too high or max spread too low) may make the strategy rarely trigger ### 6.6 Other Notes @@ -420,7 +437,7 @@ You can modify strategy parameters at any time: - Time window - Price range - Investment mode -- Minimum spread settings +- Spread filter (mode, direction, value) - Enabled status **Note**: Modified strategies take effect in the next cycle. @@ -441,7 +458,7 @@ Crypto Tail Strategy is a powerful automated trading tool that can help you: 1. **Automated Trading**: No need for manual monitoring, system executes automatically 2. **Precise Control**: Precisely control trigger conditions through time windows and price ranges 3. **Flexible Configuration**: Supports both ratio and fixed amount investment modes -4. **Risk Filtering**: Filter market volatility through minimum spread feature +4. **Risk Filtering**: Control volatility conditions through spread filter (min spread / max spread) **Usage Recommendations**: - For first-time users, start with simple strategies (no spread filter) diff --git a/docs/zh/crypto-tail-strategy-flow.md b/docs/crypto-tail-strategy/zh/crypto-tail-strategy-flow.md similarity index 100% rename from docs/zh/crypto-tail-strategy-flow.md rename to docs/crypto-tail-strategy/zh/crypto-tail-strategy-flow.md diff --git a/docs/zh/crypto-tail-strategy-market-data.md b/docs/crypto-tail-strategy/zh/crypto-tail-strategy-market-data.md similarity index 100% rename from docs/zh/crypto-tail-strategy-market-data.md rename to docs/crypto-tail-strategy/zh/crypto-tail-strategy-market-data.md diff --git a/docs/zh/crypto-tail-strategy-min-spread-flow.md b/docs/crypto-tail-strategy/zh/crypto-tail-strategy-min-spread-flow.md similarity index 100% rename from docs/zh/crypto-tail-strategy-min-spread-flow.md rename to docs/crypto-tail-strategy/zh/crypto-tail-strategy-min-spread-flow.md diff --git a/docs/zh/crypto-tail-strategy-tasks.md b/docs/crypto-tail-strategy/zh/crypto-tail-strategy-tasks.md similarity index 100% rename from docs/zh/crypto-tail-strategy-tasks.md rename to docs/crypto-tail-strategy/zh/crypto-tail-strategy-tasks.md diff --git a/docs/zh/crypto-tail-strategy-ui-spec.md b/docs/crypto-tail-strategy/zh/crypto-tail-strategy-ui-spec.md similarity index 100% rename from docs/zh/crypto-tail-strategy-ui-spec.md rename to docs/crypto-tail-strategy/zh/crypto-tail-strategy-ui-spec.md diff --git a/docs/zh/crypto-tail-strategy-user-guide.md b/docs/crypto-tail-strategy/zh/crypto-tail-strategy-user-guide.md similarity index 80% rename from docs/zh/crypto-tail-strategy-user-guide.md rename to docs/crypto-tail-strategy/zh/crypto-tail-strategy-user-guide.md index 75b914d..b4eac4e 100644 --- a/docs/zh/crypto-tail-strategy-user-guide.md +++ b/docs/crypto-tail-strategy/zh/crypto-tail-strategy-user-guide.md @@ -120,16 +120,24 @@ - 最小下单金额:至少 1 USDC - 如果账户余额不足,下单会失败并记录失败原因 -### 3.5 最小价差(高级功能) +### 3.5 价差过滤(高级功能) -最小价差功能用于过滤市场波动,只在币安 BTC/USDC 价格波动达到一定幅度时才触发。 +价差功能用于根据币安 BTC/USDC 的 K 线波动决定是否触发,支持「最小价差」与「最大价差」两种方向。 | 参数 | 说明 | 必填 | 示例 | |------|------|------|------| -| **最小价差模式** | 选择价差校验方式 | ✅ | 无 / 固定 / 自动 | -| **最小价差值** | 固定模式时填写 | 条件必填 | 30 | +| **价差模式** | 选择价差校验方式 | ✅ | 无 / 固定 / 自动 | +| **价差方向** | 最小价差(≥ 触发)或 最大价差(≤ 触发) | ✅ | 最小价差 / 最大价差 | +| **价差值** | 固定模式时填写(单位:USDC) | 条件必填 | 30 | -**三种模式说明**: +**价差方向说明**: + +- **最小价差**:当币安 K 线价差 **≥** 设定值时才触发 + - 适合:只在波动「足够大」时交易(避免波动过小、不值得进场) +- **最大价差**:当币安 K 线价差 **≤** 设定值时才触发 + - 适合:只在波动「足够小」时交易(避免波动过大、风险高) + +**三种价差模式**: **模式一:无 (NONE)** - 不进行价差校验 @@ -137,24 +145,26 @@ - **适合**:不关心币安价格波动,只看 Polymarket 价格 **模式二:固定 (FIXED)** -- 设置一个固定的最小价差值(单位:USDC) -- 当币安 BTC/USDC 的 K 线价差(|收盘价 - 开盘价|)≥ 设定值时,才触发 -- **示例**:设置 30 - - 周期内币安 K 线价差 ≥ 30:触发 ✅ - - 周期内币安 K 线价差 < 30:不触发 -- **适合**:您知道期望的价差阈值 +- 设置一个固定的价差值(单位:USDC) +- **最小价差**:当 K 线价差 ≥ 设定值时触发 + - 示例:设定 30,价差 ≥ 30 触发 ✅,价差 < 30 不触发 +- **最大价差**:当 K 线价差 ≤ 设定值时触发 + - 示例:设定 50,价差 ≤ 50 触发 ✅,价差 > 50 不触发 +- **适合**:您有明确的价差阈值 **模式三:自动 (AUTO)** -- 系统根据历史 20 根 K 线自动计算最小价差 +- 系统根据历史 20 根 K 线自动计算基准价差 - 计算逻辑: 1. 获取最近 20 根 K 线(与策略周期一致) 2. 按方向筛选(Up 方向只看上涨的 K 线,Down 方向只看下跌的 K 线) 3. 剔除异常值(使用 IQR 方法) - 4. 计算平均价差 × 0.8 作为最小价差 -- **适合**:希望根据历史数据自动调整,无需手动设置 + 4. 计算平均价差 × 0.8 作为有效价差 +- **最小价差**:K 线价差 ≥ 有效价差时触发 +- **最大价差**:K 线价差 ≤ 有效价差时触发 +- **适合**:希望根据历史数据自动调整,无需手动设具体数值 **价差说明**: -- 价差 = |收盘价 - 开盘价| +- 价差 = |收盘价 - 开盘价|(币安 BTC/USDC 当根 K 线) - 例如:开盘价 50000,收盘价 50030,价差 = 30 - 价差越大,说明该周期内价格波动越大 @@ -176,7 +186,7 @@ 最高价:0.60 投入方式:固定金额 固定金额:10 USDC -最小价差模式:无 +价差模式:无 启用状态:开启 ``` @@ -200,7 +210,7 @@ 最高价:0.70 投入方式:按比例 比例:15% -最小价差模式:无 +价差模式:无 启用状态:开启 ``` @@ -224,15 +234,16 @@ 最高价:0.80 投入方式:固定金额 固定金额:20 USDC -最小价差模式:固定 -最小价差值:50 +价差模式:固定 +价差方向:最小价差 +价差值:50 启用状态:开启 ``` **说明**: - 周期开始后 10~14 分钟:同时满足以下条件才触发 1. 价格在 0.50~0.80 之间 ✅ - 2. 币安 BTC/USDC 价差 ≥ 50 ✅ + 2. 价差方向为「最小价差」且币安价差 ≥ 50 ✅ - 如果价差只有 30,即使价格满足也不会触发 --- @@ -251,15 +262,16 @@ 最高价:0.90 投入方式:按比例 比例:20% -最小价差模式:自动 +价差模式:自动 +价差方向:最小价差 启用状态:开启 ``` **说明**: -- 系统会根据历史 20 根 K 线自动计算最小价差 +- 系统会根据历史 20 根 K 线自动计算有效价差 - 周期开始后 2~8 分钟:同时满足以下条件才触发 1. 价格在 0.30~0.90 之间 ✅ - 2. 币安 BTC/USDC 价差 ≥ 系统计算的最小价差 ✅ + 2. 价差方向为「最小价差」且币安价差 ≥ 系统计算的有效价差 ✅ --- @@ -271,7 +283,7 @@ 1. ✅ 当前时间在时间窗口内 2. ✅ 市场价格在 [最低价, 最高价] 区间内 3. ✅ 本周期尚未触发过(每周期最多触发一次) -4. ✅ 如果设置了最小价差,币安价差也需要满足条件 +4. ✅ 如果设置了价差过滤,币安价差与价差方向需同时满足条件 ### Q2:为什么我的策略没有触发? @@ -279,7 +291,7 @@ 1. **时间窗口不对**:当前时间不在设定的时间窗口内 2. **价格不在区间**:市场价格不在 [最低价, 最高价] 范围内 3. **本周期已触发**:该周期已经触发过一次,不会再触发 -4. **价差不满足**:如果设置了最小价差,币安价差未达到要求 +4. **价差不满足**:如果设置了价差过滤,币安价差或价差方向未满足要求 5. **账户余额不足**:账户余额小于设定的投入金额 6. **策略未启用**:检查策略的启用状态是否为"开启" @@ -305,18 +317,22 @@ - 例如:设置 10%,账户有 100 USDC 时投入 10 USDC,余额变为 90 USDC 后下次投入 9 USDC - 自动适应余额变化 -### Q5:最小价差功能有什么用? +### Q5:价差过滤功能有什么用? -**A**:最小价差用于过滤市场波动,只在币安 BTC/USDC 价格波动达到一定幅度时才触发。 +**A**:价差过滤根据币安 BTC/USDC 的 K 线波动决定是否触发,支持两种方向。 -**场景**: -- 如果市场波动很小(价差 < 设定值),可能不值得交易 -- 通过设置最小价差,可以避免在波动过小时触发 +**最小价差**(价差 ≥ 设定值才触发): +- 波动太小时不触发,避免在波动不足时进场 +- 例如:设定 30,只有价差 ≥ 30 才触发 + +**最大价差**(价差 ≤ 设定值才触发): +- 波动太大时不触发,避免在波动过大、风险高时进场 +- 例如:设定 50,只有价差 ≤ 50 才触发 **三种模式选择建议**: - **无**:不关心币安价格波动,只看 Polymarket 价格 -- **固定**:您知道期望的价差阈值(例如:至少波动 30 USDC 才值得交易) -- **自动**:希望根据历史数据自动调整,无需手动设置 +- **固定**:您知道期望的价差阈值(配合最小/最大价差方向使用) +- **自动**:希望根据历史数据自动计算有效价差,无需手动设具体数值 ### Q6:为什么建议使用单独的钱包? @@ -375,11 +391,12 @@ - ⚠️ 确保账户余额充足,避免下单失败 - ⚠️ 按比例模式:注意账户余额变化对投入金额的影响 -### 6.5 最小价差设置 +### 6.5 价差过滤设置 +- ⚠️ 价差方向:最小价差为「≥ 触发」,最大价差为「≤ 触发」,请按需求选择 - ⚠️ 固定模式:需要填写合理的价差值(单位:USDC) -- ⚠️ 自动模式:系统会在周期开始时自动计算,无需手动设置 -- ⚠️ 价差设置过大可能导致策略难以触发 +- ⚠️ 自动模式:系统会在周期内按窗口进度自动计算有效价差,无需手动设置 +- ⚠️ 价差设定过严(最小价差设得过大或最大价差设得过小)可能导致策略难以触发 ### 6.6 其他注意事项 @@ -420,7 +437,7 @@ - 时间窗口 - 价格区间 - 投入方式 -- 最小价差设置 +- 价差过滤(模式、方向、数值) - 启用状态 **注意**:修改后的策略会在下一个周期生效。 @@ -441,7 +458,7 @@ 1. **自动化交易**:无需手动盯盘,系统自动执行 2. **精准控制**:通过时间窗口和价格区间精确控制触发条件 3. **灵活配置**:支持比例和固定金额两种投入方式 -4. **风险过滤**:通过最小价差功能过滤市场波动 +4. **风险过滤**:通过价差过滤(最小价差/最大价差)控制波动条件 **使用建议**: - 初次使用建议从简单策略开始(无价差过滤) diff --git a/frontend/src/pages/CryptoTailStrategyList.tsx b/frontend/src/pages/CryptoTailStrategyList.tsx index 3ff8c37..5d03d9a 100644 --- a/frontend/src/pages/CryptoTailStrategyList.tsx +++ b/frontend/src/pages/CryptoTailStrategyList.tsx @@ -539,7 +539,7 @@ const CryptoTailStrategyList: React.FC = () => { const getGuideUrl = () => { const { githubRepoUrl } = getVersionInfo() const lang = i18n.language === 'zh-CN' || i18n.language === 'zh-TW' ? 'zh' : 'en' - return `${githubRepoUrl}/blob/main/docs/${lang}/crypto-tail-strategy-user-guide.md` + return `${githubRepoUrl}/blob/main/docs/crypto-tail-strategy/${lang}/crypto-tail-strategy-user-guide.md` } return (