Gate.hk 期权 WebSocket v4

Gate.hk 提供了一个简单而强大 Websocket 频道来集成gate.io底层选项 交易状态进入您的业务或应用程序。

我们在Python中有语言绑定，将来还会有更多！您可以在右侧的深色区域中查看代码示例，并且可以通过右上角的选项卡切换示例的编程语言。

服务器地址

以下是我们提供的期权交易服务器地址，您可以根据您的情况选择其中之一。

地址列表:

• 线上交易: wss://op-ws.gateio.live/v4/ws
• 模拟盘交易: wss://op-ws-testnet.gateio.live/v4/ws

变更日志

# !/usr/bin/env python
# coding: utf-8

import hashlib
import hmac
import json
import logging
import time

from websocket import WebSocketApp

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)


class GateWebSocketApp(WebSocketApp):

   def __init__(self, url, api_key, api_secret, **kwargs):
      super(GateWebSocketApp, self).__init__(url, **kwargs)
      self._api_key = api_key
      self._api_secret = api_secret

   def _send_ping(self, interval, event, payload):
      while not event.wait(interval):
         self.last_ping_tm = time.time()
         if self.sock:
            try:
               self.sock.ping(payload)
            except Exception as ex:
               logger.warning("send_ping routine terminated: {}".format(ex))
               break
            try:
               self._request("options.ping", auth_required=False)
            except Exception as e:
               raise e

   def _request(self, channel, event=None, payload=None, auth_required=True):
      current_time = int(time.time())
      data = {
         "time": current_time,
         "channel": channel,
         "event": event,
         "payload": payload,
      }
      if auth_required:
         message = 'channel=%s&event=%s&time=%d' % (channel, event, current_time)
         data['auth'] = {
            "method": "api_key",
            "KEY": self._api_key,
            "SIGN": self.get_sign(message),
         }
      data = json.dumps(data)
      logger.info('request: %s', data)
      self.send(data)

   def get_sign(self, message):
      h = hmac.new(self._api_secret.encode("utf8"), message.encode("utf8"), hashlib.sha512)
      return h.hexdigest()

   def subscribe(self, channel, payload=None, auth_required=True):
      self._request(channel, "subscribe", payload, auth_required)

   def unsubscribe(self, channel, payload=None, auth_required=True):
        self._request(channel, "unsubscribe", payload, auth_required)


def on_message(ws, message):
    # type: (GateWebSocketApp, str) -> None
    # handle message received
    logger.info("message received from server: {}".format(message))


def on_open(ws):
    # type: (GateWebSocketApp) -> None
    # subscribe to channels interested
    logger.info('websocket connected')
    ws.subscribe("options.contract_tickers", ['BTC_USDT-20211231-59800-C'], False)


if __name__ == "__main__":
    logging.basicConfig(format="%(asctime)s - %(message)s", level=logging.DEBUG)
    app = GateWebSocketApp("wss://op-ws.gateio.live/v4/ws",
                           "YOUR_API_KEY",
                           "YOUR_API_SECRET",
                           on_open=on_open,
                           on_message=on_message)
    app.run_forever(ping_interval=5)

package main

import (
	"crypto/hmac"
	"crypto/sha512"
	"crypto/tls"
	"encoding/hex"
	"encoding/json"
	"fmt"
	"io"
	"net/url"
	"time"

	"github.com/gorilla/websocket"
)

type Msg struct {
	Time    int64    `json:"time"`
	Channel string   `json:"channel"`
	Event   string   `json:"event"`
	Payload []string `json:"payload"`
	Auth    *Auth    `json:"auth"`
}

type Auth struct {
	Method string `json:"method"`
	KEY    string `json:"KEY"`
	SIGN   string `json:"SIGN"`
}

const (
	Key    = "YOUR_API_KEY"
	Secret = "YOUR_API_SECRETY"
)

func sign(channel, event string, t int64) string {
	message := fmt.Sprintf("channel=%s&event=%s&time=%d", channel, event, t)
	h2 := hmac.New(sha512.New, []byte(Secret))
	io.WriteString(h2, message)
	return hex.EncodeToString(h2.Sum(nil))
}

func (msg *Msg) sign() {
	signStr := sign(msg.Channel, msg.Event, msg.Time)
	msg.Auth = &Auth{
		Method: "api_key",
		KEY:    Key,
		SIGN:   signStr,
	}
}

func (msg *Msg) send(c *websocket.Conn) error {
	msgByte, err := json.Marshal(msg)
	if err != nil {
		return err
	}
	return c.WriteMessage(websocket.TextMessage, msgByte)
}

func NewMsg(channel, event string, t int64, payload []string) *Msg {
	return &Msg{
		Time:    t,
		Channel: channel,
		Event:   event,
		Payload: payload,
	}
}

func main() {
	u := url.URL{Scheme: "wss", Host: "op-ws.gateio.live", Path: "/v4/ws"}
	websocket.DefaultDialer.TLSClientConfig = &tls.Config{RootCAs: nil, InsecureSkipVerify: true}
	c, _, err := websocket.DefaultDialer.Dial(u.String(), nil)
	if err != nil {
		panic(err)
	}
	c.SetPingHandler(nil)

	// read msg
	go func() {
		for {
			_, message, err := c.ReadMessage()
			if err != nil {
				c.Close()
				panic(err)
			}
			fmt.Printf("recv: %s\n", message)
		}
	}()

	t := time.Now().Unix()
	pingMsg := NewMsg("options.ping", "", t, []string{})
	err = pingMsg.send(c)
	if err != nil {
		panic(err)
	}

	// subscribe order book
	orderBookMsg := NewMsg("options.order_book", "subscribe", t, []string{"BTC_USDT-20211231-59800-C"})
	err = orderBookMsg.send(c)
	if err != nil {
		panic(err)
	}

	// subscribe positions
	positionsMsg := NewMsg("options.positions", "subscribe", t, []string{"USERID", "BTC_USDT-20211231-59800-C"})
	positionsMsg.sign()
	err = positionsMsg.send(c)
	if err != nil {
		panic(err)
	}

	select {}
}

2021-12-28

• 初次发版

Websocket API概述

事件

每个通用 频道（例如行情、订单簿等）都支持 4 种不同的事件消息，它们是：

1. subscribe (推荐使用)

   订阅，接受服务器的新数据推送。

2. unsubscribe

   如果取消订阅，服务器将不会发送新数据推送。

3. update

   服务器将向客户端发送新的订阅数据（增量数据）

4. all

   如果有新订阅的数据（所有数据）可用，服务器将向客户端发送推送。

请求参数

每个请求都遵循通用格式，其中包含 time, channel, event 和 payload。

名称	类型	必选	描述
time	Integer	是	请求时间
channel	String	是	请求 subscribe/unsubscribe频道
auth	String	否	请求身份验证信息，请参阅身份验证部分了解详细信息
event	String	是	请求 event (subscribe/unsubscribe/update/all)
payload	Array	是	请求详细参数

推送参数

与请求类似，推送参数遵循以下通用格式，其中包含： time, channel, event, error 和 result.

名称	类型	必选	描述
time	Integer	是	推送时间
channel	String	是	推送频道
event	String	是	推送频道事件 (update/all)
error	Object	是	推送错误
result	Array	是	推送详细参数

错误

如果出现错误，您会收到error字段，其中包含错误代码和错误的类型。

Code	Message
1	invalid argument struct
2	invalid argument
3	service error

鉴权

WARNING

注意: 您使用的 GateAPIv4 密钥对必须至少启用选项读取权限， 如果启用了密钥的白名单，则您的出站 IP 地址必须在密钥的 IP 白名单中。

# example WebSocket signature calculation implementation in Python
import hmac, hashlib, json, time


def gen_sign(channel, event, timestamp):
    # GateAPIv4 key pair
    api_key = 'YOUR_API_KEY'
    api_secret = 'YOUR_API_SECRET'

    s = 'channel=%s&event=%s&time=%d' % (channel, event, timestamp)
    sign = hmac.new(api_secret.encode('utf-8'), s.encode('utf-8'), hashlib.sha512).hexdigest()
    return {'method': 'api_key', 'KEY': api_key, 'SIGN': sign}


request = {
    'id': int(time.time() * 1e6),
    'time': int(time.time()),
    'channel': 'options.orders',
    'event': 'subscribe',
    'payload': ["1001", "BTC_USDT-20211231-59800-C"]
}
request['auth'] = gen_sign(request['channel'], request['event'], request['time'])
print(json.dumps(request))

如果频道是私有的，例如，客户端请求需要携带身份验证信息。例如： options.orders检索用户订单更新的频道。

身份验证通过请求正文中的auth字段发送，格式如下:

名称	类型	描述
method	String	验证方式: api_key
KEY	String	apiKey的值
SIGN	String	签名结果

WebSocket认证使用与Gate APIv4 API相同的签名计算方法，即HexEncode(HMAC_SHA512(secret, signature_string)), 但有以下区别:

1. 签名字符串拼接方式： channel=<channel>&event=<event>&time=<time>, 其中 <channel>, <event>, <time> 是对应的请求信息
2. 身份验证信息在请求正文中的 auth字段中发送。

您可以登录账户获取永续合约账户的api_key和secret。

System API

提供系统状态检查，如ping/pong。

Ping/Pong

options.ping

Ping/Pong 检查服务器/客户端连接.

gateway.io websocket使用协议层ping/pong消息。服务器会发起ping操作。如果客户端没有回复，客户端将被断开。 protocol layer ping/pong (opens new window) 如果想主动检测连接状态，可以发送应用层ping消息，并接收 pong 消息。

例子：

import time
# pip install websocket_client
from websocket import create_connection

ws = create_connection("wss://op-ws.gateio.live/v4/ws")
ws.send('{"time": %d, "channel": "options.ping"}'% int(time.time()))
print(ws.recv())

操作返回 JSON 结构如下：

{
  "time": 1630566602,
  "channel": "options.pong",
  "event": "",
  "error": null,
  "result": null
}

合约行情频道

options.contract_tickers

tickers是行情的高级概述。它显示最新交易价格、最佳卖出价格、最佳买入价格、指数价格等信息。

推送类型: incremental

更新频率: 1s

客户订阅

例子：

import time
import json

# pip install websocket_client
from websocket import create_connection

ws = create_connection("wss://op-ws.gateio.live/v4/ws")
ws.send(json.dumps({
    "time": int(time.time()),
    "channel": "options.contract_tickers",
    "event": "subscribe",  # "unsubscribe" for unsubscription
    "payload": ["BTC_USDT-20211231-59800-C"]
}))
print(ws.recv())

格式:

名称	类型	必选	描述
payload	Array[String]	是	合约列表

您可以多次订阅/取消订阅。除非明确取消订阅，否则之前订阅的合同不会被覆盖。

TIP

不需要认证

服务端推送

推送示例

{
  "time": 1630576352,
  "channel": "options.contract_tickers",
  "event": "update",
  "result": {
    "name": "BTC_USDT-20211231-59800-P",
    "last_price": "11349.5",
    "mark_price": "11170.19",
    "index_price": "",
    "position_size": 993,
    "bid1_price": "10611.7",
    "bid1_size": 100,
    "ask1_price": "11728.7",
    "ask1_size": 100,
    "vega": "34.8731",
    "theta": "-72.80588",
    "rho": "-28.53331",
    "gamma": "0.00003",
    "delta": "-0.78311",
    "mark_iv": "0.86695",
    "bid_iv": "0.65481",
    "ask_iv": "0.88145",
    "leverage": "3.5541112718136"
  }
}

Result format:

名称	类型	描述
result	Object	Ticker Object
»» name	string	标的名称
»»last_price	string	最新成交价
»» mark_price	string	当前标记价格
»» index_price	string	当前指数价格
»» ask1_size	integer(int64)	最佳卖出大小
»» ask1_price	string	最佳卖出价格
»» bid1_size	integer(int64)	最佳买入大小
»» bid1_price	string	最佳买入价格
»» position_size	integer(int64)	当前多头头寸总规模
»» mark_iv	string	隐含波动率
»» bid_iv	string	买入隐含波动率
»» ask_iv	string	卖出隐含波动率
»» leverage	string	当前杠杆。公式: underlying_price / mark_price * delta
»» delta	string	Delta
»» gamma	string	Gamma

标的资产行情通道

options.ul_tickers

底层计时器显示了买入交易、卖出交易以及标的资产的指数价格。

推送类型: incremental

推送频率: 1s

客户端订阅

例子：

import time
import json

# pip install websocket_client
from websocket import create_connection

ws = create_connection("wss://op-ws.gateio.live/v4/ws")
ws.send(json.dumps({
    "time": int(time.time()),
    "channel": "options.ul_tickers",
    "event": "subscribe",  # "unsubscribe" for unsubscription
    "payload": ["BTC_USDT"]
}))
print(ws.recv())

格式:

名称	类型	必选	描述
payload	Array[String]	是	标的 列表

您可以多次订阅/取消订阅。除非明确取消订阅，否则之前订阅的合同不会被覆盖。

TIP

不需要认证

服务端推送

推送示例

{
  "time": 1630576352,
  "channel": "options.ul_tickers",
  "event": "update",
  "result": {
    "trade_put": 800,
    "trade_call": 41700,
    "index_price": "50695.43",
    "name": "BTC_USDT"
  }
}

推送参数:

字段	类型	描述
result	Object	报价对象
»name	String	标的物名称
»trade_put	integer(int64)	过去24小时内的看跌期权交易总量（单位：合约数量）
» trade_call	integer(int64)	过去24小时内的看涨期权交易总量（单位：合约数量）
» index_price	string	指数价格（报价货币）

公开合约交易频道

options.trades

该频道在gate.io发生交易时发送交易消息。它包括交易的详细信息，如价格、数量和时间。

推送类型: continuous

更新频率: real-time

客户订阅

代码示例

import time
import json

# pip install websocket_client
from websocket import create_connection

ws = create_connection("wss://op-ws.gateio.live/v4/ws")
ws.send(json.dumps({
    "time": int(time.time()),
    "channel": "options.trades",
    "event": "subscribe",  # "unsubscribe" for unsubscription
    "payload": ["BTC_USDT-20211231-59800-C"]
}))
print(ws.recv())

请求参数:

名称	类型	必选	描述
payload	Array[String]	是	合约列表

您可以多次订阅/取消订阅。除非明确取消订阅，否则先前订阅的合约不会被覆盖。

TIP

不需要认证

服务端推送

推送示例

{
  "time": 1630576356,
  "channel": "options.trades",
  "event": "update",
  "result": [
    {
      "contract": "BTC_USDT-20211231-59800-C",
      "create_time": 1639144526,
      "id": 12279,
      "price": 997.8,
      "size": -100,
      "create_time_ms": 1639144526597,
      "underlying": "BTC_USDT"
    }
  ]
}

请注意，公开交易频道只会通推送交易中的接收方（taker）。下方的私人用户交易频道将推送所有与用户相关的交易。

推送参数:

名称	类型	描述
result	Array	交易数组
»contract	String	期权合约名称
»size	int	T交易量
»id	int	交易ID
»create_time	int	交易时间（交易发生的时间）
» create_time_ms	int	交易时间，毫秒精确到小数点后3位。
»price	Float	交易价格
»underlying	String	标的物名称

公开基础交易频道

options.ul_trades

该频道在gate.io上每次发生交易时都会发送交易消息，其中包括交易的详细信息，如价格、数量和时间。这些消息涵盖了所有合约交易数据，而不仅仅是基础交易数据。

推送类型: continuous

更新频率: real-time

客户端订阅

代码示例

import time
import json

# pip install websocket_client
from websocket import create_connection

ws = create_connection("wss://op-ws.gateio.live/v4/ws")
ws.send(json.dumps({
    "time": int(time.time()),
    "channel": "options.ul_trades",
    "event": "subscribe",  # "unsubscribe" for unsubscription
    "payload": ["BTC_USDT"]
}))
print(ws.recv())

数据格式:

名称	类型	必选	描述
payload	Array[String]	是	标的 列表

您可以多次订阅/取消订阅。之前订阅的合约不会被覆盖，除非明确取消订阅。

TIP

不需要认证

服务端推送

推送示例

{
  "time": 1630576356,
  "channel": "options.ul_trades",
  "event": "update",
  "result": [
    {
      "contract": "BTC_USDT-20211231-59800-C",
      "create_time": 1639144526,
      "id": 12279,
      "price": 997.8,
      "size": -100,
      "create_time_ms": 1639144526597,
      "underlying": "BTC_USDT",
      "is_call": true
    }
  ]
}

推送参数:

名称	类型	描述
result	Array	交易数组
»contract	String	期权合约名称
»size	int	交易量
»id	int	交易ID
»create_time	int	交易时间
» create_time_ms	int	交易时间，毫秒精确到3位小数。
»price	Float	交易价格
»underlying	String	标的物名称
»is_call	Bool	是: CALL，否:PUT

基础资产价格频道

options.ul_price

该频道发送基础资产价格更新消息。

p推送类型: continuous

更新频率: real-time

客户端订阅

代码示例

import time
import json

# pip install websocket_client
from websocket import create_connection

ws = create_connection("wss://op-ws.gateio.live/v4/ws")
ws.send(json.dumps({
    "time": int(time.time()),
    "channel": "options.ul_price",
    "event": "subscribe",  # "unsubscribe" for unsubscription
    "payload": ["BTC_USDT"]
}))
print(ws.recv())

数据格式:

名称	类型	必选	描述
payload	Array[String]	是	标的 列表

您可以多次订阅/取消订阅。之前订阅的合约不会被覆盖，除非明确取消订阅。

TIP

不需要认证

服务端推送

推送示例

{
  "time": 1630576356,
  "channel": "options.ul_price",
  "event": "update",
  "result": {
    "underlying": "BTC_USDT",
    "price": 49653.24,
    "time": 1639143988,
    "time_ms": 1639143988931
  }
}

推送参数:

名称	类型	描述
result	Object	价格更新结果
»underlying	String	期权标的物名称
»price	Float	标的物价格
»time	int	更新时间（来自Gate引擎的时间）
»time_ms	int	更新时间（毫秒，来自Gate引擎的时间）

标记价格频道

options.mark_price

该频道发送标记价格更新消息。

推送类型: continuous

更新频率: real-time

客户端订阅

代码示例

import time
import json

# pip install websocket_client
from websocket import create_connection

ws = create_connection("wss://op-ws.gateio.live/v4/ws")
ws.send(json.dumps({
    "time": int(time.time()),
    "channel": "options.mark_price",
    "event": "subscribe",  # "unsubscribe" for unsubscription
    "payload": ["BTC_USDT-20211231-59800-P"]
}))
print(ws.recv())

数据格式:

名称	类型	必选	描述
payload	Array[String]	是	合约列表

您可以多次订阅/取消订阅。之前订阅的合约不会被覆盖，除非明确取消订阅。

TIP

不需要认证

服务端推送

推送示例

{
  "time": 1630576356,
  "channel": "options.mark_price",
  "event": "update",
  "result": {
    "contract": "BTC_USDT-20211231-59800-P",
    "price": 11021.27,
    "time": 1639143401,
    "time_ms": 1639143401676
  }
}

推送参数:

名称	类型	描述
result	Object	标记价格对象
»contract	String	期权合约名称
»price	Float	标的物价格
»time	int	更新时间
»time_ms	int	更新时间（毫秒）

结算频道

options.settlements

该频道发送合约结算更新消息。

推送类型: continuous

更新频率: real-time

客户端订阅

代码示例

import time
import json

# pip install websocket_client
from websocket import create_connection

ws = create_connection("wss://op-ws.gateio.live/v4/ws")
ws.send(json.dumps({
    "time": int(time.time()),
    "channel": "options.settlements",
    "event": "subscribe",  # "unsubscribe" for unsubscription
    "payload": ["BTC_USDT-20211130-55000-P"]
}))
print(ws.recv())

数据格式:

名称	类型	必选	描述
payload	Array[String]	是	合约列表

您可以多次订阅/取消订阅。之前订阅的合约不会被覆盖，除非明确取消订阅。

TIP

不需要认证

服务端推送

推送示例

{
  "time": 1630576356,
  "channel": "options.settlements",
  "event": "update",
  "result": {
    "contract": "BTC_USDT-20211130-55000-P",
    "orderbook_id": 2,
    "position_size": 1,
    "profit": 0.5,
    "settle_price": 70000,
    "strike_price": 65000,
    "tag": "WEEK",
    "trade_id": 1,
    "trade_size": 1,
    "underlying": "BTC_USDT",
    "time": 1639051907,
    "time_ms": 1639051907000
  }
}

推送参数:

名称	类型	描述
result	Object	结算对象
» time	Int	配置的最后更改时间（结算时间）
» time_ms	Int	配置的最后更改时间（毫秒）
» contract	string	合约名称
» profit	string	每个大小的结算利润
» settle_price	string	结算价格
» strike_price	Int	行权价格
» orderbook_id	Int	当前订单簿ID
» position_size	Int	当前总多头持仓规模
» tag	String	结算标签
» trade_id	int	当前交易ID
» trade_size	Int	历史累计交易规模
» underlying	String	标的物名称

合约频道

options.contracts

该频道发送合约更新消息。

推送类型: continuous

更新频率: real-time

客户端订阅

代码示例

import time
import json

# pip install websocket_client
from websocket import create_connection

ws = create_connection("wss://op-ws.gateio.live/v4/ws")
ws.send(json.dumps({
    "time": int(time.time()),
    "channel": "options.contracts",
    "event": "subscribe",  # "unsubscribe" for unsubscription
    "payload": ["BTC_USDT-20211130-50000-P"]
}))
print(ws.recv())

数据格式:

名称	类型	必选	描述
payload	Array[String]	是	合约列表

您可以多次订阅/取消订阅。之前订阅的合约不会被覆盖，除非明确取消订阅。

TIP

不需要认证

服务端推送

推送示例

{
  "time": 1630576356,
  "channel": "options.contracts",
  "event": "update",
  "result": {
    "contract": "BTC_USDT-20211130-50000-P",
    "create_time": 1637917026,
    "expiration_time": 1638230400,
    "init_margin_high": 0.15,
    "init_margin_low": 0.1,
    "is_call": false,
    "maint_margin_base": 0.075,
    "maker_fee_rate": 0.0004,
    "mark_price_round": 0.1,
    "min_balance_short": 0.5,
    "min_order_margin": 0.1,
    "multiplier": 0.0001,
    "order_price_deviate": 0,
    "order_price_round": 0.1,
    "order_size_max": 1,
    "order_size_min": 10,
    "orders_limit": 100000,
    "ref_discount_rate": 0.1,
    "ref_rebate_rate": 0,
    "strike_price": 50000,
    "tag": "WEEK",
    "taker_fee_rate": 0.0004,
    "underlying": "BTC_USDT",
    "time": 1639051907,
    "time_ms": 1639051907000
  }
}

推送参数:

名称	类型	描述
result	Object	合约对象
» contract	string	期权合约
» tag	string	标记
» create_time	integer(int64)	合约创建时间
» expiration_time	integer(int64)	合约到期时间
» init_margin_high	float	初始头寸保证金上限
» init_margin_low	float	初始头寸保证金下限
» is_call	boolean	true 表示看涨期权，而 false 表示看跌期权
» maint_margin_base	float	头寸维持保证金基数
» multiplier	string	用于从开票货币转换为结算货币的乘数
» underlying	string	标的
» maker_fee_rate	string	Maker手续费率，负值表示返点
» taker_fee_rate	string	Taker手续费率
» order_price_round	string	最小订单价格增量
» mark_price_round	string	M最小标记价格增量
» order_size_min	integer(int64)	合约允许的最小订单规模
» order_size_max	integer(int64)	合约允许的最大订单规模
» order_price_deviate	string	订单价格与当前指数价格之间的偏差。如果订单价格表示为order_price，则必须满足以下条件：abs(order_price - mark_price) <= mark_price * order_price_deviate
» ref_discount_rate	string	推荐费率折扣
» ref_rebate_rate	string	推荐人佣金比例
» orders_limit	integer	最大开放订单数量
» min_balance_short	float	未完成订单的余额保证金
» min_order_margin	Float	未完成订单的订单保证金
» strike_price	float	行权价格
» time	Int64	消息创建时间
» time_ms	Int64	消息创建时间（毫秒）

合约K线频道

options.contract_candlesticks

提供了一种访问K线信息的方式。

推送类型: incremental

更新频率: 2s

客户端订阅

如果在 contract 前加上 mark_，将订阅合约的标记价格K线；如果在 contract 前加上 index_，将订阅指数价格K线。

import time
import json

# pip install websocket_client
from websocket import create_connection

ws = create_connection("wss://op-ws.gateio.live/v4/ws")
ws.send(json.dumps({
    "time": int(time.time()),
    "channel": "options.contract_candlesticks",
    "event": "subscribe",  # "unsubscribe" for unsubscription
    "payload": ["10s", "BTC_USDT-20211231-59800-C"]
}))
print(ws.recv())

数据格式:

名称	类型	必选	描述
payload	Array[String]	是	订阅参数。从左到右，interval, cp
» interval	String	是	K线数据点间隔
» contract	String	是	期权合约名称

Enumerated Values

属性	值
interval	10s
interval	1m
interval	5m
interval	15m
interval	30m
interval	1h
interval	4h
interval	8h
interval	1d
interval	7d

要订阅多个合约或使用不同的间隔，只需发送多个具有不同参数的订阅请求。

TIP

不需要认证

服务端推送

推送示例

{
  "time": 1630650451,
  "channel": "options.contract_candlesticks",
  "event": "update",
  "result": [
    {
      "t": 1639039260,
      "v": 100,
      "c": "1041.4",
      "h": "1041.4",
      "l": "1041.4",
      "o": "1041.4",
      "a": "0",
      "n": "10s_BTC_USDT-20211231-59800-C"
    }
  ]
}

数据结构:

名称	类型	描述
result	Array	K线数据数组
t	Integer	以秒为单位的Unix时间戳
o	String	开盘价
c	String	收盘价
h	String	最高价
l	String	最低价
v	Integer	总成交量
a	String	数量
n	String	订阅的名称，格式为 <interval>_<cp>

K线频道

options.ul_candlesticks

提供了一种访问图表下层K线信息的方式。

推送类型: continuous

更新频率: 2s

客户端订阅

如果在contract前加上mark_，将订阅合约的标记价格K线；如果在contract前加上index_，将订阅指数价格K线

import time
import json

# pip install websocket_client
from websocket import create_connection

ws = create_connection("wss://op-ws.gateio.live/v4/ws")
ws.send(json.dumps({
    "time": int(time.time()),
    "channel": "options.ul_candlesticks",
    "event": "subscribe",  # "unsubscribe" for unsubscription
    "payload": ["10s", "BTC_USDT"]
}))
print(ws.recv())

数据格式:

名称	类型	必选	描述
payload	Array[String]	是	订阅参数。从左到右， interval, cp
» interval	String	是	K线数据点间隔
» contract	String	是	期权合约名称

枚举

属性	值
interval	10s
interval	1m
interval	5m
interval	15m
interval	30m
interval	1h
interval	4h
interval	8h
interval	1d
interval	7d

要订阅多个合约或使用不同的时间间隔，只需发送多个具有不同参数的订阅请求。

TIP

不需要认证。

服务端推送

推送示例

{
  "time": 1630650451,
  "channel": "options.ul_candlesticks",
  "event": "update",
  "result": [
    {
      "t": 1639039260,
      "v": 100,
      "c": "1041.4",
      "h": "1041.4",
      "l": "1041.4",
      "o": "1041.4",
      "a": "0",
      "n": "10s_BTC_USDT"
    }
  ]
}

推送参数:

名称	类型	描述
result	Array	k线数组
t	Integer	以秒为单位的UNIX时间戳
o	String	开盘价
c	String	收盘价
h	String	最高价
l	String	最低价
v	Integer	总成交量
a	String	数量
n	String	订阅的名称，格式为 <interval>_<cp>

订单簿频道

order_book 通道允许您跟踪 gate.io 订单簿深度的状态。它以价格聚合的方式提供，可自定义精度。

有三个不同的订单簿订阅频道：

• options.order_book

传统的频道，使用all来推送完整的有限级别订单簿，使用update来发送每个订单簿变动事件。

• options.book_ticker

  实时推送最佳买入和卖出价格。

• options.order_book_update

  按照用户指定的更新频率推送订单簿变动。

WARNING

不建议使用options.order_book，而是使用options.order_book_update，这样可以提供更及时的更新，并减少网络流量。

如何维护本地订单簿:

1. 订阅options.order_book_update，指定级别和更新频率。例如，["BTC_USDT-20211130-50000-C", "1000ms", "10"]表示每1秒推送BTC_USDT订单簿中前10个级别的更新。
2. 缓存WebSocket推送。每个推送使用U和u来告知自上次推送以来的第一个和最后一个更新ID。
3. 使用REST API检索基础订单簿，并确保订单簿ID被记录下来（在下面称为baseID） 例如. https://api.gateio.ws/api/v4/options/order_book?contract=BTC_USDT-20211130-50000-C&limit=10&with_id=true 检索BTC_USDT的10级基础订单簿
4. 遍历缓存的WebSocket推送，找到第一个包含baseID的推送，即U <= baseID + 1且u >= baseID + 1，然后从该推送开始消费。请注意，推送中的数量都是绝对值。使用它们来替换相应价格的原始数量。如果数量等于0，则从订单簿中删除该价格。
5. 转储所有满足u < baseID+1的推送。如果baseID+1 < 第一个推送的U，则表示当前基础订单簿落后于推送。从步骤3开始获取更新的基础订单簿。
6. 如果找到任何满足U > baseID+1的后续推送，意味着有一些更新丢失了。从步骤3中重新构建本地订单簿。

您可以在以下示例应用程序中找到实现上述方法的示例 SDK GitHub repository (opens new window)

最优买卖价

options.book_ticker

推送类型: continuous

更新频率: real-time

客户端订阅

代码示例

import time
import json

# pip install websocket_client
from websocket import create_connection

ws = create_connection("wss://op-ws.gateio.live/v4/ws")
ws.send(json.dumps({
    "time": int(time.time()),
    "channel": "options.book_ticker",
    "event": "subscribe",  # "unsubscribe" for unsubscription
    "payload": ["BTC_USDT-20211130-50000-C"]
}))
print(ws.recv())

数据结构:

名称	类型	必选	描述
payload	Array[String]	是	合约列表

您可以多次订阅/取消订阅。之前订阅的合约不会被覆盖，除非明确取消订阅。

TIP

不需要认证

服务端推送

如果a是空字符串，则表示没有卖单；如果b是空字符串，则表示没有买单。

推送示例

{
  "time": 1630650452,
  "channel": "options.book_ticker",
  "event": "update",
  "result": {
    "t": 1615366379123,
    "u": 2517661076,
    "s": "BTC_USDT-20211130-50000-C",
    "b": "54696.6",
    "B": 37000,
    "a": "54696.7",
    "A": 47061
  }
}

推送参数:

名称	类型	描述
result	object	订单簿行情对象
» t	Integer	订单簿更新时间（毫秒）
» u	String	订单簿更新ID
» s	Integer	合约名称
» b	String	最佳买入价格。如果没有买单，则为空字符串。
» B	Integer	最佳买入数量。如果没有买单，则为0。
» a	String	最佳卖出价格。如果没有卖单，则为空字符串。
» A	Integer	最佳卖出数量。如果没有卖单，则为0。

深度增量更新频道

options.order_book_update

推送类型: continuous

更新频率: 100ms

客户端订阅

代码示例

import time
import json

# pip install websocket_client
from websocket import create_connection

ws = create_connection("wss://op-ws.gateio.live/v4/ws")
ws.send(json.dumps({
    "time": int(time.time()),
    "channel": "options.order_book_update",
    "event": "subscribe",  # "unsubscribe" for unsubscription
    "payload": ["BTC_USDT-20211130-50000-C", "1000ms", "20"]
}))
print(ws.recv())

数据结构:

名称	类型	必选	描述
payload	Array[String]	是	订阅参数，从左到右， contract, interval
» contract	String	是	合约名称
» interval	String	是	推送更新速度
» level	String	否	感兴趣的可选级别。只有在其中的更新才会被推送。

枚举

属性	值
interval	100ms
interval	1000ms

属性	值
level	5
level	10
level	20
level	50

您可以多次订阅/取消订阅。之前订阅的合约不会被覆盖，除非明确取消订阅。

TIP

不需要认证。

服务端推送

推送示例

{
  "time": 1630650445,
  "channel": "options.order_book_update",
  "event": "update",
  "result": {
    "t": 1615366381417,
    "s": "BTC_USDT-20211130-50000-C",
    "U": 2517661101,
    "u": 2517661113,
    "b": [
      {
        "p": "54672.1",
        "s": 0
      },
      {
        "p": "54664.5",
        "s": 58794
      }
    ],
    "a": [
      {
        "p": "54743.6",
        "s": 0
      },
      {
        "p": "54742",
        "s": 95
      }
    ]
  }
}

推送参数:

名称	类型	描述
result	object	自上次更新以来的卖出和买入变动。
» t	Integer	订单簿更新时间（毫秒）。
» s	Integer	合约名称
» U	Integer	自上次更新以来的首个订单簿更新ID。
» u	Integer	自上次更新以来的最后一个订单簿更新ID。
» b	String	变更的买单
»» p	String	变更价格
»» s	String	变更后的绝对数量值。如果为0，则从订单簿中移除该价格
» a	String	变更的买单
»» p	String	变更的价格
»» s	String	变更后的绝对数量值。如果为0，则从订单簿中移除该价格

深度全量更新频道

options.order_book

推送类型: continuous

更新频率: 250ms

客户端订阅

代码示例

import time
import json

# pip install websocket_client
from websocket import create_connection

ws = create_connection("wss://op-ws.gateio.live/v4/ws")
ws.send(json.dumps({
    "time": int(time.time()),
    "channel": "options.order_book",
    "event": "subscribe",  # "unsubscribe" for unsubscription
    "payload": ["BTC_USDT-20211130-50000-C", "20", "0"]
}))
print(ws.recv())

数据结构:

名称	类型	必选	描述
contract	String	是	合约名称
limit	String	是	法定限制：50，20，10，5，1。
accuracy	String	是	目前只支持"0"。

枚举

属性	值
level	5
level	10
level	20

属性	值
accuracy	0

您可以多次订阅/取消订阅。之前订阅的合约除非明确取消订阅，否则不会被覆盖。

TIP

不需要认证

服务端推送

推送示例

{
  "time": 1630650445,
  "channel": "options.order_book",
  "event": "all",
  "result": {
    "t": 1541500161123,
    "contract": "BTC_USDT-20211130-50000-C",
    "id": 93973511,
    "asks": [
      {
        "p": "97.1",
        "s": 2245
      },
      {
        "p": "97.1",
        "s": 2245
      }
    ],
    "bids": [
      {
        "p": "97.1",
        "s": 2245
      },
      {
        "p": "97.1",
        "s": 2245
      }
    ]
  }
}

Or

{
  "channel": "options.order_book",
  "event": "update",
  "time": 1630650445,
  "result": [
    {
      "p": "49525.6",
      "s": 7726,
      "c": "BTC_USDT-20211130-50000-C",
      "id": 93973511
    }
  ]
}

推送参数:

名称	类型	描述
result	Array	结果
»c	String	期权合约名称
»s	Integer	这个数字是最终值，计算得出的值。正数表示多头（买入），负数表示空头（卖出）。
»p	String	订单簿价格
»id	Integer	价格订单簿ID

订单频道

options.orders

提供了一种接收用户已关闭订单的方式。

推送类型: continuous

更新频率: real-time

客户端订阅

代码示例

import time
import json

# pip install websocket_client
from websocket import create_connection

ws = create_connection("wss://op-ws.gateio.live/v4/ws")
request = {
    "time": int(time.time()),
    "channel": "options.orders",
    "event": "subscribe",  # "unsubscribe" for unsubscription
    "payload": ["1001","BTC_USDT-20211130-65000-C"]
}
# refer to Authentication section for gen_sign implementation
request['auth'] = gen_sign(request['channel'], request['event'], request['time'])
ws.send(json.dumps(request))
print(ws.recv())

数据结构:

名称	类型	必选	描述
user id	String	是	用户 id
contract	String	是	合于期权名称

您可以多次订阅/取消订阅。之前订阅的合约除非明确取消订阅，否则不会被覆盖。

如果您想订阅所有合约中的所有订单更新，您可以在合约列表中包含!all。

WARNING

需要认证

服务端推送

推送示例

{
  "time": 1630654851,
  "channel": "options.orders",
  "event": "update",
  "result": [
    {
      "contract": "BTC_USDT-20211130-65000-C",
      "create_time": 1637897000,
      "fill_price": 0,
      "finish_as": "cancelled",
      "iceberg": 0,
      "id": 106,
      "is_close": false,
      "is_liq": false,
      "is_reduce_only": false,
      "left": -10,
      "mkfr": 0.0004,
      "price": 15000,
      "refr": 0,
      "refu": 0,
      "size": -10,
      "status": "finished",
      "text": "web",
      "tif": "gtc",
      "tkfr": 0.0004,
      "underlying": "BTC_USDT",
      "user": "9xxx",
      "time": 1639051907,
      "time_ms": 1639051907000
    }
  ]
}

已更新的订单列表。请注意，可能会在一条推送中更新多个合约的订单。

推送参数:

名称	类型	描述
result	Array[Object]	更新的订单列表
» id	integer(int64)	期权订单 ID
» user	String	用户 ID
» create_time	integer(int64)	订单创建时间
» finish_as	string	订单如何完成：- filled：全部成交 - cancelled：手动取消 - liquidated：因清算而取消 - ioc：即时生效订单，立即完成 - auto_deleveraged：被自动减仓完成 - reduce_only：因为设置了"只减仓"，所以取消了订单 - position_closed：因为持仓平仓而取消
» status	string	订单状态 - open: 等待成交 - finished: 完成
» contract	string	合约名称
» size	integer(int64)	订单大小。使用正数表示买入报价，使用负数表示卖出报价。
» iceberg	integer(int64)	显示冰山订单的显示大小。非冰山订单显示大小为0。请注意，您需要支付隐藏数量的吃单方手续费。
» price	string	订单价格。若以tif设置为ioc的市价单，则价格为0。
» is_close	boolean	该订单是否用于平仓操作。
» is_reduce_only	boolean	该订单是否为"只减仓"订单。
» is_liq	boolean	该订单是否用于清算操作。
» tif	string	有效期限 - gtc: 长期有效 - ioc: 即时成交或取消, 仅吃单 - poc: 待定或已取消，仅减仓
» left	integer(int64)	待交易的剩余数量
» fill_price	string	订单成交价格
» tkfr	Float	吃单费用
» mkfr	Float	挂单费用
» refu	integer	推荐人 ID
» refr	Float	推荐人返利
» underlying	String	标的物名称
» time	int	创建时间
» time_ms	Int	创建时间（毫秒）

用户交易频道

options.usertrades

提供了一种接收用户交易的方式。

推送类型: continuous

更新频率: real-time

客户端订阅

代码示例

import time
import json

# pip install websocket_client
from websocket import create_connection

ws = create_connection("wss://op-ws.gateio.live/v4/ws")
request = {
    "time": int(time.time()),
    "channel": "options.usertrades",
    "event": "subscribe",  # "unsubscribe" for unsubscription
    "payload": ["1001", "BTC_USDT-20211216-44800-C"]
}
# refer to Authentication section for gen_sign implementation
request['auth'] = gen_sign(request['channel'], request['event'], request['time'])
ws.send(json.dumps(request))
print(ws.recv())

数据格式:

名称	类型	必选	描述
user id	String	是	用户 id
contract	String	是	期权合约名称

您可以多次订阅/取消订阅。之前订阅的合约除非明确取消订阅，否则不会被覆盖。

如果您想订阅所有合约中的用户交易更新，可以在合约列表中包含!all。

WARNING

需要认证

服务端推送

推送示例

{
  "time": 1639144214,
  "channel": "options.usertrades",
  "event": "update",
  "result": [
    {
      "id": "1",
      "underlying": "BTC_USDT",
      "order": "557940",
      "contract": "BTC_USDT-20211216-44800-C",
      "create_time": 1639144214,
      "create_time_ms": 1639144214583,
      "price": "4999",
      "role": "taker",
      "size": -1
    }
  ]
}

已更新的用户交易列表。请注意，可能会在一条推送中更新多个合约的交易记录。

推送参数:

名称	类型	描述
result	Array	结果
»contract	String	期权合约名称
»create_time	Integer	创建时间
»create_time_ms	Integer	创建时间（毫秒）
»id	String	交易 id
»order	String	订单 Id
»price	String	交易价格
»size	Integer	交易量
»role	String	用户角色（挂单方/吃单方）

枚举

属性	值
role	maker
role	taker

清算频道

options.liquidates

提供了一种接收用户清算信息的方式。

推送类型: continuous

更新频率: real-time

客户端订阅

代码示例

import time
import json

# pip install websocket_client
from websocket import create_connection

ws = create_connection("wss://op-ws.gateio.live/v4/ws")
request = {
    "time": int(time.time()),
    "channel": "options.liquidates",
    "event": "subscribe",  # "unsubscribe" for unsubscription
    "payload": ["1001", "BTC_USDT-20211130-50000-C"]
}
# refer to Authentication section for gen_sign implementation
request['auth'] = gen_sign(request['channel'], request['event'], request['time'])
ws.send(json.dumps(request))
print(ws.recv())

数据格式:

名称	类型	必选	描述
user id	String	是	用户 id
contract	String	是	期权合约名称

您可以多次订阅/取消订阅。之前订阅的合约除非明确取消订阅，否则不会被覆盖。

WARNING

需要认证

服务端推送

推送示例

{
  "channel": "options.liquidates",
  "event": "update",
  "time": 1630654851,
  "result": [
    {
      "user": "1xxxx",
      "init_margin": 1190,
      "maint_margin": 1042.5,
      "order_margin": 0,
      "time": 1639051907,
      "time_ms": 1639051907000
    }
  ]
}

Result format:

名称	类型	描述
result	Array	结果
» time	int64	平仓时间
» time	int64	平仓时间（毫秒）
» user	string	用户 id
» init_margin	float	初始持仓保证金
» maint_margin	float	持仓维持保证金
» order_margin	float	未完成订单的委托保证金

用户结算频道

options.user_settlements

提供了一种接收用户结算信息的方式。

推送类型: continuous

更新频率: real-time

客户端订阅

代码示例

import time
import json

# pip install websocket_client
from websocket import create_connection

ws = create_connection("wss://op-ws.gateio.live/v4/ws")
request = {
    "time": int(time.time()),
    "channel": "options.user_settlements",
    "event": "subscribe",  # "unsubscribe" for unsubscription
    "payload": ["1001", "BTC_USDT-20211130-65000-C"]
}
# refer to Authentication section for gen_sign implementation
request['auth'] = gen_sign(request['channel'], request['event'], request['time'])
ws.send(json.dumps(request))
print(ws.recv())

数据格式:

名称	类型	必选	描述
user id	String	是	用户 id
contract	String	是	期权合约名称

您可以多次订阅/取消订阅。之前订阅的合约除非明确取消订阅，否则不会被覆盖。

WARNING

需要认证

服务端推送

推送示例

{
  "channel": "options.user_settlements",
  "event": "update",
  "time": 1639051907,
  "result": [
    {
      "contract": "BTC_USDT-20211130-65000-C",
      "realised_pnl": -13.028,
      "settle_price": 70000,
      "settle_profit": 5,
      "size": 10,
      "strike_price": 65000,
      "underlying": "BTC_USDT",
      "user": "9xxx",
      "time": 1639051907,
      "time_ms": 1639051907000
    }
  ]
}

名称	类型	描述
result	Array	结果
»realised_pnl	Float	实现盈亏
»settle_price	Float	结算价格
»settle_profit	Integer	每份结算利润
»strike_price	float	行权价格
»underlying	string	标的物名称
»size	Integer	交易量
»time	Integer	结算时间
»time_ms	Integer	结算时间（毫秒）
»user	String	用户 id
»contract	String	期权合约名称

持仓平仓频道

options.position_closes

提供了一种接收用户平仓信息的方式。

推送类型: continuous

更新频率: real-time

客户端订阅

代码示例

import time
import json

# pip install websocket_client
from websocket import create_connection

ws = create_connection("wss://op-ws.gateio.live/v4/ws")
request = {
    "time": int(time.time()),
    "channel": "options.position_closes",
    "event": "subscribe",  # "unsubscribe" for unsubscription
    "payload": ["1001", "BTC_USDT-20211130-50000-C"]
}
# refer to Authentication section for gen_sign implementation
request['auth'] = gen_sign(request['channel'], request['event'], request['time'])
ws.send(json.dumps(request))
print(ws.recv())

数据格式:

名称	类型	必选	描述
user id	String	是	用户 id
contract	String	是	期权合约名称

您可以多次订阅/取消订阅。之前订阅的合约除非明确取消订阅，否则不会被覆盖。

WARNING

需要认证

服务端推送

推送示例

{
  "channel": "options.position_closes",
  "event": "update",
  "time": 1630654851,
  "result": [
    {
      "contract": "BTC_USDT-20211130-50000-C",
      "pnl": -0.0056,
      "settle_size": 0,
      "side": "long",
      "text": "web",
      "underlying": "BTC_USDT",
      "user": "11xxxxx",
      "time": 1639051907,
      "time_ms": 1639051907000
    }
  ]
}

推送参数:

名称	类型	描述
result	Array	数组结果
»contract	String	期权合约名称
»pnl	Float	利润与损失
»side	String	持仓方向，多头或空头
»text	String	平仓订单的文本
»time	Integer	平仓时间
»time_ms	Integer	平仓时间（毫秒）
»user	String	用户 id
»underlying	string	标的唔名称

枚举值

属性	值
side	long
side	Short

余额频道

options.balances

提供一种接收用户余额信息的方式。

推送类型: continuous

更新频率: real-time

客户端订阅

代码示例

import json
import time
from websocket import create_connection

ws = create_connection("wss://op-ws.gateio.live/v4/ws")
request = {
    "time": int(time.time()),
    "channel": "options.balances",
    "event": "subscribe",  # "unsubscribe" for unsubscription
    "payload": ["1001"]
}
# refer to Authentication section for gen_sign implementation
request['auth'] = gen_sign(request['channel'], request['event'], request['time'])
ws.send(json.dumps(request))
print(ws.recv())

数据格式:

名称	类型	必选	描述
user id	String	是	用户 id

WARNING

需要认证

服务端推送

推送示例

{
  "channel": "options.balances",
  "event": "update",
  "time": 1630654851,
  "result": [
    {
      "balance": 60.79009,
      "change": -0.5,
      "text": "BTC_USDT-20211130-55000-P",
      "type": "set",
      "user": "11xxxx",
      "time": 1639051907,
      "time_ms": 1639051907000
    }
  ]
}

推送参数:

名称	类型	描述
result	Array	结果对象数组
»balance	Float	变化后的余额
»change	Float	变化大小
»text	String	余额变动消息
»time	Integer	余额变动时间
»time_ms	Integer	余额变动时间（毫秒）
»type	String	类型
»user	String	用户 id

持仓频道

options.positions

提供了一种接收用户持仓信息的方式。

推送类型: continuous

更新频率: real-time

客户端订阅

代码示例

import json
import time
from websocket import create_connection

ws = create_connection("wss://op-ws.gateio.live/v4/ws")
request = {
    "time": int(time.time()),
    "channel": "options.positions",
    "event": "subscribe",  # "unsubscribe" for unsubscription
    "payload": ["1001", "BTC_USDT-20211130-65000-C"]
}
# refer to Authentication section for gen_sign implementation
request['auth'] = gen_sign(request['channel'], request['event'], request['time'])
ws.send(json.dumps(request))
print(ws.recv())

数据格式:

名称	类型	必选	描述
user id	String	是	用户 id
contract	String	是	期权合约名称

您可以多次订阅/取消订阅。之前订阅的合约除非明确取消订阅，否则不会被覆盖。

WARNING

需要认证

服务端推送

推送示例

{
  "time": 1630654851,
  "channel": "options.positions",
  "event": "update",
  "error": null,
  "result": [
    {
      "entry_price": 0,
      "realised_pnl": -13.028,
      "size": 0,
      "contract": "BTC_USDT-20211130-65000-C",
      "user": "9010",
      "time": 1639051907,
      "time_ms": 1639051907000
    }
  ]
}

推送参数:

名称	类型	描述
result	Array	Array of objects
»contract	String	期权合约名称
»entry_price	Float	入场价格
»realised_pnl	Float	已实现盈亏
»size	Integer	合约大小
»time	Integer	更新的UNIX时间戳
»time_ms	Integer	以毫秒为单位的更新UNIX时间戳
»user	String	用户 id