欧易 OKX调用手册
签名查询模拟盘交易账户余额
用 Read 权限的模拟盘 Key 查询 USDT 余额,包含时间校准与完整 HMAC 签名。
← 返回平台功能接入准备
- 拥有适用地区的合资格 OKX 账户;本例使用模拟盘专用 API Key。
- 在模拟盘 API 管理创建 Key,只选必要 Read 权限,并记录 API Key、Secret Key 和自设 Passphrase。
准备环境变量
示例值需要替换为自己的凭证或资源 ID。代码在本机或服务端运行;密钥不应放进公开网页。
OKX_DEMO_API_KEY- 模拟盘 API 管理生成的 Read Key。
OKX_DEMO_SECRET_KEY- 该模拟盘 Key 的 Secret Key,只保存在服务端。
OKX_DEMO_PASSPHRASE- 创建该 Key 时自己设置的 Passphrase。
OKX_API_HOST- 按账户所属地区选择文档要求的官方 API 域名;可选 www.okx.com/us.okx.com,需确认模拟盘支持。
export OKX_DEMO_API_KEY='replace_with_demo_api_key'
export OKX_DEMO_SECRET_KEY='replace_with_demo_secret'
export OKX_DEMO_PASSPHRASE='replace_with_demo_passphrase'
export OKX_API_HOST='https://www.okx.com'以上 export 适用于 macOS / Linux 的终端,在同一终端内运行后续代码。Python 示例保存为 request.py 后执行 python3 request.py。
调用步骤
- 01
进入模拟交易页面的 API 管理,创建模拟盘 Key;模拟盘 Key 与实盘 Key 不通用。
- 02
将三个值分别设置为下方 OKX_DEMO_* 环境变量;按所属地区核对 OKX_API_HOST。
- 03
运行 Python 3 代码,代码先取公开服务器时间,再对实际请求 path+query 计算签名,并固定发送 x-simulated-trading: 1。
- 04
只有 HTTP 成功且 code=0 才读取 data[0].details;模拟资金账户与交易账户不是同一个余额接口。
调用 01
查询交易账户余额
签名是 Base64(HMAC-SHA256(secret, timestamp + GET + path含query + 空body));不是十六进制。
GET
https://www.okx.com/api/v5/account/balance?ccy=USDT请求头
x-simulated-trading1Acceptapplication/json
参数说明
参数表可左右滑动,查看完整说明。
| 字段 / 位置 | 类型 / 必填 | 说明 |
|---|---|---|
ccyQuery | string可选 | 币种筛选,示例 USDT;不传为可返回的全部资产。 |
OK-ACCESS-*Header | string必填 | Key、实时签名、UTC 毫秒时间戳和 Passphrase;由完整代码生成。 |
x-simulated-tradingHeader | string必填 | 本场景固定 1,必须与模拟盘 Key 配套。 |
调用代码
替换示例 ID 与请求体内容后运行。
import base64, datetime, hashlib, hmac, json, os, urllib.request, urllib.error
# 只读模拟盘示例,环境与密钥不能混用。
key = os.environ["OKX_DEMO_API_KEY"]
secret = os.environ["OKX_DEMO_SECRET_KEY"]
passphrase = os.environ["OKX_DEMO_PASSPHRASE"]
host = os.environ.get("OKX_API_HOST", "https://www.okx.com")
allowed_hosts = {"https://www.okx.com", "https://us.okx.com"}
if host not in allowed_hosts:
raise SystemExit("请按所属地区核对文档中的官方 API 域名")
# 获取服务器时间,降低本机时钟漂移造成的错误。
try:
with urllib.request.urlopen(host + "/api/v5/public/time", timeout=20) as response:
clock = json.load(response)
if clock.get("code") != "0":
raise ValueError("服务器时间查询失败")
server_ms = int(clock["data"][0]["ts"])
timestamp = datetime.datetime.fromtimestamp(server_ms / 1000, datetime.timezone.utc).isoformat(timespec="milliseconds").replace("+00:00", "Z")
path = "/api/v5/account/balance?ccy=USDT"
message = timestamp + "GET" + path # GET 没有 body,query 必须包含在 path 中。
signature = base64.b64encode(hmac.new(secret.encode(), message.encode(), hashlib.sha256).digest()).decode()
req = urllib.request.Request(host + path, headers={
"OK-ACCESS-KEY": key,
"OK-ACCESS-SIGN": signature,
"OK-ACCESS-TIMESTAMP": timestamp,
"OK-ACCESS-PASSPHRASE": passphrase,
"x-simulated-trading": "1",
"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 result.get("code") != "0":
raise SystemExit(json.dumps(result, ensure_ascii=False))
print(json.dumps(result, ensure_ascii=False, indent=2))
返回示例
按官方结构整理的节选示意,非实测结果。data[0].totalEq 为账户美元权益,details[].ccy 是币种,cashBal 是现金余额,availBal 是可用余额;字段适用性依账户模式。 以下为结构示意,非本站实测结果。
{
"code": "0",
"msg": "",
"data": [
{
"totalEq": "1000",
"details": [
{
"ccy": "USDT",
"cashBal": "1000",
"availBal": "1000"
}
]
}
]
}常见错误与排查
50102请求时间戳超出服务端允许偏差- 核对 UTC、毫秒格式、网络延迟,重新取服务器时间后签名。
HTTP 401 / code 非 0认证或业务校验未通过- 核对模拟盘标识、Key 环境、Passphrase、IP 白名单和 msg,不打印 Secret 或签名原文中的秘密。
调用注意
- 签名的 UTC 时间戳必须与发送头完全一致;不要改动签名后 URL 参数顺序或编码。
- 这是交易账户 /account/balance;资金账户使用 /asset/balances,本例不调用。
- 代码固定模拟盘;不改成实盘、不提供交易下单。
注意事项
- 本页只查询,不下单、不划转、不提现。访问域名、账户与产品资格按所属服务地区确认。
- 行情读取无订单成交费用;频控、账户服务与实际交易费用是不同概念,不将公开查询解释为所有服务免费。
- 账户余额是私有数据;代码打印结果仅供自己本地检查,不应直接变成无需授权的公开接口。
核验来源
本站按官方资料整理本场景的必要调用步骤与代码,覆盖范围以本页列出的接口为准。官方资料用于追溯规范及查看变更。
- 01OKX API Key 权限与 REST 签名核验日期 2026-10-15
- 02OKX 模拟盘环境核验日期 2026-10-15
- 03OKX 交易账户余额核验日期 2026-10-15
