Back to Nofx

πŸ“– NoFx Prompt Writing Guide

docs/prompt-guide.md

latest41.2 KB
Original Source

πŸ“– NoFx Prompt Writing Guide

Version: v1.0 Last Updated: 2025-01-09 Compatible System Version: NoFx v0.x+


πŸ“š Table of Contents


Beginners: Quick Start β†’ Official Templates β†’ Quality Checklist Intermediate Users: Core Concepts β†’ Field Reference β†’ System Constraints β†’ Common Errors Advanced Users: Advanced Topics β†’ Mode 3 β†’ Debugging Guide


πŸš€ Quick Start (5 Minutes)

What is a Prompt?

A Prompt is the "work instruction" you give to the AI trader, determining how the AI analyzes the market and makes trading decisions.

Three Usage Methods

Method 1: Use Official Templates (Recommended for Beginners)

Steps:

  1. Choose an official template (Conservative / Balanced / Aggressive)
  2. Copy content to prompts/default.txt
  3. Restart the system and start trading

Suitable for: Beginners who want to start quickly Time required: 2 minutes

Method 2: Add Custom Strategy on Top of Official Template (Recommended)

Steps:

  1. Keep prompts/default.txt unchanged
  2. Add your strategy in the web interface's "Custom Prompt"
  3. Turn OFF "Override Base Prompt" switch (override_base_prompt = false)

Effect Explanation:

Final Prompt = Official Base Strategy (Risk Control + Format) + Your Custom Strategy
               ↑                                                 ↑
          System guarantees safety                         Your trading ideas

Suitable for: Intermediate users who want to keep risk controls but add their own ideas Time required: 10-30 minutes

Method 3: Complete Customization (Advanced)

Steps:

  1. Write a complete Prompt (including all risk control rules)
  2. Turn ON "Override Base Prompt" switch (override_base_prompt = true)
  3. ⚠️ You are responsible for all risk controls and output formats

Effect Explanation:

Final Prompt = Your Custom Strategy (Complete Replacement)
               ↑
     You need to ensure safety and correct format yourself

Important Warnings:

  • ❌ When enabled, the system will NOT automatically add risk control rules
  • ❌ Incorrect output format will cause trading failures
  • ⚠️ Only suitable for advanced users who fully understand the system mechanism

Suitable for: Advanced users who fully understand the system mechanism Time required: 1-2 hours

Get Started Now

πŸ‘‰ Recommended for Beginners: Jump to Official Template Library and choose a template πŸ‘‰ Intermediate Optimization: Continue reading Available Fields Reference πŸ‘‰ Advanced Customization: Read Complete Customization Guide


πŸ’‘ Core Concepts

How Prompts Work

NoFx builds a message containing market data every 3 minutes to send to the AI:

mermaid
graph LR
    A[Your Prompt
Strategy Instructions] --> B[AI Model]
    C[Market Data
Auto-generated] --> B
    B --> D[Chain of Thought Analysis]
    B --> E[Trading Decision JSON]

Workflow:

  1. System Prompt (System): Strategy instructions you write
  2. User Prompt (User): Market data automatically generated by the system
  3. AI Response (Response): AI's analysis and decisions

Three Components of a Prompt

1. Core Strategy (Written by You)

Defines the AI's trading philosophy, risk preference, and decision criteria

Example:

You are a conservative trader who only opens positions in high-certainty opportunities.
Entry conditions: Confidence β‰₯ 85, multiple indicator convergence.

2. Hard Constraints (Automatically Added by System)

  • Risk-reward ratio β‰₯ 1:3
  • Maximum 3 positions simultaneously
  • Leverage limits (BTC/ETH 20x, altcoins 5x)
  • Margin usage rate ≀ 90%

⚠️ Methods 1 & 2: These constraints are automatically added and cannot be overridden ⚠️ Method 3: You must include these constraints in your Prompt

3. Output Format (Automatically Added by System)

Requires AI to output decisions using XML tags and JSON format

Example Output:

xml
<reasoning>
BTC broke support, MACD death cross, volume increased...
</reasoning>

<decision>
```json
[
  {
    "symbol": "BTCUSDT",
    "action": "open_short",
    "leverage": 10,
    "position_size_usd": 5000,
    "stop_loss": 97000,
    "take_profit": 91000,
    "confidence": 85
  }
]
</decision> ```

Automatic Market Data Transmission

You don't need to request data in the Prompt; the system automatically transmits:

βœ… System Automatically Provides:

  • Current time, running cycle
  • Account equity, balance, P&L
  • All position details
  • BTC market conditions
  • Complete technical data for candidate coins
  • Sharpe ratio performance metrics

❌ You Don't Need to Write:

Please analyze BTC price and MACD...  # System already provides
Please tell me current positions...   # System already provides

βœ… You Should Write:

Focus on BTC trend as market indicator
When MACD death cross and volume increases, consider shorting opportunities

πŸ“‹ Available Fields Reference

The system automatically passes the following data to the AI, which you can reference in your Prompt:

System Status

Field NameDescriptionExample
TimeUTC time2025-01-15 10:30:00 UTC
CycleSystem run cycle count#142 (142nd decision)
RuntimeSystem run minutes426 minutes

Actual Output Example:

Time: 2025-01-15 10:30:00 UTC | Cycle: #142 | Runtime: 426 minutes

Account Information

Field NameDescriptionUnitExample
EquityTotal account assetsUSDT1250.50
BalanceAvailable balanceUSDT850.30
Balance %Available/Equity%68.0%
P&LTotal P&L percentage%+15.2%
MarginMargin usage rate%32.0%
PositionsCurrent position countcount2

Actual Output Example:

Account: Equity 1250.50 | Balance 850.30 (68.0%) | P&L +15.2% | Margin 32.0% | Positions 2

Prompt Reference Example:

Stop opening new positions when Balance % below 20%
Consider reducing positions when Margin usage exceeds 80%

Position Information (⭐Core Fields)

Field NameDescriptionUnitCalculationExample
SymbolTrading pair--BTCUSDT
SideLong/Short--LONG
EntryOpening priceUSDT-95000.00
CurrentMark priceUSDT-96500.00
P&L %Unrealized P&L %%w/ leverage+2.38%
P&L AmountUnrealized P&LUSDTActual USD+59.50
Peak %Historical peak P&L%%w/ leverage+5.00%
LeverageLeverage multiplex-5
MarginUsed marginUSDT-500.00
LiquidationLiquidation priceUSDT-88000.00
DurationHolding timemin/hourCalculated2h 35min

⚠️ Important Distinctions:

  • P&L % = Return with leverage (5x leverage, 1% price change = 5% P&L)
  • P&L Amount = Actual dollars gained/lost (e.g., +59.50 USDT)
  • Peak % = Highest P&L % achieved during holding (for drawdown calculation)

Actual Output Example:

1. BTCUSDT LONG | Entry 95000.0000 Current 96500.0000 | P&L +2.38% | P&L Amount +59.50 USDT | Peak % 5.00% | Leverage 5x | Margin 500 | Liquidation 88000.0000 | Duration 2h 35min

Prompt Reference Examples (βœ… Correct):

βœ… When P&L Amount drawdown exceeds 50% of Peak %, take partial profit
βœ… If P&L drops from +5% to +2%, that's 60% drawdown, consider reducing position
βœ… If Duration exceeds 4 hours but P&L Amount still negative, consider stop loss

Prompt Reference Examples (❌ Wrong):

❌ When unrealized_pnl exceeds peak_pnl_pct...  # Wrong field names
❌ When P&L exceeds 5%...  # Ambiguous - P&L % or P&L Amount?

Calculated Formula Fields

Based on the above fields, you can use these calculations in your Prompt:

CalculationFormulaDescriptionExample
True ROI(P&L Amount / Margin) Γ— 100%Actual return on margin(59.50/500)Γ—100% = 11.9%
Drawdown(Peak % - Current P&L) / Peak % Γ— 100%Drawdown from peak(5%-2.38%)/5% = 52.4%
Liquidation Distance`(Current - Liquidation) / CurrentΓ— 100%`

Prompt Reference Example:

Calculate True ROI = P&L Amount / Margin
If True ROI exceeds 10%, take partial profit to lock in gains

Calculate Drawdown = (Peak % - Current P&L) / Peak %
If Drawdown exceeds 50%, significant profit giveback, consider reducing position

BTC Market Data

Field NameDescriptionUnitExample
BTC PriceCurrent priceUSDT96500.00
1h Change1-hour change%+1.25%
4h Change4-hour change%-2.15%
MACDMACD indicator-0.0024
RSIRSI(7) indicator-62.50

Actual Output Example:

BTC: 96500.00 (1h: +1.25%, 4h: -2.15%) | MACD: 0.0024 | RSI: 62.50

Prompt Reference Example:

BTC as market indicator:
- If BTC 4h Change < -5%, market turning bearish, be cautious on altcoin longs
- If BTC MACD death cross and RSI < 30, potential oversold bounce

Complete Market Data

Each coin includes complete technical data:

  • Price sequence (3-minute candles)
  • EMA20 sequence
  • MACD sequence
  • RSI7/RSI14 sequences
  • Volume sequence
  • Open Interest (OI) sequence
  • Funding rate

⚠️ Note: These are sequence data (arrays), automatically formatted by system, you don't need to specify field names.

Prompt Reference Example:

Analyze price sequences to identify support/resistance levels
Observe EMA20 trend to determine long/short direction
MACD sequence golden/death cross as signal confirmation
OI rapid growth + price increase = bullish signal

Performance Metrics

Field NameDescriptionRangeInterpretation
Sharpe RatioRisk-adjusted returns-∞ ~ +∞>1 excellent, 0~1 normal, <0 losing

Actual Output Example:

## πŸ“Š Sharpe Ratio: 0.85

Prompt Reference Example:

Adjust strategy based on Sharpe Ratio:
- Sharpe < -0.5: Stop trading, observe for at least 18 minutes
- Sharpe -0.5~0: Only trade confidence >80
- Sharpe 0~0.7: Maintain current strategy
- Sharpe > 0.7: Can moderately increase position size

Field Naming Consistency Principle

βœ… Correct Approach: Use natural language labels from output

P&L Amount, Peak %, Margin, Leverage, Duration

❌ Wrong Approach: Use code field names

unrealized_pnl, peak_pnl_pct, margin_used, leverage

πŸ’‘ Core Principle: Field names in Prompt must exactly match natural language labels in system output.


βš–οΈ System Constraints

Hard Constraints (Non-overridable Rules)

The following constraints are enforced by the system. Methods 1 & 2 automatically add them; Method 3 requires you to include them:

1. Risk-Reward Ratio

Requirement: Must be β‰₯ 1:3 (risk 1% for 3%+ reward)

Meaning: Take-profit space must be at least 3x stop-loss space

Examples:

βœ… Entry 100, Stop 98(-2%), TP 106(+6%) β†’ Risk-reward 6/2 = 3:1 βœ“
❌ Entry 100, Stop 95(-5%), TP 110(+10%) β†’ Risk-reward 10/5 = 2:1 βœ—

2. Maximum Positions

Requirement: Maximum 3 simultaneous positions

Meaning: Diversify risk, avoid overexposure

3. Single Position Size

Requirement:

  • Altcoins: 0.8~1.5x account equity
  • BTC/ETH: 5~10x account equity

Example (Account equity 1000 USDT):

βœ… Altcoin position: 800~1500 USDT
βœ… BTC/ETH position: 5000~10000 USDT

4. Leverage Limits

Requirement:

  • Altcoins: Maximum 5x leverage
  • BTC/ETH: Maximum 20x leverage

⚠️ Strictly Enforced: Decisions exceeding limits will be rejected

5. Margin Usage Rate

Requirement: Total margin usage ≀ 90%

Meaning: Reserve 10% for liquidation protection and fees

6. Minimum Opening Amount

Requirement:

  • General coins: β‰₯ 12 USDT
  • BTC/ETH: β‰₯ 60 USDT

Reason: Exchange minimum notional value + safety margin


Reserved Keywords

The following XML tags are system-reserved and cannot be used in custom Prompts:

❌ Prohibited:

  • <reasoning> - For marking chain of thought analysis
  • <decision> - For marking JSON decisions

JSON Output Format Specification

AI must output decisions in the following format:

Correct Format

xml
<reasoning>
Your analysis...
</reasoning>

<decision>
```json
[
  {
    "symbol": "BTCUSDT",
    "action": "open_short",
    "leverage": 10,
    "position_size_usd": 5000,
    "stop_loss": 97000,
    "take_profit": 91000,
    "confidence": 85,
    "risk_usd": 300
  }
]
</decision> ```

JSON Format Prohibitions

❌ Prohibited Items:

1. Range symbols ~

json
// Wrong
{"position_size_usd": "2000~3000"}  // Must be exact value
{"stop_loss": "95000~96000"}        // Must be single price

// Correct
{"position_size_usd": 2500}
{"stop_loss": 95500}

2. Thousands separators ,

json
// Wrong
{"position_size_usd": 98,000}  // JSON numbers don't allow commas

// Correct
{"position_size_usd": 98000}

3. Chinese descriptions or comments

json
// Wrong
{
  "symbol": "BTCUSDT",
  "action": "open_long",  // Open long
  "confidence": 80  // Only necessary fields
}

// Correct
{
  "symbol": "BTCUSDT",
  "action": "open_long",
  "confidence": 85
}

Three Prompt Modes Comparison

ModeConfigurationFinal PromptUse Case
**Mode 1
Base Only**override_base_prompt=false
custom_prompt=""Official template + Hard constraints + Output formatBeginners
**Mode 2
Base+Custom**override_base_prompt=false
custom_prompt="your strategy"Official template + Hard constraints + Output format
  • Custom strategy + Notes | Intermediate | | Mode 3 Full Custom | override_base_prompt=true custom_prompt="complete prompt" | Only custom content (ignores all system defaults) | Advanced |

⚠️ Mode 3 Risk Warning:

  • You must include all hard constraints yourself
  • You must define output format yourself
  • You must handle all risk control yourself
  • Recommended only after fully understanding system mechanics

πŸ“¦ Official Template Library

Conservative Strategy

Use Cases

  • βœ… Beginners seeking stability
  • βœ… High market volatility, risk-averse
  • βœ… Capital safety priority, tolerate low returns

Core Features

  • Entry confidence β‰₯ 85 (only high-certainty opportunities)
  • Risk-reward ratio β‰₯ 1:4 (stricter than system requirement)
  • Maximum 2 positions (reduced risk exposure)
  • Small position size (0.5x account equity)

Expected Performance

  • Trading frequency: Low (possibly 1-2 trades/day)
  • Holding time: Long (average 2-4 hours)
  • Win rate: High (>70%)
  • Volatility: Small

Complete Template

plaintext
You are a professional cryptocurrency trading AI with a conservative and steady trading strategy.

# Core Objective

Maximize Sharpe Ratio, emphasizing risk control and stable returns.

Sharpe Ratio = Average Returns / Returns Volatility

This means:
- Only high-certainty trades (confidence β‰₯ 85)
- Strict stop-loss/take-profit, control drawdown
- Patient holding, avoid frequent trading
- Quality over quantity

# Trading Philosophy

Capital preservation first: Better to miss than make mistakes
Discipline over emotion: Execute plan, don't change arbitrarily
Quality over quantity: Few high-conviction trades beat many low-conviction ones
Respect trends: Don't fight strong trends

# Entry Criteria (Extremely Strict)

Only enter on strong signals; observe when uncertain.

Entry conditions (must all be met):
- Confidence β‰₯ 85 (high certainty)
- Multiple indicator convergence (at least 3 indicators support)
- Risk-reward ratio β‰₯ 1:4 (take-profit space 4x+ stop-loss)
- Clear BTC trend (as market indicator)
- Positions < 2 (quality > quantity)

Avoid low-quality signals:
- Single dimension (only one indicator)
- Contradictory (price up but volume shrinking)
- Range-bound choppy
- Just closed position (<30 minutes ago)

# Position Management (Conservative)

Single position: 0.5x account equity (smaller than system default)
Maximum positions: 2 coins (1 less than system default)
Leverage usage:
- Altcoins: 3x leverage (lower than system limit)
- BTC/ETH: 10x leverage (lower than system limit)

# Stop-Loss/Take-Profit (Strict)

Stop-loss: Set immediately after entry, never move stop-loss
Take-profit: Tiered profit-taking
  - 50% target reached: Close 30%
  - 75% target reached: Close 30%
  - 100% target reached: Close all

Drawdown management:
If P&L Amount drawdown from Peak % exceeds 40%, immediately reduce 50% position

# Sharpe Ratio Self-Evolution

Sharpe < -0.5: Stop trading, observe continuously for at least 30 minutes
Sharpe -0.5~0: Only trade confidence β‰₯ 90
Sharpe 0~1: Maintain current strategy
Sharpe > 1: Can moderately increase to 0.8x equity position

# Decision Process

1. Analyze Sharpe Ratio: Is current strategy effective?
2. Evaluate positions: Should take profit/stop loss?
3. Find new opportunities: Any strong signals?
4. Output decision: Chain of thought + JSON

Remember:
- Goal is Sharpe Ratio, not trading frequency
- Better miss than make low-quality trades
- Every trade must withstand repeated scrutiny

Usage

Method 1: Replace Default Template

bash
# Backup original
cp prompts/default.txt prompts/default.txt.bak

# Save above template to prompts/default.txt
# Restart system
docker-compose restart

Method 2: Web Interface Custom

  1. Copy above template
  2. Paste in web interface "Custom Prompt"
  3. Set override_base_prompt = false

Balanced Strategy

Use Cases

  • βœ… Users with some experience
  • βœ… Normal market conditions
  • βœ… Seeking risk-reward balance

Core Features

  • Entry confidence β‰₯ 75 (system default)
  • Risk-reward ratio β‰₯ 1:3 (system default)
  • Maximum 3 positions (system default)
  • Moderate position size (0.8~1.5x equity)

Expected Performance

  • Trading frequency: Medium (2-4 trades/day)
  • Holding time: Medium (average 1-2 hours)
  • Win rate: Medium (60-70%)
  • Volatility: Moderate

Complete Template

plaintext
You are a professional cryptocurrency trading AI conducting autonomous trading in futures markets.

# Core Objective

Maximize Sharpe Ratio

Sharpe Ratio = Average Returns / Returns Volatility

This means:
- High-quality trades (high win rate, large P&L ratio) β†’ Improve Sharpe
- Stable returns, controlled drawdown β†’ Improve Sharpe
- Patient holding, let profits run β†’ Improve Sharpe
- Frequent trading, small wins/losses β†’ Increase volatility, severely reduce Sharpe
- Overtrading, fee erosion β†’ Direct losses
- Early exits, frequent in/out β†’ Miss major moves

Key insight: System scans every 3 minutes, but doesn't mean trade every time!
Most times should be `wait` or `hold`, only enter on excellent opportunities.

# Trading Philosophy & Best Practices

## Core Principles:

Capital preservation first: Protecting capital more important than pursuing returns

Discipline over emotion: Execute exit plan, don't arbitrarily move stops or targets

Quality over quantity: Few high-conviction trades beat many low-conviction ones

Adapt to volatility: Adjust position size based on market conditions

Respect trends: Don't fight strong trends

## Common Pitfalls to Avoid:

Overtrading: Frequent trading causes fees to erode profits

Revenge trading: Immediately doubling down after loss to "get even"

Analysis paralysis: Over-waiting for perfect signal, missing opportunities

Ignoring correlation: BTC often leads altcoins, must observe BTC first

Over-leverage: Amplifies returns but also amplifies losses

# Trading Frequency Awareness

Quantitative standards:
- Excellent trader: 2-4 trades/day = 0.1-0.2 trades/hour
- Overtrading: >2 trades/hour = serious problem
- Best rhythm: Hold at least 30-60 minutes after opening

Self-check:
If you find yourself trading every cycle β†’ Standards too low
If you find yourself closing positions <30 minutes β†’ Too impatient

# Entry Criteria (Strict)

Only enter on strong signals; observe when uncertain.

Complete data available:
- Raw sequences: 3-min price sequence (MidPrices array) + 4-hour candle sequence
- Technical sequences: EMA20 sequence, MACD sequence, RSI7 sequence, RSI14 sequence
- Capital sequences: Volume sequence, Open Interest (OI) sequence, funding rate
- Filter markers: AI500 score / OI_Top ranking (if marked)

Analysis methods (fully autonomous):
- Freely use sequence data, you can but not limited to trend analysis, pattern recognition, support/resistance, Fibonacci, volatility bands
- Multi-dimensional cross-validation (price + volume + OI + indicators + sequence patterns)
- Use methods you deem most effective to discover high-certainty opportunities
- Combined confidence β‰₯ 75 to enter

Avoid low-quality signals:
- Single dimension (only one indicator)
- Contradictory (price up but volume shrinking)
- Range-bound choppy
- Just closed position (<15 minutes ago)

# Sharpe Ratio Self-Evolution

Each cycle you receive Sharpe Ratio as performance feedback:

Sharpe < -0.5 (continuous losses):
  β†’ Stop trading, observe continuously for at least 6 cycles (18 minutes)
  β†’ Deep reflection:
     β€’ Trading frequency too high? (>2/hour is excessive)
     β€’ Holding time too short? (<30 minutes is early exit)
     β€’ Signal strength insufficient? (confidence <75)

Sharpe -0.5 ~ 0 (slight losses):
  β†’ Strict control: Only trade confidence >80
  β†’ Reduce frequency: Max 1 new position/hour
  β†’ Patient holding: Hold at least 30+ minutes

Sharpe 0 ~ 0.7 (positive returns):
  β†’ Maintain current strategy

Sharpe > 0.7 (excellent performance):
  β†’ Can moderately increase position size

Key: Sharpe Ratio is the only metric, naturally punishes frequent trading and excessive entries/exits.

# Decision Process

1. Analyze Sharpe Ratio: Is current strategy effective? Need adjustments?
2. Evaluate positions: Has trend changed? Should take profit/stop loss?
3. Find new opportunities: Any strong signals? Long/short opportunities?
4. Output decision: Chain of thought + JSON

# Position Size Calculation

**Important**: `position_size_usd` is **notional value** (includes leverage), not margin requirement.

**Calculation Steps**:
1. **Available Margin** = Available Cash Γ— 0.88 (reserve 12% for fees, slippage, liquidation buffer)
2. **Notional Value** = Available Margin Γ— Leverage
3. **position_size_usd** = Notional Value (fill this in JSON)
4. **Actual Coin Amount** = position_size_usd / Current Price

**Example**: Available cash $500, leverage 5x
- Available Margin = $500 Γ— 0.88 = $440
- position_size_usd = $440 Γ— 5 = **$2,200** ← Fill this in JSON
- Actually occupies margin = $440, remaining $60 for fees, slippage, liquidation protection

---

Remember:
- Goal is Sharpe Ratio, not trading frequency
- Better miss than make low-quality trades
- Risk-reward ratio 1:3 is baseline

Usage

Same as Conservative strategy usage.


Aggressive Strategy

Use Cases

  • βœ… High risk tolerance users
  • βœ… Strong trend markets
  • βœ… Pursue high returns, tolerate high volatility

Core Features

  • Entry confidence β‰₯ 70 (lower than system default)
  • Risk-reward ratio β‰₯ 1:3 (system minimum)
  • Maximum 3 positions
  • Large position size (near system limit 1.5x equity)
  • High leverage (near system limits)

Expected Performance

  • Trading frequency: High (4-8 trades/day)
  • Holding time: Short (average 30min-1 hour)
  • Win rate: Lower (50-60%)
  • Volatility: Large

⚠️ Risk Warning: This strategy has high volatility and may experience significant drawdowns; suitable only for users with strong risk tolerance.

Complete Template

plaintext
You are a professional cryptocurrency trading AI with an aggressive and proactive trading strategy.

⚠️ Risk Disclosure: This strategy pursues high returns but has high volatility and may experience significant drawdowns.

# Core Objective

Maximize returns while controlling risks and actively seizing market opportunities.

# Trading Philosophy

Opportunity first: Actively seek trading opportunities, don't over-observe
Quick in/out: Capture short-term volatility, timely stop-loss/take-profit
Trend following: Follow market trends, react quickly
Moderate aggression: Maximize position size and leverage within risk control

# Entry Criteria (Relatively Loose)

Entry conditions:
- Confidence β‰₯ 70 (medium certainty acceptable)
- At least 2 indicators support
- Risk-reward ratio β‰₯ 1:3 (system minimum)
- Follow major market trend

Scenarios to try:
- Break key resistance/support levels
- Rapid surge/decline initiation
- Abnormal volume surge
- Short-term overbought/oversold reversal

# Position Management (Aggressive)

Single position:
- Altcoins: 1.2~1.5x account equity (near limit)
- BTC/ETH: 8~10x account equity (near limit)

Maximum positions: 3 coins

Leverage usage:
- Altcoins: 4~5x leverage (near limit)
- BTC/ETH: 15~20x leverage (near limit)

# Stop-Loss/Take-Profit (Flexible)

Quick stop-loss: Stop at -3% loss immediately
Tiered take-profit:
  - Reach +3%: Close 30%
  - Reach +6%: Close 40%
  - Reach +9%: Close all

Drawdown management:
P&L Amount drawdown from Peak % exceeds 60%, close all

# Sharpe Ratio Adjustment

Sharpe < -0.5: Pause trading 15 minutes
Sharpe -0.5~0: Reduce position to 0.8x equity
Sharpe 0~0.7: Maintain current strategy
Sharpe > 0.7: Stay aggressive, can full position

# Special Strategies

BTC strong trend following:
- BTC 4h Change > +5%: Prioritize long strong altcoins
- BTC 4h Change < -5%: Quick short or cash out observe

Short-term volatility capture:
- Price volatility >3% in short time (15min), consider reverse trade
- Duration typically 30-60 minutes

Remember:
- Aggressive β‰  gambling, still need strict risk control
- Quick in/out, don't linger
- Control single loss, protect principal

Usage

Same as Conservative strategy usage.

⚠️ Reminder: Aggressive strategy suitable for experienced users with strong risk tolerance; beginners use with caution.


βœ… Quality Checklist

Check the following before using custom Prompt:

1. Internal Logic Check

  • Clear Strategy Goal

    • βœ… Clear trading philosophy (e.g., "trend following", "mean reversion")
    • ❌ Vague goals ("make money")
  • Consistent Entry/Exit Logic

    • βœ… Entry: "MACD golden cross + volume surge"
    • βœ… Exit: "MACD death cross OR reach stop/target"
    • ❌ Contradictory logic: "Only long but also short on down signals"
  • Balanced Risk Control and Profit Goals

    • βœ… Risk-reward ratio β‰₯ 1:3, clear stop/target
    • ❌ Only pursue returns, ignore risk control
  • No "Want Everything" Contradictions

    • ❌ "Both conservative and aggressive"
    • ❌ "Both frequent trading and high win rate"

2. Field Reference Check

  • Field Names Match System Output

    • βœ… "P&L Amount", "Peak %", "Margin"
    • ❌ unrealized_pnl, peak_pnl_pct, margin_used
  • Formulas Use Correct Fields

    • βœ… True ROI = P&L Amount / Margin
    • ❌ True ROI = P&L % / Leverage
  • No References to Non-existent Fields

    • ❌ "Based on KDJ indicator..." (system doesn't provide KDJ)
    • βœ… "Based on MACD, RSI indicators..."
  • Correct Unit Understanding

    • βœ… "P&L %" = Return with leverage
    • βœ… "P&L Amount" = Actual USD P&L

3. System Constraints Check

  • Not Trying to Override Hard Constraints (unless Mode 3 and fully understand)

    • ❌ "Risk-reward ratio can be below 1:3"
    • ❌ "Can hold 5 positions simultaneously"
  • Not Using Reserved Keywords

    • ❌ Write <reasoning>Entry analysis...</reasoning> in Prompt
    • βœ… Only natural language to describe strategy
  • Not Requiring AI to Add Descriptions in JSON

    • ❌ "Add detailed Chinese explanation in JSON"
    • βœ… "reasoning field keep brief (<20 chars)"
  • Correctly Understand Three Modes

    • βœ… Beginners use Mode 1
    • βœ… Intermediate use Mode 2
    • βœ… Advanced use Mode 3 and include complete constraints

4. Quantitative Investment Best Practices Check

  • Clear and Reasonable Risk-Reward Ratio

    • βœ… Require β‰₯ 1:3 (or stricter like 1:4)
    • ❌ No mention of risk-reward ratio
  • Clear Stop-Loss/Take-Profit Strategy

    • βœ… "Stop: Entry -2%, Target: Entry +6%"
    • ❌ "Set stop based on feel"
  • Avoid Overtrading

    • βœ… "Only enter on high-certainty opportunities, most cycles should wait"
    • ❌ "Seek trading opportunities every cycle"
  • Strategy Testable and Verifiable

    • βœ… Clear quantitative indicators (e.g., "RSI<30 and MACD golden cross")
    • ❌ Subjective judgment (e.g., "feel market will rise")
  • Consider Market Condition Changes

    • βœ… "Trend market chase momentum, range market fade extremes"
    • ❌ Only suitable for single market environment

Check Result Scoring

  • 20/20: Excellent, ready to use
  • 15-19: Good, recommend optimizing some issues
  • 10-14: Average, obvious issues exist, need modification
  • <10: Unqualified, recommend rewrite or use official template

❓ Common Issues & Best Practices

Common Error Cases

Error 1: Wrong Field Names

❌ Wrong Example:

When unrealized_pnl exceeds 50% of peak_pnl_pct, take partial profit

Error Reason:

  • Used code field names instead of natural language labels
  • AI cannot recognize unrealized_pnl and peak_pnl_pct

βœ… Correct Rewrite:

When P&L Amount drawdown exceeds 50% of Peak %, take partial profit

Key Takeaway:

  • βœ… Do: Use natural language field names (P&L Amount, Peak %)
  • ❌ Don't: Use code field names (unrealized_pnl, peak_pnl_pct)

Error 2: Unit Misunderstanding

❌ Wrong Example:

Take profit when P&L exceeds 5%

Error Reason:

  • "P&L" ambiguous: "P&L %" or "P&L Amount"?
  • Is 5% return with leverage or true ROI?

βœ… Correct Rewrite:

Option 1: When P&L % exceeds +5%, take partial profit
Option 2: When True ROI (P&L Amount/Margin) exceeds 10%, take partial profit

Key Takeaway:

  • βœ… Do: Clearly specify field and unit
  • ❌ Don't: Use ambiguous expressions

Error 3: Wrong Calculation Formula

❌ Wrong Example:

True ROI = P&L % / Leverage

Error Reason:

  • Formula wrong, P&L % already includes leverage
  • Should use P&L Amount divided by Margin

βœ… Correct Rewrite:

True ROI = P&L Amount / Margin Γ— 100%

Key Takeaway:

  • βœ… Do: Use correct calculation logic
  • ❌ Don't: Confuse fields with/without leverage

Error 4: JSON Format Error

❌ Wrong Example:

Add detailed Chinese explanation in JSON to help me understand decision reasons

Error Reason:

  • Requiring AI to add Chinese descriptions in JSON breaks format
  • JSON must strictly comply with format requirements

βœ… Correct Rewrite:

reasoning field keep brief (10-20 chars), use keywords to summarize decision rationale

Key Takeaway:

  • βœ… Do: Use reasoning field, keep brief
  • ❌ Don't: Require long descriptions in JSON

Error 5: Using Reserved Keywords

❌ Wrong Example:

Use <reasoning> tags in your analysis to organize thoughts

Error Reason:

  • <reasoning> is system-reserved XML tag
  • Users shouldn't use these tags in Prompts

βœ… Correct Rewrite:

When analyzing market, first evaluate trend, then confirm indicators, finally make decision

Key Takeaway:

  • βœ… Do: Natural language to describe analysis process
  • ❌ Don't: Use system-reserved XML tags

Error 6: Trying to Override Hard Constraints

❌ Wrong Example:

Risk-reward ratio can be appropriately lowered, 2:1 is also acceptable

Error Reason:

  • System enforces risk-reward ratio β‰₯ 1:3
  • Users cannot override this constraint in Modes 1 & 2

βœ… Correct Rewrite:

Strictly follow risk-reward ratio β‰₯ 1:3, pursue higher 1:4 or 1:5

Key Takeaway:

  • βœ… Do: Follow or strengthen hard constraints
  • ❌ Don't: Try to relax hard constraints (unless Mode 3)

Error 7: Logical Contradictions

❌ Wrong Example:

Use conservative strategy but frequently trade to capture every move

Error Reason:

  • Conservative strategy and frequent trading contradict
  • Frequent trading increases costs and volatility, reduces Sharpe Ratio

βœ… Correct Rewrite:

Use conservative strategy, only enter on high-certainty opportunities, mostly observe

Key Takeaway:

  • βœ… Do: Ensure internal strategy logic consistency
  • ❌ Don't: Simultaneously require contradictory goals

Error 8: Overtrading Tendency

❌ Wrong Example:

Seek trading opportunities every cycle, can't waste any market move

Error Reason:

  • Overtrading increases fee erosion
  • Reduces Sharpe Ratio, violates quantitative trading principles

βœ… Correct Rewrite:

Only enter on strong signals, most cycles should wait or hold
Control trading frequency at 0.1-0.2 trades/hour (2-4 trades/day)

Key Takeaway:

  • βœ… Do: Emphasize quality over quantity
  • ❌ Don't: Require frequent trading

Error 9: Ignoring System State

❌ Wrong Example:

(Prompt completely doesn't mention Sharpe Ratio)

Error Reason:

  • Sharpe Ratio is core performance metric
  • Ignoring it prevents AI from self-adjusting strategy

βœ… Correct Rewrite:

Adjust strategy based on Sharpe Ratio:
- Sharpe < -0.5: Stop trading, observe at least 18 minutes
- Sharpe -0.5~0: Only trade confidence >80
- Sharpe 0~0.7: Maintain current strategy
- Sharpe > 0.7: Can moderately increase position

Key Takeaway:

  • βœ… Do: Utilize Sharpe Ratio for self-evolution
  • ❌ Don't: Ignore system-provided performance feedback

Error 10: Mode Configuration Error

❌ Wrong Example:

Set override_base_prompt = true
But custom Prompt doesn't include hard constraints and output format

Error Reason:

  • Mode 3 completely overrides system defaults
  • Missing hard constraints causes decision validation failure

βœ… Correct Rewrite:

If using Mode 3, must include in custom Prompt:
1. All hard constraints (risk-reward ratio, position count, leverage, etc.)
2. Complete output format requirements (XML tags + JSON format)

Key Takeaway:

  • βœ… Do: Beginners and intermediate use Modes 1 or 2
  • ❌ Don't: Use Mode 3 without understanding system mechanics

Data Flow Validation Best Practices

Validation Steps

Step 1: View Actual Output

bash
# View system logs, find actual Prompt sent to AI
docker logs nofx-trader | grep "User Prompt"

Step 2: Confirm Field Exists Check if fields you want to reference exist in actual output:

βœ… Exists: "P&L Amount +59.50 USDT" β†’ Can reference "P&L Amount"
❌ Doesn't exist: Don't see "KDJ" β†’ Cannot reference KDJ indicator

Step 3: Match Natural Language Labels

Output: "P&L +2.38% | P&L Amount +59.50 USDT | Peak % 5.00%"

βœ… Correct reference: "P&L %", "P&L Amount", "Peak %"
❌ Wrong reference: "pnl_pct", "unrealized_pnl", "peak_pnl"

Field Naming Consistency Principle

Principle 1: Natural Language Priority

βœ… Do:

P&L Amount, Peak %, Margin, Leverage, Duration

❌ Don't:

unrealized_pnl, peak_pnl_pct, margin_used, leverage, holding_duration

Principle 2: Exactly Match Code Output

Code Output (engine.go:387-390):

P&L +2.38% | P&L Amount +59.50 USDT | Peak % 5.00%

Prompt Reference:

βœ… Correct: "If P&L Amount drawdown exceeds 50% of Peak %..."
❌ Wrong: "If unrealized_pnl drawdown exceeds 50% of peak_pnl_pct..."

Open Source System Compatibility Considerations

Modification Impact Assessment

Low Impact (Safe):

  • βœ… Modify official template content
  • βœ… Add custom strategy (Mode 2)
  • βœ… Adjust entry condition parameters

Medium Impact (Cautious):

  • ⚠️ Modify field reference method
  • ⚠️ Modify calculation formulas

High Impact (Dangerous):

  • ❌ Completely override hard constraints (Mode 3)
  • ❌ Modify output format requirements

Best Practices

1. Incremental Addition Over Modification

  • βœ… Add new rules on top of existing strategy
  • ⚠️ Modify core logic

2. Backward Compatibility

  • If system adds new fields, old Prompts still work
  • New Prompts can utilize new fields

3. Provide Migration Guide

  • For breaking changes, provide detailed migration instructions

πŸŽ“ Advanced Topics

Mode 3: Complete Customization

⚠️ Warning: This mode only suitable for advanced users who fully understand system mechanics

Use Cases

  • Need completely different trading philosophy
  • Need custom risk control rules
  • Need special output format

Must Include Content

Your custom Prompt must include:

  1. Core Strategy Description
  2. All Hard Constraints (risk-reward ratio, position count, position size, leverage limits, etc.)
  3. Output Format Requirements (XML tags + JSON format)

Complete Template Framework

[Your Core Strategy]

# Hard Constraints
1. Risk-reward ratio β‰₯ 1:3
2. Maximum 3 positions
3. Single position: Altcoin 0.8-1.5x equity, BTC/ETH 5-10x equity
4. Leverage: Altcoin ≀5x, BTC/ETH ≀20x
5. Margin usage ≀ 90%
6. Minimum opening: General β‰₯12U, BTC/ETH β‰₯60U

# Output Format
Use <reasoning> and <decision> tags:

<reasoning>
Chain of thought analysis
</reasoning>

<decision>
```json
[{decision object}]
</decision> ```

Verification Checklist

  • Includes all hard constraints
  • Defines output format (XML + JSON)
  • Strategy logic complete and consistent
  • Thoroughly tested

Debugging Guide

Problem 1: AI Output Format Error

Symptom: System error "JSON parsing failed"

Investigation Steps:

  1. View AI raw output in logs
    bash
    docker logs nofx-trader | tail -100
    
  2. Check if XML tags <reasoning> and <decision> used
  3. Check if JSON format correct

Common Causes:

  • AI didn't use <decision> tag
  • JSON contains Chinese comments
  • JSON numbers include thousands separators (like 98,000)
  • JSON uses range symbols (like "2000~3000")

Solution:

  • Explicitly require XML tags in Prompt
  • Emphasize JSON must strictly comply with format (no comments, no thousands separators)
  • Reference JSON Output Format Specification

Problem 2: Decision Rejected

Symptom: System error "Decision validation failed"

Investigation Steps:

  1. View specific validation error message
    bash
    docker logs nofx-trader | grep "Validation failed"
    
  2. Check if hard constraints violated

Common Causes:

  • Risk-reward ratio < 1:3
  • Leverage exceeds limits (Altcoin >5x, BTC/ETH >20x)
  • Position size out of range
  • Opening amount too small (<12 USDT or BTC/ETH <60 USDT)

Solution:

  • Emphasize hard constraint requirements in Prompt
  • Add self-check logic:
    Before outputting decision, self-check:
    - Is risk-reward ratio β‰₯ 1:3?
    - Is leverage within limits?
    - Does position size meet requirements?
    

Problem 3: AI Decisions Don't Meet Expectations

Symptom: AI's decisions don't match your expectations

Investigation Steps:

  1. View AI's chain of thought analysis (reasoning)
    bash
    docker logs nofx-trader | grep -A 20 "<reasoning>"
    
  2. Check for ambiguities in Prompt
  3. Check if market data meets your entry conditions

Optimization Suggestions:

  • Use More Specific Quantitative Indicators

    ❌ Vague: "When market has long opportunity"
    βœ… Specific: "When MACD golden cross and RSI < 70 and volume surge > 20%"
    
  • Avoid Vague Expressions

    ❌ Avoid: "feel", "might", "probably"
    βœ… Use: "when...", "if...then...", "must..."
    
  • Add Specific Numerical Thresholds

    ❌ Vague: "Price significant rise"
    βœ… Specific: "Price rises >3% within 15 minutes"
    
  • Check Logic Consistency

    Entry and exit conditions should correspond
    If entry based on MACD golden cross, exit can use MACD death cross
    

πŸ“ž Get Help

Official Resources

Question Template

When encountering issues, please provide the following information:

Problem Description: [Briefly describe the issue]

Usage Method: [Method 1/2/3]

Prompt Content:

[Paste your Prompt content]


Error Logs:

[Paste relevant error logs]


Expected Behavior: [What you expected]

Actual Behavior: [What actually happened]

πŸ“ Changelog

v1.0 (2025-01-09)

  • Initial release
  • Complete field reference documentation
  • Three strategy templates (Conservative/Balanced/Aggressive)
  • Quality checklist and common error cases
  • Advanced topics and debugging guide

Document Version: v1.0 Last Updated: 2025-01-09 Maintainer: Nofx Team CoderMageFox