# 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.usmartsg.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
Authentication
Heartbeat maintenance
Subscribe quotes/unsubscribe
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
Subscription requests are limited to a maximum of 10 topics per second
The subscription request limit limits the maximum number of subscription topics to 10
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 |