Practical Examples & Common Workflows

This guide provides practical, real-world examples for using the Wealth trading bot. All examples assume you've completed the Getting Started guide.

Quick Start Example
Opening Your First Position
Monitoring Active Positions
Closing Positions
Alert Integration
Troubleshooting Common Issues

Quick Start Example

Complete Workflow from Scratch

This example shows the complete workflow from installation to your first trade:

# 1. Download and install (or use Docker)
# See Getting Started guide for installation options

# 2. Set up credentials
export CREDENTIALS_PASSPHRASE="your-secure-passphrase-here"
wealth credentials create
wealth credentials add binance   # Interactive prompts
wealth credentials add hyperliquid

# 3. Verify setup
wealth verify

# 4. Run the bot (paper trading by default)
wealth run

📖 For detailed setup instructions, see:

Getting Started - First Run

Security Guide - Credential Setup

Expected Output:

2025-11-07T10:30:00Z INFO  Wealth Trading Bot
2025-11-07T10:30:00Z INFO  Mode: PAPER TRADING (no real orders)
2025-11-07T10:30:01Z INFO  Initialized leverage: BTCUSDT = 15x
2025-11-07T10:30:02Z INFO  WebSocket connected: Binance ticker stream
2025-11-07T10:30:03Z INFO  WebSocket connected: HyperLiquid ticker stream
2025-11-07T10:30:04Z INFO  Fetching funding rates...
2025-11-07T10:30:05Z INFO  Binance BTCUSDT: 0.0100%
2025-11-07T10:30:05Z INFO  HyperLiquid BTC: 0.0500%
2025-11-07T10:30:05Z INFO  Spread detected: 0.0400% (above 0.0300% threshold)
2025-11-07T10:30:05Z INFO  Opening arbitrage position...

Opening Your First Position

Manual Position Opening (Development/Testing)

# Check current funding rates
wealth funding

# Output:
# Exchange      Symbol      Rate        Next Payment
# binance       BTCUSDT     0.0100%     2025-11-07 12:00:00 UTC
# hyperliquid   BTC         0.0500%     2025-11-07 11:00:00 UTC
# Spread: 0.0400% ✓ (above 0.0300% threshold)

# Check available balance
wealth balance

# Output:
# Exchange      Asset    Free         Total        Reserved
# binance       USDT     10000.00     10000.00     0.00
# hyperliquid   USDT     10000.00     10000.00     0.00

# Start the bot (it will auto-open positions when spreads are found)
wealth run

Understanding Position Logic

The bot opens positions automatically when:

Spread Check: funding_rate_high - funding_rate_low >= 0.0300% (configurable)
Balance Validation: Sufficient collateral with 20% safety buffer
Leverage Validation: Within exchange limits (1-125x Binance/Aster, 1-100x Bybit, 1-50x HyperLiquid)
Position Limits: Under max concurrent pairs (default: 3)

Example Calculation:

Given:
- Position size: $1,000
- Leverage: 10x
- Safety buffer: 20%

Required collateral = ($1,000 / 10) * 1.2 = $120 per exchange
Total required = $120 + $120 = $240

If available balance >= $240, position opens

Monitoring Active Positions

Check Current Positions

# View all open positions
wealth positions

# Output:
# ID    Symbol      Long Exchange  Short Exchange  Size       Entry Spread  Current Spread  Funding Collected  P&L      Age
# 1     BTCUSDT     binance       hyperliquid     0.1 BTC    0.0400%      0.0350%         $2.40             $12.50   2h 15m
# 2     ETHUSDT     bybit         binance         2.0 ETH    0.0380%      0.0420%         $1.80             $8.30    1h 45m

Real-Time Monitoring with OpenTelemetry

The bot exports metrics via OTLP to your observability backend. Check configuration:

# View OTLP configuration (JSON response)
curl -s localhost:9090/metrics | jq

# Output:
# {
#   "status": "operational",
#   "backend": "OpenTelemetry OTLP",
#   "endpoint": "http://localhost:4317",
#   "protocol": "gRPC"
# }

# Query actual metrics in Grafana or your OTLP-compatible backend:
# wealth_funding_rate{exchange="binance",symbol="BTCUSDT"}
# wealth_positions_active
# wealth_profit_loss_usd

Using Grafana (Optional)

# Start Grafana with docker-compose
docker-compose up -d grafana

# Access dashboard at http://localhost:3000
# Default credentials: admin/admin
# Pre-configured dashboard shows:
# - Active positions
# - Funding rate spreads
# - P&L over time
# - WebSocket health
# - API latency

Closing Positions

Automatic Closing (Normal Operation)

Positions close automatically when any condition is met:

Target Profit Reached: 5% profit (configurable via target_profit)
Spread Reversal: Spread drops below 50% of entry spread
Emergency: Critical errors or shutdown signal

Example Auto-Close:

2025-11-07T14:30:00Z INFO  Position #1 BTCUSDT reached target profit (5.2%)
2025-11-07T14:30:01Z INFO  Closing position atomically...
2025-11-07T14:30:02Z INFO  Close order placed: Binance (sell 0.1 BTC)
2025-11-07T14:30:03Z INFO  Close order placed: HyperLiquid (buy 0.1 BTC)
2025-11-07T14:30:04Z INFO  Position closed successfully. Final P&L: $52.40

Manual Emergency Close

# Close positions on specific exchange
wealth close --exchange binance --confirm

# Close positions for specific symbol
wealth close --symbol BTCUSDT --confirm

# Emergency close ALL positions (requires confirmation)
wealth close --all --confirm

# Graceful shutdown (closes all non-held positions cleanly)
# Press Ctrl+C once and wait (~6-8 seconds typical)
# Note: Held positions (marked with 🔒 in TUI) are preserved
^C
2025-11-07T14:35:00Z INFO  Shutdown signal received
2025-11-07T14:35:01Z INFO  Closing all positions gracefully...
2025-11-07T14:35:01Z INFO  Skipping held position ETHUSDT (will persist)
2025-11-07T14:35:05Z INFO  All non-held positions closed. Exiting.

Note: All close commands require --confirm flag for safety.

Verifying Position Closure

# Check positions after close
wealth positions

# Output should be empty:
# 📊 Current Positions
#
#   No active positions

# Check balances are back to normal
wealth balance

Alert Integration

Discord Notifications

Set up Discord alerts for important events:

# Set your Discord webhook URL
export DISCORD_WEBHOOK_URL="https://discord.com/api/webhooks/..."

# The bot will send notifications for:
# - Position opened/closed
# - Target profit reached
# - Errors or warnings

Slack Notifications

# Set your Slack webhook URL
export SLACK_WEBHOOK_URL="https://hooks.slack.com/services/..."

Dynamic Pair Discovery Examples

Using Loris.tools Arbitrage Mode (Recommended)

The bot can automatically discover trading pairs using Loris.tools API, sorted by arbitrage opportunity:

# config.toml - Maximum arbitrage opportunities
[instrument_discovery]
enabled = true
use_loris_rankings = true         # Use Loris.tools API
loris_sort_by = "arbitrage"       # Sort by funding spread (default)
min_24h_volume_usd = 1_000_000    # $1M minimum liquidity
quote_asset = "USDT"
max_symbols = 20
min_exchanges = 2
exclude = ["BULL", "BEAR", "UP", "DOWN"]
refresh_interval_hours = 6        # Refresh pairs every 6 hours

# Run with discovery enabled
wealth run --enable-discovery

# Output shows arbitrage-sorted pairs:
# INFO Pair discovery using Loris rankings (sort: arbitrage)
# INFO Top arbitrage opportunities:
#   1. DOGE: spread=0.12% (Binance: -0.05%, Bybit: 0.07%)
#   2. SOL:  spread=0.08% (Binance: 0.01%, HyperLiquid: 0.09%)
#   3. BTC:  spread=0.04% (Binance: 0.01%, Bybit: 0.05%)

Using Loris.tools OI Rank Mode (Liquidity-Focused)

For conservative strategies prioritizing liquidity:

# config.toml - Most liquid pairs
[instrument_discovery]
enabled = true
use_loris_rankings = true
loris_sort_by = "oi_rank"         # Sort by open interest (liquidity)
min_24h_volume_usd = 1_000_000
quote_asset = "USDT"
max_symbols = 10                   # Fewer, more liquid pairs
min_exchanges = 2
exclude = ["BULL", "BEAR", "UP", "DOWN"]
refresh_interval_hours = 6         # Refresh pairs every 6 hours

# Output shows OI-sorted pairs:
# INFO Pair discovery using Loris rankings (sort: oi_rank)
# INFO Top pairs by liquidity:
#   1. BTC:  OI rank=1
#   2. ETH:  OI rank=2
#   3. SOL:  OI rank=5

Using Exchange Volume Data (Direct)

For maximum control without third-party APIs:

# config.toml - Direct exchange data
[instrument_discovery]
enabled = true
use_loris_rankings = false        # Use exchange APIs directly
min_24h_volume_usd = 5_000_000    # Higher threshold
quote_asset = "USDT"
max_symbols = 20
min_exchanges = 2
exchanges = ["binance_futures", "bybit_perpetuals_usd"]
refresh_interval_hours = 0        # No periodic refresh (runs at startup only)

Troubleshooting Common Issues

Issue: "Insufficient balance" error

Solution:

# Check current balance
wealth balance

# If balance is low, deposit more funds or reduce position size
# Edit config.toml:
[trading]
position_size_percentage = 0.1  # Reduce from 30% to 10%
max_position_usd = 5000.0       # Reduce cap

Issue: Position not opening despite good spread

Possible causes:

Balance too low

# Check required collateral
# For $1000 position at 10x leverage with 20% buffer:
# Required = ($1000 / 10) * 1.2 = $120 per exchange

Leverage not initialized

# Check logs for:
grep "Initialized leverage" logs/wealth.log

# If missing, verify config.toml has leverage section

Max concurrent positions reached

# Check current count
wealth positions | wc -l

# Increase in config if needed:
"max_concurrent_pairs": 5

Issue: WebSocket keeps disconnecting

Automatic Recovery (v0.54.0+):

The bot now includes automatic per-exchange health monitoring and restart:

Health checks every 30 seconds using ping/pong heartbeats
Only unhealthy exchanges are restarted (not all)
90-second threshold before considering a stream unhealthy
60-second grace period for newly restarted streams

Manual troubleshooting:

# Check network connectivity
curl -I https://fstream.binance.com
curl -I https://stream.bybit.com

# Enable detailed logging to see health check status
export RUST_LOG=wealth::market_data=debug
wealth run

# Look for these log patterns:
# "All WebSocket streams healthy" - system is working
# "Exchange binance unhealthy: No activity for 95s" - single exchange restart
# "Restarting single exchange stream" - per-exchange recovery in progress

Persistent disconnection issues:

Network instability: Check your connection quality
Exchange rate limiting: The bot uses exponential backoff; wait for recovery
Firewall/proxy: Ensure WebSocket connections (wss://) are allowed

Issue: Orders rejected by exchange

Common reasons:

Quantity too small

# Binance minimum: 0.001 BTC
# HyperLiquid minimum: 0.01 BTC (varies by symbol)

# Increase position size or use different symbol

Insufficient margin

# Check exchange-specific requirements:
wealth verify --check-margin

Position mode not set (Binance)

# Bot auto-initializes hedge mode, but if it fails:
# Manually set in Binance UI: Futures > Preferences > Position Mode > Hedge Mode

Getting Started - Initial setup
Configuration Guide - Detailed config options
CLI Reference - All commands
API Reference - Programmatic usage
Troubleshooting - Detailed problem solving

Next Steps

Test in Paper Trading Mode: Run with WEALTH__EXECUTION__MODE=paper for 1-2 weeks
Monitor Metrics: Set up Grafana dashboard for visualization
Set Up Alerts: Configure Discord/Slack notifications for important events
Gradual Scaling: Start with small position sizes, increase gradually
Review Performance: Use wealth stats to analyze historical performance

Questions? See Troubleshooting or check the logs in logs/wealth.log.

Wealth Trading System - User Guide