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. ```php // 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 ```bash composer update tigusigalpa/bingx-php ``` That's... basically it. ### Step 2: Clear Cache (Laravel folks) ```bash php artisan config:clear php artisan cache:clear ``` ### Step 3: Make Sure Nothing Broke Run your existing code. It should just work: ```php // 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: ```php // 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: ```php // 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: ```php // 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: ```php $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: ```env 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): ```env BINGX_SOURCE_KEY=your_source_key ``` ## Sanity Check Run these to make sure everything's working: ### 1. Can We Get Market Data? ```php // 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? ```php $balance = Bingx::account()->getBalance(); $positions = Bingx::account()->getPositions(); $leverage = Bingx::account()->getLeverage('BTC-USDT'); echo "Account access: ✅\n"; ``` ### 3. Can We Trade? (Small Test!) ```php // 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? ```php // 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):** ```php 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):** ```php // 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):** ```php 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):** ```php $positions = Bingx::account()->getPositions(); foreach ($positions as $pos) { echo "{$pos['symbol']}: {$pos['unrealizedProfit']}\n"; } ``` **After (v2.0 - enhanced):** ```php $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):** ```php // 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):** ```php // 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:** ```bash 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): ```bash # 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? - [API v3 Features](API-v3-Features.md) — See all the new toys - [TWAP Service](TWAP-Service.md) — Trade like institutions - [Risk Management](Risk-Management.md) — Stay in the game - [Examples](Examples.md) — Copy-paste your way to success --- **Still stuck?** [Open an issue](https://github.com/tigusigalpa/bingx-php/issues). We read them all. *Welcome to v2.0. Now go make some money.* 🚀