Create new MarginTrading interface

[Nullably]

• Create new MarginTrading interface (class) based on Define scope for margin trading (design) #3311
• Create a new BinanceMargin connector (inherited from BinanceExchange) as proof of concept and as an example for new connectors to follow.

┆Issue is synchronized with this Clickup task by Unito

[mhrvth]

At a minimum level the connector should support these actions:

• Cross Margin Account Transfer POST /sapi/v1/margin/transfer
• Margin Account Borrow POST /sapi/v1/margin/loan
• Margin Account Repay POST /sapi/v1/margin/repay
• Query Margin Asset GET /sapi/v1/margin/asset
• Query Cross Margin Pair GET /sapi/v1/margin/pair
• Get All Margin Assets GET /sapi/v1/margin/allAssets
• Get All Cross Margin Pairs GET /sapi/v1/margin/allPairs
• Query Margin PriceIndex GET /sapi/v1/margin/priceIndex
• Margin Account New Order POST /sapi/v1/margin/order
• Margin Account Cancel Order DELETE /sapi/v1/margin/order
• Margin Account Cancel all Open Orders on a Symbol DELETE /sapi/v1/margin/openOrders
• Query Loan Record GET /sapi/v1/margin/loan
• Query Repay Record GET /sapi/v1/margin/repay
• Get Interest History GET /sapi/v1/margin/interestHistory
• Query Cross Margin Account Details GET /sapi/v1/margin/account
• Query Margin Account's Order GET /sapi/v1/margin/order
• Query Margin Account's Open Orders GET /sapi/v1/margin/openOrders
• Query Margin Account's All Orders GET /sapi/v1/margin/allOrders
• Query Max Borrow GET /sapi/v1/margin/maxBorrowable
• Query Max Transfer-Out Amount GET /sapi/v1/margin/maxTransferable

Other functionalities like isolated margin accounts are nice to have, but not necessary. For example the isolated margin functionality only makes sense if the client trades multiple assets at once, which for now it doesn't. And moreover each time a user would want to change the asset being traded, new account info would need to be provided for the individual margin account. So it's better to have simply a one universal cross margin account.

Margin level needs to be periodically queried with the REST request GET /sapi/v1/margin/account . It's not available through a web socket. It needs to be periodically checked to prevent a margin call or position liquidation. But the strategy doesn't need to be aware of it all the time, so it should be available just as a connector parameter, upon request.

Binance doesn't seem to provide any margin call specific query, it needs to be determined from the margin level. But to a strategy it should be provided as an event. Checking whether margin call occurred should be done within the connector as it depends on a fixed value of margin level.

The same goes for interest rates. If interest rates become too high, the strategy may decide to liquidate its positions as keeping them would be unprofitable. But a strategy may also decide to not to care about interest rates if they stay roughly the same, therefore being interrupted on every update is not desirable. Instead there should be defined triggers within the connector which will notify the strategy through an event if an interest rate of an asset crosses a certain level.

Borrowing and repaying funds should be in control of the strategy, not the connector.

[Nullably]

@mhrvth Well written and detailed, thanks.
I have a couple of points

For example the isolated margin functionality only makes sense if the client trades multiple assets at once, which for now it doesn't.

We do have a strategy that trades multiple assets at once, Liquidity Mining strategy. I believe this will become more and more common (having strategies that trade broadly). Also our users could be using Hummingbot while doing their own trading on the same account (not uncommon). I think having isolated margin is a good option, it helps users manage risk better. When crypto markets tank, often they all tank together, having isolated margin prevents liquidation of the entire account.

Instead there should be defined triggers within the connector which will notify the strategy through an event if an interest rate of an asset crosses a certain level.

An event trigger might be hard to implement as a certain level of interest rate is subjective and hard to define concretely. I think fetch loop update style is sufficient for this.

[MHHukiewitz]

@mhrvth That's quite a lot to digest and I try to compare to mango.markets UX. I also need some clarification on some other endpoints.

• Margin Account Borrow POST /sapi/v1/margin/loan
• Margin Account Repay POST /sapi/v1/margin/repay

Those two have optimal usages such that it shouldn't be up to the strategy (but to the gateway) to loan and repay collateral, as soon as needed. Mango's UI does not allow for such manual borrowing/repaying, as it automatically repays, if possible. Trades requiring borrowing, should do so automatically IMHO.

• Query Cross Margin Pair GET /sapi/v1/margin/pair

Does this query the L2 order book?

• Query Loan Record GET /sapi/v1/margin/loan
• Query Repay Record GET /sapi/v1/margin/repay

How might this be relevant to the trading algos?

• Get Interest History GET /sapi/v1/margin/interestHistory

Is this interest payment history or interest rate history?

That being said, the particularity of endpoints is satisfying, as it guarantees that only absolutely needed data is queried.

[mhrvth]

@MHHukiewitz to answer your questions:

Being able to control loans gives strategies power to further optimize their performance. If a strategy knows the interest rate, it can accurately calculate its projected P/L, and if it's able to loan or repay its collateral it gives it power to further maximize its overall profit, or minimize overall loss.

A strategy needs to be able to query the real state of the account at the exchange in general, because the client may have an incorrect information due to all kinds of errors (rounding, desynchronization, network ... ).

Having an interest history can give strategies an option to predict future interest rates and plan their loans accordingly.

Does this query the L2 order book?

It queries meta information about the pair:

{
   "id":323355778339572400,
   "symbol":"BTCUSDT",
   "base":"BTC",
   "quote":"USDT",
   "isMarginTrade":true,
   "isBuyAllowed":true,
   "isSellAllowed":true
}

Is this interest payment history or interest rate history?

It's both interest and interest rate:

{
    "rows":[
        {
            "isolatedSymbol": "BNBUSDT", // isolated symbol, will not be returned for crossed margin
            "asset": "BNB",
            "interest": "0.02414667",
            "interestAccuredTime": 1566813600000,
            "interestRate": "0.01600000",
            "principal": "36.22000000",
            "type": "ON_BORROW"
        }
    ],
    "total": 1
}

If an exchange is not able to provide some data, the method should return None or similar. Strategies would then need to check whether they can obtain the data.

[MHHukiewitz]

@cardosofede Is this indeed implemented now?

[cardosofede]

Nope

…

On Thu, 27 Apr 2023 at 08:38 Mike Hukiewitz ***@***.***> wrote: @cardosofede <https://github.com/cardosofede> Is this indeed implemented now? — Reply to this email directly, view it on GitHub <#3307 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AIZJOSDU2EABMMB6LLVU3PTXDJLCTANCNFSM44AB6VPA> . You are receiving this because you were mentioned.Message ID: ***@***.***>