欧易 OKX调用手册

签名查询模拟盘交易账户余额

用 Read 权限的模拟盘 Key 查询 USDT 余额,包含时间校准与完整 HMAC 签名。

官方资料核对 2026-10-15示例代码,未进行真实接口实测
← 返回平台功能

接入准备

  • 拥有适用地区的合资格 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。

调用步骤

  1. 01

    进入模拟交易页面的 API 管理,创建模拟盘 Key;模拟盘 Key 与实盘 Key 不通用。

  2. 02

    将三个值分别设置为下方 OKX_DEMO_* 环境变量;按所属地区核对 OKX_API_HOST。

  3. 03

    运行 Python 3 代码,代码先取公开服务器时间,再对实际请求 path+query 计算签名,并固定发送 x-simulated-trading: 1。

  4. 04

    只有 HTTP 成功且 code=0 才读取 data[0].details;模拟资金账户与交易账户不是同一个余额接口。

调用 01

查询交易账户余额

签名是 Base64(HMAC-SHA256(secret, timestamp + GET + path含query + 空body));不是十六进制。

GEThttps://www.okx.com/api/v5/account/balance?ccy=USDT

请求头

x-simulated-trading
1
Accept
application/json

参数说明

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

字段 / 位置类型 / 必填说明
ccyQuerystring可选币种筛选,示例 USDT;不传为可返回的全部资产。
OK-ACCESS-*Headerstring必填Key、实时签名、UTC 毫秒时间戳和 Passphrase;由完整代码生成。
x-simulated-tradingHeaderstring必填本场景固定 1,必须与模拟盘 Key 配套。

调用代码

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

Python 3
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 是可用余额;字段适用性依账户模式。 以下为结构示意,非本站实测结果。

JSON
{
  "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,本例不调用。
  • 代码固定模拟盘;不改成实盘、不提供交易下单。

注意事项

  • 本页只查询,不下单、不划转、不提现。访问域名、账户与产品资格按所属服务地区确认。
  • 行情读取无订单成交费用;频控、账户服务与实际交易费用是不同概念,不将公开查询解释为所有服务免费。
  • 账户余额是私有数据;代码打印结果仅供自己本地检查,不应直接变成无需授权的公开接口。

核验来源

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

  1. 01
    OKX API Key 权限与 REST 签名核验日期 2026-10-15
  2. 02
    OKX 模拟盘环境核验日期 2026-10-15
  3. 03
    OKX 交易账户余额核验日期 2026-10-15

欧易 OKX的其他调用手册

← 返回欧易 OKX的全部功能