uSMART

# Quote push access protocol

# Imprint

Modification time Version Modify description
2019.12.30 v1.0.0 Initial document
2020.01.19 v1.0.0 Added orderbook push instructions
2020.02.26 v1.0.0 New fields for real-time quotes

# Brief description

uSMART Open Platform maintains a long connection with the client through websocket, thereby providing real-time quotes push service, this document is the websocket long connection access guide.

# 1. Access address

  • Production environment access address wss://open-hz.yxzq.com:8443/wss/v1

  • Test environment access address

wss://open-hz-uat.yxzq.com/wss/v1

  • Access protocol

websocket

  • Data interaction format

json

# 2. Access steps

  1. Authentication

  2. Heartbeat maintenance

  3. Subscribe quotes/unsubscribe

  4. Receive pushes

# 2.1 Authentication

Client authentication request

{
    "op": "auth",
    "ts": 1575531634,  //unix 时间戳
    "reqId": 666666,  //unix 请求序列号，
    "accessToken": "4F65x5A2bLyMWVQj3Aqp+B4w+ivaA7n5Oi2SuYtCJ9o=" // 登录成功之后返回的token
}

Server authentication reply

{
    "op": "auth",
    "ts": 1575531634,  //unix 时间戳
    "reqId": 666666,  //unix 请求序列号
    "code": 0,  //状态码 成功
    "msg": "success"  //状态描述
}

# 2.2 Heartbeat maintenance

Server-side ping

{
    "op": "ping",
    "ts": 1575531634,  //unix 时间戳
    "reqId": 666666  //unix 请求序列号
}

Client-side pong

{
    "op": "pong",
    "ts": 1575531634,  //unix 时间戳
    "reqId": 666666  //unix 请求序列号
}

# 2.3 Quotes subscription

Client-sidesubscription requests

{
    "op": "sub",
    "ts": 1575531634,  //unix 时间戳
    "reqId": 666666,  //unix 请求序列号
    "topiclist": ["$type.$market.$code",...] // 示例:["rt.hk.00700", "tk.hk.00700","ob.hk.00700"]
}

Server-side subscription response

{
    "op": "sub",
    "ts": 1575531634,  //unix 时间戳
    "reqId": 666666,  //unix 请求序列号
    "code": 0,  //状态码 成功
    "msg": "success"  //状态描述
}

# 2.4 Cancel subscription

Client-side cancel subscription request

{
    "op": "unsub",
    "ts": 1575531634,  //unix 时间戳
    "reqId": 666666,  //unix 请求序列号
    "topiclist": ["$type.$market.$code",...] // 示例:["rt.hk.00700", "tk.hk.00700","ob.hk.00700"]
}

Server-side cancel subscription response

{
    "op": "unsub",
    "ts": 1575531634,  //unix 时间戳
    "reqId": 666666,  //unix 请求序列号
    "code": 0,  //状态码 成功
    "msg": "success"  //状态描述
}

# 2.5 Quotes push

After successful subscription, the server will actively push the real-time quotes

{
    "op": "update",
    "topic": "$type.$market.$code", //内容所属topic
    "data": {}  //更新内容，base64编码，根据实时，tick等具体业务定
}

# 3. Push data structure

# 3.1 Real-time quote

Real-time quotes response field descriptions

Parameter name Type Description
market string Market identity
symbol string Stock code
latestPrice double Latest price
open double Openning price
low double Lowest price
close double Closing price
high double Highest price
latestTime int64 Latest quote time
preClose double Yesterday's closing price
turnOver double Total turnover
volume int64 Total volume
bidPrice double Bid price
bidSize int64 Bid size
askPrice double Ask price
askSize int64 Ask size
upLimit double Up limit price
downLimit double Down limit price
qtyUnit double Real-time spreads
trdStatus int32 Stock status, as detailed in the description of the status of the securities below

Example of a real-time response:

{
    "market": "sz",
    "symbol": "000001",
    "latestTime": 20191226103118000,
    "latestPrice": 16.43,
    "open": 16.34,
    "close": 0,
    "high": 16.48,
    "low": 16.34,
    "preClose": 16.3,
    "volume": 11858618,
    "turnOver": 194666461.75,
    "askPrice": 16.43,
    "askSize": 8103,
    "bidPrice": 16.42,
    "bidSize": 48300,
    "trdStatus": 6
}

# 3.2 Tick quote

Tick Response Description

Parameter name Type Description
seq int32 Quote sequence number
time int64 Quote time
price double Price
volume double Volume
direction double Directions, 0: default，1：buy，2：sell
trdType int64 Item-by-item entries type，unique to Hong Kong stocks, the corresponding relationship between the value and type is：4:P 22:M 100:Y 101:X 102:D 103:U

Tick response example

{
    "market": "sz",
    "symbol": "000002",
    "seq": 1,
    "time": 20191226103118000,
    "price": 31.25,
    "volume": 4600,
    "direction": 2,
    "trdType": 0
}

# 3.3 Orderbook

Orderbook Description

Parameter name Type Description
bidPrice double Bid price
bidVolume int64 Bid volume
bidOrderCount int64 Nnumber of bid order
askPrice double Ask price
askVolume int64 Ask volume
askOrderCount int64 Number of ask order

Response example:


[
    {
        "bidPrice": 9.31,
        "bidVolume": 12000,
        "bidOrderCount": 5,
        "askPrice": 9.32,
        "askVolume": 21600,
        "askOrderCount": 3
    }
]

# 4. Common error code definitions

Value Description
0 successful
800001 Authentication failed
800002 Parameter error
800003 Internal error
800004 Subscription/Cancel subscription topic exceeded limit
800005 Illegal Request
800006 Token in use
800007 Topic format error
800008 Token is occupied

# 5.API limitations

  1. Subscription requests are limited to a maximum of 10 topics per second

  2. The subscription request limit limits the maximum number of subscription topics to 10

  3. Cancel subscription limits the ability to unsubscribe up to 10 topics per second

# 6.

Market identity

Value Description
hk Hongkong Market
us U.S. Market
sh Shanghai Market
sz Shenzhen Market

# 7. Quotes Type

Value Description
rt Real-time quote
tk tick
ob orderbook

# 8. Description of the stock status

Value Description
0 Unknown
1 Suspension
2 Hongkong stock volatility is interrupted
3 Not listed
4 Suspension of Listing (A shares)
5 Delisting
6 In the trading

← Trading Account Open API →