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 (encrypted storage)
export CREDENTIALS_PASSPHRASE="your-secure-passphrase-here"
wealth credentials create

# 3. Add exchange API credentials
wealth credentials add binance "your-binance-api-key" "your-binance-secret-key"
wealth credentials add hyperliquid "your-hyperliquid-wallet" "your-hyperliquid-key"

# 4. Configure trading parameters (edit config.toml)
# See Configuration Guide for all options

# 5. Verify configuration
wealth verify

# 6. Check balances (paper trading mode by default)
export WEALTH__EXECUTION__MODE=paper
wealth balance

# 7. Run the bot
wealth run

Expected Output:

2025-11-07T10:30:00Z INFO  Wealth Trading Bot v0.33.0
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, 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 positions cleanly)
# Press Ctrl+C once and wait (~6-8 seconds typical)
^C
2025-11-07T14:35:00Z INFO  Shutdown signal received
2025-11-07T14:35:01Z INFO  Closing all positions gracefully...
2025-11-07T14:35:05Z INFO  All 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/..."

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