pdmt5 0.1.5__tar.gz → 0.1.7__tar.gz

{pdmt5-0.1.5 → pdmt5-0.1.7}/.github/workflows/ci.yml

@@ -42,7 +42,7 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
       - name: Set up uv
-        uses: astral-sh/setup-uv@7edac99f961f18b581bbd960d59d049f04c0002f  # v6.4.1
+        uses: astral-sh/setup-uv@e92bafb6253dcd438e0484186d7669ea7a8ca1cc  # v6.4.3
       - name: Install the package
         run: >
           uv sync

{pdmt5-0.1.5 → pdmt5-0.1.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pdmt5
-Version: 0.1.5
+Version: 0.1.7
 Summary: Pandas-based data handler for MetaTrader 5
 Project-URL: Repository, https://github.com/dceoy/pdmt5.git
 Author-email: dceoy <dceoy@users.noreply.github.com>
@@ -42,6 +42,8 @@ Pandas-based data handler for MetaTrader 5
 - 🚀 **Context Manager Support**: Clean initialization and cleanup with `with` statements
 - 📈 **Time Series Ready**: OHLCV data with proper datetime indexing
 - 🛡️ **Robust Error Handling**: Custom exceptions with detailed MT5 error information
+- 💰 **Advanced Trading Operations**: Position management, margin calculations, and risk analysis tools
+- 🧪 **Dry Run Mode**: Test trading strategies without executing real trades
 
 ## Requirements
 
@@ -189,15 +191,13 @@ Extends Mt5Client with pandas DataFrame and dictionary conversions:
 
 Advanced trading operations client that extends Mt5DataClient:
 
-- **Trading Configuration**:
-  - `order_filling_mode` - Order execution mode: "IOC" (default), "FOK", or "RETURN"
-  - `dry_run` - Test mode flag for simulating trades without execution
 - **Position Management**:
   - `close_open_positions()` - Close all positions for specified symbol(s)
   - `place_market_order()` - Place market orders with configurable side, volume, and execution modes
-  - `update_open_position_sltp()` - Modify stop loss and take profit levels for open positions
-- **Market Analysis**:
-  - `calculate_minimum_order_margins()` - Calculate minimum required margins for buy/sell orders
+  - `update_sltp_for_open_positions()` - Modify stop loss and take profit levels for open positions
+- **Margin Calculations**:
+  - `calculate_minimum_order_margin()` - Calculate minimum required margin for a specific order side
+  - `calculate_volume_by_margin()` - Calculate maximum volume for given margin amount
   - `calculate_spread_ratio()` - Calculate normalized bid-ask spread ratio
   - `calculate_new_position_margin_ratio()` - Calculate margin ratio for potential new positions
 - **Simplified Data Access**:
@@ -210,7 +210,6 @@ Advanced trading operations client that extends Mt5DataClient:
   - Comprehensive error handling with `Mt5TradingError`
   - Support for batch operations on multiple symbols
   - Automatic position closing with proper order type reversal
-  - Dry run mode for strategy testing without real trades
 
 ### Configuration
 
@@ -287,8 +286,8 @@ with Mt5DataClient(config=config) as client:
 ```python
 from pdmt5 import Mt5TradingClient
 
-# Create trading client with specific order filling mode
-with Mt5TradingClient(config=config, order_filling_mode="IOC") as trader:
+# Create trading client
+with Mt5TradingClient(config=config) as trader:
     # Place a market buy order
     order_result = trader.place_market_order(
         symbol="EURUSD",
@@ -299,44 +298,33 @@ with Mt5TradingClient(config=config, order_filling_mode="IOC") as trader:
     )
     print(f"Order placed: {order_result['retcode']}")
 
-    # Update stop loss and take profit for an open position
-    if positions := trader.positions_get_as_df(symbol="EURUSD"):
-        position_ticket = positions.iloc[0]['ticket']
-        update_result = trader.update_open_position_sltp(
-            symbol="EURUSD",
-            position_ticket=position_ticket,
-            sl=1.0950,  # New stop loss
-            tp=1.1050   # New take profit
-        )
-        print(f"Position updated: {update_result['retcode']}")
+    # Update stop loss and take profit for open positions
+    update_results = trader.update_sltp_for_open_positions(
+        symbol="EURUSD",
+        stop_loss=1.0950,   # New stop loss
+        take_profit=1.1050  # New take profit
+    )
+    for result in update_results:
+        print(f"Position updated: {result['retcode']}")
 
     # Calculate margin ratio for a new position
     margin_ratio = trader.calculate_new_position_margin_ratio(
         symbol="EURUSD",
-        new_side="SELL",
-        new_volume=0.2
+        new_position_side="SELL",
+        new_position_volume=0.2
     )
     print(f"New position margin ratio: {margin_ratio:.2%}")
 
-    # Close all EURUSD positions
-    results = trader.close_open_positions(symbols="EURUSD")
+    # Close all EURUSD positions with specific order filling mode
+    results = trader.close_open_positions(
+        symbols="EURUSD",
+        order_filling_mode="FOK"  # Fill or Kill
+    )
 
     if results:
         for symbol, close_results in results.items():
             for result in close_results:
                 print(f"Closed position {result.get('position')} with result: {result['retcode']}")
-
-    # Using dry run mode for testing
-    trader_dry = Mt5TradingClient(config=config, dry_run=True)
-    with trader_dry:
-        # Test placing an order without actual execution
-        test_order = trader_dry.place_market_order(
-            symbol="GBPUSD",
-            volume=0.1,
-            order_side="SELL",
-            dry_run=True  # Override instance setting
-        )
-        print(f"Test order validation: {test_order['retcode']}")
 ```
 
 ### Market Analysis with Mt5TradingClient
@@ -347,10 +335,18 @@ with Mt5TradingClient(config=config) as trader:
     spread_ratio = trader.calculate_spread_ratio("EURUSD")
     print(f"EURUSD spread ratio: {spread_ratio:.5f}")
 
-    # Get minimum order margins
-    margins = trader.calculate_minimum_order_margins("EURUSD")
-    print(f"Minimum ask margin: {margins['ask']}")
-    print(f"Minimum bid margin: {margins['bid']}")
+    # Get minimum order margin for BUY and SELL
+    buy_margin = trader.calculate_minimum_order_margin("EURUSD", "BUY")
+    sell_margin = trader.calculate_minimum_order_margin("EURUSD", "SELL")
+    print(f"Minimum BUY margin: {buy_margin['margin']} (volume: {buy_margin['volume']})")
+    print(f"Minimum SELL margin: {sell_margin['margin']} (volume: {sell_margin['volume']})")
+    
+    # Calculate volume by margin
+    available_margin = 1000.0
+    max_buy_volume = trader.calculate_volume_by_margin("EURUSD", available_margin, "BUY")
+    max_sell_volume = trader.calculate_volume_by_margin("EURUSD", available_margin, "SELL")
+    print(f"Max BUY volume for ${available_margin}: {max_buy_volume}")
+    print(f"Max SELL volume for ${available_margin}: {max_sell_volume}")
 
     # Get recent OHLC data with custom timeframe
     rates_df = trader.fetch_latest_rates_as_df(

{pdmt5-0.1.5 → pdmt5-0.1.7}/README.md

@@ -19,6 +19,8 @@ Pandas-based data handler for MetaTrader 5
 - 🚀 **Context Manager Support**: Clean initialization and cleanup with `with` statements
 - 📈 **Time Series Ready**: OHLCV data with proper datetime indexing
 - 🛡️ **Robust Error Handling**: Custom exceptions with detailed MT5 error information
+- 💰 **Advanced Trading Operations**: Position management, margin calculations, and risk analysis tools
+- 🧪 **Dry Run Mode**: Test trading strategies without executing real trades
 
 ## Requirements
 
@@ -166,15 +168,13 @@ Extends Mt5Client with pandas DataFrame and dictionary conversions:
 
 Advanced trading operations client that extends Mt5DataClient:
 
-- **Trading Configuration**:
-  - `order_filling_mode` - Order execution mode: "IOC" (default), "FOK", or "RETURN"
-  - `dry_run` - Test mode flag for simulating trades without execution
 - **Position Management**:
   - `close_open_positions()` - Close all positions for specified symbol(s)
   - `place_market_order()` - Place market orders with configurable side, volume, and execution modes
-  - `update_open_position_sltp()` - Modify stop loss and take profit levels for open positions
-- **Market Analysis**:
-  - `calculate_minimum_order_margins()` - Calculate minimum required margins for buy/sell orders
+  - `update_sltp_for_open_positions()` - Modify stop loss and take profit levels for open positions
+- **Margin Calculations**:
+  - `calculate_minimum_order_margin()` - Calculate minimum required margin for a specific order side
+  - `calculate_volume_by_margin()` - Calculate maximum volume for given margin amount
   - `calculate_spread_ratio()` - Calculate normalized bid-ask spread ratio
   - `calculate_new_position_margin_ratio()` - Calculate margin ratio for potential new positions
 - **Simplified Data Access**:
@@ -187,7 +187,6 @@ Advanced trading operations client that extends Mt5DataClient:
   - Comprehensive error handling with `Mt5TradingError`
   - Support for batch operations on multiple symbols
   - Automatic position closing with proper order type reversal
-  - Dry run mode for strategy testing without real trades
 
 ### Configuration
 
@@ -264,8 +263,8 @@ with Mt5DataClient(config=config) as client:
 ```python
 from pdmt5 import Mt5TradingClient
 
-# Create trading client with specific order filling mode
-with Mt5TradingClient(config=config, order_filling_mode="IOC") as trader:
+# Create trading client
+with Mt5TradingClient(config=config) as trader:
     # Place a market buy order
     order_result = trader.place_market_order(
         symbol="EURUSD",
@@ -276,44 +275,33 @@ with Mt5TradingClient(config=config, order_filling_mode="IOC") as trader:
     )
     print(f"Order placed: {order_result['retcode']}")
 
-    # Update stop loss and take profit for an open position
-    if positions := trader.positions_get_as_df(symbol="EURUSD"):
-        position_ticket = positions.iloc[0]['ticket']
-        update_result = trader.update_open_position_sltp(
-            symbol="EURUSD",
-            position_ticket=position_ticket,
-            sl=1.0950,  # New stop loss
-            tp=1.1050   # New take profit
-        )
-        print(f"Position updated: {update_result['retcode']}")
+    # Update stop loss and take profit for open positions
+    update_results = trader.update_sltp_for_open_positions(
+        symbol="EURUSD",
+        stop_loss=1.0950,   # New stop loss
+        take_profit=1.1050  # New take profit
+    )
+    for result in update_results:
+        print(f"Position updated: {result['retcode']}")
 
     # Calculate margin ratio for a new position
     margin_ratio = trader.calculate_new_position_margin_ratio(
         symbol="EURUSD",
-        new_side="SELL",
-        new_volume=0.2
+        new_position_side="SELL",
+        new_position_volume=0.2
     )
     print(f"New position margin ratio: {margin_ratio:.2%}")
 
-    # Close all EURUSD positions
-    results = trader.close_open_positions(symbols="EURUSD")
+    # Close all EURUSD positions with specific order filling mode
+    results = trader.close_open_positions(
+        symbols="EURUSD",
+        order_filling_mode="FOK"  # Fill or Kill
+    )
 
     if results:
         for symbol, close_results in results.items():
             for result in close_results:
                 print(f"Closed position {result.get('position')} with result: {result['retcode']}")
-
-    # Using dry run mode for testing
-    trader_dry = Mt5TradingClient(config=config, dry_run=True)
-    with trader_dry:
-        # Test placing an order without actual execution
-        test_order = trader_dry.place_market_order(
-            symbol="GBPUSD",
-            volume=0.1,
-            order_side="SELL",
-            dry_run=True  # Override instance setting
-        )
-        print(f"Test order validation: {test_order['retcode']}")
 ```
 
 ### Market Analysis with Mt5TradingClient
@@ -324,10 +312,18 @@ with Mt5TradingClient(config=config) as trader:
     spread_ratio = trader.calculate_spread_ratio("EURUSD")
     print(f"EURUSD spread ratio: {spread_ratio:.5f}")
 
-    # Get minimum order margins
-    margins = trader.calculate_minimum_order_margins("EURUSD")
-    print(f"Minimum ask margin: {margins['ask']}")
-    print(f"Minimum bid margin: {margins['bid']}")
+    # Get minimum order margin for BUY and SELL
+    buy_margin = trader.calculate_minimum_order_margin("EURUSD", "BUY")
+    sell_margin = trader.calculate_minimum_order_margin("EURUSD", "SELL")
+    print(f"Minimum BUY margin: {buy_margin['margin']} (volume: {buy_margin['volume']})")
+    print(f"Minimum SELL margin: {sell_margin['margin']} (volume: {sell_margin['volume']})")
+    
+    # Calculate volume by margin
+    available_margin = 1000.0
+    max_buy_volume = trader.calculate_volume_by_margin("EURUSD", available_margin, "BUY")
+    max_sell_volume = trader.calculate_volume_by_margin("EURUSD", available_margin, "SELL")
+    print(f"Max BUY volume for ${available_margin}: {max_buy_volume}")
+    print(f"Max SELL volume for ${available_margin}: {max_sell_volume}")
 
     # Get recent OHLC data with custom timeframe
     rates_df = trader.fetch_latest_rates_as_df(

pdmt5-0.1.7/docs/api/trading.md

@@ -0,0 +1,396 @@
+# Trading
+
+::: pdmt5.trading
+
+## Overview
+
+The trading module extends Mt5DataClient with advanced trading operations including position management, order execution, and dry run support for testing trading strategies without actual execution.
+
+## Classes
+
+### Mt5TradingClient
+::: pdmt5.trading.Mt5TradingClient
+    options:
+      show_bases: false
+
+Advanced trading client class that inherits from `Mt5DataClient` and provides specialized trading functionality.
+
+### Mt5TradingError
+::: pdmt5.trading.Mt5TradingError
+    options:
+      show_bases: false
+
+Custom runtime exception for trading-specific errors.
+
+## Usage Examples
+
+### Basic Trading Operations
+
+```python
+import MetaTrader5 as mt5
+from pdmt5 import Mt5TradingClient, Mt5Config
+
+# Create configuration
+config = Mt5Config(
+    login=123456,
+    password="your_password",
+    server="broker_server",
+    timeout=60000,
+    portable=False
+)
+
+# Create client with dry run mode for testing
+client = Mt5TradingClient(config=config, dry_run=True)
+
+# Use as context manager
+with client:
+    # Get current positions as DataFrame
+    positions_df = client.get_positions_as_df()
+    print(f"Open positions: {len(positions_df)}")
+
+    # Close positions for specific symbol
+    results = client.close_open_positions("EURUSD")
+    print(f"Closed positions: {results}")
+```
+
+### Production Trading
+
+```python
+# Create client for live trading (dry_run=False)
+client = Mt5TradingClient(config=config, dry_run=False)
+
+with client:
+    # Close all positions for multiple symbols
+    results = client.close_open_positions(["EURUSD", "GBPUSD", "USDJPY"])
+
+    # Close all positions (all symbols)
+    all_results = client.close_open_positions()
+```
+
+### Order Filling Modes
+
+```python
+with Mt5TradingClient(config=config) as client:
+    # Use IOC (Immediate or Cancel) - default
+    results_ioc = client.close_open_positions(
+        symbols="EURUSD",
+        order_filling_mode="IOC"
+    )
+
+    # Use FOK (Fill or Kill)
+    results_fok = client.close_open_positions(
+        symbols="GBPUSD",
+        order_filling_mode="FOK"
+    )
+
+    # Use RETURN (Return if not filled)
+    results_return = client.close_open_positions(
+        symbols="USDJPY",
+        order_filling_mode="RETURN"
+    )
+```
+
+### Custom Order Parameters
+
+```python
+with client:
+    # Close positions with custom parameters and order filling mode
+    results = client.close_open_positions(
+        "EURUSD",
+        order_filling_mode="IOC",  # Specify per method call
+        comment="Closing all EURUSD positions",
+        deviation=10  # Maximum price deviation
+    )
+```
+
+### Error Handling
+
+```python
+from pdmt5.trading import Mt5TradingError
+
+try:
+    with client:
+        results = client.close_open_positions("EURUSD")
+except Mt5TradingError as e:
+    print(f"Trading error: {e}")
+    # Handle specific trading errors
+```
+
+### Checking Order Status
+
+```python
+with client:
+    # Check order (note: send_or_check_order is an internal method)
+    # For trading operations, use the provided methods like close_open_positions
+
+    # Example: Check if we can close a position
+    positions = client.get_positions_as_df()
+    if not positions.empty:
+        # Close specific position
+        results = client.close_open_positions("EURUSD")
+```
+
+## Position Management Features
+
+The Mt5TradingClient provides intelligent position management:
+
+- **Automatic Position Reversal**: Automatically determines the correct order type to close positions
+- **Batch Operations**: Close multiple positions for one or more symbols
+- **Dry Run Support**: Test trading logic without executing real trades
+- **Flexible Filtering**: Close positions by symbol, group, or all positions
+- **Custom Parameters**: Support for additional order parameters like comment, deviation, etc.
+
+## Dry Run Mode
+
+Dry run mode is essential for testing trading strategies:
+
+```python
+# Test mode - validates orders without execution
+test_client = Mt5TradingClient(config=config, dry_run=True)
+
+# Production mode - executes real orders
+prod_client = Mt5TradingClient(config=config, dry_run=False)
+```
+
+In dry run mode:
+- Orders are validated using `order_check()` instead of `order_send()`
+- No actual trades are executed
+- Full validation of margin requirements and order parameters
+- Same return structure as live trading for easy testing
+
+## Return Values
+
+The `close_open_positions()` method returns a dictionary with symbols as keys:
+
+```python
+{
+    "EURUSD": [
+        {
+            "retcode": 10009,  # Trade done
+            "deal": 123456,
+            "order": 789012,
+            "volume": 1.0,
+            "price": 1.1000,
+            "comment": "Request executed",
+            ...
+        }
+    ],
+    "GBPUSD": [...]
+}
+```
+
+## Best Practices
+
+1. **Always use dry run mode first** to test your trading logic
+2. **Handle Mt5TradingError exceptions** for proper error management
+3. **Check return codes** to verify successful execution
+4. **Use context managers** for automatic connection handling
+5. **Log trading operations** for audit trails
+6. **Validate positions exist** before attempting to close them
+7. **Consider market hours** and trading session times
+
+## Common Return Codes
+
+- `TRADE_RETCODE_DONE` (10009): Trade operation completed successfully
+- `TRADE_RETCODE_TRADE_DISABLED`: Trading disabled for the account
+- `TRADE_RETCODE_MARKET_CLOSED`: Market is closed
+- `TRADE_RETCODE_NO_MONEY`: Insufficient funds
+- `TRADE_RETCODE_INVALID_VOLUME`: Invalid trade volume
+
+## Margin Calculation Methods
+
+The trading client provides advanced margin calculation capabilities:
+
+### Calculate Minimum Order Margin
+
+```python
+with client:
+    # Calculate minimum margin required for BUY order
+    min_margin_buy = client.calculate_minimum_order_margin("EURUSD", "BUY")
+    print(f"Minimum volume: {min_margin_buy['volume']}")
+    print(f"Minimum margin: {min_margin_buy['margin']}")
+
+    # Calculate minimum margin required for SELL order
+    min_margin_sell = client.calculate_minimum_order_margin("EURUSD", "SELL")
+```
+
+### Calculate Volume by Margin
+
+```python
+with client:
+    # Calculate maximum volume for given margin amount
+    available_margin = 1000.0  # USD
+    max_volume_buy = client.calculate_volume_by_margin("EURUSD", available_margin, "BUY")
+    max_volume_sell = client.calculate_volume_by_margin("EURUSD", available_margin, "SELL")
+
+    print(f"Max BUY volume for ${available_margin}: {max_volume_buy}")
+    print(f"Max SELL volume for ${available_margin}: {max_volume_sell}")
+```
+
+### Calculate New Position Margin Ratio
+
+```python
+with client:
+    # Calculate margin ratio for potential new position
+    margin_ratio = client.calculate_new_position_margin_ratio(
+        symbol="EURUSD",
+        new_position_side="BUY",
+        new_position_volume=1.0
+    )
+    print(f"New position would use {margin_ratio:.2%} of account equity")
+
+    # Check if adding position would exceed risk limits
+    if margin_ratio > 0.1:  # 10% risk limit
+        print("Position size too large for risk management")
+```
+
+## Market Order Placement
+
+Place market orders with flexible configuration:
+
+```python
+with client:
+    # Place a BUY market order
+    result = client.place_market_order(
+        symbol="EURUSD",
+        volume=1.0,
+        order_side="BUY",
+        order_filling_mode="IOC",  # Immediate or Cancel
+        order_time_mode="GTC",     # Good Till Cancelled
+        dry_run=False,             # Set to True for testing
+        comment="My buy order"
+    )
+
+    # Place a SELL market order with FOK filling
+    result = client.place_market_order(
+        symbol="EURUSD",
+        volume=0.5,
+        order_side="SELL",
+        order_filling_mode="FOK",  # Fill or Kill
+        dry_run=True  # Test mode
+    )
+
+    print(f"Order result: {result}")
+```
+
+## Stop Loss and Take Profit Management
+
+Update SL/TP for existing positions:
+
+```python
+with client:
+    # Update SL/TP for all EURUSD positions
+    results = client.update_sltp_for_open_positions(
+        symbol="EURUSD",
+        stop_loss=1.0950,
+        take_profit=1.1100,
+        dry_run=False
+    )
+
+    # Update only specific positions by ticket
+    results = client.update_sltp_for_open_positions(
+        symbol="EURUSD",
+        stop_loss=1.0950,
+        tickets=[123456, 789012],  # Specific position tickets
+        dry_run=True
+    )
+```
+
+## Market Data and Analysis Methods
+
+### Spread Analysis
+
+```python
+with client:
+    # Calculate spread ratio for symbol
+    spread_ratio = client.calculate_spread_ratio("EURUSD")
+    print(f"EURUSD spread ratio: {spread_ratio:.6f}")
+```
+
+### OHLC Data Retrieval
+
+```python
+with client:
+    # Fetch latest rate data as DataFrame
+    rates_df = client.fetch_latest_rates_as_df(
+        symbol="EURUSD",
+        granularity="M1",  # 1-minute bars
+        count=1440,        # Last 24 hours
+        index_keys="time"
+    )
+    print(f"Latest rates: {rates_df.tail()}")
+```
+
+### Tick Data Analysis
+
+```python
+with client:
+    # Fetch recent tick data
+    ticks_df = client.fetch_latest_ticks_as_df(
+        symbol="EURUSD",
+        seconds=300,           # Last 5 minutes
+        index_keys="time_msc"
+    )
+    print(f"Tick count: {len(ticks_df)}")
+```
+
+### Position Analytics with Enhanced Metrics
+
+```python
+with client:
+    # Get positions with additional calculated metrics
+    positions_df = client.fetch_positions_with_metrics_as_df("EURUSD")
+
+    if not positions_df.empty:
+        print("Position metrics:")
+        print(f"Total signed volume: {positions_df['signed_volume'].sum()}")
+        print(f"Total signed margin: {positions_df['signed_margin'].sum()}")
+        print(f"Average profit ratio: {positions_df['underlier_profit_ratio'].mean():.4f}")
+```
+
+### Deal History Analysis
+
+```python
+with client:
+    # Collect entry deals for analysis
+    deals_df = client.collect_entry_deals_as_df(
+        symbol="EURUSD",
+        history_seconds=3600,  # Last hour
+        index_keys="ticket"
+    )
+
+    if not deals_df.empty:
+        print(f"Entry deals found: {len(deals_df)}")
+        print(f"Deal types: {deals_df['type'].value_counts()}")
+```
+
+## Integration with Mt5DataClient
+
+Since Mt5TradingClient inherits from Mt5DataClient, all data retrieval methods are available:
+
+```python
+with Mt5TradingClient(config=config) as client:
+    # Get current positions as DataFrame
+    positions_df = client.get_positions_as_df()
+
+    # Analyze positions
+    if not positions_df.empty:
+        # Calculate total exposure
+        total_volume = positions_df['volume'].sum()
+
+        # Close losing positions
+        losing_positions = positions_df[positions_df['profit'] < 0]
+        for symbol in losing_positions['symbol'].unique():
+            client.close_open_positions(symbol)
+
+    # Risk management with margin calculations
+    for symbol in ["EURUSD", "GBPUSD", "USDJPY"]:
+        # Calculate current margin usage
+        current_ratio = client.calculate_new_position_margin_ratio(symbol)
+        print(f"{symbol} current margin ratio: {current_ratio:.2%}")
+
+        # Calculate maximum safe position size
+        safe_margin = 500.0  # USD
+        max_safe_volume = client.calculate_volume_by_margin(symbol, safe_margin, "BUY")
+        print(f"{symbol} max safe volume: {max_safe_volume}")
+```