How to Use the “sideEffectType” Parameter with the Margin Order Endpoints?

2024-01-31 10:44

Last updated: 12 Sep 2024

Binance provides four order placement endpoints for all Cross Margin and Isolated Margin users:

POST /sapi/v1/margin/order
POST /sapi/v1/margin/order/oco
POST /sapi/v1/margin/order/oto
POST /sapi/v1/margin/order/otoco

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_REPAY mode is not suitable for the endpoints of “/sapi/v1/margin/order/otoco” and “/sapi/v1/margin/order/oto”
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".
- AUTO_BORROW_REPAY mode is not suitable for the endpoints of “/sapi/v1/margin/order/otoco” and “/sapi/v1/margin/order/oto”

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 USDC 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 USDC, User A now holds 40,000 USDC assets and 10,000 USDC liabilities.

Parameters:

Parameter	Value
symbol	BTCUSDC
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": "BTCUSDC",

"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": "USDC"

}

]

}

Example 2

User B holds 1 BTC asset and 10,000 USDC 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 USDC, User B automatically borrows 20,000 USDC. User B now has 1.5 BTC assets and 30,000 USDC liabilities.

Parameters:

Parameter	Value
symbol	BTCUSDC
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": "BTCUSDC",

"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": "USDC", // 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": "USDC"

}

]

}

Example 3

User C holds 1 BTC asset and 10,000 USDC 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 USDC, the system automatically repays the 10,000 USDC liability (interest is ignored here). User C now holds 30,000 USDC assets and no outstanding debts.

Parameters:

Parameter	Value
symbol	BTCUSDC
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": "BTCUSDC",

"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": "USDC"

}

]

}

Example 4

User D holds 1 BTC asset and 10,000 USDC 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 USDC, the system automatically borrows 4 ETH and at the same time repays 10,000 USDC (interest is ignored here). As a result, User D holds 1 BTC asset and 4 ETH liabilities.

Parameters:

Parameter	Value
symbol	ETHUSDC
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": "ETHUSDC",

"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": "USDC"

}

]

}

For more examples, please refer to Margin Account and Trading Interface on GibHub.

How to Use the “sideEffectType” Parameter with the Margin Order Endpoints?

Related Articles

Frequently Asked Questions on Margin Special API Key