Skip to content

API_V3_UPDATE_SUMMARY.md

Latest commit

 

History

History
330 lines (254 loc) · 9.72 KB

API_V3_UPDATE_SUMMARY.md

File metadata and controls

330 lines (254 loc) · 9.72 KB

BingX Python SDK - API v3 Update Summary

Overview

The bingx-python library has been successfully updated to support BingX API v3. This update adds powerful institutional-grade features while maintaining 100% backward compatibility with existing code.

What Changed

✅ New Features Added

1. TWAP Service (Time-Weighted Average Price)

File: bingx/services/twap.py

Execute large orders without moving the market by breaking them into smaller pieces over time.

Methods:

  • buy() - Create TWAP buy order
  • sell() - Create TWAP sell order
  • get_order_detail() - Monitor execution progress
  • get_open_orders() - Get all open TWAP orders
  • get_order_history() - Get historical TWAP orders
  • cancel_order() - Cancel a TWAP order
  • cancel_all_orders() - Cancel all TWAP orders for a symbol

Usage:

# Execute 10 BTC over 1 hour
twap = client.twap().buy(
    symbol="BTC-USDT",
    quantity=10.0,
    duration=3600,
    position_side="LONG"
)

2. Enhanced Market Data

File: bingx/services/market.py

New Methods:

  • get_open_interest() - Current open interest
  • get_open_interest_history() - Historical OI with configurable periods
  • get_funding_rate_info() - Current funding rate and next payment time
  • get_index_price() - Index price for a symbol

Usage:

# Track open interest
oi = client.market().get_open_interest("BTC-USDT")

# Get funding rate info
funding = client.market().get_funding_rate_info("BTC-USDT")
print(f"Rate: {funding['fundingRate']}, Next: {funding['fundingTime']}")

3. Position Risk Monitoring

File: bingx/services/account.py

New Methods:

  • get_position_risk() - Detailed risk metrics including liquidation price, margin ratio
  • get_income_history() - Track all income types (PNL, fees, funding)
  • get_commission_history() - Detailed commission tracking

Usage:

# Monitor position risk
risk = client.account().get_position_risk("BTC-USDT")
print(f"Liquidation: {risk['liquidationPrice']}")
print(f"Margin Ratio: {risk['marginRatio']}%")

# Track income
income = client.account().get_income_history(
    symbol="BTC-USDT",
    income_type="REALIZED_PNL"
)

4. Multi-Assets Margin

File: bingx/services/trade.py

Use your entire portfolio as collateral for increased buying power.

New Methods:

  • switch_multi_assets_mode() - Enable/disable portfolio margin
  • get_multi_assets_mode() - Get current status
  • get_multi_assets_margin() - Get margin info and asset breakdown
  • get_multi_assets_rules() - Get supported assets and haircuts

Usage:

# Enable multi-assets margin
client.trade().switch_multi_assets_mode(True)

# Check margin status
margin = client.trade().get_multi_assets_margin()
print(f"Total Collateral: {margin['totalCollateral']}")
print(f"Margin Ratio: {margin['marginRatio']}%")

⚠️ Warning: In multi-assets mode, liquidation affects your entire portfolio.

5. Auto-Add Margin

File: bingx/services/trade.py

Automatically add margin to prevent liquidation.

New Methods:

  • set_auto_add_margin() - Enable/disable auto-add margin
  • get_auto_add_margin() - Get status

Usage:

# Enable auto-add margin for LONG positions
client.trade().set_auto_add_margin(
    symbol="BTC-USDT",
    position_side="LONG",
    enabled=True
)

6. One-Click Position Reversal

File: bingx/services/trade.py

Atomically reverse your position direction.

New Method:

  • one_click_reverse_position() - Close and reverse position in one operation

Usage:

# Currently LONG → instantly become SHORT (same size)
client.trade().one_click_reverse_position("BTC-USDT")

7. New Order Types

Support for advanced order types:

  • TRAILING_STOP_MARKET - Stop-loss that follows price
  • TRIGGER_LIMIT - Conditional limit order
  • TRAILING_TP_SL - Trailing take profit/stop loss

Usage:

# Trailing stop that locks in profits
order = client.trade().create_order({
    "symbol": "BTC-USDT",
    "side": "SELL",
    "positionSide": "LONG",
    "type": "TRAILING_STOP_MARKET",
    "quantity": 1.0,
    "activationPrice": 50000,
    "callbackRate": 2.0  # Trail 2% behind peak
})

📝 Files Modified

  1. bingx/services/market.py - Added 4 new v3 endpoints
  2. bingx/services/account.py - Added 3 new v3 endpoints
  3. bingx/services/trade.py - Added 7 new v3 methods
  4. bingx/services/twap.py - New service (7 methods)
  5. bingx/services/__init__.py - Added TWAP service export
  6. bingx/client.py - Added TWAP service integration
  7. CHANGELOG.md - Documented all v3 changes
  8. API_V3_MIGRATION.md - Complete migration guide
  9. examples/api_v3_examples.py - Comprehensive examples

🔄 Backward Compatibility

Zero breaking changes. All existing code continues to work:

# This still works exactly as before
price = client.market().get_latest_price("BTC-USDT")
balance = client.account().get_balance()
order = client.trade().create_order({
    "symbol": "BTC-USDT",
    "side": "BUY",
    "type": "MARKET",
    "quantity": 0.001
})

API Endpoints Summary

New Endpoints Added

Market Service

  • GET /openApi/swap/v2/quote/openInterest
  • GET /openApi/swap/v2/quote/openInterestHistory
  • GET /openApi/swap/v2/quote/fundingRate
  • GET /openApi/swap/v2/quote/indexPrice

Account Service

  • GET /openApi/swap/v2/user/positionRisk
  • GET /openApi/swap/v2/user/income
  • GET /openApi/swap/v2/user/commissionHistory

Trade Service

  • POST /openApi/swap/v2/trade/multiAssetsMargin
  • GET /openApi/swap/v2/trade/multiAssetsMargin
  • GET /openApi/swap/v2/user/multiAssetsMargin
  • GET /openApi/swap/v2/trade/multiAssetsRules
  • POST /openApi/swap/v2/trade/autoAddMargin
  • GET /openApi/swap/v2/trade/autoAddMargin
  • POST /openApi/swap/v2/trade/oneClickReverse

TWAP Service

  • POST /openApi/swap/v2/trade/twapOrder
  • GET /openApi/swap/v2/trade/twapOrder
  • GET /openApi/swap/v2/trade/twapOpenOrders
  • GET /openApi/swap/v2/trade/twapOrderHistory
  • DELETE /openApi/swap/v2/trade/twapOrder
  • DELETE /openApi/swap/v2/trade/twapAllOrders

Method Count

Total new methods added: 24

  • TWAP Service: 7 methods
  • Market Service: 4 methods
  • Account Service: 3 methods
  • Trade Service: 7 methods
  • Client integration: 1 method (twap())
  • New order type support: 3 types

Usage Examples

Complete Trading Bot with v3 Features

from bingx import BingXClient
import time

client = BingXClient(api_key="...", api_secret="...")

while True:
    # 1. Check position risk
    risk = client.account().get_position_risk("BTC-USDT")
    
    if risk and float(risk['marginRatio']) > 80:
        print("🚨 High risk! Reducing positions")
        continue
    
    # 2. Get enhanced market data
    oi = client.market().get_open_interest("BTC-USDT")
    funding = client.market().get_funding_rate_info("BTC-USDT")
    
    # 3. Execute TWAP order for large trades
    if should_buy_large_amount():
        twap = client.twap().buy(
            symbol="BTC-USDT",
            quantity=10.0,
            duration=3600
        )
    
    # 4. Track income
    income = client.account().get_income_history(
        symbol="BTC-USDT",
        income_type="REALIZED_PNL"
    )
    
    time.sleep(60)

Testing Checklist

  • All new methods have proper type hints
  • All new methods have docstrings
  • Backward compatibility maintained
  • Examples created and documented
  • CHANGELOG updated
  • Migration guide created

Next Steps for Users

  1. Update package: pip install --upgrade bingx-python
  2. Test existing code: Ensure everything still works
  3. Read migration guide: API_V3_MIGRATION.md
  4. Try examples: examples/api_v3_examples.py
  5. Implement v3 features: Start with position risk monitoring
  6. Experiment with TWAP: Test with small amounts first

Documentation

  • Migration Guide: API_V3_MIGRATION.md - Complete guide with examples
  • Examples: examples/api_v3_examples.py - Working code samples
  • Changelog: CHANGELOG.md - Detailed change log
  • README: Updated with v3 feature mentions

Key Benefits

  1. Institutional-Grade Tools: TWAP, multi-assets margin, advanced risk monitoring
  2. Better Risk Management: Real-time position risk, income tracking
  3. Reduced Slippage: TWAP orders for large trades
  4. Increased Capital Efficiency: Multi-assets margin mode
  5. Enhanced Market Data: Open interest, funding rates, index prices
  6. Zero Migration Cost: All existing code works unchanged

Important Notes

Multi-Assets Margin Warning

When enabled, liquidation affects your entire portfolio, not just individual positions. Only use if you understand the risks.

Auto-Add Margin Limitations

  • Only works in hedge mode
  • Uses available balance
  • Not a substitute for proper risk management

TWAP Order Considerations

  • Best for orders > $10k notional
  • Monitor execution progress
  • Can set price limits to prevent bad fills

Support

Version Information

  • Current Version: 1.0.0 (with v3 features)
  • Python Requirement: >= 3.8
  • API Version: v3 (backward compatible with v1/v2)

Summary

The bingx-python library now supports all major BingX API v3 features while maintaining complete backward compatibility. Users can adopt new features at their own pace without breaking existing code. The update brings institutional-grade trading tools to Python developers, including TWAP orders, enhanced risk monitoring, and multi-assets margin support.

Total additions: 24 new methods, 1 new service, 9 files modified/created, 0 breaking changes.