uSMART

# Basic Quotes Open API

# Imprint

Date Version Description
2019-12-27 v1.0.0 Creation
2019-02-24 v1.0.1 New fields have been added to the Basic Information API
2019-02-27 v1.0.1 Add API restriction description

# Overview

The uSMART Securities Open Platform provides most of the services through the HTTP API, and most of the API functions are accessed through simple HTTP POST requests. The API about the basic quotes are called through the Unified API.

# API request restriction

# Whitelist restrictions:

Client IP need to be whitelisted for authorization, and unauthorized requests are denied access

# Request frequency limit:

  • High-frequency requests
API name One-minute request limit
Real-time quotes API 120
Tick API 120
Candlestick API 120
Deal by lot API 120
Market status API 120
Order API 120
  • Low-frequency requests
API name One-minute request limit
Stock Basic Information API 20

# Unified domain name

  • Official domain name： https://open-hz.usmartsg.com:8443
  • Test domain name： https://open-hz-uat.yxzq.com

If during the test debugging phase, all the following API addresses https://open-hz.usmartsg.com:8443will be change to https://open-hz-uat.yxzq.com。

# 1. Unified HTTP header

# Brief description

The API of the basic quotes, each call must carry some necessary HTTP headers, these HTTP headers and their functions are as follows:

parameter name Required Type Description
Content-Type Yes string Must contain：application/json
Authorization Yes string The authentication token returned after successful login
X-Channel Yes string Channel identity
X-Lang Yes int Language type：The default is Simplified Chinese，1：Simplified Chinese，2：Traditional Chinese，3：English
X-Request-Id Yes string The length is 19 digits and must be used only for idempotent weight protection. It is recommended to use the distributed Snowflake algorithm to generate.
X-Time Yes string unix time stamp
X-Sign Yes string Signature

# Signature description

X-Sign generation rules：

  1. Authorization, X-Channel, X-Lang, X-Request-Id, X-Time header fields and body content are spliced sequentially into the rowContent

  2. MD5withRSA algorithm is used to abstract rowContent and encrypt it to generate cipherContent

  3. Then use safeBase64 encoding to generate X-Sign for cipherContent

# 2. Market status API

# Brief description

Used to obtain market status information

# Request URL

  • https://open-hz.usmartsg.com:8443/quotes-openservice/api/v1/marketstate

# Request method

  • POST

# Request parameters

parameter name Required Type Description
market Yes string Market identity，hk：Hongkong，us：U.S.，sh：Shanghai，sz：Shenzhen

# Return results

Parameter name Type Description
code int Error codes, 0 indicates success, others indicate failure
msg string message
data Dictionary type Data area, the specific API refers to the specific market API

# Description of market status structure

Parameter name Type Description
market string Market logo, what is entered, what will be returned here
desc string Description of the current market status
tradingDayType int For the current trading day type, please refer to the trading day type description below
status int The current market status, please refer to the market status description below

# Description of the type of trading day

Value Description
0 Non-trading days
1 All-day market
2 First half day market
3 Second half day market

# Description of the market status

Value Description
0 Unknown
1 Before the start and the opening of the market
2 Open call auction 9:15-9:25
3 Suspended 9:25-9:30，HK stock 09:28 - 09:30
4 Continuous Trading Session 9:30-11:30,13:00-15:00，14:57-15:00 Except for Shenzhen Stock Exchange
5 Closed at noon 11:30-13:00
6 Closing call auction Shenzhen Stock Exchange14:57-15:00
7 Closed 15:00-7b:00
20 Enter the order 09:00 - 09:15，Hong Kong stock specific status
21 Before order matching 09:15 - 09:20，Hong Kong stock specific status
22 Order matching 09:20 - 09:28，Hong Kong stock specific status
23 Reference Pricing，Hong Kong stocks close to the collective auction
24 Enter the order，Hong Kong stocks close to the collective auction
25 Non-cancellable，Hong Kong stocks close to the collective auction
26 Random closing，Hong Kong stocks close to the collective auction
27 Order matching，Hong Kong stocks close to the collective auction
31 Pre-market，all U.S. stocks
32 Post-market，all U.S. stocks
61 After-hours matching，A-share science and technology innovation board
62 Fixed-price trading，A-share science and technology innovation board

# Example

# Requst

POST /quotes-openservice/api/v1/marketstate HTTP/1.1
Content-Type: application/json; charset=utf-8

{"market":"sh"}

# Result

{
  "code": 0,
  "msg": "success",
  "data": {
    "market": "sh",
    "desc": "已收盘",
    "tradingDayType": 1,
    "status": 7
  }
}

# 3. Baisic information API

# Brief description

API for getting basic information

# Request URL

  • https://open-hz.usmartsg.com:8443/quotes-openservice/api/v1/basicinfo

# Request method

  • POST

# Request parameters

Parameter name Required Type Description
market Yes string Market identity，hk：Hongkong，us：U.S.，sh：Shanghai，sz：Shenzhen

# Return Results

Parameter name Type Description
code int Error code, 0 means success, other means failure
msg string Message
data Dictionary type Data area, containing an array of entry-by-entry, as described below

# data structure

Parameter name Type Description
market string stock market，eg：hk、us、sh、sz
list array List of basic information. See "Basic Information Items" for a description of each item.

# Basic Information Items

Parameter name Type Description
symbol string stock code
nameChs string Chinese abbreviation of stock
nameCht string Traditional abbreviation of stock
nameEn string English abbreviation of stock
type1 int32 Security type，See Security Types below for details
lotSize int32 Minimum number of orders

# Security type

Parameter name Type Description
0 int32 Unknown
1 int32 Stock
2 int32 Fund
3 int32 Futures
4 int32 Bond
5 int32 Derivative securities
6 int32 Index
7 int32 Forex
8 int32 Other
9 int32 Board

# Example

POST /quotes-openservice/api/v1/basicinfo HTTP/1.1
Content-Type: application/json; charset=utf-8

{"market":"hk"}

{
  "code": 0,
  "msg": "success",
  "data": {
   "market": "hk",
    "list": [
      {
        "symbol": "21922",
        "nameChs": "腾讯东亚零四沽B",
        "nameCht": "騰訊東亞零四沽B",
        "nameEn": "EATENCT@EP2004B",
        "type1": 5,
        "lotSize": 5000
      },
      {
        "symbol": "29260",
        "nameChs": "银证瑞银零八购A",
        "nameCht": "銀證瑞銀零八購A",
        "nameEn": "UB-CGS @EC2008A",
        "type1": 5,
        "lotSize": 5000
      }
    ]
  }
}

# 4. Real-time quotes API

# Brief description

API to get real-time quotation data.

# Request URL

  • https://open-hz.usmartsg.com:8443/quotes-openservice/api/v1/realtime

# Request method

  • POST

# Request parameters

Parameter name Required Type Description
secuIds Yes array Array of strings, each element is a unique identifier of the security, which is composed of a market identifier + a security code, such as Tencent's unique identifier of hk00700

# Return Results

Parameter name Type Description
code int Error codes, 0 indicates success, others indicate failure
msg string Message
data Dictionary type Data area, containing a list field, the meaning of the fields in the list object,as described below

# Description of the object data fields in the list

Parameter name Type Description
market string Market identity
symbol string Stock code
latestPrice double Latest price
open double Opening price
low double Lowest price
close double Closing price
high double Highest price
latestTime int64 Recent Quote Time
preClose double Yesterday's closing price
turnOver double Total turnover
volume int64 Total volume
bidPrice double First bid price
bidSize int64 First bid volume
askPrice double First ask price
askSize int64 First ask volume
upLimit double Limit up
downLimit double Limit down
qtyUnit double Real-time spreads
trdStatus int32 Securities status, see the description of securities status below

# Description of securities status

Value Description
0 Unknown
1 Suspension
2 Hong Kong stock volatility interrupted
3 Not listed
4 Suspension of Listing (A shares)
5 Delisting
6 Trading

# Example

POST /quotes-openservice/api/v1/realtime HTTP/1.1
Content-Type: application/json; charset=utf-8

{"secuIds":["hk00700"]}

{
  "code": 0,
  "msg": "success",
  "data": {
    "list": [
      {
        "latestPrice": 376.8,
        "open": 379,
        "low": 376.8,
        "bidPrice": 376.6,
        "symbol": "00700",
        "close": 376.8,
        "high": 379.8,
        "latestTime": 20191224120822000,
        "preClose": 377.8,
        "turnOver": 2403547632,
        "bidSize": 23100,
        "trdStatus": 6,
        "market": "hk",
        "volume": 6360485,
        "askPrice": 376.8,
        "askSize": 12300
      }
    ]
  }
}

# 5. Timeline API

# Brief description

API to get timeline data.

# Request URL

  • https://open-hz.usmartsg.com:8443/quotes-openservice/api/v1/timeline

# Request method

  • POST

# Request parameters

Parameter name Required Type Description
secuId Yes string The unique identifier of the security, consisting of market identifier + security code, e.g. Tencent's unique identifier is hk00700
type Yes int Tick type, 0：one day tick，1：five day tick

# Return Results

Parameter name Type Description
code int Error codes, 0 indicates success, others indicate failure
msg string Message
data Dictionary type Data area, which contains an array of tick structures, see the tick interface below

# Timeline structure description

Parameter name Type Description
price double Latest price
avg double Average price
latestTime int64 Recent Quote Time
preClose double Yesterday's closing price
amount double Turnover
volume int64 Volume
netchng double Chg
pctchng double Chg(%)

# Example

POST /quotes-openservice/api/v1/timeline HTTP/1.1
Content-Type: application/json; charset=utf-8

{"secuId":"hk02208","type":0}

{
  "code": 0,
  "msg": "success",
  "data": {
    "list": [
     {
        "latestTime": 20191224093000000,
        "preClose": 8.69,
        "price": 8.7,
        "avg": 8.629,
        "volume": 1400,
        "amount": 12080,
        "netchng": 0.01,
        "pctchng": 0.0012
      }
    ]
  }
}

# 6. K-line API

# Brief description

API to get K-line data.

# Request URL

  • https://open-hz.usmartsg.com:8443/quotes-openservice/api/v1/kline

# Request method

  • POST

# Request parameters

Parameter name Required Type Description
secuId Yes string The unique identifier of the security, consisting of market identifier + security code, e.g. Tencent's unique identifier is hk00700
type Yes int32 K-line type, see the K-line type description below
start Yes int64 The start time of the current page, the first page can be passed 0
right Yes int32 Reinstatement type，0：No reinstatement，1：Former reinstatement，2：Post-reinstatement
count Yes int32 Size per page

# K-line type description

Value Description
0 Default value,no data is returned
1 1 minute K-line
2 5 minutes K-line
3 10 minutes K-line
4 15 minutes K-line
5 30 minutes K-line
6 60 minutes K-line
7 1-day K-line
8 1-week K-line
9 1-month K-line
10 3-months K-line
11 6-months K-line
12 1-year K-line

# Return Results

Parameter name Type Description
code int Error codes, 0 indicates success, others indicate failure
msg string Message
data Dictionary type Data area, specific API refer to the specific quotation API

# K-line structure description

Parameter name Type Description
open double Opening Price
close double Closing Price
latestTime int64 Recent Quote Time
preClose double Yesterday's closing price
amount double Turnover
volume int64 Volume
high double Highest Price
low double Lowest Price

# Example

POST /quotes-openservice/api/v1/kline HTTP/1.1
Content-Type: application/json; charset=utf-8

{"secuId":"sh600001","type":7,"start":0,"count":0,"right":0}

{
  "code": 0,
  "msg": "success",
  "data": {
    "list": [
     {
        "latestTime": 20090716000000000,
        "preClose": 6.6,
        "open": 6.6,
        "close": 6.54,
        "high": 6.7,
        "low": 6.5,
        "volume": 41413014,
        "amount": 272594480
      }
    ]
  }
}

# 7. Tick API

# Brief description

  • API to get tick data.

# Request URL

  • https://open-hz.usmartsg.com:8443/quotes-openservice/api/v1/tick

# Request method

  • POST

# Request parameters

Parameter name Required Type Description
secuId Yes string The unique identifier of the security, consisting of market identifier + security code, e.g. Tencent's unique identifier is hk00700
tradeTime Yes int64 The starting quote time, the first page can be passed 0, and the last or initial one of the other pagination results can be passed on the latestTime
seq Yes int64 The starting quote serial number, the first page can be transmitted 0, other pagination passes the req of the last or first entry in the result
count int64 string The size of the data per page
sortDirection int32 string Sort direction，0：Time reverse order，1：Chronological order

# Return Results

Parameter name Type Description
code int Error codes, 0 indicates success, others indicate failure
msg string Message
data Dictionary type Data area,vcontains an array of item-by-item entries, refer to the item-by-item description below

# Entry-by-entry description

Parameter name Type Description
seq int32 Quote sequence number
time int64 Quotes time
price double Price
volume int64 Volume
direction double Direction， 0: default，1：Buy，2：Sell
trdType int64 Uitem-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

# Example

POST /quotes-openservice/api/v1/tick HTTP/1.1
Content-Type: application/json; charset=utf-8

{"secuId":"sh600001","tradeTime":0,"start":0,"count":0,"sortDirection":0}


{
  "code": 0,
  "msg": "success",
  "data": {
   "market": "hk",
    "symbol": "00001",
    "start": "0",
    "list": [
      {
        "seq": 1202,
        "time": 20191224120820000,
        "price": 74.65,
        "volume": 1000,
        "direction": 0,
        "trdType": 103
      }
    ]
  }
}

# 8. Orderbook API

# Brief description

  • API to get orderbook data.

# Request URL

  • https://open-hz.usmartsg.com:8443/quotes-openservice/api/v1/orderbook

# Request method

  • POST

# Request parameters

Parameter name Required Type Description
secuId Yes string The unique identifier of the security, consisting of market identifier + security code, e.g. Tencent's unique identifier is hk00700

# Return Results

Parameter name Type Description
code int Error codes, 0 indicates success, others indicate failure
msg string Message
data Dictionary type Data area, contains a latest quote time(lastTime), an array of orderbook entries, as described below

# Orderbook entries description

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

# Example

POST /quotes-openservice/api/v1/orderbook HTTP/1.1
Content-Type: application/json; charset=utf-8

{"secuId":"hk00001"}

{
  "code": 0,
  "msg": "success",
  "data": {
   "market": "hk",
    "symbol": "00001",
    "latestTime": 20200109153121000,
    "list": [
      {
         "bidPrice": 9.31,
         "bidVolume": 12000,
         "bidOrderCount": 5,
         "askPrice": 9.32,
         "askVolume": 21600,
         "askOrderCount": 3
       }
    ]
  }
}

# 9. Error code description

Error code Explanation
806000 Parameter error
806100 Unknown error
806109 Permission error
806110 Internal service error
806111 Illeagal stock code or market

← Quote push access protocol →