跳至主要内容

簽名生成

⚠️ 現貨與合約的簽名方式不同

本頁說明的是現貨 API（s-api）。合約 API（f-api）使用不同的待簽名串，請參見合約：簽名生成。把合約的簽名程式碼用在現貨上（或反過來）是導致 AUTH_103 最常見的原因。

現貨（本頁）合約
待簽名串X#METHOD#path[#query][#body]X#path[#query][#body]
X（請求頭部分）validate-algorithms=..&validate-appkey=..&validate-recvwindow=..&validate-timestamp=..（4 項）validate-appkey=..&validate-timestamp=..（2 項）
待簽名串是否包含 HTTP 方法是（大寫）否
必填請求頭algorithms、appkey、recvwindow、timestamp、signatureappkey、timestamp、signature

待簽名串不包含域名，因此兩個生產域名使用相同的簽名。

1. 請求頭​

以下五個請求頭均為必填。

請求頭說明
validate-algorithms簽名演算法：HmacSHA256（推薦）、HmacSHA1、HmacSHA224、HmacSHA384、HmacSHA512、HmacMD5
validate-appkey你的 API key
validate-recvwindow有效時間窗口，單位為毫秒，取值 5000 至 60000
validate-timestamp發送請求時的 Unix 時間，單位為毫秒（13 位）
validate-signature按下文計算出的簽名

如 validate-timestamp 與伺服器時間的差值不小於 validate-recvwindow，請求會被拒絕（AUTH_105）。

2. 構建待簽名串​

original = X + "#" + METHOD + "#" + path [+ "#" + query] [+ "#" + body]
X        = "validate-algorithms=" + algorithms + "&validate-appkey=" + appkey
         + "&validate-recvwindow=" + recvwindow + "&validate-timestamp=" + timestamp
  • X —— 只包含這四項，且順序固定，取值與你發送的請求頭相同。
  • METHOD —— 大寫的 HTTP 方法：GET、POST、DELETE、PUT。
  • path —— 實際發送的請求路徑，以 /az/spot/... 開頭，不含域名，也不含 ?。例如：/az/spot/order。
  • query —— 僅當 URL 帶有查詢參數時加入：按 key 的 ASCII 順序排序（大寫字母排在小寫字母之前），以 key=value 形式用 & 連接。使用未編碼的值（伺服器以解碼後的值簽名；傳輸中的 a%2Cb 按 a,b 簽名）。同一個 key 出現多次時，只取第一個值。參數一律以 key=value 形式發送（不要有不帶 = 的 key）。
  • body —— 僅當請求帶有請求體時加入：與實際發送完全相同的請求體字串，逐位元組一致。不排序、不重新格式化、不做 URL 解碼。空物件 {} 也是請求體，必須拼接。
  • 不存在的部分連同其 # 一併省略——待簽名串絕不能以 # 結尾。
請求包含待簽名串
無查詢參數、無請求體X#METHOD#path
僅查詢參數X#METHOD#path#query
僅請求體X#METHOD#path#body
查詢參數和請求體X#METHOD#path#query#body

3. 計算簽名​

signature = hex( HMAC-<algorithm>( key = secretKey, message = original ) )

使用 validate-algorithms 中指定的演算法，secretKey 字串按原樣使用（UTF-8）。輸出為小寫或大寫的 hex（不是 Base64），放入 validate-signature 請求頭。

4. 測試向量​

請用以下數值檢驗你的實現。你的程式碼必須產生完全相同的 original 和 signature。

appKey     : 3976eb88-76d0-4f6e-a6b2-a57980770085
secretKey  : bc6630d0231fda5cd98794f52c4998659beda290
timestamp  : 1641446237201
recvwindow : 5000
algorithms : HmacSHA256

帶查詢參數的 GET —— GET /az/spot/balance?currency=usdt

original  : validate-algorithms=HmacSHA256&validate-appkey=3976eb88-76d0-4f6e-a6b2-a57980770085&validate-recvwindow=5000&validate-timestamp=1641446237201#GET#/az/spot/balance#currency=usdt
signature : 7242659cfd6867b7b64dea781c40af20aba45082e9194caeb0c55ae96dbd8f1c

帶 JSON 請求體的 POST —— POST /az/spot/order

body      : {"symbol":"btc_usdt","side":"BUY","type":"LIMIT","timeInForce":"GTC","bizType":"SPOT","price":"70000","quantity":"0.001"}
original  : validate-algorithms=HmacSHA256&validate-appkey=3976eb88-76d0-4f6e-a6b2-a57980770085&validate-recvwindow=5000&validate-timestamp=1641446237201#POST#/az/spot/order#{"symbol":"btc_usdt","side":"BUY","type":"LIMIT","timeInForce":"GTC","bizType":"SPOT","price":"70000","quantity":"0.001"}
signature : 7def8177a2f43efd55b539f6c7366d09cd7ec976728317249e64685284258713

5. 程式碼示例​

每個示例都會查詢餘額（帶查詢參數的 GET）並下一張限價單（帶 JSON 請求體的 POST）。請先設定環境變數 AZ_API_KEY 和 AZ_SECRET_KEY。每個示例都會輸出 original，方便你對照上述規則。

⚠️ 示例會真實下單

示例預設連接沙盒環境（https://s-api.az-qa2.xyz）；沙盒與生產環境的 API key 不同。如要在生產環境執行，請設定 AZ_HOST=https://s-api.azverse.xyz，並先調整 price / quantity。訂單為只做 Maker（GTX），不會立即成交；執行後請自行撤單。

所有示例的關鍵規則：請求體只序列化一次，對該字串簽名，並發送同一個字串。

Python​

import hashlib
import hmac
import json
import os
import time
from urllib.parse import urlencode

import requests

HOST = os.getenv("AZ_HOST", "https://s-api.az-qa2.xyz")  # sandbox; production: https://s-api.azverse.xyz
API_KEY = os.environ["AZ_API_KEY"]
SECRET_KEY = os.environ["AZ_SECRET_KEY"]


def signed_request(method, path, params=None, payload=None):
    timestamp = str(int(time.time() * 1000))  # milliseconds (13 digits)
    recv_window = "5000"  # 5000 ~ 60000

    # Spot: header part has 4 items in this fixed order, followed by #METHOD#path
    original = (f"validate-algorithms=HmacSHA256&validate-appkey={API_KEY}"
                f"&validate-recvwindow={recv_window}&validate-timestamp={timestamp}"
                f"#{method.upper()}#{path}")

    query = ""
    if params:
        items = sorted(params.items())  # sort by key (ASCII order)
        original += "#" + "&".join(f"{k}={v}" for k, v in items)  # un-encoded values
        query = "?" + urlencode(items)  # URL-encoded on the wire

    body = None
    if payload is not None:
        body = json.dumps(payload, separators=(",", ":"))  # serialize ONCE
        original += "#" + body  # sign exactly the string you send

    signature = hmac.new(SECRET_KEY.encode(), original.encode(), hashlib.sha256).hexdigest()
    print("original :", original)

    headers = {
        "Content-Type": "application/json",
        "validate-algorithms": "HmacSHA256",
        "validate-appkey": API_KEY,
        "validate-recvwindow": recv_window,
        "validate-timestamp": timestamp,  # the SAME timestamp used in `original`
        "validate-signature": signature,
    }
    # send the signed string itself (as UTF-8 bytes), NOT json=payload (requests would re-serialize it)
    data = None if body is None else body.encode("utf-8")
    resp = requests.request(method, HOST + path + query, headers=headers, data=data)
    return resp.json()


# GET with query parameters
print(signed_request("GET", "/az/spot/balance", params={"currency": "usdt"}))

# POST with JSON body: place a post-only limit order
print(signed_request("POST", "/az/spot/order", payload={
    "symbol": "btc_usdt",
    "side": "BUY",
    "type": "LIMIT",
    "timeInForce": "GTX",  # post-only: never fills immediately
    "bizType": "SPOT",
    "price": "70000",  # pass decimals as strings to keep their exact text
    "quantity": "0.001",
}))

JavaScript (Node.js 18+)​

// Node.js 18+ (built-in fetch and crypto). Save as sign.mjs and run: node sign.mjs
import crypto from 'node:crypto';

const HOST = process.env.AZ_HOST || 'https://s-api.az-qa2.xyz'; // sandbox; production: https://s-api.azverse.xyz
const API_KEY = process.env.AZ_API_KEY;
const SECRET_KEY = process.env.AZ_SECRET_KEY;

async function signedRequest(method, path, params, payload) {
  const timestamp = String(Date.now()); // milliseconds (13 digits)
  const recvWindow = '5000'; // 5000 ~ 60000

  // Spot: header part has 4 items in this fixed order, followed by #METHOD#path
  let original = `validate-algorithms=HmacSHA256&validate-appkey=${API_KEY}`
    + `&validate-recvwindow=${recvWindow}&validate-timestamp=${timestamp}`
    + `#${method.toUpperCase()}#${path}`;

  let query = '';
  if (params && Object.keys(params).length) {
    const keys = Object.keys(params).sort(); // sort by key (ASCII order)
    original += '#' + keys.map((k) => `${k}=${params[k]}`).join('&'); // un-encoded values
    query = '?' + keys.map((k) => `${encodeURIComponent(k)}=${encodeURIComponent(params[k])}`).join('&');
  }

  let body;
  if (payload !== undefined) {
    body = JSON.stringify(payload); // serialize ONCE
    original += '#' + body; // sign exactly the string you send
  }

  const signature = crypto.createHmac('sha256', SECRET_KEY).update(original).digest('hex');
  console.log('original :', original);

  const resp = await fetch(HOST + path + query, {
    method,
    headers: {
      'Content-Type': 'application/json',
      'validate-algorithms': 'HmacSHA256',
      'validate-appkey': API_KEY,
      'validate-recvwindow': recvWindow,
      'validate-timestamp': timestamp, // the SAME timestamp used in `original`
      'validate-signature': signature,
    },
    body, // the signed string itself
  });
  return resp.json();
}

// GET with query parameters
console.log(await signedRequest('GET', '/az/spot/balance', { currency: 'usdt' }));

// POST with JSON body: place a post-only limit order
console.log(await signedRequest('POST', '/az/spot/order', null, {
  symbol: 'btc_usdt',
  side: 'BUY',
  type: 'LIMIT',
  timeInForce: 'GTX', // post-only: never fills immediately
  bizType: 'SPOT',
  price: '70000', // pass decimals as strings to keep their exact text
  quantity: '0.001',
}));

Java (11+)​

// Java 11+ (no third-party dependency). Save as Sign.java and run: java Sign.java
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.net.URI;
import java.net.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.util.Map;
import java.util.TreeMap;
import java.util.stream.Collectors;

public class Sign {
    static final String HOST = System.getenv().getOrDefault("AZ_HOST", "https://s-api.az-qa2.xyz"); // sandbox; production: https://s-api.azverse.xyz
    static final String API_KEY = System.getenv("AZ_API_KEY");
    static final String SECRET_KEY = System.getenv("AZ_SECRET_KEY");
    static final HttpClient HTTP = HttpClient.newHttpClient();

    static String hmacSha256Hex(String secret, String data) throws Exception {
        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
        StringBuilder hex = new StringBuilder();
        for (byte b : mac.doFinal(data.getBytes(StandardCharsets.UTF_8))) {
            hex.append(String.format("%02x", b));
        }
        return hex.toString();
    }

    static String signedRequest(String method, String path, Map<String, String> params, String body) throws Exception {
        String timestamp = String.valueOf(System.currentTimeMillis()); // milliseconds (13 digits)
        String recvWindow = "5000"; // 5000 ~ 60000

        // Spot: header part has 4 items in this fixed order, followed by #METHOD#path
        StringBuilder original = new StringBuilder("validate-algorithms=HmacSHA256&validate-appkey=" + API_KEY
                + "&validate-recvwindow=" + recvWindow + "&validate-timestamp=" + timestamp
                + "#" + method.toUpperCase() + "#" + path);

        String query = "";
        if (params != null && !params.isEmpty()) {
            TreeMap<String, String> sorted = new TreeMap<>(params); // sort by key (ASCII order)
            original.append("#").append(sorted.entrySet().stream()
                    .map(e -> e.getKey() + "=" + e.getValue()) // un-encoded values
                    .collect(Collectors.joining("&")));
            query = "?" + sorted.entrySet().stream()
                    .map(e -> URLEncoder.encode(e.getKey(), StandardCharsets.UTF_8) + "="
                            + URLEncoder.encode(e.getValue(), StandardCharsets.UTF_8).replace("+", "%20"))
                    .collect(Collectors.joining("&"));
        }
        if (body != null) {
            original.append("#").append(body); // sign exactly the string you send
        }

        String signature = hmacSha256Hex(SECRET_KEY, original.toString());
        System.out.println("original : " + original);

        HttpRequest request = HttpRequest.newBuilder(URI.create(HOST + path + query))
                .header("Content-Type", "application/json")
                .header("validate-algorithms", "HmacSHA256")
                .header("validate-appkey", API_KEY)
                .header("validate-recvwindow", recvWindow)
                .header("validate-timestamp", timestamp) // the SAME timestamp used in `original`
                .header("validate-signature", signature)
                .method(method, body == null ? HttpRequest.BodyPublishers.noBody()
                        : HttpRequest.BodyPublishers.ofString(body, StandardCharsets.UTF_8))
                .build();
        return HTTP.send(request, HttpResponse.BodyHandlers.ofString()).body();
    }

    public static void main(String[] args) throws Exception {
        // GET with query parameters
        System.out.println(signedRequest("GET", "/az/spot/balance", Map.of("currency", "usdt"), null));

        // POST with JSON body: place a post-only limit order (GTX never fills immediately).
        // Build the JSON string ONCE (by hand or with your JSON library) and use it for both signing and sending.
        String body = "{\"symbol\":\"btc_usdt\",\"side\":\"BUY\",\"type\":\"LIMIT\",\"timeInForce\":\"GTX\","
                + "\"bizType\":\"SPOT\",\"price\":\"70000\",\"quantity\":\"0.001\"}";
        System.out.println(signedRequest("POST", "/az/spot/order", null, body));
    }
}

curl + openssl (bash)​

#!/usr/bin/env bash
# Requires: bash, openssl, curl. Export AZ_API_KEY / AZ_SECRET_KEY first.
HOST="${AZ_HOST:-https://s-api.az-qa2.xyz}"   # sandbox; production: https://s-api.azverse.xyz
METHOD="POST"
PATH_="/az/spot/order"
BODY='{"symbol":"btc_usdt","side":"BUY","type":"LIMIT","timeInForce":"GTX","bizType":"SPOT","price":"70000","quantity":"0.001"}'
RECV=5000                       # 5000 ~ 60000
TS=$(( $(date +%s) * 1000 ))    # milliseconds (13 digits)

# Spot: header part has 4 items in this fixed order, followed by #METHOD#path
ORIGINAL="validate-algorithms=HmacSHA256&validate-appkey=${AZ_API_KEY}&validate-recvwindow=${RECV}&validate-timestamp=${TS}#${METHOD}#${PATH_}#${BODY}"
SIGNATURE=$(printf '%s' "$ORIGINAL" | openssl dgst -sha256 -hmac "$AZ_SECRET_KEY" | awk '{print $NF}')
echo "original : $ORIGINAL"

curl -sS -X "$METHOD" "${HOST}${PATH_}" \
  -H 'Content-Type: application/json' \
  -H 'validate-algorithms: HmacSHA256' \
  -H "validate-appkey: ${AZ_API_KEY}" \
  -H "validate-recvwindow: ${RECV}" \
  -H "validate-timestamp: ${TS}" \
  -H "validate-signature: ${SIGNATURE}" \
  --data-raw "$BODY"
echo

6. 仍然收到 AUTH_103？​

輸出你的 original 字串，按上述規則逐段比對，然後逐項查閱簽名常見錯誤。