Binance provides two order placement endpoints for all Cross Margin and Isolated Margin users:
- POST /sapi/v1/margin/order
- POST /sapi/v1/margin/order/oco
Under the endpoints, you can use four different modes to place orders with the “sideEffectType” parameter:
- NO_SIDE_EFFECT (normal mode): It places a buy/sell order using the existing assets in the Margin Account. Under normal circumstances, you’d need to manually borrow and repay on the Margin platform, or through POST /sapi/v1/margin/borrow-repay.
- MARGIN_BUY (automatic borrowing): It automatically borrows assets to place a buy/sell order based on your maximum leverage level. It’s equivalent to "borrow asset + place order".
- Please note that borrowing is considered complete when the order is successfully placed. It doesn’t mean that your order is executed.
- AUTO_REPAY (automatic repayment): After the buy/sell order is complete, the system will automatically use the received assets to repay that asset’s liabilities. Simply put, it’s equivalent to “place order + order execution + repayment".
- Your repayment needs to be the same cryptocurrency as the one you borrowed. For example, if you borrowed ETH, your account must have ETH when you repay.
- Any repayment will be applied to the outstanding interest first before being used to reduce the outstanding principal.
- AUTO_BORROW_REPAY (automatic borrowing and repayment, simultaneously): When the user places an order, combining MARGIN_BUY and AUTO_REPAY modes, it completes "borrow asset + place order + order execution + repayment".
Below are some examples of using “sideEffectType”. Click to expand each box to view more details.
Example 1
User A holds 1 BTC asset and 10,000 USDT liabilities. They use the “POST /sapi/v1/margin/order” endpoint and set “sideEffectType”' to “NO_SIDE_EFFECT”. After placing a sell order for 1 BTC at 40,000 USDT, User A now holds 40,000 USDT assets and 10,000 USDT liabilities.
Parameters:
| Parameter | Value |
| symbol | BTCUSDT |
| isIsolated | FALSE |
| side | SELL |
| type | Limit |
| quantity | 1 |
| quoteOrderQty | |
| price | 40,000 |
| stopPrice | |
| newClientOrderId | |
| icebergQty | |
| newOrderRespType | |
| sideEffectType | NO_SIDE_EFFECT |
| timeInForce | GTC |
| selfTradePreventionMode | NONE |
| autoRepayAtCancel | |
| recvWindow | |
| timestamp | 1507725176595 |
Response:
{
"symbol": "BTCUSDT",
"orderId": 28,
"clientOrderId": "6gCrw2kRUAF9CvJDGP16IP",
"transactTime": 1507725176595,
"price": "40000.00000000",
"origQty": "1.00000000",
"executedQty": "1.00000000",
"cummulativeQuoteQty": "1.00000000",
"status": "FILLED",
"timeInForce": "GTC",
"type": "Limit",
"side": "SELL",
"isIsolated": false, // true for Isolated Margin
"selfTradePreventionMode": "NONE",
"fills": [
{
"price": "40000.00000000",
"qty": "1.00000000",
"commission": "40.00000000",
"commissionAsset": "USDT"
}
]
}
Example 2
User B holds 1 BTC asset and 10,000 USDT liabilities. They used the “POST /sapi/v1/margin/order” endpoint and set “sideEffectType” to “MARGIN_BUY”. After placing a buy order for 0.5 BTC at 40,000 USDT, User B automatically borrows 20,000 USDT. User B now has 1.5 BTC assets and 30,000 USDT liabilities.
Parameters:
| Parameter | Value |
| symbol | BTCUSDT |
| isIsolated | FALSE |
| side | BUY |
| type | Limit |
| quantity | 0.5 |
| quoteOrderQty | |
| price | 40,000 |
| stopPrice | |
| newClientOrderId | |
| icebergQty | |
| newOrderRespType | |
| sideEffectType | MARGIN_BUY |
| timeInForce | GTC |
| selfTradePreventionMode | NONE |
| autoRepayAtCancel | TRUE |
| recvWindow | |
| timestamp | 1507725176595 |
Response:
{
"symbol": "BTCUSDT",
"orderId": 29,
"clientOrderId": "6gCrw2kRUAF9CvJDGP16IP",
"transactTime": 1507725176595,
"price": "40000.00000000",
"origQty": "0.50000000",
"executedQty": "0.50000000",
"cummulativeQuoteQty": "0.50000000",
"status": "FILLED",
"timeInForce": "GTC",
"type": "Limit",
"side": "BUY",
"marginBuyBorrowAmount": 20000, // will not return if no margin trade happens
"marginBuyBorrowAsset": "USDT", // will not return if no margin trade happens
"isIsolated": false, // true for Isolated Margin
"selfTradePreventionMode": "NONE",
"fills": [
{
"price": "40000.00000000",
"qty": "0.50000000",
"commission": "20.00000000",
"commissionAsset": "USDT"
}
]
}
Example 3
User C holds 1 BTC asset and 10,000 USDT liabilities. They used the “POST /sapi/v1/margin/order” endpoint and set “sideEffectType” to “AUTO_REPAY”. After placing a sell order for 1 BTC at 40,000 USDT, the system automatically repays the 10,000 USDT liability (interest is ignored here). User C now holds 30,000 USDT assets and no outstanding debts.
Parameters:
| Parameter | Value |
| symbol | BTCUSDT |
| isIsolated | FALSE |
| side | SELL |
| type | Limit |
| quantity | 1 |
| quoteOrderQty | |
| price | 40,000 |
| stopPrice | |
| newClientOrderId | |
| icebergQty | |
| newOrderRespType | |
| sideEffectType | AUTO_REPAY |
| timeInForce | GTC |
| selfTradePreventionMode | NONE |
| autoRepayAtCancel | |
| recvWindow | |
| timestamp | 1507725176595 |
Response:
{
"symbol": "BTCUSDT",
"orderId": 30,
"clientOrderId": "6gCrw2kRUAF9CvJDGP16IP",
"transactTime": 1507725176595,
"price": "40000.00000000",
"origQty": "1.00000000",
"executedQty": "1.00000000",
"cummulativeQuoteQty": "1.00000000",
"status": "FILLED",
"timeInForce": "GTC",
"type": "Limit",
"side": "SELL",
"isIsolated": false, // true for Isolated Margin
"selfTradePreventionMode": "NONE",
"fills": [
{
"price": "40000.00000000",
"qty": "1.00000000",
"commission": "40.00000000",
"commissionAsset": "USDT"
}
]
}
Example 4
User D holds 1 BTC asset and 10,000 USDT liabilities. They used the “POST /sapi/v1/margin/order” endpoint and set “sideEffectType” to “AUTO_BORROW_REPAY”. After placing a sell order for 4 ETH at 2,500 USDT, the system automatically borrows 4 ETH and at the same time repays 10,000 USDT (interest is ignored here). As a result, User D holds 1 BTC asset and 4 ETH liabilities.
Parameters:
| Parameter | Value |
| symbol | ETHUSDT |
| isIsolated | FALSE |
| side | SELL |
| type | Limit |
| quantity | 4 |
| quoteOrderQty | |
| price | 2,500 |
| stopPrice | |
| newClientOrderId | |
| icebergQty | |
| newOrderRespType | |
| sideEffectType | AUTO_BORROW_REPAY |
| timeInForce | GTC |
| selfTradePreventionMode | NONE |
| autoRepayAtCancel | TRUE |
| recvWindow | |
| timestamp | 1507725176595 |
Response:
{
"symbol": "ETHUSDT",
"orderId": 31,
"clientOrderId": "6gCrw2kRUAF9CvJDGP16IP",
"transactTime": 1507725176595,
"price": "2500.00000000",
"origQty": "4.00000000",
"executedQty": "4.00000000",
"cummulativeQuoteQty": "4.00000000",
"status": "FILLED",
"timeInForce": "GTC",
"type": "Limit",
"side": "SELL",
"marginBuyBorrowAmount": 4,// will not return if no margin trade happens
"marginBuyBorrowAsset": "ETH", // will not return if no margin trade happens
"isIsolated": false, // true for Isolated Margin
"selfTradePreventionMode": "NONE",
"fills": [
{
"price": "2500.00000000",
"qty": "4.00000000",
"commission": "10.00000000",
"commissionAsset": "USDT"
}
]
}
For more examples, please refer to Margin Account and Trading Interface on GibHub.