Skip to main content

Off-chain API Reference

Introduction​

Request API​

All endpoints require the following additional parameters, which are placed in the header

  • x-api-key: optional, contact us to generate the apiKey and secretKey for you
  • x-api-timestamp：the millisecond timestamp of when the request was created and sent(UTC+0)
  • x-api-signature: signature(optional), for specific signature rules, see signature

Data signature​

tip

Please note that the signature is optional here. You can still access our API without signature. However, you will be limited to a lower rate. If you foresee your application having a higher rate to the Off-chain API, please contact us for a dedicated apiKey and apiSecret.

  • Endpoints use HMAC SHA256 signatures. The HMAC SHA256 signature is a keyed HMAC SHA256 operation. Use your secretKey as the key and totalParams as the value for the HMAC operation
  • The signature is not case sensitive
  • The parameters of the query string and request body are sorted in ascending order by key, with & links in the middle, and finally the x-api-timestamp in the header is spliced

Example​

  • x-api-key:754ead833a9ff0e3884ee5dd689ddba2dd1dc66af1342b754291568e01fb6a5f
  • secretKey:846dca24075f067de980a4bfbae1c02599c4c34b748ce17b40ebc94e0818a9ba

request body

{
    "sign":true,
    "symbols":"BTC/USD,ETH/USD"
}

x-api-timestamp:1669845709998

After sorting and splicing

sign=true&symbols=BTC/USD,ETH/USD&x-api-timestamp=1669845961970

HMAC SHA256 signature:

echo -n "sign=true&symbols=BTC/USD,ETH/USD&x-api-timestamp=1669845961970" | openssl dgst -sha256 -hmac "846dca24075f067de980a4bfbae1c02599c4c34b748ce17b40ebc94e0818a9ba"
(stdin)= 0eb116708c7913cb35338fc93924775048a2cab1ddcd0aea2cd7ff90bf401bc9

Code sample​

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "fmt"
    "strconv"
    "strings"
    "time"
)
func main() {
    apiSecret := "" // the apiSecret secret
    apiKey := ""                                       // the apiKey
    timestamp := strconv.FormatInt(time.Now().UnixMilli(), 10) // the timestamp
    fmt.Println(timestamp)
    query := make(map[string]string) //the query parameters, it can be empty
    body := make(map[string]string) // the request body,can be empty
    body["sign"] = "false"
    body["symbols"] = "ETH/USD"
    msgForSig := GenerateMsgForSig(timestamp, query, body)
    sig := ComputeSig(msgForSig, apiSecret)
}

func GenerateMsgForSig(timestamp string, query map[string]string, body map[string]string) string {
    var sortedKeys []string
    if len(query) > 0 || len(body) > 0 {
        sortedKeys = make([]string, len(query)+len(body))
        if len(query) > 0 {
            for k := range query {
                sortedKeys = append(sortedKeys, k)
            }
        }
        if len(body) > 0 {
            for k := range body {
                sortedKeys = append(sortedKeys, k)
            }
        }
    }
    var strBuild strings.Builder
    if len(sortedKeys) > 0 {
        for _, k := range sortedKeys {
            if len(query) > 0 {
                if v, ok := query[k]; ok {
                    strBuild.WriteString(fmt.Sprintf("&%s=%s", k, v))
                }
            }
            if len(body) > 0 {
                if v, ok := body[k]; ok {
                    strBuild.WriteString(fmt.Sprintf("&%s=%s", k, v))
                }
            }
        }
    }
    strBuild.WriteString(fmt.Sprintf("&%s=%s", "x-api-timestamp", timestamp))
    return strings.Replace(strBuild.String(), "&", "", 1)
}
func ComputeSig(msgForSig, appSecret string) string {
    message := []byte(msgForSig)

    key := []byte(appSecret)
    h := hmac.New(sha256.New, key)
    h.Write(message)

    return hex.EncodeToString(h.Sum(nil))
}

Endpoints Info​

Query the available symbols​

GET /api/gw/available-symbols

Parameters

None

Response

[
  "ETH/USD",
  "BTC/USD",
  "BNB/USD"
]

Return supported symbols

Query the price data of symbol​

POST /api/gw/symbol-price

Parameters

{
  "sign": true,
  "symbols": "ETH/USD,BTC/USD"
}
NameTypeMandatoryDescription
symbolsStringYesThe currency pairs to be queried, separated by commas,example:BTC/USD,ETH/USD
signBoolNoDefault false.Signed data will be returned if and only if the input is true and the configuration needs to sign and sign the data when applying for apiKey

Response

{
  "timestamp": 1669874762,
  "data": [
    {
      "symbol": "BTC/USD",
      "price": 1712142814285,
      "scale": 8
    },
    {
      "symbol": "ETH/USD",
      "price": 128367756871,
      "scale": 8
    }
  ],
  "signature": "0x5f78653dfcf141f6eb86efe3a9b7dcf1eb77fdcf4ef1c8134ea4921d68e35b052fe1fcb74e73b4ca6b992d1b224767b682436380c81ab593b00599741f4d704d000000000000000000000000000000000000000000000000000000000000001b",
  "message": "0000000000000000000000000000000000000000000000000000000000000080000000000000000000000000000000000000000000000000000000006388444a00000000000000000000000000000000000000000000000000000000000000c000000000000000000000000000000000000000000000000000000000000001a00000000000000000000000000000000000000000000000000000000000000002763100000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000040000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000000074254432f5553440000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000074554482f5553440000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000018ea3aa0c4d0000000000000000000000000000000000000000000000000000001de3508647",
  "pubKey": "0x0361463e05a2fe473bc6c03bcb0b0999e84af8a86ed40cd547fc02923008cb4341"
}
  • data is the unsigned raw price details data
  • message is the data to be signed,message encode format:
string version,uint64 timestamp,string[] symbol,uint64[] price

current version: v1

Decode in smart contract

 (string version, uint64 timestamp, string[] symbos,uint64[] prices) = abi.decode(message, (string, uint64, string[],uint64[]))
  • signature is the signed data
  • pubKey is the public key corresponding to the signature

Error Codes and Messages​

Any endpoint can return an ERROR The error payload is as follows:

{
  "msg": "symbol not support",
  "errorCode": "200001"
}

Specific error codes and messages are defined in the following table

CodeDescription
000001Too many requests
000002Unauthorized，invalid apiKey
000003Bad request
100001System error
100002System load is too high, please try again later
200001symbol not support
200002Illegal parameter
200003Signature error