---
# System prepended metadata

title: MXCPERP OPEN-API接口模块

---

# MXCPERP OPEN-API接口模块

##基本信息:

url: https:contract.mxc.com 、  https:contract.mxc.io 、 https:contract.mxc.ai

## 通用响应数据结构:
```json
    {
      "success": true,
      "code": 0,
      "data":
       {
          "symbol":"BTC_USD",
          "fairPrice":8000,
          "timestamp":1111111111
         }
    }
```
or
```json
    {
      "success": false,
       "code":500,
      "message": "系统内部错误!"
    }
```
## 请求格式:

相应API接受GET，POST或DELETE类型的请求,post请求的Content-Type为:application/json.参数以json格式发送(参数命名规则为驼峰命名),get请求以requestParam形式发送(参数命名规则为'_'隔开)
鉴权方式:
    
    1.对于公共接口,不需要签名
    2.对于私有接口,需要在header中传入ApiKey、Request-Time、Signature、Revc-Window(可选)参数,Signature为签名字符串,签名规则如下:
        1)签名时需要先获得请求参数字符串,无参时为"";对于get请求,按字典序拼接业务参数以&间隔，
          并最终获得签名目标串（在批量操作的API中，若参数值中有逗号等特殊符号，这些符号在签名时需要做URL encode）,
          对于post请求,签名参数为json字符串;
        2)获得参数字符串后,再拼接签名目标串,规则为:accessKey+时间戳+获取到的参数字符串
        3)要求使用HMAC SHA256算法对目标串进行签名，并最终将签名作为参数携带到header中
        4)参与签名的业务参数为null时,不参与签名,对于path参数,也不参与签名;注意get请求将参数拼接至url上时,如果参数为null,
          后台解析时,会解析成"",固当get请求,某参数为null时,不要传该参数,或者签名时,将该参数的值设置为"",否则会出现验签失败!
        5)请求时将签名时用到的req_time的值放入header的Request-Time参数中,获得的签名字符串放入header的Signature参数中,将APIKEY的Access Key放在header的ApiKey参数中,其余业务参数按正常传递即可
时间安全:

    所有签名接口均需要传入header参数Request-Time，即以毫秒表示的时间戳字符串，服务端接收到请求后会验证请求发出的时间
    范围。若接受请求时，收到的req_time小于服务端时间10秒（默认值）以上（该时间窗口值可以通过发送可选header参数
    Revc-Window来自定义，其最大值为60，不推荐使用30秒以上的recv_window），或大于服务端时间2秒以上，则认为该请求无效

java示例:

            /**
             * 获取get请求参数字符串
             *
             * @param param get/delete请求参数map
             * @return
             */
           public static String getRequestParamString(Map<String, String> param) {
               if (MapUtils.isEmpty(param)) {
                   return "";
               }
               StringBuilder sb = new StringBuilder(1024);
               SortedMap<String, String> map = new TreeMap<>(param);
               for (Map.Entry<String, String> entry : map.entrySet()) {
                   String key = entry.getKey();
                   String value = StringUtils.isBlank(entry.getValue()) ? "" : entry.getValue();
                   sb.append(key).append('=').append(urlEncode(value)).append('&');
               }
               sb.deleteCharAt(sb.length() - 1);
               return sb.toString();
           }
          public static String urlEncode(String s) {
              try {
                  return URLEncoder.encode(s, "UTF-8").replaceAll("\\+", "%20");
              } catch (UnsupportedEncodingException e) {
                  throw new IllegalArgumentException("UTF-8 encoding not supported!");
              }
          } 
          
         /**签名*/
          public static String sign(SignVo signVo) {
                  if (signVo.getRequestParam() == null) {
                      signVo.setRequestParam("");
                  }
                  String str = signVo.getAccessKey() + signVo.getReqTime() + signVo.getRequestParam();
                  return actualSignature(str, signVo.getSecretKey());
              }
              
              
          public static String actualSignature(String inputStr, String key) {
                  Mac hmacSha256;
                  try {
                      hmacSha256 = Mac.getInstance("HmacSHA256");
                      SecretKeySpec secKey =
                              new SecretKeySpec(key.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
                      hmacSha256.init(secKey);
                  } catch (NoSuchAlgorithmException e) {
                      throw new RuntimeException("No such algorithm: " + e.getMessage());
                  } catch (InvalidKeyException e) {
                      throw new RuntimeException("Invalid key: " + e.getMessage());
                  }
                  byte[] hash = hmacSha256.doFinal(inputStr.getBytes(StandardCharsets.UTF_8));
                  return Hex.encodeHexString(hash);
              }
          @Getter
          @Setter
          public static class SignVo {
              private String reqTime;
              private String accessKey;
              private String secretKey;
              private String requestParam; //get请求参数根据字典顺序排序,使用&拼接字符串,post为json字符串
          }

## 创建API key

用户可以在MXC站点个人中心，创建API key，其包括两个部分，Access keyAPI的访问秘钥，Secret key对应的秘钥，用于签名计算及验证

***

##  合约行情接口(公共)
***
获取服务器时间:GET api/v1/contract/ping

获取合约信息:GET api/v1/contract/detail

获取合约支持划转的币种:GET api/v1/contract/support_currencies

获取合约深度信息:GET api/v1/contract/depth/{symbol}

获取合约深度信息:GET api/v1/contract/depth_commits/{symbol}/{limit}

获取合约指数价格:GET api/v1/contract/index_price/{symbol}

获取合约合理价格:GET api/v1/contract/fair_price/{symbol}

获取合约资金费率:GET api/v1/contract/funding_rate/{symbol}

获取合约K线数据: GET api/v1/contract/kline/{symbol}

获取指数价格K线数据: GET api/v1/contract/kline/index_price/{symbol}

获取合理价格K线数据: GET api/v1/contract/kline/fair_price/{symbol}

获取合约成交数据: GET api/v1/contract/deals/{symbol}

获取合约ticker数据: GET api/v1/contract/ticker

获取合约风险基金余额: GET api/v1/contract/risk_reverse/{symbol}

获取合约风险基金余额历史: GET api/v1/contract/risk_reverse/history

获取合约资金费率历史: GET api/v1/contract/funding_rate/history

***
+ ### 获取服务器时间
+ ##### 限速规则: 20次/2秒 
+ ##### method: 
     + **GET api/v1/contract/ping**
- ##### 请求参数: 无

   - ##### 响应参数 :
示例:
```json
    {
      "success": true,
      "data":111111111 
    }
```
***

+ ### 获取合约信息
+ ##### 限速规则: 1次/5秒 
+ ##### method: 
     + **GET api/v1/contract/detail**
- ##### 请求参数:
    
| 参数名  | 类型  | 是否必填  |  说明 |
| ------------ | ------------ | ------------ | ------------ |
|  symbol | string  | false  | 合约名  |


   - ##### 响应参数 :
	
| 参数名  | 类型  | 说明  |
| ------------ | ------------ | ------------ |
| symbol  | string | 合约名 |
| displayName  | string | 展示名 |
| displayNameEn  | string | 英文展示名 |
| positionOpenType  | int  |  开仓类型,1：逐仓，2：全仓，3：全仓，逐仓都支持 |
| baseCoin  | string  | 标的货币 如 BTC |
| quoteCoin  | string  | 标价货币 如 USDT |
| settleCoin  | string  | 结算货币 如 USDT|
| contractSize  | decimal  | 合约面值 |
| minLeverage  | int  | 杠杆倍数下限 |
| maxLeverage  | int  | 杠杆倍数上限 |
| priceScale  | int  | 价格精度 |
| volScale  | int  | 数量精度 |
| amountScale  | int  | 金额精度 |
| priceUnit  | int  | 价格的最小步进单位 |
| volUnit  | int  | 数量的最小步进单位 |
| minVol  | decimal  | 订单张数下限|
| maxVol  | decimal  | 订单张数上限 |
| bidLimitPriceRate  | decimal  | 卖单价格限制比率 |
| askLimitPriceRate  | decimal  | 买单价格限制比率 |
| takerFeeRate  | decimal  | 买单费率 |
| makerFeeRate  | decimal  | 卖单费率 |
| maintenanceMarginRate  | decimal  | 维持保证金率 |
| initialMarginRate  | decimal  | 初始保证金率 |
| riskBaseVol  | decimal  | 基本张数 |
| riskIncrVol  | decimal  | 递增张数 |
| riskIncrMmr  | decimal  | 维持保证金率递增量 |
| riskIncrImr  | decimal  | 初始保证金率递增量 |
| riskLevelLimit  | int  | 风险限额档位数 |
| priceCoefficientVariation  | decimal  | 合理价格偏离指数价格系数 |
| indexOrigin  | List<String>  | 指数来源 |
| state  | int  | 状态,0:启用,1:交割,2:交割完成,3:下线,4: 暂停|

***
+ ### 获取可划转币种
+ ##### 限速规则: 20次/2秒 
+ ##### method: 
     + **GET api/v1/contract/support_currencies**
- ##### 请求参数: 无

   - ##### 响应参数 :
示例:
```json
    {
      "success": true,
      "data":["USDT","BTC","ETH"] 
    }
```
***
+ ### 获取合约深度信息
+ ##### 限速规则: 20次/2秒 
+ ##### method: 
     + **GET api/v1/contract/depth/{symbol}**
- ##### 请求参数:
	
| 参数名  | 类型  | 是否必填  |  说明 |
| ------------ | ------------ | ------------ | ------------ |
| symbol | string  | true  | 合约名  |

   - ##### 响应参数:
	
| 参数名  | 类型  | 说明  |
| ------------ | ------------ | ------------ |
| asks  | List<Numeric[]> |卖方深度 |
| bids  | List<Numeric[]> | 买方深度 |
| version  | long  | 版本号 |

备注: [411.8, 10, 1] 411.8为价格，10为此价格的合约张数,1为订单数量
返回示例:
```json
{
    "asks":[
        [
            3968.5,
            121
        ],
        [
            3968.6,
            160,
            4
        ]
    ],
    "bids":[
        [
            3968.4,
            179,
            4
        ],
        [
            3968,
            914,
            3
        ]
    ],
    "version":1
}
```
***
+ ### 获取合约最近N条深度信息快照
+ ##### 限速规则: 20次/2秒 
+ ##### method: 
     + **GET api/v1/contract/depth_commits/{symbol}/{limit}**
- ##### 请求参数:
	
| 参数名  | 类型  | 是否必填  |  说明 |
| ------------ | ------------ | ------------ | ------------ |
| symbol | string  | true  | 合约名  |
| limit | int  | true  | 条数  |

   - ##### 响应参数:
	
| 参数名  | 类型  | 说明  |
| ------------ | ------------ | ------------ |
| asks  | List<Numeric[]> |卖方深度 |
| bids  | List<Numeric[]> | 买方深度 |
| version  | long  | 版本号 |

***
+ ### 获取合约指数价格
+ ##### 限速规则: 20次/2秒 
+ ##### method: 
     + **GET api/v1/contract/index_price/{symbol}**
- ##### 请求参数:
	
| 参数名  | 类型  | 是否必填  |  说明 |
| ------------ | ------------ | ------------ | ------------ |
| symbol | string  | true  | 合约名  |

   - ##### 响应参数:
	
| 参数名  | 类型  | 说明  |
| ------------ | ------------ | ------------ |
| symbol  | string | 交易对 |
| indexPrice  | decimal  | 指数价格 |
| timestamp  | long   | 系统时间戳 |

***

+ ### 获取合约合理价格
+ ##### 限速规则: 20次/2秒 
+ ##### method: 
     + **GET api/v1/contract/fair_price/{symbol}**
- ##### 请求参数:
	
| 参数名  | 类型  | 是否必填  |  说明 |
| ------------ | ------------ | ------------ | ------------ |
| symbol  | string  | true  | 合约名  |

   - ##### 响应参数:
	
| 参数名  | 类型  | 说明  |
| ------------ | ------------ | ------------ |
| symbol | string| 合约名 |
| fairPrice  | decimal  | 合理价格 |
| timestamp  | long   | 系统时间戳 |

***
+ ### 获取合约资金费率
+ ##### 限速规则: 20次/2秒 
+ ##### method: 
     + **GET api/v1/contract/funding_rate/{symbol}**
- ##### 请求参数:
	
| 参数名  | 类型  | 是否必填  |  说明 |
| ------------ | ------------ | ------------ | ------------ |
| symbol  | string  | true  | 合约名  |

   - ##### 响应参数:
	
| 参数名  | 类型  | 说明  |
| ------------ | ------------ | ------------ |
| symbol  | string | 合约名 |
| fundingRate  | decimal  | 资金费率 |
| maxFundingRate  | decimal  | 资金费率上限 |
| minFundingRate  | decimal  | 资金费率下限 |
| collectCycle  | int  | 收取周期 |
| nextSettleTime  | long  | 下次收取时间 |
| timestamp  | long   | 系统时间戳 |

***

+ ### 获取k线数据
+ ##### 限速规则: 20次/2秒 
+ ##### method: 
     + **GET api/v1/contract/kline/{symbol}**
- ##### 请求参数:
	
| 参数名  | 类型  | 是否必填  |  说明 |
| ------------ | ------------ | ------------ | ------------ |
| symbol  | string  | true  | 合约名  |
| interval   | string  | true  | 间隔: Min1、Min5、Min15、Min30、Min60、Hour4、Hour8、Day1、Week1、Month1  |
| start  | long  | true  | 开始时间戳  |
| end  | long  | true  | 结束时间戳  |

   - ##### 响应参数:
	
| 参数名  | 类型  | 说明  |
| ------------ | ------------ | ------------ |
| open  | double[]  | 开盘价 |
| close  | double[]   | 收盘价 |
| high  | double[]   | 最高价 |
| low  | double[]   | 最低价 |
| vol  | double[]   | 成交量 |
| time  | long[]   | 时间窗口 |

***

+ ### 获取指数价格k线数据
+ ##### 限速规则: 20次/2秒 
+ ##### method: 
     + **GET api/v1/contract/kline/index_price/{symbol}**
- ##### 请求参数:
	
| 参数名  | 类型  | 是否必填  |  说明 |
| ------------ | ------------ | ------------ | ------------ |
| symbol  | string  | true  | 合约名  |
| interval   | string  | true  | 间隔: Min1、Min5、Min15、Min30、Min60、Hour4、Hour8、Day1、Week1、Month1  |
| start  | long  | true  | 开始时间戳  |
| end  | long  | true  | 结束时间戳  |

   - ##### 响应参数:
	
| 参数名  | 类型  | 说明  |
| ------------ | ------------ | ------------ |
| open  | double[]  | 开盘价 |
| close  | double[]   | 收盘价 |
| high  | double[]   | 最高价 |
| low  | double[]   | 最低价 |
| vol  | double[]   | 成交量 |
| time  | long[]   | 时间窗口 |

***

+ ### 获取合理价格k线数据
+ ##### 限速规则: 20次/2秒 
+ ##### method: 
     + **GET api/v1/contract/kline/fair_price/{symbol}**
- ##### 请求参数:
	
| 参数名  | 类型  | 是否必填  |  说明 |
| ------------ | ------------ | ------------ | ------------ |
| symbol  | string  | true  | 合约名  |
| interval   | string  | true  | 间隔: Min1、Min5、Min15、Min30、Min60、Hour4、Hour8、Day1、Week1、Month1  |
| start  | long  | true  | 开始时间戳  |
| end  | long  | true  | 结束时间戳  |

   - ##### 响应参数:
	
| 参数名  | 类型  | 说明  |
| ------------ | ------------ | ------------ |
| open  | double[]  | 开盘价 |
| close  | double[]   | 收盘价 |
| high  | double[]   | 最高价 |
| low  | double[]   | 最低价 |
| vol  | double[]   | 成交量 |
| time  | long[]   | 时间窗口 |

***

+ ### 获取成交数据
+ ##### 限速规则: 20次/2秒 
+ ##### method: 
     + **GET api/v1/contract/deals/{symbol}**
- ##### 请求参数:
	
| 参数名  | 类型  | 是否必填  |  说明 |
| ------------ | ------------ | ------------ | ------------ |
| symbol  | string  | true  | 合约名  |
| limit  | int  | false  | 结果集数量，最大为100，不填默认返回100条  |

   - ##### 响应参数:
	
| 参数名  | 类型  | 说明  |
| ------------ | ------------ | ------------ |
| p  | decimal  | 成交价 |
| v  | decimal  | 数量 |
| T  | int  | 成交方向,1:买,2:卖 |
| O  | int   | 是否是开仓，1:是,2:否,当O为1的时候, vol是新增的持仓量 |
| M  | int   | 是否为自成交,1:是,2:否 |
| t  | long   | 成交时间|

***


+ ### 获取合约ticker数据
+ ##### 限速规则: 20次/2秒 
+ ##### method: 
     + **GET api/v1/contract/ticker**
- ##### 请求参数:
	
| 参数名  | 类型  | 是否必填  |  说明 |
| ------------ | ------------ | ------------ | ------------ |
| symbol  | string  | false  | 合约名 |


   - ##### 响应参数:
	
| 参数名  | 类型  | 说明  |
| ------------ | ------------ | ------------ |
| symbol  | string | 合约名 |
| lastPrice  | decimal  | 最新价 |
| bid1  | decimal  | 买一价 |
| ask1  | decimal  | 卖一价 |
| volume24  | decimal  | 24小时成交量，按张数统计 |
| holdVol| decimal  | 总持仓量 |
| lower24Price  | decimal  | 24小时最低价 |
| high24Price  | decimal  | 24小时内最高价 |
| riseFallRate  | decimal  | 涨跌幅 |
| riseFallValue  | decimal  | 涨跌额 |
| indexPrice  | decimal  | 指数价格 |
| fairPrice  | decimal  | 合理价 |
| fundingRate  | decimal  | 资金费率 |
| timestamp  | long   | 成交时间 |

***
+ ### 获取合约风险基金余额
+ ##### 限速规则: 20次/2秒 
+ ##### method: 
     + **GET  api/v1/contract/risk_reverse/{symbol}**
- ##### 请求参数:
	
| 参数名  | 类型  | 是否必填  |  说明 |
| ------------ | ------------ | ------------ | ------------ |
| symbol  | string  | true  | 合约名 |


   - ##### 响应参数:
	
| 参数名  | 类型  | 说明  |
| ------------ | ------------ | ------------ |
| symbol  | string | 合约名 |
| currency  | string  | 结算货币 |
| available  | decimal  | 余额 |
***

+ ### 获取合约风险基金余额历史
+ ##### 限速规则: 20次/2秒 
+ ##### method: 
     + **GET  api/v1/contract/risk_reverse/history**
- ##### 请求参数:
	
| 参数名  | 类型  | 是否必填  |  说明 |
| ------------ | ------------ | ------------ | ------------ |
| symbol  | string  | true  | 合约名 |
| page_num  | int  | true  | 当前页数,默认为1  |
| page_size  | int  | true  | 每页大小,默认20,最大100  |


   - ##### 响应参数:
	
| 参数名  | 类型  | 说明  |
| ------------ | ------------ | ------------ |
| pageSize  | int  | 页面大小 |
| totalCount  | int  | 总条数 |
| totalPage  | int  | 总页数 |
| currentPage  | int  | 当前页 |
| resultList  | list  | 数据结果集 |
| symbol  | string | 合约名 |
| currency  | string  | 结算货币 |
| available  | decimal  | 余额 |
| snapshotTime  | long  | 快照时间 |
***

+ ### 获取合约资金费率历史
+ ##### 限速规则: 20次/2秒 
+ ##### method: 
     + **GET  api/v1/contract/funding_rate/history**
- ##### 请求参数:
	
| 参数名  | 类型  | 是否必填  |  说明 |
| ------------ | ------------ | ------------ | ------------ |
| symbol  | string  | true  | 合约名 |
| page_num  | int  | true  | 当前页数,默认为1  |
| page_size  | int  | true  | 每页大小,默认20,最大100  |


   - ##### 响应参数:
	
| 参数名  | 类型  | 说明  |
| ------------ | ------------ | ------------ |
| pageSize  | int  | 页面大小 |
| totalCount  | int  | 总条数 |
| totalPage  | int  | 总页数 |
| currentPage  | int  | 当前页 |
| resultList  | list  | 数据结果集 |
| symbol  | string | 合约名 |
| fundingRate  | decimal  | 资金费率 |
| settleTime  | long  | 结算时间 |
***


## 私有接口
***
获取用户所有资产信息:GET api/v1/private/account/assets

获取用户资产信息:GET api/v1/private/account/asset/{currency}

获取用户资产划转记录:GET api/v1/private/account/transfer_record

获取用户历史持仓:GET api/v1/private/position/history_positions

获取用户当前持仓:GET api/v1/private/position/open_positions

获取资金费用明细:GET api/v1/private/position/funding_records

获取用户当前活跃订单:GET api/v1/private/order/open_orders/{symbol}

获取用户所有历史订单:GET api/v1/private/order/history_orders

通过外部订单号获取单个订单:GET api/v1/private/order/external/{symbol}/{external_oid}

通过订单号获取单个订单:GET api/v1/private/order/get/{order_id}

获取订单成交明细:GET api/v1/private/order/deal_details/{order_id}


获取风险限额: GET api/v1/private/account/risk_limit


修改持仓保证金:POST api/v1/private/position/change_margin

修改持仓杠杆倍数:POST api/v1/private/position/change_leverage

下单:POST api/v1/private/order/submit

批量下单:POST api/v1/private/order/submit_batch

取消订单:POST api/v1/private/order/cancel

取消所有订单:POST api/v1/private/order/cancel_all

修改风险等级: POST api/v1/private/account/change_risk_level


***

+ ### 获取用户所有资产信息
+ ##### 限速规则: 20次/2秒 
+ ##### method: 
     + **GET api/v1/private/account/assets**
- ##### 请求参数: 无

   - ##### 响应参数:
	
| 参数名  | 类型  | 说明  |
| ------------ | ------------ | ------------ |
| currency  | string  | 币种 |
| positionMargin  | decimal   | 仓位保证金 |
| frozenBalance  | decimal   | 冻结余额 |
| availableBalance  | decimal   | 当前可用余额 |
| cashBalance  | decimal   | 可提现余额 |

***

+ ### 获取用户单个币种资产信息
+ ##### 限速规则: 20次/2秒 
+ ##### method: 
     + **GET api/v1/private/account/asset/{currency}**
- ##### 请求参数:
	
| 参数名  | 类型  | 是否必填  |  说明 |
| ------------ | ------------ | ------------ | ------------ |
| currency  | string  | true  | 币种  |

   - ##### 响应参数:
	
| 参数名  | 类型  | 说明  |
| ------------ | ------------ | ------------ |
| currency  | string  | 币种 |
| positionMargin  | decimal   | 仓位保证金 |
| frozenBalance  | decimal   | 冻结余额 |
| availableBalance  | decimal   | 当前可用余额 |
| cashBalance  | decimal   | 可提现余额 |

***

+ ### 获取用户资产划转记录
+ ##### 限速规则: 20次/2秒 
+ ##### method: 
     + **GET api/v1/private/account/transfer_record**
- ##### 请求参数:
	
| 参数名  | 类型  | 是否必填  |  说明 |
| ------------ | ------------ | ------------ | ------------ |
| currency  | string  | false  | 币种  |
| state  | string  | false  | 状态:WAIT 、SUCCESS 、FAILED  |
| type  | string  | false  | 类型:IN 、OUT  |
| page_num  | int  | true  | 当前页数,默认为1  |
| page_size  | int  | true  | 每页大小,默认20,最大100  |

   - ##### 响应参数:
	
| 参数名  | 类型  | 说明  |
| ------------ | ------------ | ------------ |
| pageSize  | int  | 页面大小 |
| totalCount  | int  | 总条数 |
| totalPage  | int  | 总页数 |
| currentPage  | int  | 当前页 |
| resultList  | list  | 数据结果集 |
| id  | long  | id |
| txid  | string  | 流水号 |
| currency  | string  | 币种 |
| amount  | decimal  | 转账金额 |
| type  | string   | 类型:IN 、OUT |
| state  | string   | 状态:WAIT 、SUCCESS 、FAILED  |
| createTime  | long   | 创建时间 |
| updateTime  | long   | 修改时间 |

***

+ ### 获取用户当前持仓
+ ##### 限速规则: 20次/2秒 
+ ##### method: 
     + **GET api/v1/private/position/open_positions**
- ##### 请求参数:
	
| 参数名  | 类型  | 是否必填  |  说明 |
| ------------ | ------------ | ------------ | ------------ |
| symbol  | string  | false  | 合约名|
   - ##### 响应参数:
	
| 参数名  | 类型  | 说明  |
| ------------ | ------------ | ------------ |
| positionId  | long  | 持仓id |
| symbol  | string  | 合约名 |
| holdVol  | decimal  | 持仓数量 |
| positionType  | int  | 仓位类型， 1多 2空 |
| openType  | int   | 开仓类型， 1逐仓 2全仓 |
| state  | int   | 仓位状态,1持仓中2系统代持3已平仓  |
| frozenVol  | decimal   | 冻结量 |
| closeVol  | decimal   | 平仓量 |
| holdAvgPrice  | decimal   | 持仓均价 |
| closeAvgPrice  | decimal   | 平仓均价 |
| openAvgPrice  | decimal   | 开仓均价 |
| liquidatePrice  | decimal   | 逐仓时的爆仓价 |
| oim  | decimal   | 原始初始保证金 |
| adlLevel  | int   | adl减仓等级,取值为 1-5，为空时需等待刷新 |
| im  | decimal   | 初始保证金， 逐仓时可以加减此项以调节爆仓价 |
| holdFee  | decimal   | 资金费, 正数表示得到，负数表示支出 |
| realised  | decimal   | 已实现盈亏 |
| createTime  | date   | 创建时间 |
| updateTime  | date   | 修改时间 |
***

+ ### 获取用户历史持仓信息
+ ##### 限速规则: 20次/2秒 
+ ##### method: 
     + **GET api/v1/private/position/history_positions**
- ##### 请求参数:
	
| 参数名  | 类型  | 是否必填  |  说明 |
| ------------ | ------------ | ------------ | ------------ |
| symbol  | string  | false  | 合约名|
| type  | int  | false  | 仓位类型， 1多 2空|
| page_num  | int  | true  | 当前页数,默认为1  |
| page_size  | int  | true  | 每页大小,默认20,最大100  |

   - ##### 响应参数:
	
| 参数名  | 类型  | 说明  |
| ------------ | ------------ | ------------ |
| pageSize  | int  | 页面大小 |
| totalCount  | int  | 总条数 |
| totalPage  | int  | 总页数 |
| currentPage  | int  | 当前页 |
| resultList  | list  | 数据结果集 |
| positionId  | long  | 持仓id |
| symbol  | string  | 合约名 |
| holdVol  | decimal  | 持仓数量 |
| positionType  | int  | 仓位类型， 1多 2空 |
| openType  | int   | 开仓类型， 1逐仓 2全仓 |
| state  | int   | 仓位状态,1持仓中2系统代持3已平仓  |
| frozenVol  | decimal   | 冻结量 |
| closeVol  | decimal   | 平仓量 |
| holdAvgPrice  | decimal   | 持仓均价 |
| closeAvgPrice  | decimal   | 平仓均价 |
| openAvgPrice  | decimal   | 开仓均价 |
| liquidatePrice  | decimal   | 逐仓时的爆仓价 |
| oim  | decimal   | 原始初始保证金 |
| im  | decimal   | 初始保证金， 逐仓时可以加减此项以调节爆仓价 |
| holdFee  | decimal   | 资金费, 正数表示得到，负数表示支出 |
| realised  | decimal   | 已实现盈亏 |
| createTime  | date   | 创建时间 |
| updateTime  | date   | 修改时间 |

***
+ ### 获取用户资金费用明细
+ ##### 限速规则: 20次/2秒 
+ ##### method: 
     + **GET api/v1/private/position/funding_records**
- ##### 请求参数:
	
| 参数名  | 类型  | 是否必填  |  说明 |
| ------------ | ------------ | ------------ | ------------ |
| symbol | string  | false  | 合约名|
| position_id  | int  | false  | 仓位id|
| page_num  | int  | true  | 当前页数,默认为1  |
| page_size  | int  | true  | 每页大小,默认20,最大100  |

   - ##### 响应参数:
	
| 参数名  | 类型  | 说明  |
| ------------ | ------------ | ------------ |
| pageSize  | int  | 页面大小 |
| totalCount  | int  | 总条数 |
| totalPage  | int  | 总页数 |
| currentPage  | int  | 当前页 |
| resultList  | list  | 数据结果集 |
| id  | long  | id |
| positionId  | long  | 持仓id |
| positionType  | string  | LONG:多仓,SHORT:空仓 |
| positionValue  | decimal  | 仓位价值 |
| funding  | decimal   | 费用 |
| rate  | decimal   | 资金费率  |
| settleTime  | date   | 清算时间 |

***

+ ### 根据外部id查询订单
+ ##### 限速规则: 20次/2秒 
+ ##### method: 
     + **GET api/v1/private/order/externa/{symbol}//{external_oid}**
- ##### 请求参数:
	
| 参数名  | 类型  | 是否必填  |  说明 |
| ------------ | ------------ | ------------ | ------------ |
| symbol  | string  | true  | 合约名|
| external_oid  | string  | true  | 外部订单号|

   - ##### 响应参数:
	
| 参数名  | 类型  | 说明  |
| ------------ | ------------ | ------------ |
| orderId  | long  | 页面大小 |
| symbol  | string  | 合约名 |
| positionId  | long  | 持仓id |
| price  | decimal  | 委托价格 |
| vol  | decimal  | 委托数量 |
| leverage  | long  | 杠杆倍数 |
| side  | int  | 订单方向 1开多,2平空,3开空,4平多 |
| category  | int  | 订单类别:1限价委托,2强平代管委托,3代管平仓委托,4ADL减仓 |
| dealAvgPrice  | decimal  | 成交均价 |
| dealVol  | decimal   | 成交数量 |
| orderMargin  | decimal   | 委托保证金  |
| takerFee  | decimal   | 买单手续费 |
| makerFee  | decimal   | 卖单手续费 |
| profit  | decimal   | 平仓盈亏 |
| feeCurrency  | string   | 收费币种 |
| openType  | int   | 开仓类型,1逐仓,2全仓 |
| state  | int   | 订单状态,1:待报,2未完成,3已完成,4已撤销,5无效 |
| externalOid  | string   | 外部订单号 |
| createTime  | date   | 创建时间 |
| updateTime  | date   | 修改时间 |

***


+ ### 根据订单id查询订单
+ ##### 限速规则: 20次/2秒 
+ ##### method: 
     + **GET api/v1/private/order/get/{order_id}**
- ##### 请求参数:
	
| 参数名  | 类型  | 是否必填  |  说明 |
| ------------ | ------------ | ------------ | ------------ |
| order_id  | string  | true  | 订单号|

   - ##### 响应参数:
	
| 参数名  | 类型  | 说明  |
| ------------ | ------------ | ------------ |
| orderId  | long  | 页面大小 |
| symbol  | string  | 合约名 |
| positionId  | long  | 持仓id |
| price  | decimal  | 委托价格 |
| vol  | decimal  | 委托数量 |
| leverage  | long  | 杠杆倍数 |
| side  | int  | 订单方向 1开多,2平空,3开空,4平多 |
| category  | int  | 订单类别:1限价委托,2强平代管委托,3代管平仓委托,4ADL减仓 |
| dealAvgPrice  | decimal  | 成交均价 |
| dealVol  | decimal   | 成交数量 |
| orderMargin  | decimal   | 委托保证金  |
| takerFee  | decimal   | 买单手续费 |
| makerFee  | decimal   | 卖单手续费 |
| profit  | decimal   | 平仓盈亏 |
| feeCurrency  | string   | 收费币种 |
| openType  | int   | 开仓类型,1逐仓,2全仓 |
| state  | int   | 订单状态,1:待报,2未完成,3已完成,4已撤销,5无效 |
| externalOid  | string   | 外部订单号 |
| createTime  | date   | 创建时间 |
| updateTime  | date   | 修改时间 |

***

+ ### 获取用户当前未结束订单
+ ##### 限速规则: 20次/2秒 
+ ##### method: 
     + **GET api/v1/private/order/open_orders/{symbol}**
- ##### 请求参数:
	
| 参数名  | 类型  | 是否必填  |  说明 |
| ------------ | ------------ | ------------ | ------------ |
| symbol  | string  | false  | 合约名,不传返回所有|
| page_num  | int  | true  | 当前页数,默认为1  |
| page_size  | int  | true  | 每页大小,默认20,最大100  |

   - ##### 响应参数:
	
| 参数名  | 类型  | 说明  |
| ------------ | ------------ | ------------ |
| pageSize  | int  | 页面大小 |
| totalCount  | int  | 总条数 |
| totalPage  | int  | 总页数 |
| currentPage  | int  | 当前页 |
| resultList  | list  | 数据结果集 |
| orderId  | long  | 页面大小 |
| symbol  | string  | 合约名 |
| positionId  | long  | 持仓id |
| price  | decimal  | 委托价格 |
| vol  | decimal  | 委托数量 |
| leverage  | long  | 杠杆倍数 |
| side  | int  | 订单方向 1开多,2平空,3开空,4平多 |
| category  | int  | 订单类别:1限价委托,2强平代管委托,4ADL减仓 |
| orderType  | int  | 1:限价单,2:Post Only只做Maker,3:立即成交或立即取消,4:全部成交或者全部取消| |
| dealAvgPrice  | decimal  | 成交均价 |
| dealVol  | decimal   | 成交数量 |
| orderMargin  | decimal   | 委托保证金  |
| usedMargin  | decimal   | 已经使用的保证金  |
| takerFee  | decimal   | 买单手续费 |
| makerFee  | decimal   | 卖单手续费 |
| profit  | decimal   | 平仓盈亏 |
| feeCurrency  | string   | 收费币种 |
| openType  | int   | 开仓类型,1逐仓,2全仓 |
| state  | int   | 订单状态,1:待报,2未完成,3已完成,4已撤销,5无效 |
| errorCode  | int   | 错误code,0:正常，1：参数错误，2：账户余额不足，3：仓位不存在，4：仓位可用持仓不足，5：多仓时， 委托价小于了强平价，空仓时， 委托价大于了强平价，6：开多时， 强平价大于了合理价，开空时， 强平价小于了合理价 ,7:超过风险限额限制|
| externalOid  | string   | 外部订单号 |
| createTime  | date   | 创建时间 |
| updateTime  | date   | 修改时间 |

***

+ ### 获取用户所有历史订单
+ ##### 限速规则: 20次/2秒 
+ ##### method: 
     + **GET api/v1/private/order/history_orders**
- ##### 请求参数:
	
| 参数名  | 类型  | 是否必填  |  说明 |
| ------------ | ------------ | ------------ | ------------ |
| symbol  | string  | false  | 合约名|
| states  | string  | false  | 订单状态,1:待报,2未完成,3已完成,4已撤销,5无效;多个用 ',' 隔开|
| category  | int  | false  | 订单类别,1:限价委托,2:强平代管委托,4:ADL减仓|
| page_num  | int  | true  | 当前页数,默认为1  |
| page_size  | int  | true  | 每页大小,默认20,最大100  |

   - ##### 响应参数:
	
| 参数名  | 类型  | 说明  |
| ------------ | ------------ | ------------ |
| pageSize  | int  | 页面大小 |
| totalCount  | int  | 总条数 |
| totalPage  | int  | 总页数 |
| currentPage  | int  | 当前页 |
| resultList  | list  | 数据结果集 |
| orderId  | long  | 页面大小 |
| symbol  | string  | 合约名 |
| positionId  | long  | 持仓id |
| price  | decimal  | 委托价格 |
| vol  | decimal  | 委托数量 |
| leverage  | long  | 杠杆倍数 |
| side  | int  | 订单方向 1开多,2平空,3开空,4平多 |
| category  | int  | 订单类别:1限价委托,2强平代管委托,4ADL减仓 |
| orderType  | int  | 1:限价单,2:Post Only只做Maker,3:立即成交或立即取消,4:全部成交或者全部取消| |
| dealAvgPrice  | decimal  | 成交均价 |
| dealVol  | decimal   | 成交数量 |
| orderMargin  | decimal   | 委托保证金  |
| usedMargin  | decimal   | 已经使用的保证金  |
| takerFee  | decimal   | 买单手续费 |
| makerFee  | decimal   | 卖单手续费 |
| profit  | decimal   | 平仓盈亏 |
| feeCurrency  | string   | 收费币种 |
| openType  | int   | 开仓类型,1逐仓,2全仓 |
| state  | int   | 订单状态,1:待报,2未完成,3已完成,4已撤销,5无效 |
| errorCode  | int   | 错误code,0:正常，1：参数错误，2：账户余额不足，3：仓位不存在，4：仓位可用持仓不足，5：多仓时， 委托价小于了强平价，空仓时， 委托价大于了强平价，6：开多时， 强平价大于了合理价，开空时， 强平价小于了合理价 |
| externalOid  | string   | 外部订单号 |
| createTime  | date   | 创建时间 |
| updateTime  | date   | 修改时间 |

***

+ ### 获取订单成交明细
+ ##### 限速规则: 20次/2秒 
+ ##### method: 
     + **GET api/v1/private/order/deal_details/{order_id}**
- ##### 请求参数:
	
| 参数名  | 类型  | 是否必填  |  说明 |
| ------------ | ------------ | ------------ | ------------ |
| order_id  | long  | true  | 订单id|

   - ##### 响应参数:
	
| 参数名  | 类型  | 说明  |
| ------------ | ------------ | ------------ |
| symbol  | string  | 合约名 |
| side  | int  | 订单方向 1开多,2平空,3开空,4平多 |
| vol  | decimal  | 成交数量|
| price  | decimal   | 成交价格 |
| fee  | decimal   | 手续费 |
| feeCurrency  | string   | 收费币种 |
| timestamp  | long   | 修改时间 |
***

+ ### 获取风险限额
+ ##### 限速规则: 20次/2秒 
+ ##### method: 
     + **GET api/v1/private/account/risk_limit**
- ##### 请求参数:
	
| 参数名  | 类型  | 是否必填  |  说明 |
| ------------ | ------------ | ------------ | ------------ |
| symbol  | string  | false  | 合约名,不传返回所有|

   - ##### 响应参数:
	
| 参数名  | 类型  | 说明  |
| ------------ | ------------ | ------------ |
| symbol  | string  | 合约名 |
| positionType  | int  | 持仓类型 1:多仓，2:空仓|
| level  | int   | 当前风险等级 |
| maxVol  | decimal   | 最大可持仓数量 |
| maxLeverage  | int   | 最大杠杆倍数 |
| mmr  | decimal   | 维持保证金率 |
| imr  | decimal   | 初始保证金率 |
***

+ ### 增加或减少仓位保证金
+ ##### 限速规则: 20次/2秒 
+ ##### method: 
     + **POST api/v1/private/position/change_margin**
- ##### 请求参数:
	
| 参数名  | 类型  | 是否必填  |  说明 |
| ------------ | ------------ | ------------ | ------------ |
| positionId  | long  | true  | 仓位id|
| amount  | decimal  | true  | 金额|
| type  | string  | true  | 类型,ADD:增加,SUB:减少|

   - ##### 响应参数: 公共参数,success: true成功,false失败

***

+ ### 修改杠杆倍数
+ ##### 限速规则: 20次/2秒 
+ ##### method: 
     + **POST api/v1/private/position/change_leverage**
- ##### 请求参数:
	
| 参数名  | 类型  | 是否必填  |  说明 |
| ------------ | ------------ | ------------ | ------------ |
| positionId  | long  | true  | 仓位id|
| leverage  | int  | true  | 杠杆倍数|

   - ##### 响应参数: 公共参数,success: true成功,false失败

***

+ ### 下单
+ ##### 限速规则: 20次/2秒 
+ ##### method: 
     + **POST api/v1/private/order/submit**
- ##### 请求参数:
	
| 参数名  | 类型  | 是否必填  |  说明 |
| ------------ | ------------ | ------------ | ------------ |
| symbol  | string  | true  | 合约名|
| price  | decimal  | true  | 价格|
| vol  | decimal  | true  | 数量|
| leverage  | int  | false  | 杠杆倍数,开仓的时候杠杆倍数必须传入|
| side  | int  | true  | 订单方向 1开多,2平空,3开空,4平多|
| type  | int  | true  | 订单类型,1:限价单,2:Post Only只做Maker,3:立即成交或立即取消,4:全部成交或者全部取消,5:市价单|
| openType  | int  | true  | 开仓类型,1:逐仓,2:全仓|
| externalOid  | string  | false  | 外部订单号|

   - ##### 响应参数: 成功时,success =true,data值为订单id,success =false,失败data=null
***
+ ### 批量下单
+ ##### 限速规则: 20次/2秒 
+ ##### method: 
     + **POST api/v1/private/order/submit_batch**
- ##### 请求参数(最大50条):
	
| 参数名  | 类型  | 是否必填  |  说明 |
| ------------ | ------------ | ------------ | ------------ |
| symbol  | string  | true  | 合约名|
| price  | decimal  | true  | 价格|
| vol  | decimal  | true  | 数量|
| leverage  | int  | false  | 杠杆倍数,开仓的时候杠杆倍数必须传入|
| side  | int  | true  | 订单方向 1开多,2平空,3开空,4平多|
| type  | int  | true  | 订单类型,1:限价单,2:Post Only只做Maker,3:立即成交或立即取消,4:全部成交或者全部取消,5:市价单|
| openType  | int  | true  | 开仓类型,1:逐仓,2:全仓|
| externalOid  | string  | false  | 外部订单号,如果已存在，返回已存在的订单id|


参数示例:
```json
    [{
      "symbol": "BTC_USD",
      "price": 8800,
      "vol": 100,
      "leverage": 20,
      "side": 1,
      "type": 1,
      "openType": 1,
      "externalOid": "order1"
    },
    {
       "symbol": "BTC_USD",
       "price": 500,
       "vol": 100,
        "leverage": 50,
        "side": 3,
        "type": 1,
        "openType": 1,
        "externalOid": "order2"
          }]
```
   - ##### 响应参数:
	
| 参数名  | 类型  | 说明  |
| ------------ | ------------ | ------------ |
| externalOid  | string  | 外部订单号 |
| orderId  | long  | 订单id,失败时为null  |
| errorMsg  | string  | 错误信息，失败时不为空|
| errorCode  | int  | 错误code，默认为0|

***

	
+ ### 取消订单
+ ##### 限速规则: 20次/2秒 
+ ##### method: 
     + **POST api/v1/private/order/cancel**
- ##### 请求参数:
	
| 参数名  | 类型  | 是否必填  |  说明 |
| ------------ | ------------ | ------------ | ------------ |
| 无  | List<Long>  | true  | 订单id列表,最大50条|

 参数示例:[1,2,3]

   - ##### 响应参数: - ##### 响应参数: 公共参数,success: true成功,false失败

***
+ ### 取消某合约下所有订单
+ ##### 限速规则: 20次/2秒 
+ ##### method: 
     + **POST api/v1/private/order/cancel_all**
- ##### 请求参数:
	
| 参数名  | 类型  | 是否必填  |  说明 |
| ------------ | ------------ | ------------ | ------------ |
| symbol  | string  | false| 合约名,传入symbol只取消该合约下的订单，不传取消所有合约下的订单|

   - ##### 响应参数: - ##### 响应参数: 公共参数,success: true成功,false失败
   
 ***
 + ### 修改风险等级
 + ##### 限速规则: 20次/2秒 
 + ##### method: 
      + **POST api/v1/private/account/change_risk_level**
 - ##### 请求参数:
 	
 | 参数名  | 类型  | 是否必填  |  说明 |
 | ------------ | ------------ | ------------ | ------------ |
 | symbol  | string  | true  | 合约名|
 | level  | int  | true  | 等级|
 | positionType  | int  | true  | 1:多仓，2:空仓|
 
    - ##### 响应参数: - ##### 响应参数: 公共参数,success: true成功,false失败
    
 ***

 - #### 错误码:
  
  | code  | 描述  |
  | ------------ | ------------ |
  | 0  | 操作成功  |
  | 9999  | 公共异常  |
  | 500  | 内部错误  |
  | 501  | 系统繁忙  |
  | 401  | 未授权  | 
  | 402  | api_key过期  |
  | 406  | 访问ip不在白名单  |
  | 506  | 未知的请求来源  |
  | 510  | 请求过于频繁  |
  | 511  | 接口禁止访问  |
  | 513  | 请求无效(针对open api 请求时间>服务器时间2秒或者<服务器时间10秒以上)  |
  | 600  | 参数错误  |
  | 601  | 数据解析错误  |
  | 602  | 验签失败  |
  | 603  | 重复请求  |
  | 1000  | 账户不存在  |
  | 1001  | 合约不存在  |
  | 1002  | 合约未启用  |
  | 1003  | 风险限额等级错误  |
  | 1004  | 金额错误  |
  | 2001  | 订单方向错误  |
  | 2002  | 开仓类型错误  |
  | 2003  | 买单价格过高  |
  | 2005  | 余额不足  |
  | 2006  | 杠杆倍数错误  |
  | 2007  | 订单价格错误  |
  | 2008  | 可平数量不足  |
  | 2009  | 仓位不存在或已平仓  |
  | 2011  | 订单数量错误  |
  | 2013  | 取消订单数量超过最大限制  |
  | 2014  | 批量下单数量超限  |
  | 2015  | 价格或者数量精度错误  |
  | 2016  | 计划委托超过最大委托数量  |
  | 2018  | 超过最大可减保证金  |
  | 2019  | 存在开仓活跃委托``  |
  | 2021  | 下单杠杆倍数和已有仓位杠杆倍数不一致  |
  | 2022  | 持仓类型错误  |
  | 2023  | 存在大于新档位最大杠杆倍数的持仓  |
  | 2024  | 存在大于新档位最大杠杆倍数的订单  |
  | 2025  | 当前持仓数量大于新档位最大允许数量  |
  | 2026  | 全仓不支持修改杠杆  |
  | 2027  | 同一方向全仓和逐仓只能存在一个  |
  | 3001  | 计划委托价格类型错误  |
  | 3002  | 计划委托触发类型错误  |
  | 3003  | 执行周期错误  |
  | 3004  | 触发价格错误  |
  | 4001  | 不支持的币种  |
***


# WEBSOCKET模块

## 基本信息:
	原生ws连接地址: wss://contract.mxc.ai/ws 、  wss://contract.mxc.com/ws 、 wss://contract.mxc.io/ws

## 数据交互命令详解:
    订阅/取消订阅数据命令列表（除个人相关命令列表之外，其余都不需要做ws认证）,服务端返回:
    {"channel":"pong","data":1587453241453},1分钟以内未收到客户端ping，将断开该客户端连接，建议10~20秒发送一次ping
### 公共模块:
***
####tickers: 

+ ##### 订阅:
```json
 {"method":"sub.tickers","param":{}}
```
如需返回明文(后面订阅一样):
```json
 {"method":"sub.tickers","param":{},"gzip": false}
```
  - ##### 响应参数:
	
| 参数名  | 类型  | 说明  |
| ------------ | ------------ | ------------ |
| symbol  | string | 合约名 |
| lastPrice  | decimal  | 最新价 |
| volume24  | decimal  | 24小时成交量，按张数统计 |
| riseFallRate  | decimal  | 涨跌幅 |
| fairPrice  | decimal  | 合理价 |
示例:
```json
 {"channel":"push.tickers",
 "data":[
    {"fairPrice":183.01,"lastPrice":183,"riseFallRate":-0.0708,"symbol":"BSV_USDT","volume24":200},
    {"fairPrice":220.22,"lastPrice":220.4,"riseFallRate":-0.0686,"symbol":"BCH_USDT","volume24":200}
    ]}
```
+ ##### 取消订阅:
```json
 {"method":"unsub.tickers","param":{}}
```
***
#### 单个ticker: 

+ ##### 订阅:
```json
{"method":"sub.ticker","param":{"symbol":"BTC_USDT"}}
```
  - ##### 响应参数:
	
| 参数名  | 类型  | 说明  |
| ------------ | ------------ | ------------ |
| symbol  | string | 合约名 |
| lastPrice  | decimal  | 最新价 |
| bid1  | decimal  | 买一价 |
| ask1  | decimal  | 卖一价 |
| volume24  | decimal  | 24小时成交量，按张数统计 |
| holdVol| decimal  | 总持仓量 |
| lower24Price  | decimal  | 24小时最低价 |
| high24Price  | decimal  | 24小时内最高价 |
| riseFallRate  | decimal  | 涨跌幅 |
| riseFallValue  | decimal  | 涨跌额 |
| indexPrice  | decimal  | 指数价格 |
| fairPrice  | decimal  | 合理价 |
| fundingRate  | decimal  | 资金费率 |
| timestamp  | long   | 成交时间 |
示例:
```json
{"channel":"push.ticker",
"data":{"ask1":6866.5,"bid1":6865,"contractId":1,"fairPrice":6867.4,
"fundingRate":0.0008,"high24Price":7223.5,"indexPrice":6861.6,
"lastPrice":6865.5,"lower24Price":6756,"maxBidPrice":7073.42,
"minAskPrice":6661.37,"riseFallRate":-0.0424,
"riseFallValue":-304.5,"symbol":"BTC_USDT",
"timestamp":1587442022003,"holdVol":2284742,"volume24":164586129},
"symbol":"BTC_USDT"
}
```
+ ##### 取消订阅:
```json
{"method":"unsub.ticker","param":{"symbol":"BTC_USDT"}}
```
***

#### 成交: 

+ ##### 订阅:
```json
{"method":"sub.deal","param":{"symbol":"BTC_USDT"}}
```
   - ##### 响应参数:
	
| 参数名  | 类型  | 说明  |
| ------------ | ------------ | ------------ |
| p  | decimal  | 成交价 |
| v  | decimal  | 数量 |
| T  | int  | 成交方向,1:买,2:卖 |
| O  | int   | 是否是开仓，1:是,2:否,当O为1的时候, vol是新增的持仓量 |
| M  | int   | 是否为自成交,1:是,2:否 |
| t  | long   | 成交时间|
示例:
```json
{"channel":"push.deal",
"data":{"M":1,"O":1,"T":1,"p":6866.5,"t":1587442049632,"v":2096},
"symbol":"BTC_USDT"
}
```
+ ##### 取消订阅:
```json
{"method":"unsub.deal","param":{"symbol":"BTC_USDT"}}
```
***

#### 深度: 

+ ##### 订阅:
```json
{"method":"sub.depth","param":{"symbol":"BTC_USDT"}}
```
   - ##### 响应参数:
	
| 参数名  | 类型  | 说明  |
| ------------ | ------------ | ------------ |
| asks  | List<Numeric[]> |卖方深度 |
| bids  | List<Numeric[]> | 买方深度 |
| version  | long  | 版本号 |
备注: [411.8, 10, 1] 411.8为价格，10为此价格的合约张数,1为订单数量

示例:
```json
{"channel":"push.depth",
"data":{"asks":[[6859.5,3251,1]],"bids":[],"version":96801927},
"symbol":"BTC_USDT"
}
```
+ ##### 取消订阅:
```json
{"method":"unsub.depth","param":{"symbol":"BTC_USDT"}}
```
***

#### K线: 

+ ##### 订阅:
```json
{"method":"sub.kline","param":{"symbol":"BTC_USDT","interval":"Min60"}}
```
interval可选参数:  Min1、Min5、Min15、Min30、Min60、Hour4、Hour8、Day1、Week1、Month1 
   - ##### 响应参数:
	
| 参数名  | 类型  | 说明  |
| ------------ | ------------ | ------------ |
| symbol  | string | 合约名 |
| a  | decimal  | 总成交金额 |
| c  | decimal  | 收盘价 |
| interval  | string  | 间隔: Min1、Min5、Min15、Min30、Min60、Hour4、Hour8、Day1、Week1、Month1 |
| l  | decimal  | 最低价 |
| o  | decimal  | 开盘价 |
| q  | decimal  | 总成交量 |
| h  | decimal  | 最高价 |
| t  | long  | 交易时间，单位：秒（s），为窗口的开始时间（windowStart） |

示例:
```json
{"channel":"push.kline",
"data":{"a":233.740269343644737245,"c":6885,"h":6910.5,
"interval":"Min60","l":6885,"o":6894.5,
"q":1611754,"symbol":"BTC_USDT","t":1587448800},
"symbol":"BTC_USDT"
}
```
+ ##### 取消订阅:
```json
{"method":"unsub.kline","param":{"symbol":"BTC_USDT"}}
```
***

#### 资金费率: 

+ ##### 订阅:
```json
{"method":"sub.funding.rate","param":{"symbol":"BTC_USDT"}}
```
   - ##### 响应参数:
	
| 参数名  | 类型  | 说明  |
| ------------ | ------------ | ------------ |
| symbol  | string | 合约名 |
| fundingRate  | decimal  | 资金费率 |
| nextSettleTime  | long  | 下一次结算时间 |

示例:
```json
{"channel":"push.funding.rate",
"data":{"rate":0.001,"symbol":"BTC_USDT"},
"symbol":"BTC_USDT"
}
```
+ ##### 取消订阅:
```json
{"method":"unsub.funding.rate","param":{"symbol":"BTC_USDT"}}
```
***

#### 指数价格: 

+ ##### 订阅:
正向及方向合约都使用同一个symbol，例如BTC_USD反向合约，订阅指数价格时，使用BTC_USDT
```json
{"method":"sub.index.price","param":{"symbol":"BTC_USDT"}}
```
  - ##### 响应参数:
	
| 参数名  | 类型  | 说明  |
| ------------ | ------------ | ------------ |
| symbol  | string | 合约名 |
| price  | decimal  | 价格 |

示例:
```json
{"channel":"push.index.price",
"data":{"price":0.001,"symbol":"BTC_USDT"},
"symbol":"BTC_USDT"
}
```
+ ##### 取消订阅:
```json
{"method":"unsub.index.price","param":{"symbol":"BTC_USDT"}}
```
***

#### 合理价格: 

+ ##### 订阅:
```json
{"method":"sub.fair.price","param":{"symbol":"BTC_USDT"}}
```
  - ##### 响应参数:
	
| 参数名  | 类型  | 说明  |
| ------------ | ------------ | ------------ |
| symbol  | string | 合约名 |
| price  | decimal  | 价格 |

示例:
```json
{"channel":"push.fair.price",
"data":{"price":0.001,"symbol":"BTC_USDT"},
"symbol":"BTC_USDT"
}
```
+ ##### 取消订阅:
```json
{"method":"unsub.fair.price","param":{"symbol":"BTC_USDT"}}
```
***

### 私有模块:

- #### 登录认证
```json
{
	"method":"login",
	"param":{
		"apiKey":"apiKey", // openapi需要传此参数，参数构造方式参照openapi文档
		"reqTime":"reqTime", // openapi需要传此参数，参数构造方式参照openapi文档
		"signature":"signature" // openapi需要传此参数，参数构造方式参照openapi文档
	}
}
```
#### 响应参数: 成功: 无，失败:返回对应错误信息,channel = rs.error

- ##### 订单(channel = push.personal.order)
| 参数名  | 类型  | 说明  |
| ------------ | ------------ | ------------ |
| orderId  | long  | 页面大小 |
| symbol  | string  | 合约名 |
| positionId  | long  | 持仓id |
| price  | decimal  | 委托价格 |
| vol  | decimal  | 委托数量 |
| leverage  | long  | 杠杆倍数 |
| side  | int  | 订单方向 1开多,2平空,3开空,4平多 |
| category  | int  | 订单类别:1限价委托,2强平代管委托,4ADL减仓 |
| orderType  | int  | 1:限价单,2:Post Only只做Maker,3:立即成交或立即取消,4:全部成交或者全部取消| |
| dealAvgPrice  | decimal  | 成交均价 |
| dealVol  | decimal   | 成交数量 |
| orderMargin  | decimal   | 委托保证金  |
| usedMargin  | decimal   | 已经使用的保证金  |
| takerFee  | decimal   | 买单手续费 |
| makerFee  | decimal   | 卖单手续费 |
| profit  | decimal   | 平仓盈亏 |
| feeCurrency  | string   | 收费币种 |
| openType  | int   | 开仓类型,1逐仓,2全仓 |
| state  | int   | 订单状态,1:待报,2未完成,3已完Fee成,4已撤销,5无效 |
| errorCode  | int   | 错误code,0:正常，1：参数错误，2：账户余额不足，3：仓位不存在，4：仓位可用持仓不足，5：多仓时， 委托价小于了强平价，空仓时， 委托价大于了强平价，6：开多时， 强平价大于了合理价，开空时， 强平价小于了合理价 ,7:超过风险限额限制|
| externalOid  | string   | 外部订单号 |
| createTime  | date   | 创建时间 |
| updateTime  | date   | 修改时间 |
 
 - ##### 资产(channel = push.personal.asset)
 
 | 参数名  | 类型  | 说明  |
 | ------------ | ------------ | ------------ |
 | currency  | string  | 币种 |
 | positionMargin  | decimal   | 仓位保证金 |
 | frozenBalance  | decimal   | 冻结余额 |
 | availableBalance  | decimal   | 当前可用余额 |
 | cashBalance  | decimal   | 可提现余额 |
 
 - ##### 仓位(channel = push.personal.position)
 	
| 参数名  | 类型  | 说明  |
| ------------ | ------------ | ------------ |
| positionId  | long  | 持仓id |
| symbol  | string  | 合约名 |
| holdVol  | decimal  | 持仓数量 |
| positionType  | int  | 仓位类型， 1多 2空 |
| openType  | int   | 开仓类型， 1逐仓 2全仓 |
| state  | int   | 仓位状态,1持仓中2系统代持3已平仓  |
| frozenVol  | decimal   | 冻结量 |
| closeVol  | decimal   | 平仓量 |
| holdAvgPrice  | decimal   | 持仓均价 |
| closeAvgPrice  | decimal   | 平仓均价 |
| openAvgPrice  | decimal   | 开仓均价 |
| liquidatePrice  | decimal   | 逐仓时的爆仓价 |
| oim  | decimal   | 原始初始保证金 |
| adlLevel  | int   | adl减仓等级,取值为 1-5，为空时需等待刷新 |
| im  | decimal   | 初始保证金， 逐仓时可以加减此项以调节爆仓价 |
| holdFee  | decimal   | 资金费, 正数表示得到，负数表示支出 |
| realised  | decimal   | 已实现盈亏 |
| createTime  | date   | 创建时间 |
| updateTime  | date   | 修改时间 |


 - ##### 风险限额(channel = push.personal.risk.limit)
 	
| 参数名  | 类型  | 说明  |
| ------------ | ------------ | ------------ |
| symbol  | string  | 合约名 |
| positionType  | int  | 持仓类型 1:多仓，2:空仓|
| level  | int   | 当前风险等级 |
| maxVol  | decimal   | 最大可持仓数量 |
| maxLeverage  | int   | 最大杠杆倍数 |
| mmr  | decimal   | 维持保证金率 |
| imr  | decimal   | 初始保证金率 |

 - ##### adl自动减仓等级(channel = push.personal.adl.level)
 	
| 参数名  | 类型  | 说明  |
| ------------ | ------------ | ------------ |
| adlLevel| int   | 当前adl等级 ：1-5|
| positionId  | long   | 仓位id |

 - ##### 如何维护深度信息
  
#### 如何维护深度信息:
        1.通过接口 https://www.mxc.com/api/v1/contract/depth/BTC_USDT获取全量深度信息，保存当前version
        2.订阅ws深度信息，收到更新后，如果收到的数据version>当前version,同一个价位，后收到的更新覆盖前面的。
        3.通过接口 https://www.mxc.com/api/v1/contract/depth/depth_commits/BTC_USDT/1000获取最新1000条深度快照
        4.将目前缓存的深度信息中同一价格，version<步骤3获取到的快照中的version的数据丢弃
        5.将深度快照中的内容更新至本地缓存，并从ws接收到的event开始继续更新
        5.每一个新event的version应该恰好等于上一个event的version+1，否则可能出现了丢包，如出现丢包或者获取到的
        event的version不连续,请从步骤3重新进行初始化。
        6.每一个event中的挂单量代表这个价格目前的挂单量绝对值，而不是相对变化。
        7.如果某个价格对应的挂单量为0，表示该价位的挂单已经撤单或者被吃，应该移除这个价位。


