Skip to content

Migration Guide

Igor Sazonov edited this page Apr 5, 2026 · 1 revision

Upgrading to v2.0? Relax. This is the easy kind of upgrade.

The TL;DR

✅ The Best News You'll Hear Today

Your code still works. All of it. We didn't break anything. Promise.

// This still works exactly as before
$price = Bingx::market()->getLatestPrice('BTC-USDT');
$balance = Bingx::account()->getBalance();
$order = Bingx::trade()->createOrder([
    'symbol' => 'BTC-USDT',
    'side' => 'BUY',
    'type' => 'MARKET',
    'quantity' => 0.001
]);

🆕 The New Toys

All opt-in. Use them when you feel like it:

  • TWAP Service — Trade like the big boys
  • Trailing Stops — Finally, stop-losses that make sense
  • Multi-Assets Margin — Your whole portfolio works for you
  • Position Risk Monitoring — Know before you blow
  • Enhanced Market Data — See what the pros see

The Upgrade (It's Easy)

Step 1: Update

composer update tigusigalpa/bingx-php

That's... basically it.

Step 2: Clear Cache (Laravel folks)

php artisan config:clear
php artisan cache:clear

Step 3: Make Sure Nothing Broke

Run your existing code. It should just work:

// Test basic operations
$price = Bingx::market()->getLatestPrice('BTC-USDT');
$balance = Bingx::account()->getBalance();
$positions = Bingx::account()->getPositions();

echo "All working? Good! ✅\n";

Step 4: Play With The New Stuff

No rush. Try things out when you're ready:

// Week 1: Add position risk monitoring
$risk = Bingx::account()->getPositionRisk('BTC-USDT');

// Week 2: Try trailing stops
$order = Bingx::trade()->order()
    ->type('TRAILING_STOP_MARKET')
    ->activationPrice(52000)
    ->callbackRate(2.0)
    ->execute();

// Week 3: Test TWAP orders
$twap = Bingx::twap()->buy('BTC-USDT', 1.0, 3600, 'LONG');

// Week 4: Consider multi-assets margin (if experienced)
Bingx::trade()->switchMultiAssetsMode(true);

Breaking Changes

There Are None 🎉

Seriously. We tested this. Your old code works. Go check. We'll wait.

Deprecated Features

Also None

We're not deprecating anything. When we do (someday), you'll get plenty of warning. Like, months of warning.

New Methods (The Fun Part)

Here's what you can now do:

// v3 methods have descriptive names
Bingx::account()->getPositionRisk()        // NEW
Bingx::account()->getIncomeHistory()       // NEW
Bingx::account()->getCommissionHistory()   // NEW

Bingx::trade()->switchMultiAssetsMode()    // NEW
Bingx::trade()->oneClickReversePosition()  // NEW
Bingx::trade()->setAutoAddMargin()         // NEW

Bingx::market()->getOpenInterest()         // NEW
Bingx::market()->getFundingRateInfo()      // NEW
Bingx::market()->getBookTicker()           // NEW

Bingx::twap()->buy()                       // NEW SERVICE
Bingx::twap()->sell()                      // NEW SERVICE

OrderBuilder Got Cooler

New order types you can use:

// Old types still work
$order = Bingx::trade()->order()
    ->type('MARKET')   // ✅ Still works
    ->type('LIMIT')    // ✅ Still works
    ->type('STOP')     // ✅ Still works

// New types available
$order = Bingx::trade()->order()
    ->type('TRAILING_STOP_MARKET')  // 🆕 v3
    ->type('TRIGGER_LIMIT')         // 🆕 v3
    ->type('TRAILING_TP_SL')        // 🆕 v3

New parameters:

$order = Bingx::trade()->order()
    // New v3 parameters
    ->activationPrice(50000)      // 🆕
    ->callbackRate(2.0)           // 🆕
    ->trailingStopPercent(1.5)    // 🆕
    ->takeProfitPrice(55000)      // 🆕
    ->stopLossPrice(48000)        // 🆕
    
    // Old parameters still work
    ->stopLossPercent(5)          // ✅
    ->takeProfitPercent(10)       // ✅

Configuration

Change Nothing

Your .env file? Leave it alone. It still works:

BINGX_API_KEY=your_key
BINGX_API_SECRET=your_secret
BINGX_BASE_URI=https://open-api.bingx.com
BINGX_SIGNATURE_ENCODING=base64

Optional: Add Source Key

If you have a source key (referral/partnership):

BINGX_SOURCE_KEY=your_source_key

Sanity Check

Run these to make sure everything's working:

1. Can We Get Market Data?

// Should work exactly as before
$price = Bingx::market()->getLatestPrice('BTC-USDT');
$depth = Bingx::market()->getDepth('BTC-USDT', 20);
$klines = Bingx::market()->getKlines('BTC-USDT', '1h', 100);

echo "Market data: ✅\n";

2. Can We See Our Account?

$balance = Bingx::account()->getBalance();
$positions = Bingx::account()->getPositions();
$leverage = Bingx::account()->getLeverage('BTC-USDT');

echo "Account access: ✅\n";

3. Can We Trade? (Small Test!)

// Test with minimum size
$order = Bingx::trade()->order()
    ->futures()
    ->symbol('BTC-USDT')
    ->buy()
    ->long()
    ->type('LIMIT')
    ->margin(10)  // Small amount
    ->price(/* current price */)
    ->leverage(1)
    ->execute();

// Cancel it
Bingx::trade()->cancelOrder('BTC-USDT', $order['orderId']);

echo "Trading: ✅\n";

4. Do The New Features Work?

// Test position risk (v3)
$risk = Bingx::account()->getPositionRisk('BTC-USDT');
echo "Position risk: ✅\n";

// Test enhanced market data (v3)
$oi = Bingx::market()->getOpenInterest('BTC-USDT');
echo "Open interest: ✅\n";

// Test TWAP (v3)
$twap = Bingx::twap()->getOpenOrders('BTC-USDT');
echo "TWAP service: ✅\n";

Real-World Examples

Your Simple Trading Bot

Before (v1.x):

while (true) {
    $price = Bingx::market()->getLatestPrice('BTC-USDT');
    
    if ($price['price'] < 48000) {
        Bingx::trade()->order()
            ->futures()
            ->symbol('BTC-USDT')
            ->buy()
            ->long()
            ->type('MARKET')
            ->margin(100)
            ->leverage(10)
            ->execute();
    }
    
    sleep(60);
}

After (literally the same code):

// Exact same code works
while (true) {
    $price = Bingx::market()->getLatestPrice('BTC-USDT');
    
    if ($price['price'] < 48000) {
        Bingx::trade()->order()
            ->futures()
            ->symbol('BTC-USDT')
            ->buy()
            ->long()
            ->type('MARKET')
            ->margin(100)
            ->leverage(10)
            ->execute();
    }
    
    sleep(60);
}

After (now with superpowers):

while (true) {
    $price = Bingx::market()->getLatestPrice('BTC-USDT');
    
    // Check position risk before trading
    $risk = Bingx::account()->getPositionRisk('BTC-USDT');
    if (!empty($risk) && $risk['marginRatio'] > 80) {
        echo "Too risky, skipping\n";
        sleep(60);
        continue;
    }
    
    if ($price['price'] < 48000) {
        // Use trailing stop instead of fixed stop
        $order = Bingx::trade()->order()
            ->futures()
            ->symbol('BTC-USDT')
            ->buy()
            ->long()
            ->type('MARKET')
            ->margin(100)
            ->leverage(10)
            ->execute();
            
        // Set trailing stop
        Bingx::trade()->order()
            ->futures()
            ->symbol('BTC-USDT')
            ->sell()
            ->long()
            ->type('TRAILING_STOP_MARKET')
            ->activationPrice(50000)
            ->callbackRate(2.0)
            ->quantity(/* size */)
            ->execute();
    }
    
    sleep(60);
}

Your Portfolio Dashboard

Before (v1.x):

$positions = Bingx::account()->getPositions();

foreach ($positions as $pos) {
    echo "{$pos['symbol']}: {$pos['unrealizedProfit']}\n";
}

After (v2.0 - enhanced):

$positions = Bingx::account()->getPositions();

foreach ($positions as $pos) {
    $symbol = $pos['symbol'];
    
    // Get detailed risk metrics (v3)
    $risk = Bingx::account()->getPositionRisk($symbol);
    
    echo "{$symbol}:\n";
    echo "  P&L: {$pos['unrealizedProfit']}\n";
    echo "  Margin Ratio: {$risk['marginRatio']}%\n";
    echo "  Liquidation: {$risk['liquidationPrice']}\n";
    
    // Alert if risky
    if ($risk['marginRatio'] > 75) {
        echo "  ⚠️ HIGH RISK!\n";
    }
}

// Get income breakdown (v3)
$income = Bingx::account()->getIncomeHistory(limit: 100);
$totalPnl = array_sum(array_column($income, 'income'));
echo "\nTotal P&L: {$totalPnl}\n";

Your Big Order Problem (Solved)

Before (v1.x):

// Market order with slippage risk
Bingx::trade()->order()
    ->futures()
    ->symbol('BTC-USDT')
    ->buy()
    ->long()
    ->type('MARKET')
    ->quantity(10.0)  // Might move the market!
    ->leverage(5)
    ->execute();

After (v2.0 - use TWAP):

// TWAP order to minimize slippage (v3)
$twap = Bingx::twap()->buy(
    symbol: 'BTC-USDT',
    quantity: 10.0,
    duration: 3600,  // Execute over 1 hour
    positionSide: 'LONG'
);

// Monitor progress
while (true) {
    $details = Bingx::twap()->getOrderDetail($twap['orderId']);
    
    if ($details['status'] === 'FILLED') {
        echo "Completed at avg price: {$details['avgPrice']}\n";
        break;
    }
    
    $progress = ($details['executedQty'] / $details['totalQty']) * 100;
    echo "Progress: {$progress}%\n";
    
    sleep(60);
}

Something Wrong?

"Method not found"

What happened: You're trying to use v3 stuff but didn't update.

Fix it:

composer update tigusigalpa/bingx-php
php artisan config:clear

"Invalid order type"

What happened: New order type, old package.

Fix it: Update the package. Done.

"Endpoint not found"

What happened: BingX might not have enabled this for your account yet.

Fix it: Contact BingX support. Some features need verification.

Oh No, Go Back!

If something's really broken (it won't be, but just in case):

# Rollback to v1.x
composer require tigusigalpa/bingx-php:^1.0

# Clear cache
php artisan config:clear
php artisan cache:clear

Back to normal. But seriously, you won't need this.

Need Help?

  1. Search this Wiki — Probably answered already
  2. Check the Examples — Copy-paste solutions
  3. Search GitHub Issues — Someone probably had the same problem
  4. Open an Issue — We're friendly, we promise

Your Checklist

  • Run composer update
  • Clear cache (Laravel)
  • Test your existing code (it works, right?)
  • Skim the new features (they're cool)
  • Try one new feature with a tiny amount
  • Update your bots when you're ready
  • Celebrate 🎉

What Now?


Still stuck? Open an issue. We read them all.

Welcome to v2.0. Now go make some money. 🚀

Clone this wiki locally