永续合约API

接口地址:
共识:
  • 订单的操作: 做多, 做空
  • 持仓的操作: 强平, 止损平, 止盈平, 选择平仓
做多/做多 --> 持仓 --> 平仓
订单分建仓和平仓两大类:
  • 建仓: 做多, 做空
  • 平仓: 强平, 止损平, 止盈平, 选择平仓
如果按买/卖来分订单的话:
  • 买(bid): 建仓做多, 买入平空
  • 卖(ask): 建仓做空, 卖出平多
测试市场:
名称合约乘数手续费率优惠券最多占手续费平多价格(点数)平空价格(点数)强平条件
BTCUSDT1建仓和平仓一样 0.05%10%0.9 * 实际价格1.1 * 实际价格亏损>=70%资产
ETHUSDT20建仓和平仓一样 0.05%10%0.9 * 实际价格1.1 * 实际价格亏损>=70%资产
下文中的合约和持仓是一个意思.

via原始API

本文档只提供改动过的 API, 很多需要用via的其它接口, 请访问:

市场列表

method: market.list
params: 无
示例:
结果:
  • {
  •     "error": null,
  •     "result": [
  •         {
  •             "name": "BTCUSDT",
  •             "money": "USDT",
  •             "stock": "BTC",
  •             "contract_multiplier": "1", // 合约乘数
  •             "build_fee_rate": "0.1", // 建仓手续费率 10%
  •             "destroy_fee_rate": "0.1", // 平仓手续费率 10%
  •             "coupon_fee_rate": "0.1", // 优惠券最多占手续费 10%
  •             "buy_sell_rate": "0.9", // 平多价格(点数) 0.9 * 实际价格为最终价格
  •             "sell_buy_rate": "1.1" // 平空价格(点数)
  •         },
  •         {
  •             "buy_sell_rate": "0.9",
  •             "name": "ETHUSDT",
  •             "contract_multiplier": "20",
  •             "stock": "ETH",            
  •             "build_fee_rate": "0.1", // 建仓手续费率 10%
  •             "destroy_fee_rate": "0.1", // 平仓手续费率 10%
  •             "coupon_fee_rate": "0.1",
  •             "money": "USDT",
  •             "sell_buy_rate": "1.1"
  •         }
  •     ],
  •     "id": 1
  • }

限价做多/做空

method: order.put_limit
params:
  • user_id: user ID, Integer
  • market: market name. String
  • side: 1: 做空, 2: 做多,Integer
  • amount: 数量, String
  • price: 价格, String
  • taker_fee_rate: 无用, 请传固定值 '0'
  • maker_fee_rate: 无用, 请传固定值 '0'
  • source: String, source,up to 30 bytes
  • contract_order_id: 合约Id, Integer, 无用, 请传固定值 0
  • deposit_rate: 保证金率, String, 如 "0.1" 表示10倍杠杆
  • stop_loss_price: 止损价, String, 如没有, 请传 "0"
  • target_profit_price: 止盈价, String, 如没有, 请传 "0"
result: order detail
示例:
用户1 以价格10元做多1合约, 杠杆为10倍, 无止损与止盈价:
  • curl http://ip:7080 -d '{"id":8,"method":"order.put_limit","params":[1,"BTCUSDT",2, "1","10","0","0","",0,"0.1","0","0"]}'

  • [1(用户id),"BTCUSDT"(market name), 2(做多), "1"(数量),"10"(价格),"0"(没用),"0"(没用),""(source),0(contract_order_id),"0.1"(deposit_rate),"0"(stop_loss_price),"0"(target_profit_price)]}'
成功返回:
  • {"error": null, "id": 8, "result": {"id": 1, "market": "BTCUSDT", "type": 1, "amount": "1", "source": "", "ctime": 1566722980.0905261, "mtime": 1566722980.0905261, "side": 2, "user": 1, "price": "10", "left": "1", "deal_fee": "0"}}
  • 有用的数据:
  • id: 订单id
  • amount: 表示数量
  • left: 表示还有多少没有成交的
失败则返回:
  • {"error": {"code": 10, "message": "balance not enough(错误信息)"}, "id": 8, "result": null}
  • 其它code代表的含义
  • code
  • 1: invalid argument
  • 10: balance not enough
  • 12: no enough trader
  • 2: internal error 其它错误

市价做多/做空

method: order.put_market
params:
  • user_id: user ID, Integer
  • market: market name. String
  • side: 1: 做空, 2: 做多,Integer
  • amount: 数量, String
  • taker_fee_rate: 无用, 请传固定值 '0'
  • source: String, source,up to 30 bytes
  • contract_order_id: 合约Id, Integer, 无用, 请传固定值 0
  • deposit_rate: 保证金率, String, 如 "0.1" 表示10倍杠杆
  • stop_loss_price: 止损价, String, 如没有, 请传 "0"
  • target_profit_price: 止盈价, String, 如没有, 请传 "0"
result: order detail
示例:
用户1 做多1合约, 杠杆为10倍, 无止损与止盈价:
  • curl http://ip:7080 -d '{"id":8,"method":"order.put_market","params":[1,"BTCUSDT",2, "1","0","",0,"0.1","0","0"]}'

  • [1(用户id),"BTCUSDT"(market name),2(做多), "1"(数量),"0"(没用),""(source),0(contract_order_id),"0.1"(deposit_rate),"0"(stop_loss_price),"0"(target_profit_price)]}'
成功返回: 参考限价做多/做空
失败则返回: 参考限价做多/做空

选择平仓

method: order.put_market
params:
  • user_id: user ID, Integer
  • market: market name, String
  • side: 3: 平空, 4: 平多, Integer
  • amount: 平仓数量, String
  • taker_fee_rate: 无用, 请传固定值 '0'
  • source: String, source,up to 30 bytes
  • contract_order_id: 合约Id, Integer
  • deposit_rate: 保证金率, String, 无用, 请传固定值 '0'
  • stop_loss_price: 止损价, String, 无用, 请传固定值 '0'
  • target_profit_price: 止盈价, String, 无用, 请传固定值 '0'
result: order detail
示例:
用户2 平多1合约(合约id为82)
  • curl http://ip:7080 -d '{"id":8,"method":"order.put_market","params":[2,"BTCUSDT",4,"1", "0", "", 82, "0", "0", "0"]}'
  • [2(用户id), "BTCUSDT", 4(平多), "1"(平仓数量), "0"(没用), "", 82(合约id), "0"(没用), "0"(没用), "0"(没用)]
成功返回: 参考限价做多/做空
失败则返回: 参考限价做多/做空

持仓列表

method: contract.order
params:
  • user_id: user ID, Integer
  • market: market name. String
result: contract order list
示例:
查询user_id 为1, BTCUSDT的合约列表
  • curl http://ip:7080 -d '{"id":19,"method":"contract.order","params":[1,"BTCUSDT"]}'
返回:
  • {
  •     "error": null,
  •     "result": {
  •         "records": [
  •             {
  •                 "user": 1,
  •                 "id": 4, // 合约id, 平仓的时候要用这个id
  •                 "order_id": 1, // 做多订单id 没用
  •                 "side": "2 ", // 1 做空, 2做多
  •                 "ctime": 1566724266.334999,
  •                 "mtime": 1566724266.335007,
  •                 
  •                 "market": "BTCUSDT",
  •                 "source": "",
  •                 
  •                 "price": "10", // 均价
  •                 "amount": "1", // 合约数量
  •                 "amount_freeze": "0", // 合约冻结数量, 做空时会冻结
  •                 "amount_left": "1", // 合约可用数量
  •                 
  •                 "deal_fee": "0", // 做空合约产生的交易费
  •                 
  •                 "deposit": "1", // 保证金
  •                 "deposit_left": "1", // 待返还的保证金

  •                 "profit_price": "0", // 已实现平仓均价
  •                 "profit": "0", // 已实现平仓收益
  •                 
  •                 // 当前市场价请使用 market.last (websocket) 得到
  •                 // 浮动收益请按最新价计算: 
  •                 // 做空 amount_left * contract_multiplier * (price - 当前市场价)
  •                 // 做多 amount_left * contract_multiplier * (当前市场价 - price)
  •                 "profit_float": "-35.15", // 浮动收益
  •                 
  •                 "deposit_rate": "0.1", // 杠杆
  •                 "contract_multiplier": 1, // 合约乘数
  •                 "stop_loss_price": "0e-8", // 止损价, 为0表示无
  •                 "target_profit_price": "0e-8" // 止赢价, 为0表示无
  •                 
  •                 "build_submit_price": "10", // v2 建仓时的委托价, 如果为0表示是市价, 请用price
  •             }
  •         ]
  •     },
  •     "id": 19
  • }

委托 pending order

订单有: 建仓 和 平仓 两大类
method: order.pending
params:
  • user_id: user ID,Integer
  • market: market name,String
  • offset: offset,Integer
  • limit: limit,Integer
result:
  • {
  •     "error": null,
  •     "result": {
  •         "records": [
  •             {}, {} // 列表, 字段请看下面
  •         ]
  •     },
  •     "id": 19
  • }

  • 字段:
  • {
  •     "id": 20,
  •     "ctime": 1566739347.524148,
  •     "ftime": 1566739347.524148,
  •     "source": "",
  •     "user": 1,
  •     "market": "BTCUSDT",
  •     "side": 1, // 1: 做空, 2: 做多, 3: 平空, 4: 平多
  •     "put_type": 2, // 1 限价, 2 市价
  •     "price": "0", // 价格
  •     "amount": "1", // 数量
  •     "left": 0, // 剩余数量
  •     "deal_fee": "0", // 交易费, 建仓时表示交的手续费, 平仓时表示平仓交的手续费
  •     "order_type": "订单类型, 1-7",

  •     // 当订单类型为 做多/空
  •     "deposit_left": "100", // 初始保证金
  •     "deposit_left": "100", // 待返还的初始保证金
  •     "fee_left": "0.3", // 待返还的交易费
  •     "deposit_rate": "0.1", // 杠杆
  •     "contract_multiplier": "1", // 合约乘数
  •     "stop_loss_price": "0", // 止损价
  •     "target_profit_price": "0", // 上盈价
  •     
  •     // 当订单类型为 平仓 (强平, 选择平, 止损, 止盈) 有以下字段    
  •     "contract_order_id": "19", // 合约id
  • }

历史订单/持仓

method: order.finished
params:
  • user_id: user ID,Integer
  • market: market name,String, v3 可传空字符串 "", 表示所有市场
  • start_time: start time,0 for unlimited,Integer
  • end_time: end time,0 for unlimited, Integer
  • offset: offset,Integer
  • limit: limit,Integer
  • order_type: Integer 订单类型
订单有以下几种类型(order_type):
持仓其实不是订单, 但也放在这个接口中.
建仓类型2个:
  • MARKET_ORDER_TYPE_BUILD_SELL   1 // 做空
  • MARKET_ORDER_TYPE_BUILD_BUY    2 // 做多
持仓:
  •  MARKET_ORDER_TYPE_CONTRACT     3 // 持仓
平仓类型分:
  • MARKET_ORDER_TYPE_DESTROY_FORCE     4 // 强平
  • MARKET_ORDER_TYPE_DESTROY_SELECT    5 // 选择平
  • MARKET_ORDER_TYPE_DESTROY_STOP_LOSS    6 // 止损
  • MARKET_ORDER_TYPE_DESTROY_TARGET_PROFIT    7 // 止赢
result:
  • {
  •     "error": null,
  •     "result": {
  •         "records": [
  •             {}, {} // 列表, 字段请看下面
  •         ]
  •     },
  •     "id": 19
  • }

  • 字段:
  • {
  •     "id": 20, // 订单或合约id
  •     "ctime": 1566739347.524148,
  •     "ftime": 1566739347.524148,
  •     "source": "",
  •     "user": 1,
  •     "market": "BTCUSDT",
  •     "side": 1, // 1做空, 2做多, 3平空, 4平多
  •     "put_type": 2, // 1 限价, 2 市价
  •     "price": "0", // 价格, 如果是持仓, 表示持仓均价, 如果限价建仓, 则是委托价, 如果是市价建仓/平仓, 则为0
  •     "amount": "1", // 数量
  •     "deal_fee": "0", // 交易费, 建仓时表示交的手续费, 平仓时表示平仓交的手续费
  •     "order_type": "订单类型, 1-7",

  •     // 当订单类型为 做多/空, 持仓时 有以下字段
  •     "deposit": "10", // 保证金
  •     "deposit_rate": "0.1", // 杠杆
  •     "contract_multiplier": "1", // 合约乘数
  •     "stop_loss_price": "0", // 止损价
  •     "target_profit_price": "0", // 止盈价
  •     
  •     // 当订单类型为 做多/空时 有以下字段
  •     "left": 0, // 剩余数量, 0表示都成交了, 如果left还有值, 表示该单撤销了
  •     
  •     // 当订单类型为持仓时
  •     "profit": "10", // 收益
  •     "profit_price": "2", // 平均平仓价
  •     "build_submit_price": "10", // v2 建仓时的委托价, 如果为0表示是市价, 请用price表示
  •     
  •     // 当订单类型为 平仓 (强平, 选择平, 止损, 止盈) 有以下字段    
  •     "contract_order_id": "19", // 合约id
  •     "left": 1, // left > 0表示平仓只有部分成交, 如果left==amount, 则平仓失败
  •     "profit": "10", // v2 盈亏: 该平仓单所平的收益, 可为负数
  •     "profit_price": "10", // v2 平仓价格: 该平仓单所平的价格
  •     "contract_order_price": "10", // v2 开仓价格: 所平持仓价格
  •     "build_submit_price": "10" // v2 委托价格: 该平仓单所平的持仓的建仓委托价, 如果为0, 请用contract_order_price
  • }

合约总浮动收益 (websocket)

  • 方法: contract.profit
  • 参数: 空
  • 结果:
  • {"profit": "10"}
净资产, 请通过:
获取到 USDT的 available+freeze 即净资产.
浮动盈亏的计算价格以对手价为准, 不是以当前价格. 因为平仓的时候是以对手价为准的, 当前价格不一定是对手价, 一般会高于对手价.

券 COUPON 被当作一种资产, 所以请和USDT一样, 使用 balance.update 为其增加/减少值.

手续费列表

balance.history 会返回资产的所有变动历史记录
method: balance.history
params:
  • user_id: user ID, Integer
  • asset: asset name, 可传空字符串
  • business: business,可传空字符串, use ',' to separate types, 如果想特意查询建仓和平仓费, 请传 "build_fee,destroy_fee" 
  • start_time: start time,0 for unlimited,Integer
  • end_time: end time,0 for unlimited, Integer
  • offset: offset position,Integer
  • limit: count limit,Integer
如有以下返回:
business 为建仓/平仓特意加了两个值:
  • build_fee 建仓费
  • destroy_fee 平仓费
  • {
  •     "error": null,
  •     "result": {
  •         "limit": 100,
  •         "offset": 0,
  •         "records": [
  •             {
  •                 "time": 1566739347.535009,
  •                 "balance": "97.6",
  •                 "available": "94.8",
  •                 "business": "build_fee", // 建仓费
  •                 "asset": "USDT",
  •                 "change": "-0.1",
  •                 "freeze": "2.8",
  •                 "detail": {
  •                     "f": "0.1",
  •                     "a": "1",
  •                     "c": "1",
  •                     "i": 11,
  •                     "m": "ETHUSDT",
  •                     "p": "1"
  •                 }
  •             },
  •             {
  •                 "time": 1566739347.52374,
  •                 "balance": "97.7",
  •                 "available": "94.6",
  •                 "business": "build_fee",
  •                 "asset": "USDT",
  •                 "change": "-0.1",
  •                 "freeze": "3.1",
  •                 "detail": {
  •                     "f": "0.1",
  •                     "a": "1",
  •                     "c": "1",
  •                     "i": 9,
  •                     "m": "BTCUSDT",
  •                     "p": "1"
  •                 }
  •             },
  •             {
  •                 "time": 1566724266.594583,
  •                 "balance": "88.72",
  •                 "available": "88.72",
  •                 "business": "destroy_fee", // 平仓费
  •                 "asset": "USDT",
  •                 "change": "-0.09",
  •                 "freeze": "0",
  •                 "detail": {
  •                     "f": "0.1",
  •                     "a": "0.9",
  •                     "c": "1",
  •                     "i": 8,
  •                     "m": "ETHUSDT",
  •                     "p": "1"
  •                 }
  •             },
  •             {
  •                 "time": 1566739347.48677,
  •                 "balance": "97.8",
  •                 "available": "94.4",
  •                 "business": "build_fee",
  •                 "asset": "USDT",
  •                 "change": "-0.1",
  •                 "freeze": "3.4",
  •                 "detail": {
  •                     "f": "0.1",
  •                     "a": "1",
  •                     "c": "1",
  •                     "i": 11,
  •                     "m": "ETHUSDT",
  •                     "p": "1"
  •                 }
  •             },
  •             {
  •                 "time": 1566739347.486431,
  •                 "balance": "97.9",
  •                 "available": "94.6",
  •                 "business": "build_fee",
  •                 "asset": "USDT",
  •                 "change": "-0.1",
  •                 "freeze": "3.3",
  •                 "detail": {
  •                     "f": "0.1",
  •                     "a": "1",
  •                     "c": "1",
  •                     "i": 9,
  •                     "m": "BTCUSDT",
  •                     "p": "1"
  •                 }
  •             },
  •             {
  •                 "time": 1566724266.594373,
  •                 "balance": "98",
  •                 "available": "96",
  •                 "business": "build_fee",
  •                 "asset": "USDT",
  •                 "change": "-1",
  •                 "freeze": "2",
  •                 "detail": {
  •                     "f": "0.1",
  •                     "a": "1",
  •                     "c": "1",
  •                     "i": 6,
  •                     "m": "ETHUSDT",
  •                     "p": "10"
  •                 }
  •             },
  •             {
  •                 "time": 1566724266.334788,
  •                 "balance": "99",
  •                 "available": "98",
  •                 "business": "build_fee",
  •                 "asset": "USDT",
  •                 "change": "-1",
  •                 "freeze": "1",
  •                 "detail": {
  •                     "f": "0.1",
  •                     "a": "1",
  •                     "c": "1",
  •                     "i": 2,
  •                     "m": "BTCUSDT",
  •                     "p": "10"
  •                 }
  •             },
  •             {
  •                 "time": 1566724266.064173,
  •                 "balance": "100",
  •                 "available": "100",
  •                 "business": "deposit",
  •                 "asset": "USDT",
  •                 "change": "100",
  •                 "freeze": "0",
  •                 "detail": {
  •                     "id": 1
  •                 }
  •             }
  •         ]
  •     },
  •     "id": 26
  • }

修改合约止损止盈价

method: contract.update_stop_price
params:
  • market string 市场名称
  • contract_order_id: 合约id 整型
  • stop_loss_price 止损价, 字符串, 如果传负数如 "-1" 表示不更新这个值
  • target_profit_price 止盈价, 字符串, 如果传传负数如 "-1"表示不更新这个值
示例:
  • curl http://ip:7080 -d '{"method":"contract.update_stop_price","id":17,"params":["BTCUSDT",3(合约id),"10"(止损价),"100"(止盈价)]}'

  • // 单独设置止损价, 止盈价不变
  • curl http://ip:7080 -d '{"method":"contract.update_stop_price","id":17,"params":["BTCUSDT",3(合约id),"10"(止损价),"-1"(止盈价)]}'

  • // 取消止损与止盈价 都设为0
  • curl http://ip:7080 -d '{"method":"contract.update_stop_price","id":17,"params":["BTCUSDT",3(合约id),"0"(止损价),"0"(止盈价)]}'
正确返回:
  • {"error": null, "id": 1, "result": {}}

止盈止损策略

每当市场交易有撮合时, 判断该市场下所有的持仓, 是否有止损止盈价格.
如果有止损价格, 看对手价是否小于等于该价格, 如果是, 则平仓
如果有止盈价格, 看对手价是否大于等于该价格, 如果是, 则平仓
平仓前取消该持仓的所有平仓订单, 再以市价平.
注意, 不是看当前交易价格, 是看对手价, 因为交易价格不一定是平仓的价格, 撮合的价格是看对手的, 不是看当前的交易价格. 所以以对手价为准.

强平策略

每当市场交易有撮合时, 计算所有用户的浮动赢亏, 如果亏损达到触发条件则强平:
  1. 取消该用户的所有订单(只要在pending order都取消掉)
  2. 强平所有持仓: 以市价平
强平可能会出现的问题:
  1. 没有足够的对手, 如果该持仓有一部分撮合, 则以最后的价格平仓
  2. 如果一个对手都没有, 全被别人吃掉了. 
    1. 如果是平多, 则以价格0平掉
    2. 如果是平空, 无法平, 它的亏损无限大, 无法平 (实际不会出现这种情况, 因为价格上天了, 总有人卖的, 机器人也可以参与进来)

强平事件 websocket

订阅 event.subscribe

参数: 无
例:
  • {"method":"event.subscribe","params":[],"id":6}

取消订阅 event.unsubscribe

参数: 无
例:
  • {"method":"event.unsubscribe","params":[],"id":7}

推送 event.update

当 发生强平/预警时, 会推送如下消息
  • {"method": "event.update", "params": ["force_destroy", "-4.0000000000000000", "20.00000000000000000000"], "id": null}

  • {"method": "event.update", "params": ["force_destroy_warning", "-2.0000000000000000", "20.00000000000000000000"], "id": null}
其中:
  • ["force_destroy", "-4.0000000000000000", "20.00000000000000000000"]
  • 参数1 force_destroy 表示已强平, force_destroy_warning 表示还没有强平, 快要到了, 比如达到了60%
  • 参数2 -4 表示合约收益
  • 参数3 20 表示净资产
注意, force_destroy_warning 的通知可能会很频繁, 前端要控制好显示的次数, 比如判断与上一次显示的时间是否超过1分钟之类的.
立即登录, 发表评论.
没有帐号? 立即注册