HMAC 签名查询测试网现货余额

从服务端时间开始，签名读取 Spot Testnet 账户，掌握私有查询而不执行交易。

官方资料核对 2026-10-15示例代码，未进行真实接口实测

接入准备

进入 Spot Testnet，按其当前注册流程建立测试网账户。
创建测试网 HMAC API Key，允许 USER_DATA 读取；本示例不适用于 RSA 或 Ed25519 类型的 Key。

准备环境变量

示例值需要替换为自己的凭证或资源 ID。代码在本机或服务端运行；密钥不应放进公开网页。

BINANCE_TESTNET_API_KEY: Spot Testnet 生成的 HMAC API Key，需有 USER_DATA 读取权限。
BINANCE_TESTNET_SECRET: 同一个 HMAC Key 对应的 Secret，留在自己的服务端。

export BINANCE_TESTNET_API_KEY='replace_with_testnet_api_key'
export BINANCE_TESTNET_SECRET='replace_with_testnet_secret'

以上 export 适用于 macOS / Linux 的终端，在同一终端内运行后续代码。Python 示例保存为 request.py 后执行 python3 request.py。

调用步骤

01
在 Spot Testnet API Key 页面生成 HMAC Key，保管 Key 与 Secret。正式 Key 不能用于测试网。
02
设置 BINANCE_TESTNET_API_KEY 和 BINANCE_TESTNET_SECRET，保存下方代码后用 Python 3 运行。
03
代码先 GET /api/v3/time，再将相同编码后的 query 用 HMAC-SHA256 签为十六进制，最后附加 signature。
04
读取 balances 的 free/locked；测试网余额为虚拟资产，测试网可能周期性重置数据。

调用 01

查询测试网账户

以下 URL 展示端点；timestamp 和 signature 必须由代码实时生成，不能使用静态签名。

GEThttps://testnet.binance.vision/api/v3/account?omitZeroBalances=true&recvWindow=5000

请求头

Accept: application/json

参数说明

参数表可左右滑动，查看完整说明。

字段 / 位置	类型 / 必填	说明
`X-MBX-APIKEY`Header	string必填	测试网 Key；签名并不能代替此 Header。
`timestamp`Query	integer必填	实时 UTC Unix 毫秒值；代码从测试网服务器取得。
`recvWindow`Query	number可选	允许时间窗口，默认 5000 毫秒，最大 60000；本例 5000。
`omitZeroBalances`Query	boolean可选	true 只返回非零余额，默认 false。
`signature`Query	string必填	对已编码的其他 query 参数按实际发送顺序计算 HMAC-SHA256 后转十六进制。

调用代码

替换示例 ID 与请求体内容后运行。

import hashlib, hmac, json, os, urllib.parse, urllib.request, urllib.error
# 固定 Spot Testnet，不向正式环境发送私有请求。
host = "https://testnet.binance.vision"
key = os.environ["BINANCE_TESTNET_API_KEY"]
secret = os.environ["BINANCE_TESTNET_SECRET"]
try:
    with urllib.request.urlopen(host + "/api/v3/time", timeout=20) as response:
        server_time = json.load(response)["serverTime"]
    query = urllib.parse.urlencode({"omitZeroBalances": "true", "recvWindow": 5000, "timestamp": server_time})
    signature = hmac.new(secret.encode(), query.encode(), hashlib.sha256).hexdigest()
    req = urllib.request.Request(host + "/api/v3/account?" + query + "&signature=" + signature,
        headers={"X-MBX-APIKEY": key, "Accept": "application/json"})
    with urllib.request.urlopen(req, timeout=20) as response:
        result = json.load(response)
except urllib.error.HTTPError as exc:
    raise SystemExit(f"HTTP {exc.code}: {exc.read().decode()}")
if isinstance(result, dict) and isinstance(result.get("code"), int) and result["code"] < 0:
    raise SystemExit(json.dumps(result))
print(json.dumps(result, indent=2))

返回示例

按官方结构整理的节选示意，非实测结果。balances[].asset 是币种，free 是可用数量，locked 是冻结数量，均保留字符串精度；canTrade 不是下单结果。以下为结构示意，非本站实测结果。

{
  "accountType": "SPOT",
  "canTrade": true,
  "balances": [
    {
      "asset": "USDT",
      "free": "10000.00000000",
      "locked": "0.00000000"
    }
  ]
}

常见错误与排查

-1021请求时间戳不在 recvWindow 内或领先服务端过多: 重新取服务器时间、检查网络耗时；不要依靠无限扩大 recvWindow 处理时钟错误。
-1022签名无效: 核对同一 HMAC Secret、编码后的签名原文与最终发送参数是否一致。
-2015Key、IP 或权限不被接受: 检查测试网环境、Key 是否有效、IP 限制及 USER_DATA 读取权限。

调用注意

本例只支持 HMAC，不可将 RSA 私钥直接当作 Secret 使用。
签名后不得改变 query 的编码或顺序；请求采用 GET，无 body。

Binance Spot USER_DATA 账户信息 Binance REST 签名与时间窗口 Binance 现货错误码

注意事项

本轮仅提供只读查询；示例不含下单、杠杆、划转或提现。Binance.com 服务与各地区独立站点的账户和资格不能互换。
公开行情无需 API Key，但仍消耗 IP 请求权重；查询权重不是交易手续费，实际交易另按账户费率。
Spot Testnet 只验证测试环境 API 行为，不能证明正式地区资格、资金可用或生产性能。

核验来源

本站按官方资料整理本场景的必要调用步骤与代码，覆盖范围以本页列出的接口为准。官方资料用于追溯规范及查看变更。

01
Binance REST 签名与时间窗口核验日期 2026-10-15
02
Binance Spot Testnet核验日期 2026-10-15
03
Binance Spot USER_DATA 账户信息核验日期 2026-10-15
04
Binance 现货错误码核验日期 2026-10-15

币安 Binance的其他调用手册

查询现货交易对最新价格读取最近的现货小时 K线

← 返回币安 Binance的全部功能