Global Leverage Configuration & Management — User Guide

Overview

This guide explains how to use the leverage configuration options in tradesettings.yaml under General Settings to manage leverage across all trading symbols on your exchange.

1. SetLeverageStartup

SetLeverageStartup: false

Purpose: Apply the defined leverage to all trading symbols when the bot starts up.

When to Enable (true)

• ✅ First-time setup: When you need to set leverage for all symbols initially
• ✅ After changing leverage settings: When you've modified your desired leverage
• ✅ After adding new symbols: When new trading pairs are added to the exchange

When to Disable (false)

• ✅ After successful leverage update: To avoid unnecessary API calls
• ✅ Normal operation: To prevent resetting leverage on every restart
• ✅ When leverage is already configured: If all symbols have correct leverage

⚠️ Important Notes

• Always set to false after leverage is successfully updated to avoid:
  • Unnecessary API calls on every initialization
  • Potential rate limiting from the exchange
  • Slower startup times

# Step 1: Enable to update leverage
SetLeverageStartup: true

# Step 2: Start bot (leverage will be applied)
# Step 3: Stop bot

# Step 4: Disable before next start
SetLeverageStartup: false

Workflow Example

1. Set desired leverage in config (e.g., 10x)
2. Enable SetLeverageStartup: true
3. Start bot → Leverage applied to all symbols
4. Stop bot
5. Disable SetLeverageStartup: false
6. Restart bot for normal trading

2. SetMaxLeverage

SetMaxLeverage: false

Purpose: Automatically use the maximum leverage allowed by the exchange for each symbol instead of your configured leverage value.

How It Works

When false (Default):

• Uses your configured leverage value for all symbols
• If unsupported, API call may fail

When true:

• Fetches maximum supported leverage for each symbol
• Uses the lower value between configured and exchange maximum

Example Scenarios

# Scenario 1: Symbol Supports Your Leverage
Your Config: 20x
Symbol Max:  50x
Result:      20x

# Scenario 2: Symbol Has Lower Max Leverage
Your Config: 20x
Symbol Max:  5x
Result:      5x
Bot Output:  "ℹ️ XYZUSDT max leverage is 5x, using 5x instead of 20x"

# Scenario 3: Symbol Has Higher Max Leverage
Your Config: 10x
Symbol Max:  125x
Result:      10x

When to Enable (true)

• ✅ Safe approach to avoid leverage-related errors
• ✅ Mixed symbol types with varying leverage limits
• ✅ Conservative trading to auto-adjust to limits
• ✅ Multi-exchange bots with different rules

When to Disable (false)

• ✅ Uniform leverage supported across all symbols
• ✅ Strategy requires exact leverage values
• ✅ Performance optimization (fewer API calls)

Integration with symbols.json

Leverage Update Flow

1. Bot reads leverage from tradesettings.yaml
2. If SetMaxLeverage: true → Fetches max leverage
3. Calculates final leverage (min of configured vs max)
4. Applies leverage via exchange API
5. ✅ Updates symbols.json with actual applied leverage
6. Bot uses leverage from symbols.json for trading

Why symbols.json Update Matters

• Ensures consistency with exchange
• Persists across restarts
• Visible tracking of actual leverage used

⚠️ Important: Sync Timing

# ❌ WRONG
SetLeverageStartup: true
SetMaxLeverage: true

# ✅ CORRECT (One-time update)
SetLeverageStartup: true
SetMaxLeverage: true
# After success:
SetLeverageStartup: false
SetMaxLeverage: false

Recommended Configuration Workflows

Initial Setup (New Bot)

# tradesettings.yaml
Leverage: 10
SetLeverageStartup: true
SetMaxLeverage: true

1. Configure settings above
2. Start bot → Leverage applied and symbols.json updated
3. Stop bot
4. Disable both settings
5. Restart for normal operation

Changing Leverage Value

# tradesettings.yaml
Leverage: 15
SetLeverageStartup: true
SetMaxLeverage: true

1. Update leverage value
2. Enable SetLeverageStartup
3. Start bot → New leverage applied
4. Stop bot
5. Disable again before next start

Normal Operation (Recommended)

# tradesettings.yaml
Leverage: 10
SetLeverageStartup: false
SetMaxLeverage: false

Bot reads leverage from symbols.json (already configured and updated).

Adding New Symbols

# tradesettings.yaml
Leverage: 10
SetLeverageStartup: true
SetMaxLeverage: true

1. Add new symbols to exchange
2. Enable SetLeverageStartup
3. Start bot → Leverage applied to all symbols
4. Stop bot
5. Disable before normal trading

Troubleshooting

• Issue: Bot keeps resetting leverage
  Cause: SetLeverageStartup: true left enabled
  Solution: Set to false after initial setup
• Issue: Leverage not applied
  Cause: SetLeverageStartup: false during update
  Solution: Temporarily enable and restart
• Issue: API errors about leverage limits
  Cause: Configured leverage exceeds exchange maximum
  Solution: Enable SetMaxLeverage: true
• Issue: symbols.json mismatch
  Cause: Manual change or desync
  Solution: Enable SetLeverageStartup: true once to resync

Best Practices

✅ DO

• Set SetLeverageStartup: false after successful updates
• Use SetMaxLeverage: true for first setup
• Verify leverage values in symbols.json
• Keep backups before changes
• Test on one symbol before all

❌ DON'T

• Leave SetLeverageStartup: true in normal operation
• Change leverage without enabling SetLeverageStartup
• Edit symbols.json manually
• Enable both repeatedly (causes API overhead)

Quick Reference Table

Support

1. Check bot logs for errors
2. Verify exchange API permissions include leverage modification
3. Ensure all symbols exist on exchange
4. Check symbols.json for correct leverage
5. Review exchange-specific leverage limits