HMAC Signature Guide

Our User-Type API provides enhanced security through HMAC (Hash-Based Message Authentication Code) signatures. Users are required to include an HMAC signature in their requests for authentication and data integrity when accessing certain endpoints, such as asset management and review historical data.

Generating HMAC Signature

Create a Canonical Request

Generate a standardized representation of your request, including the HTTP method, API URL, parameters, and other relevant information.

Include Timestamp

To prevent replay attacks, include a timestamp in your request.

Generate String to Sign

Combine the timestamp and canonical request into a string. This string will be used for Signing.
Format:

format = {timestamp} + {request method} + {api path} + [opt]{'?' + 'request parameters'} + [opt]{request body}

Example:

"1701336941814GET/api/v1/trades?symbol=WBTCUSDT"

Sign the String

Use your secret key (API_SECRET) to generate the HMAC (SHA-256). This ensures that only users with the correct secret key can sign requests.

Base64 Encode

Convert the calculated signature to Base64 format.

Include HMAC Signature

Add the HMAC signature to the request, typically in a designated header (Vessel-Signature).

JavaScript Example

Example below is in JavaScript, integrated with the Apifox Preprocessor for ease, that simplifies generating HMAC signatures for your requests.

To execute, simply replace the Environment Variable with your own.

var cryptoJs = require("crypto-js");

var secret = pm.environment.get("API_SECRET").slice(2);

var timestamp = new Date().getTime();

var requestMethod = pm.request.method.toUpperCase();

var requestPath = pm.request.url.getPath();

var params = pm.request.url.query.filter(item => (!item.disabled)).map(item => `${item.key}=${item.value}`).join('&');
if (params.length != 0) params = '?' + params;

const requestData = !pm.request.body.isEmpty() ? encodeURIComponent(pm.request.body.raw) : ''

var signature = cryptoJs.HmacSHA256(
      `${timestamp}${requestMethod}${requestPath}${params}${requestData}`,
      cryptoJs.enc.Hex.parse(secret),
    );
signature = cryptoJs.enc.Base64.stringify(signature);

pm.request.headers.upsert(
  {
    key: "VESSEL-TIMESTAMP",
    value: timestamp
  }
)
pm.request.headers.upsert(
  {key: "VESSEL-SIGNATURE", 
   value: signature});

Please Note that this script is specifically designed for Apifox and cannot be run independently outside of the Apifox environment. If you wish to adapt it for external use, you can use it as a reference to create a standalone script.

Important Notes

Keep Your Secret Key and Passphrase Secure

Never share your secret key and passphrase with anyone. It's crucial for generating valid HMAC signatures.

Timestamp Usage

Including a timestamp in your request helps prevent replay attacks.

HMAC Header

Always include the HMAC signature in the designated header.

Feel free to reach out if you have any questions or need further assistance.

Generating HMAC Signature#

Create a Canonical Request#

Include Timestamp#

Generate String to Sign#

Sign the String#

Base64 Encode#

Include HMAC Signature#

JavaScript Example#

Important Notes#

Keep Your Secret Key and Passphrase Secure#

Timestamp Usage#

HMAC Header#