Add ras api doc (#115)

Co-authored-by: yongli.wang <yongli.wang@cmexpro.com>

Author: alex0367

Public-Hedged-Perpetual-API.md

@@ -46,6 +46,8 @@
     * [Unsubscribe Kline](#klinesub)
     * [Subscribe Account-Order-Position (AOP)](#aopsub)
     * [Unsubscribe Account-Order-Position (AOP)](#aopunsub)
+    * [Subscribe account margin (RAS)](#rassub)
+    * [Unsubscribe account margin (RAS)](#rasunsub)
     * [Subscribe 24 Hours Ticker](#tickersub)
     * [Subscribe symbol price](#symbpricesub)
 
@@ -2225,15 +2227,6 @@ AOP subscription requires the session been authorized successfully. DataGW extra
 
 
 
-* Sample:
-
-```
-< {"accounts":[{"accountBalanceEv":100000024,"accountID":675340001,"bonusBalanceEv":0,"currency":"BTC","totalUsedBalanceEv":1222,"userID":67534}],"orders":[{"accountID":675340001,"action":"New","actionBy":"ByUser","actionTimeNs":1573711481897337000,"addedSeq":1110523,"bonusChangedAmountEv":0,"clOrdID":"uuid-1573711480091","closedPnlEv":0,"closedSize":0,"code":0,"cumQty":2,"cumValueEv":23018,"curAccBalanceEv":100000005,"curAssignedPosBalanceEv":0,"curBonusBalanceEv":0,"curLeverageEr":0,"curPosSide":"Buy","curPosSize":2,"curPosTerm":1,"curPosValueEv":23018,"curRiskLimitEv":10000000000,"currency":"BTC","cxlRejReason":0,"displayQty":2,"execFeeEv":-5,"execID":"92301512-7a79-5138-b582-ac185223727d","execPriceEp":86885000,"execQty":2,"execSeq":1131034,"execStatus":"MakerFill","execValueEv":23018,"feeRateEr":-25000,"lastLiquidityInd":"AddedLiquidity","leavesQty":0,"leavesValueEv":0,"message":"No error","ordStatus":"Filled","ordType":"Limit","orderID":"e9a45803-0af8-41b7-9c63-9b7c417715d9","orderQty":2,"pegOffsetValueEp":0,"priceEp":86885000,"relatedPosTerm":1,"relatedReqNum":2,"side":"Buy","stopLossEp":0,"stopPxEp":0,"symbol":"BTCUSD","takeProfitEp":0,"timeInForce":"GoodTillCancel","tradeType":"Trade","transactTimeNs":1573712555309040417,"userID":67534},{"accountID":675340001,"action":"New","actionBy":"ByUser","actionTimeNs":1573711490507067000,"addedSeq":1110980,"bonusChangedAmountEv":0,"clOrdID":"uuid-1573711488668","closedPnlEv":0,"closedSize":0,"code":0,"cumQty":3,"cumValueEv":34530,"curAccBalanceEv":100000013,"curAssignedPosBalanceEv":0,"curBonusBalanceEv":0,"curLeverageEr":0,"curPosSide":"Buy","curPosSize":5,"curPosTerm":1,"curPosValueEv":57548,"curRiskLimitEv":10000000000,"currency":"BTC","cxlRejReason":0,"displayQty":3,"execFeeEv":-8,"execID":"80899855-5b95-55aa-b84e-8d1052f19886","execPriceEp":86880000,"execQty":3,"execSeq":1131408,"execStatus":"MakerFill","execValueEv":34530,"feeRateEr":-25000,"lastLiquidityInd":"AddedLiquidity","leavesQty":0,"leavesValueEv":0,"message":"No error","ordStatus":"Filled","ordType":"Limit","orderID":"7e03cd6b-e45e-48d9-8937-8c6628e7a79d","orderQty":3,"pegOffsetValueEp":0,"priceEp":86880000,"relatedPosTerm":1,"relatedReqNum":3,"side":"Buy","stopLossEp":0,"stopPxEp":0,"symbol":"BTCUSD","takeProfitEp":0,"timeInForce":"GoodTillCancel","tradeType":"Trade","transactTimeNs":1573712559100655668,"userID":67534},{"accountID":675340001,"action":"New","actionBy":"ByUser","actionTimeNs":1573711499282604000,"addedSeq":1111025,"bonusChangedAmountEv":0,"clOrdID":"uuid-1573711497265","closedPnlEv":0,"closedSize":0,"code":0,"cumQty":4,"cumValueEv":46048,"curAccBalanceEv":100000024,"curAssignedPosBalanceEv":0,"curBonusBalanceEv":0,"curLeverageEr":0,"curPosSide":"Buy","curPosSize":9,"curPosTerm":1,"curPosValueEv":103596,"curRiskLimitEv":10000000000,"currency":"BTC","cxlRejReason":0,"displayQty":4,"execFeeEv":-11,"execID":"0be06645-90b8-5abe-8eb0-dca8e852f82f","execPriceEp":86865000,"execQty":4,"execSeq":1132422,"execStatus":"MakerFill","execValueEv":46048,"feeRateEr":-25000,"lastLiquidityInd":"AddedLiquidity","leavesQty":0,"leavesValueEv":0,"message":"No error","ordStatus":"Filled","ordType":"Limit","orderID":"66753807-9204-443d-acf9-946d15d5bedb","orderQty":4,"pegOffsetValueEp":0,"priceEp":86865000,"relatedPosTerm":1,"relatedReqNum":4,"side":"Buy","stopLossEp":0,"stopPxEp":0,"symbol":"BTCUSD","takeProfitEp":0,"timeInForce":"GoodTillCancel","tradeType":"Trade","transactTimeNs":1573712618104628671,"userID":67534}],"positions":[{"accountID":675340001,"assignedPosBalanceEv":0,"avgEntryPriceEp":86875941,"bankruptCommEv":75022,"bankruptPriceEp":90000,"buyLeavesQty":0,"buyLeavesValueEv":0,"buyValueToCostEr":1150750,"createdAtNs":0,"crossSharedBalanceEv":99998802,"cumClosedPnlEv":0,"cumFundingFeeEv":0,"cumTransactFeeEv":-24,"currency":"BTC","dataVer":4,"deleveragePercentileEr":0,"displayLeverageEr":1000000,"estimatedOrdLossEv":0,"execSeq":1132422,"freeCostEv":0,"freeQty":-9,"initMarginReqEr":1000000,"lastFundingTime":1573703858883133252,"lastTermEndTime":0,"leverageEr":0,"liquidationPriceEp":90000,"maintMarginReqEr":500000,"makerFeeRateEr":0,"markPriceEp":86786292,"orderCostEv":0,"posCostEv":1115,"positionMarginEv":99925002,"positionStatus":"Normal","riskLimitEv":10000000000,"sellLeavesQty":0,"sellLeavesValueEv":0,"sellValueToCostEr":1149250,"side":"Buy","size":9,"symbol":"BTCUSD","takerFeeRateEr":0,"term":1,"transactTimeNs":1573712618104628671,"unrealisedPnlEv":-107,"updatedAtNs":0,"usedBalanceEv":1222,"userID":67534,"valueEv":103596}],"sequence":1310812,"timestamp":1573716998131003833,"type":"snapshot"}
-< {"accounts":[{"accountBalanceEv":99999989,"accountID":675340001,"bonusBalanceEv":0,"currency":"BTC","totalUsedBalanceEv":1803,"userID":67534}],"orders":[{"accountID":675340001,"action":"New","actionBy":"ByUser","actionTimeNs":1573717286765750000,"addedSeq":1192303,"bonusChangedAmountEv":0,"clOrdID":"uuid-1573717284329","closedPnlEv":0,"closedSize":0,"code":0,"cumQty":0,"cumValueEv":0,"curAccBalanceEv":100000024,"curAssignedPosBalanceEv":0,"curBonusBalanceEv":0,"curLeverageEr":0,"curPosSide":"Buy","curPosSize":9,"curPosTerm":1,"curPosValueEv":103596,"curRiskLimitEv":10000000000,"currency":"BTC","cxlRejReason":0,"displayQty":4,"execFeeEv":0,"execID":"00000000-0000-0000-0000-000000000000","execPriceEp":0,"execQty":0,"execSeq":1192303,"execStatus":"New","execValueEv":0,"feeRateEr":0,"leavesQty":4,"leavesValueEv":46098,"message":"No error","ordStatus":"New","ordType":"Limit","orderID":"e329ae87-ce80-439d-b0cf-ad65272ed44c","orderQty":4,"pegOffsetValueEp":0,"priceEp":86770000,"relatedPosTerm":1,"relatedReqNum":5,"side":"Buy","stopLossEp":0,"stopPxEp":0,"symbol":"BTCUSD","takeProfitEp":0,"timeInForce":"GoodTillCancel","transactTimeNs":1573717286765896560,"userID":67534},{"accountID":675340001,"action":"New","actionBy":"ByUser","actionTimeNs":1573717286765750000,"addedSeq":1192303,"bonusChangedAmountEv":0,"clOrdID":"uuid-1573717284329","closedPnlEv":0,"closedSize":0,"code":0,"cumQty":4,"cumValueEv":46098,"curAccBalanceEv":99999989,"curAssignedPosBalanceEv":0,"curBonusBalanceEv":0,"curLeverageEr":0,"curPosSide":"Buy","curPosSize":13,"curPosTerm":1,"curPosValueEv":149694,"curRiskLimitEv":10000000000,"currency":"BTC","cxlRejReason":0,"displayQty":4,"execFeeEv":35,"execID":"8d1848a2-5faf-52dd-be71-9fecbc8926be","execPriceEp":86770000,"execQty":4,"execSeq":1192303,"execStatus":"TakerFill","execValueEv":46098,"feeRateEr":75000,"lastLiquidityInd":"RemovedLiquidity","leavesQty":0,"leavesValueEv":0,"message":"No error","ordStatus":"Filled","ordType":"Limit","orderID":"e329ae87-ce80-439d-b0cf-ad65272ed44c","orderQty":4,"pegOffsetValueEp":0,"priceEp":86770000,"relatedPosTerm":1,"relatedReqNum":5,"side":"Buy","stopLossEp":0,"stopPxEp":0,"symbol":"BTCUSD","takeProfitEp":0,"timeInForce":"GoodTillCancel","tradeType":"Trade","transactTimeNs":1573717286765896560,"userID":67534}],"positions":[{"accountID":675340001,"assignedPosBalanceEv":0,"avgEntryPriceEp":86843828,"bankruptCommEv":75056,"bankruptPriceEp":130000,"buyLeavesQty":0,"buyLeavesValueEv":0,"buyValueToCostEr":1150750,"createdAtNs":0,"crossSharedBalanceEv":99998186,"cumClosedPnlEv":0,"cumFundingFeeEv":0,"cumTransactFeeEv":11,"currency":"BTC","dataVer":5,"deleveragePercentileEr":0,"displayLeverageEr":1000000,"estimatedOrdLossEv":0,"execSeq":1192303,"freeCostEv":0,"freeQty":-13,"initMarginReqEr":1000000,"lastFundingTime":1573703858883133252,"lastTermEndTime":0,"leverageEr":0,"liquidationPriceEp":130000,"maintMarginReqEr":500000,"makerFeeRateEr":0,"markPriceEp":86732335,"orderCostEv":0,"posCostEv":1611,"positionMarginEv":99924933,"positionStatus":"Normal","riskLimitEv":10000000000,"sellLeavesQty":0,"sellLeavesValueEv":0,"sellValueToCostEr":1149250,"side":"Buy","size":13,"symbol":"BTCUSD","takerFeeRateEr":0,"term":1,"transactTimeNs":1573717286765896560,"unrealisedPnlEv":-192,"updatedAtNs":0,"usedBalanceEv":1803,"userID":67534,"valueEv":149694}],"sequence":1315725,"timestamp":1573717286767188294,"type":"incremental"}
-
-```
-
-
 <a name="aopunsub"/>
 
 ### Unsubscribe Account-Order-Position (AOP)
@@ -2259,6 +2252,123 @@ AOP subscription requires the session been authorized successfully. DataGW extra
 }
 ```
 
+<a name="rassub"/>
+
+### Subscribe account margin (RAS)
+
+RAS subscription requires the session been authorized successfully. DataGW extracts the user information from the given token and sends RAS messages back to client accordingly. Latest account snapshot messages will be sent to client immediately on subscription, and incremental messages will be sent for later updates. Each account snapshot contains one risk unit for cross margin positions, and each one risk unit for each isolated position. And also one risk wallet for each currency.
+
+* Request:
+
+```
+{
+    "id": <id>,
+    "method": "ras_p.subscribe",
+    "params": {}
+}
+```
+
+* Response:
+
+```
+{
+    "error": null,
+    "id": <id>,
+    "result": {
+        "stauts": "success"
+    }
+}
+```
+
+* Sample
+```
+> {
+    "id": 1234,
+    "method": "ras_p.subscribe",
+    "params": {}
+}
+
+< {
+    "error": null,
+    "id": 1234,
+    "result": {
+        "stauts": "success"
+    }
+}
+```
+
+#### account margin (RAS) Message Sample:
+
+```json
+{"risk_units":[{"estAvailableBalanceRv":"1806.82960617341","lastUpdateTimeNs":"2024-06-07T02:01:51.246394043Z","marginRatioRr":"999","posSide":0,"riskMode":"CrossAsset","symbol":"","totalBalanceRv":"1806.82960617341","totalEquityRv":"1806.82960617341","userID":944384,"userStatus":"Normal","userType":"Normal","valuationCurrency":"USDT","version":111},{"estAvailableBalanceRv":"-7.866995297237","fixedUsedRv":"8.180373498854","lastUpdateTimeNs":"2024-06-07T02:01:51.246394134Z","marginRatioRr":"14.28230196","posSide":3,"riskMode":"Isolated","symbol":"BTCUSDT","totalBalanceRv":"1075.34407386659","totalEquityRv":"1075.657452068207","totalPosCostRv":"1075.34407386659","totalPosMMRv":"74.741248391009","totalPosUnpnlRv":"0.313378201617","userID":944384,"userStatus":"Normal","userType":"Normal","valuationCurrency":"USDT","version":76}],"risk_wallets":[{"balanceRv":"2882.17368004","clReqVid":1,"currency":"USDT","lastUpdateTimeNs":"2024-06-07T02:01:51.246394235Z","userID":944384,"version":51}],"sequence":13144420,"timestamp":0,"type":"snapshot"}
+```
+
+| Field       | Type   | Description      | Possible values |
+|-------------|--------|------------------|-----------------|
+| timestamp   | Integer| Transaction timestamp in nanoseconds | |
+| sequence    | Integer| Latest message sequence |          |
+| type        | String | Message type     | snapshot, incremental |
+
+#### Fields in RiskUnit
+
+| Field    | Type     | Description    | Possible Values |
+|----------|----------|----------------|-----------------|
+| riskMode | String | "CrossAsset" for Cross Margin Positions, and "Isolated" for isolated position | 1, 3 |
+| estAvailableBalanceRv | String | estimated available balance for new orders | |
+| fixedUsedRv | String | margins allocated to fully hedged positions and bankrupt commission | |
+| lastUpdateTimeNs | Integer | the time in ns the message is generated | |
+| MarginRatioRr | String | the margin ratio level for the current risk unit | | 
+| posSide | Integer | the position side | 1, 2, 3 |
+| symbol      | String | Contract symbol name    |          |
+| totalBalanceRv | String | sum of balanceRv of all risk wallet | |
+| totalEquityRv | String | total equity excluding debt and interest | |
+| totalPosCostRv | String | total initial margin of position(s) | |
+| totalPosMMRv | String | total maintainence margin of position(s) | |
+| totalPosUnpnlRv | String | sum of unrealised pnl of position(s) | |
+| userID | Integer | user id | |
+| userStatus | String | user status | "Unspecified/Normal" for normal, "Banned" for banned, "Liq*" for liquidation |
+| userType | String| user type | always "Normal" for user |
+| valuationCurrency | String | settle currency | |
+| version | Integer | risk unit version | |
+
+#### Fields of RiskWallet 
+
+| Field    | Type    | Description   | Possible values |
+|----------|---------|---------------|-----------------|
+| balanceRv | String | available balance, including bonus and debt | | 
+| currency | String | wallet currency | |
+| lastUpdateTimeNs | Integer | the time in ns the message is generated | |
+| userID | Integer | user id | |
+| version | Integer | wallet version | |
+
+
+
+
+<a name="rasunsub">
+
+### Unsubscribe account margin (RAS)
+
+* Request:
+
+```
+{
+    "id": <id>,
+    "method": "ras_p.unsubscribe",
+    "params": []
+}
+```
+
+* Response:
+
+```
+{
+    "error": null,
+    "id": <id>,
+    "result": {
+        "status": "success"
+    }
+}
+```
 
 <a name="tickersub"/>