OKEx API接口详解：量化交易与数据分析指南
OKEx API 接口使用详解
OKEx (现更名为OKX) 作为全球领先的数字资产交易平台之一，拥有庞大的用户群体和极高的交易深度，为开发者提供了功能强大的 API 接口，方便他们访问实时市场数据、历史数据，并执行自动化交易策略。这些API 接口涵盖了现货交易、合约交易、期权交易等多种交易类型，满足不同开发者的需求。 熟练掌握 OKEx API 的使用，对于构建高效的量化交易策略、创建专业的数据分析平台、开发智能交易机器人以及其他与加密货币相关的创新型应用至关重要。 通过 API，开发者可以实现自动下单、风险控制、资金管理等功能，从而提升交易效率并降低人工操作的风险。 本文将以专业的视角，详细介绍 OKEx API 的各个方面，包括身份验证、数据请求、交易指令、错误处理等关键环节，帮助开发者快速上手，并深入了解其高级功能和最佳实践。
API 概览
OKX API 提供了全面的接口，覆盖了加密货币交易的各个环节，从获取实时市场行情到执行交易以及管理账户资产。 这些 API 主要分为以下几个类别，旨在满足不同层次开发者的需求，构建丰富的交易应用和策略：
公共 API: 提供无需身份验证即可访问的数据，例如行情信息、交易对信息、K 线数据等。API 接口采用 RESTful 风格，使用 HTTP 请求进行数据交互。 数据格式通常为 JSON 。
身份验证
访问 OKEx 私有 API 必须进行身份验证，这是为了确保只有授权用户才能访问其账户信息和执行交易操作。身份验证过程的核心在于生成一个精心构造的签名，该签名包含三个关键要素：您的 API Key（公共标识符）、Secret Key（私密密钥）以及 passphrase（可选但强烈推荐的安全短语）。这些要素协同工作，构成一个独特的、可验证的身份证明。
API Key 相当于您的用户名，用于标识您的账户。Secret Key 类似于您的密码，用于对请求进行签名，证明请求的合法性。Passphrase 则是在您创建 API Key 时设置的附加安全层，进一步增强账户的安全性。强烈建议设置并妥善保管您的 passphrase，以防止未经授权的访问。
获取 API Key、Secret Key 和 passphrase: 登录 OKEx 账户，在 API 管理页面创建 API Key。 创建时需要设置权限，例如只读权限、交易权限等。- 将请求参数按照字母顺序排序。
- 将排序后的参数拼接成字符串。
- 在字符串末尾添加时间戳（Unix 时间戳，单位为秒）。
- 使用 Secret Key 对拼接后的字符串进行 HMAC-SHA256 加密。
- 将加密后的结果转换为 Base64 编码。
OK-ACCESS-KEY: API KeyOK-ACCESS-SIGN: 生成的签名OK-ACCESS-TIMESTAMP: 时间戳OK-ACCESS-PASSPHRASE: 创建 API Key 时设置的 passphrase
公共 API 使用示例
获取当前交易对的行情信息
GET /api/v5/market/ticker?instId=BTC-USD-SWAP
此接口用于获取指定交易对的最新行情数据。通过提供交易对ID，可以实时查询该交易对的价格、成交量等信息，为交易决策提供数据支持。
请求参数：
-
instId: 交易对 ID，指定要查询的交易对。例如BTC-USD-SWAP表示比特币兑美元的永续合约。该参数是必需的，必须提供有效的交易对ID，否则请求将返回错误。 交易所支持的交易对ID列表通常可以在API文档或交易所网站上找到。
响应示例：
响应数据以JSON格式返回，包含交易对的详细行情信息。
{ "code": "0", "msg": "", "data": [ { "instId": "BTC-USD-SWAP", "last": "27000", "lastSz": "1", "askPx": "27000.5", "askSz": "10", "bidPx": "26999.5", "bidSz": "10", "open24h": "26500", "high24h": "27200", "low24h": "26400", "volCcy24h": "1000000", "vol24h": "37", "ts": "1678886400000", "sodUtc0": "26500", "sodUtc8": "26800" } ] }
字段解释：
-
code: 响应状态码，"0"表示成功，其他值表示错误。 -
msg: 响应消息，通常为空，错误时会包含错误信息。 -
data: 包含行情数据的数组，通常只有一个元素。 -
instId: 交易对 ID，与请求参数中的instId相同。 -
last: 最新成交价。 -
lastSz: 最新成交数量。 -
askPx: 卖一价（最优卖出价格）。 -
askSz: 卖一量（卖一价格对应的数量）。 -
bidPx: 买一价（最优买入价格）。 -
bidSz: 买一量（买一价格对应的数量）。 -
open24h: 24小时开盘价。 -
high24h: 24小时最高价。 -
low24h: 24小时最低价。 -
volCcy24h: 24小时成交量（以计价货币计价）。例如，如果交易对是 BTC-USD，则这是以美元计价的成交量。 -
vol24h: 24小时成交量（以基础货币计价）。 例如，如果交易对是 BTC-USD，则这是以BTC计价的成交量。 -
ts: 时间戳，表示数据生成的时间，以毫秒为单位的 Unix 时间戳。 -
sodUtc0: UTC 0时区当日开盘价。 -
sodUtc8: UTC 8时区当日开盘价（北京时间）。
获取 K 线数据
使用 GET 方法向指定的 API 端点发送请求，以获取加密货币的 K 线数据。以下是一个示例请求：
GET /api/v5/market/candles?instId=BTC-USD-SWAP&bar=1m&limit=100
请求参数：
-
instId: 交易对 ID，用于指定要获取 K 线数据的加密货币交易对。例如，BTC-USD-SWAP代表比特币与美元的永续合约交易对。 -
bar: K 线周期，定义每个 K 线的时间跨度。支持的周期包括：-
1m: 1 分钟 -
5m: 5 分钟 -
15m: 15 分钟 -
30m: 30 分钟 -
1h: 1 小时 -
2h: 2 小时 -
4h: 4 小时 -
6h: 6 小时 -
12h: 12 小时 -
1d: 1 天 -
1w: 1 周 -
1M: 1 月 -
3M: 3 个月
-
-
limit: 返回 K 线数据的数量上限。最大值为 1440。如果未指定此参数，则交易所可能会返回默认数量的 K 线数据。建议明确指定limit参数以确保获得期望的数据量。 -
after(可选): 返回此时间戳之后的数据，时间戳单位为毫秒。 -
before(可选): 返回此时间戳之前的数据，时间戳单位为毫秒。
响应示例：
以下是一个 JSON 格式的响应示例，展示了 K 线数据的结构：
{
"code": "0",
"msg": "",
"data": [
[
"1678886400000", // 开盘时间，Unix 时间戳（毫秒）
"26800", // 开盘价
"27000", // 最高价
"26700", // 最低价
"26900", // 收盘价
"37", // 成交量（张）
"1000000" // 成交额（美元）
],
[
"1678886460000", // 开盘时间，Unix 时间戳（毫秒）
"26900", // 开盘价
"27100", // 最高价
"26800", // 最低价
"27000", // 收盘价
"40", // 成交量（张）
"1100000" // 成交额（美元）
]
]
}
响应数据字段说明：
-
code: 响应状态码，"0"表示成功。 -
msg: 响应消息，通常为空字符串。 -
data: 包含 K 线数据的数组。数组中的每个元素代表一个 K 线，包含以下信息：- 时间戳 (毫秒): K 线开盘时间，使用 Unix 时间戳表示。
- 开盘价: 该 K 线周期的第一个成交价格。
- 最高价: 该 K 线周期内的最高成交价格。
- 最低价: 该 K 线周期内的最低成交价格。
- 收盘价: 该 K 线周期的最后一个成交价格。
- 成交量: 该 K 线周期内的成交量，单位通常为张或合约。
- 成交额: 该 K 线周期内的成交额，单位通常为基础货币（如美元）。
私有 API 使用示例
下单
使用
POST
方法向
/api/v5/trade/order
端点发送请求，可以提交新的交易订单。
请求体（
JSON
格式）：
{
"instId": "BTC-USD-SWAP",
"tdMode": "cash",
"side": "buy",
"ordType": "market",
"sz": "1",
"px": "可选，价格",
"posSide": "可选，多空方向，仅适用于单币永续合约。long：多仓，short：空仓",
"tpTriggerPx": "可选，止盈触发价",
"tpOrdPx": "可选，止盈委托价",
"slTriggerPx": "可选，止损触发价",
"slOrdPx": "可选，止损委托价",
"clOrdId": "可选，客户自定义订单ID，仅支持字母或数字，长度不超过32字符",
"tag": "可选，订单标签，仅支持字母或数字，长度不超过16字符",
"reduceOnly": "可选，是否只减仓，true 或 false，默认为 false"
}
请求参数说明：
-
instId: 必需 。交易对 ID，例如BTC-USD-SWAP，指定了交易的市场。 -
tdMode: 必需 。交易模式，用于指定账户模式。常用的模式包括cash(币币现货),cross(全仓杠杆),isolated(逐仓杠杆)。不同模式下的风险和收益有所不同。 -
side: 必需 。买卖方向，指示是买入 (buy) 还是卖出 (sell)。 -
ordType: 必需 。订单类型，定义了订单的执行方式。常用的类型包括market(市价单，立即以市场最优价格成交) 和limit(限价单，只有当市场价格达到指定价格时才成交)。 -
sz: 必需 。订单数量，指定了要交易的标的数量。需要根据交易对的精度要求进行设置。 -
px: 可选 。委托价格，仅在限价单 (limit) 模式下有效。 -
posSide: 可选 。持仓方向，仅适用于单币永续合约。可选值为long（多仓）或short（空仓）。用于指定开仓的方向。 -
tpTriggerPx: 可选 。止盈触发价格。当市场价格达到该价格时，将触发止盈订单。 -
tpOrdPx: 可选 。止盈委托价格。触发止盈后，将以该价格提交止盈订单。如果未填写，则会按照市价止盈。 -
slTriggerPx: 可选 。止损触发价格。当市场价格达到该价格时，将触发止损订单。 -
slOrdPx: 可选 。止损委托价格。触发止损后，将以该价格提交止损订单。如果未填写，则会按照市价止损。 -
clOrdId: 可选 。客户自定义订单 ID，用于方便用户跟踪订单。仅支持字母或数字，长度不超过 32 个字符。 -
tag: 可选 。订单标签，用于对订单进行分类或标记。仅支持字母或数字，长度不超过 16 个字符。 -
reduceOnly: 可选 。只减仓模式。如果设置为true，则该订单只能用于减少现有持仓，不能增加持仓。默认为false。
响应示例：
{
"code": "0",
"msg": "",
"data": [
{
"ordId": "1234567890",
"clOrdId": "",
"tag": "",
"sCode": "0",
"sMsg": ""
}
]
}
响应参数说明：
-
code: 返回码。"0"表示成功，其他值表示失败。 -
msg: 返回信息。通常为空字符串，如果发生错误，则包含错误描述。 -
data: 订单数据数组。 -
ordId: 订单 ID，由交易所生成。 -
clOrdId: 客户端自定义订单 ID。 -
tag: 订单标签。 -
sCode: 订单状态码。"0"表示成功。 -
sMsg: 订单状态信息。
撤单
POST
/api/v5/trade/cancel-order
用于取消尚未完全成交的订单。撤单操作会将订单从订单簿中移除，并释放冻结的保证金或资产。
请求体（JSON 格式）：
{
"instId": "BTC-USD-SWAP",
"ordId": "1234567890"
}
请求参数：
-
instId: 交易对 ID。指定需要撤销订单的交易品种，例如BTC-USD-SWAP代表比特币美元永续合约。请确保instId与要撤销的订单的交易对 ID 匹配，否则撤单操作可能会失败。 -
ordId: 订单 ID。需要撤销的订单的唯一标识符。订单 ID 由交易所生成，并在下单成功后返回。请确认提供的ordId是准确的，否则将无法找到要撤销的订单。
响应示例：
{
"code": "0",
"msg": "",
"data": [
{
"ordId": "1234567890",
"sCode": "0",
"sMsg": ""
}
]
}
响应参数说明：
-
code: 返回码。"0"表示撤单请求已成功提交至服务器。其他非零值代表发生了错误。 -
msg: 错误信息。当code不为"0"时，该字段会包含错误描述。 -
data: 包含撤单操作结果的数组。
data
数组中的对象参数说明：
-
ordId: 撤销的订单 ID。应该与请求参数中的ordId相同。 -
sCode: 单个订单的撤单状态码。"0"表示订单撤销成功。其他非零值代表撤单过程中出现了问题。 -
sMsg: 单个订单的撤单信息。当sCode不为"0"时，该字段会包含撤单失败的错误描述。
注意事项：
- 如果订单已经完全成交，则无法撤销。
- 撤单请求可能会因为网络延迟或其他原因而失败。在这种情况下，建议重试撤单操作。
-
请务必检查响应中的
code和sCode，以确认撤单操作是否成功。 - 高频撤单操作可能会触发交易所的风控策略，导致账户被限制。
获取账户余额
通过
GET /api/v5/account/balance
接口，您可以查询指定币种的账户余额信息。此接口提供账户总余额、可用余额和冻结余额等详细数据，帮助您全面掌握资金状况。
请求地址：
GET /api/v5/account/balance
请求参数：
-
ccy: 币种。指定需要查询余额的币种，区分大小写。例如：BTC（比特币）、ETH（以太坊）、USDT（泰达币）等。此参数为必填项。
请求示例：
要查询比特币 (BTC) 的账户余额，您需要发送以下请求：
GET /api/v5/account/balance?ccy=BTC
响应示例：
以下是一个成功的响应示例，展示了比特币 (BTC) 的账户余额信息：
{
"code": "0",
"msg": "",
"data": [
{
"ccy": "BTC",
"bal": "1.23456789",
"eq": "1.23456789",
"availBal": "1.23456789",
"lockedBal": "0"
}
]
}
响应字段解释：
-
code: 响应代码。"0"表示请求成功，其他值表示发生错误。 -
msg: 响应消息。当code不为"0"时，此字段包含错误信息。 -
data: 包含账户余额信息的数组。数组中的每个元素代表一种币种的余额信息。 -
ccy: 币种。与请求参数中的ccy对应，表示该条数据所代表的币种。 -
bal: 总余额。账户中该币种的总余额，包括可用余额和冻结余额。 -
eq: 等值余额。将该币种的余额折算成指定计价货币（通常为 USD）的等值金额，用于综合评估账户价值。 -
availBal: 可用余额。可以用于交易或转账的余额。 -
lockedBal: 冻结余额。由于挂单或其他原因被冻结的余额，不能用于交易或转账。
错误处理：
如果请求失败，
code
字段将返回非
"0"
的值，并且
msg
字段将包含错误信息。请根据错误信息进行问题排查和修复。
常见问题
-
什么是加密货币？
加密货币是一种使用密码学技术来保证安全性的数字或虚拟货币。它通常是去中心化的，意味着它不受政府或金融机构的控制。加密货币使用区块链技术，这是一种分布式账本，记录所有交易，使其透明且难以篡改。
加密货币的价值波动性较大，投资前应充分了解相关风险。常见的加密货币包括比特币（Bitcoin）、以太坊（Ethereum）、莱特币（Litecoin）和瑞波币（Ripple）等。
希望本文能够帮助您快速上手 OKEx API 的使用。 掌握 API 的使用技巧，可以更高效地进行数字资产交易和数据分析。