PolyHermes/docs/crypto-tail-strategy/en/crypto-tail-strategy-user-guide.md

Crypto Spread Strategy Configuration Guide

Part 1: What is Crypto Spread Strategy?

Crypto Spread Strategy is an automated trading strategy designed specifically for Polymarket crypto markets' 5-minute or 15-minute "Up or Down" markets.

Core Logic: Within a specified time window, when the market price enters your set price range, the system will automatically buy at a fixed price (0.99) without manual operation.

Use Cases:

• You want to capture price fluctuations at the end of market cycles
• You want to automate trading execution and avoid manual monitoring
• You have some judgment about market trends and want to set conditions for automatic triggering

---

Part 2: How the Strategy Works

2.1 Basic Flow

Cycle Start → Within Time Window → Price Enters Range → Auto Order

1. Cycle: Each market runs on fixed cycles (5 minutes or 15 minutes)

   • 5-minute market: Every 5 minutes is a cycle (e.g., 10:00, 10:05, 10:10...)
   • 15-minute market: Every 15 minutes is a cycle (e.g., 10:00, 10:15, 10:30...)

2. Time Window: You can set a time period within the cycle

   • Example: 15-minute market, set window to "3 minutes ~ 12 minutes"
   • Meaning: Only triggers between the 3rd and 12th minute after cycle start

3. Price Range: Set the trigger price range

   • Example: Minimum price 0.50, Maximum price 0.80
   • Meaning: Only triggers when market price is between 0.50 ~ 0.80

4. Auto Order: After conditions are met, the system automatically buys at price 0.99

2.2 Important Limitations

• Maximum one trigger per cycle: Within the same cycle, even if conditions are met multiple times, only one order is placed
• Fixed order price: All orders are submitted at price 0.99
• Requires separate wallet: It's recommended to use a dedicated wallet for crypto spread strategies to avoid conflicts with other operations (manual trading, copy trading, etc.)

---

Part 3: Parameter Details

3.1 Basic Parameters

Parameter	Description	Required	Example
Account	Select the wallet account for trading	✅	Account A
Strategy Name	Name your strategy for easy identification	❌	"BTC 15min Crypto Spread Strategy"
Market	Select the market to trade (5-minute or 15-minute)	✅	btc-updown-15m

3.2 Cycle Settings

Parameter	Description	Required	Example
Cycle Length	Automatically determined by selected market	✅	15 minutes (900 seconds)
Time Window Start	Minutes after cycle start to begin monitoring	✅	3 min 0 sec
Time Window End	Minutes after cycle start to stop monitoring	✅	12 min 0 sec

Time Window Explanation:

• 5-minute market: Can choose any time period within 0 ~ 5 minutes
• 15-minute market: Can choose any time period within 0 ~ 15 minutes
• Start time must ≤ End time
• Times outside the window won't trigger even if price conditions are met

Example:

• 15-minute market, window "3 min 0 sec ~ 12 min 0 sec"
  • 0 ~ 3 minutes after cycle start: Not monitoring
  • 3 ~ 12 minutes after cycle start: Monitoring price, triggers when conditions met
  • 12 ~ 15 minutes after cycle start: Not monitoring

3.3 Price Range

Parameter	Description	Required	Range	Example
Minimum Price (minPrice)	Minimum trigger price	✅	0 ~ 1	0.50
Maximum Price (maxPrice)	Maximum trigger price	❌	0 ~ 1, default 1	0.80

Price Range Explanation:

• Price range is a decimal between 0 ~ 1
• Only triggers when market price is within [Minimum Price, Maximum Price]
• If maximum price is not filled, defaults to 1.0 (triggers as long as price ≥ minimum price)

Example:

• Minimum price 0.50, Maximum price 0.80
  • Price 0.45: Not triggered (below minimum)
  • Price 0.60: Triggered ✅ (within range)
  • Price 0.85: Not triggered (above maximum)

3.4 Investment Amount

Parameter	Description	Required	Example
Investment Mode	Choose ratio or fixed amount	✅	Ratio / Fixed Amount
Ratio (%)	Percentage of account balance to invest	Conditionally required	10% (Account has 100 USDC, invest 10 USDC)
Fixed Amount (USDC)	Fixed amount to invest each time	Conditionally required	50 USDC

Investment Mode Explanation:

Mode 1: By Ratio (RATIO)

• Each trigger invests a percentage of current available balance
• Example: Account has 100 USDC, set ratio to 10%
  • 1st trigger: Invest 10 USDC
  • 2nd trigger: If balance becomes 90 USDC, invest 9 USDC
• Advantages: Automatically adapts to account balance changes
• Disadvantages: Investment amount may vary each time

Mode 2: Fixed Amount (FIXED)

• Each trigger invests a fixed specified amount
• Example: Set fixed amount to 50 USDC
  • Every trigger invests 50 USDC
• Advantages: Stable investment amount, easy to manage
• Disadvantages: Need to ensure sufficient account balance

Notes:

• Minimum order amount: At least 1 USDC
• If account balance is insufficient, order will fail and record failure reason

3.5 Spread Filter (Advanced Feature)

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

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
• Triggers as long as time window and price range conditions are met
• Suitable for: Not concerned about Binance price volatility, only watching Polymarket price

Mode 2: Fixed (FIXED)

• 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 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 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| (Binance BTC/USDC for that K-line)
• Example: Open price 50000, close price 50030, spread = 30
• Larger spread means greater price volatility in that cycle

---

Part 4: Configuration Examples

Example 1: Simple Strategy (5-minute Market)

Scenario: In the last 2 minutes of a 5-minute market, if price is below 0.60, automatically buy 10 USDC

Configuration:

Account: Account A
Strategy Name: BTC 5min Simple Strategy
Market: btc-updown-5m
Time Window: 3 min 0 sec ~ 5 min 0 sec
Minimum Price: 0.00
Maximum Price: 0.60
Investment Mode: Fixed Amount
Fixed Amount: 10 USDC
Spread Mode: None
Enabled: On

Explanation:

• 0 ~ 3 minutes after cycle start: Not monitoring
• 3 ~ 5 minutes after cycle start: If price ≤ 0.60, automatically buy 10 USDC

---

Example 2: Ratio Investment Strategy (15-minute Market)

Scenario: In the middle segment (5 ~ 10 minutes) of a 15-minute market, if price is between 0.40 ~ 0.70, invest 15% of account balance

Configuration:

Account: Account B
Strategy Name: BTC 15min Ratio Strategy
Market: btc-updown-15m
Time Window: 5 min 0 sec ~ 10 min 0 sec
Minimum Price: 0.40
Maximum Price: 0.70
Investment Mode: By Ratio
Ratio: 15%
Spread Mode: None
Enabled: On

Explanation:

• Assuming account balance is 100 USDC
• 5 ~ 10 minutes after cycle start: If price is between 0.40 ~ 0.70, automatically buy about 15 USDC (100 × 15%)

---

Example 3: Strategy with Spread Filter (15-minute Market)

Scenario: In the latter segment (10 ~ 14 minutes) of a 15-minute market, if price is between 0.50 ~ 0.80 and Binance spread ≥ 50, invest 20 USDC

Configuration:

Account: Account C
Strategy Name: BTC 15min Spread Strategy
Market: btc-updown-15m
Time Window: 10 min 0 sec ~ 14 min 0 sec
Minimum Price: 0.50
Maximum Price: 0.80
Investment Mode: Fixed Amount
Fixed Amount: 20 USDC
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. Spread direction is "Min spread" and Binance spread ≥ 50 ✅
• If spread is only 30, won't trigger even if price condition is met

---

Example 4: Auto Spread Strategy (15-minute Market)

Scenario: In the early segment (2 ~ 8 minutes) of a 15-minute market, if price is between 0.30 ~ 0.90, invest 20% of account balance, spread calculated automatically by system

Configuration:

Account: Account D
Strategy Name: BTC 15min Auto Spread Strategy
Market: btc-updown-15m
Time Window: 2 min 0 sec ~ 8 min 0 sec
Minimum Price: 0.30
Maximum Price: 0.90
Investment Mode: By Ratio
Ratio: 20%
Spread Mode: Auto
Spread Direction: Min spread
Enabled: On

Explanation:

• 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. Spread direction is "Min spread" and Binance spread ≥ system-calculated effective spread ✅

---

Part 5: Frequently Asked Questions

Q1: When will the strategy trigger?

A: All of the following conditions must be met simultaneously:

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 spread filter is set, Binance spread and spread direction must both be satisfied

Q2: Why didn't my strategy trigger?

Possible reasons:

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 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"

Q3: What does "maximum one trigger per cycle" mean?

A: Within each cycle (5 minutes or 15 minutes), even if conditions are met multiple times, only one order is placed.

Example:

• 15-minute market, cycle starts at 10:00
• At 10:05, price meets condition, triggers order ✅
• At 10:08, price meets condition again, but won't place another order (already triggered this cycle)
• At 10:15, new cycle starts, can trigger again

Q4: What's the difference between fixed amount and ratio?

Fixed Amount:

• Invests the same amount each trigger
• Example: Set 50 USDC, every trigger is 50 USDC
• Need to ensure sufficient account balance

By Ratio:

• Invests a percentage of account balance each trigger
• 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 spread filter feature?

A: The spread filter decides whether to trigger based on Binance BTC/USDC K-line volatility. It supports two directions.

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 (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?

A: To avoid the following issues:

1. Balance changes: If wallet is also used for manual trading, balance changes may affect strategy execution
2. Position conflicts: Manual trading and strategy trading may conflict
3. Management confusion: Difficult to distinguish which orders are from strategy vs manual

Recommendation: Create a dedicated wallet, only for crypto spread strategies.

Q7: Why is the order price fixed at 0.99?

A: This is a design feature of the strategy:

• 0.99 is the highest price in the market (close to 1.0)
• Buying at the highest price ensures orders execute quickly
• Although buying price is higher, the strategy's core is capturing market volatility, not pursuing optimal price

Q8: Does the strategy depend on auto-redeem functionality?

A: Yes, crypto spread strategy depends on auto-redeem functionality.

Reasons:

• Strategy orders create positions after execution
• These positions need to be automatically redeemed after market settlement
• If auto-redeem is not configured, positions may not be redeemed in time

Configuration Requirements:

• Configure Builder API Key in "System Settings"
• Enable auto-redeem functionality

---

Part 6: Important Notes

6.1 Account Requirements

• ✅ Account must have API Key, API Secret, API Passphrase configured
• ✅ Account must have sufficient USDC balance
• ✅ Recommended to use a dedicated wallet to avoid conflicts with other operations

6.2 Time Window Settings

• ⚠️ Start time must ≤ End time
• ⚠️ Time window cannot exceed cycle length (5-minute market ≤ 5 minutes, 15-minute market ≤ 15 minutes)
• ⚠️ Recommended to set reasonable time windows, avoid triggering at cycle start or end

6.3 Price Range Settings

• ⚠️ Minimum price must ≤ Maximum price
• ⚠️ Price range is a decimal between 0 ~ 1
• ⚠️ Recommended to set reasonable price ranges based on market conditions

6.4 Investment Amount Settings

• ⚠️ Minimum order amount: At least 1 USDC
• ⚠️ Ensure sufficient account balance to avoid order failures
• ⚠️ Ratio mode: Note the impact of account balance changes on investment amount

6.5 Spread Filter Settings

• ⚠️ 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

• ⚠️ Strategy is enabled by default after creation, can disable "Enabled Status" if need to pause
• ⚠️ Maximum one trigger per cycle, set trigger conditions reasonably
• ⚠️ Strategy depends on auto-redeem functionality, ensure Builder API Key is configured
• ⚠️ Recommended to regularly check trigger records to understand strategy execution

---

Part 7: Strategy Management

7.1 View Strategy List

On the "Crypto Spread Strategy" page, you can view all strategies:

• Strategy name
• Market information
• Time window
• Price range
• Investment mode
• Enabled status
• Last trigger time
• Statistics like total profit, win rate

7.2 View Trigger Records

Click on a strategy to view detailed trigger records:

• Trigger time
• Market price
• Investment amount
• Order ID
• Order status (success/fail)
• Settlement information (profit/loss, win rate, etc.)

7.3 Edit Strategy

You can modify strategy parameters at any time:

• Time window
• Price range
• Investment mode
• Spread filter (mode, direction, value)
• Enabled status

Note: Modified strategies take effect in the next cycle.

7.4 Delete Strategy

After deleting a strategy:

• Strategy configuration is deleted
• Historical trigger records are retained
• Already placed orders are not affected

---

Part 8: Summary

Crypto Spread 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: Control volatility conditions through spread filter (min spread / max spread)

Usage Recommendations:

• For first-time users, start with simple strategies (no spread filter)
• After familiarizing, try adding spread filter features
• Regularly check trigger records, adjust strategy parameters based on actual situation
• Use a dedicated wallet to avoid conflicts with other operations

Happy Trading! 🚀