Skip to main content

Signature generation

Take https://sapi.xt.com/v4/order as an example.

The following is an example appkey and secret for placing an order using echo openssl and curl tools in the Linux bash environment (for demonstration purposes only):

Key: AppKey: 3976eb88-76d0-4f6e-a6b2-a57980770085

SecretKey: bc6630d0231fda5cd98794f52c4998659beda290 :::

Header part data​

validate-algorithms: HmacSHA256
validate-appkey: 3976eb88-76d0-4f6e-a6b2-a57980770085
validate-recvwindow: 5000
validate-timestamp: 1641446237201
validate-signature: 2b5eb11e18796d12d88f13dc27dbbd02c2cc51ff7059765ed9821957d82bb4d9

Request data​

{
  "type": "LIMIT",
  "timeInForce": "GTC",
  "side": "BUY",
  "symbol": "btc_usdt",
  "price": "39000",
  "quantity": "2"
}

1. Data part​

  • method: UpperCase method. eg: GET, POST, DELETE, PUT
  • path: Concatenate all values in the order in path. e.g. /sign/test/bb/aa
  • query: Sort all key=value according to lexicographical order. Example: userName=dfdfdf&password=ggg
  • body:
    • JSON: use JSON string directly
    • x-www-form-urlencoded: sort all key=values by lexicographical order
    • form-data: not supported

Re-splicing order: path + query + body

Examples

  • Method: POST
  • Path: /v4/order
  • Query: symbol=btc_usdt
  • Body (x-www-form-urlencoded): 
    symbol=btc_usdt&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1
  • Body (json): 
    {
      "symbol": "btc_usdt",
      "side": "BUY",
      "type": "LIMIT",
      "timeInForce": "GTC",
      "quantity": 2,
      "price": 39000
    }

Mixed usage:

Query: symbol=btc_usdt&side=BUY&type=LIMIT
Body: {"symbol":"btc_usdt","side":"BUY","type":"LIMIT"}

Final concatenated value (Y):

Y = #method#path#query#body

Rules:

  • query has data, body empty → Y=#method#path#query
  • query empty, body has data → Y=#method#path#body
  • both exist → Y=#method#path#query#body

2. Request header part​

Keys sorted in natural ascending alphabetical order, joined with & to form X.

validate-algorithms=HmacSHA256&validate-appkey=3976eb88-76d0-4f6e-a6b2-a57980770085&validate-recvwindow=5000&validate-timestamp=1641446237201

3. Generate signature​

Final string to encrypt:

original = X + Y

Signature generation:

signature = org.apache.commons.codec.digest.HmacUtils.hmacSha256Hex(secretKey, original);

Put the generated signature in request header:

validate-signature: {signature}

4. Example​

Original signature message

validate-algorithms=HmacSHA256&validate-appkey=2063495b-85ec-41b3-a810-be84ceb78751&validate-recvwindow=60000&validate-timestamp=1666026215729#POST#/v4/order#{"symbol":"XT_USDT","side":"BUY","type":"LIMIT","timeInForce":"GTC","bizType":"SPOT","price":3,"quantity":2}

Sample request message

curl --location --request POST 'https://sapi.xt.com/v4/order' \
--header 'accept: */*' \
--header 'Content-Type: application/json' \
--header 'validate-algorithms: HmacSHA256' \
--header 'validate-appkey: 10c172ca-d791-4da5-91cd-e74d202dac96' \
--header 'validate-recvwindow: 60000' \
--header 'validate-timestamp: 1666026215729' \
--header 'validate-signature: 4cb36e820f50d2e353e5e0a182dc4a955b1c26efcb4b513d81eec31dd36072ba' \
--data-raw '{"symbol":"XT_USDT","side":"BUY","type":"LIMIT","timeInForce":"GTC","bizType":"SPOT","price":3,"quantity":2}'

Matters needing attention​

  • Check Content-Type format
  • Verify signature original message matches request body
  • Validate request header parameters