欧意交易所的API接口介绍
欧意交易所（OKX, formerly OKEx）提供了一套全面的应用程序编程接口（API），允许开发者以编程方式访问其平台，进行交易、数据查询以及账户管理等操作。 这些API为构建自动化交易策略、集成第三方应用以及分析市场数据提供了强大的工具。
API概览
欧易（OKX）交易所的应用程序编程接口（API）主要分为以下三大类，每类API服务于不同的目的，并具有不同的访问权限要求：
-
公共API (Public API)：
公共API提供无需身份验证即可访问的市场数据。这些API端点允许开发者获取各种实时和历史市场信息，例如：
- 实时价格： 获取指定交易对的最新成交价格。
- 交易历史： 查询历史成交记录，用于市场分析和趋势预测。
- 订单簿深度： 获取当前市场深度信息，包括买单和卖单的价格和数量，有助于评估市场流动性。
- K线数据： 获取不同时间周期的K线图数据，用于技术分析。
- 交易对信息： 查询交易所支持的交易对及其相关信息。
-
私有API (Private API)：
私有API用于账户管理和交易操作，因此需要身份验证才能访问。通过私有API，用户可以安全地进行以下操作：
- 下单： 创建限价单、市价单等各种类型的订单。
- 撤单： 取消尚未成交的订单。
- 查询账户余额： 获取账户中各种币种的可用余额和冻结余额。
- 查看交易记录： 查询历史交易记录，包括成交时间和交易价格等信息。
- 资金划转： 在不同账户之间划转资金，例如从交易账户划转到资金账户。
- API Key管理： 创建、修改和删除API Key，用于管理API访问权限。
-
WebSocket API：
WebSocket API提供实时数据流，允许开发者订阅市场数据和账户信息，从而实现低延迟的实时更新。相比于传统的REST API轮询方式，WebSocket API可以显著降低延迟，提高数据更新效率。通过WebSocket API，开发者可以：
- 订阅市场数据： 实时接收价格更新、成交记录、订单簿变化等信息。
- 订阅账户信息： 实时接收账户余额变动、订单状态更新等信息。
公共API
公共API允许开发者无需身份验证即可获取有关市场的实时和历史信息。这些API接口通常不需要API密钥或签名，方便快速集成和数据分析。以下是一些常用的公共API接口，涵盖了交易对信息、市场行情、K线数据、订单簿和历史成交记录：
-
获取交易对信息 (
GET /api/v5/public/instruments)： 获取所有可交易的交易对及其详细信息。这些信息包括交易对名称(instId)、基础货币(baseCcy)、报价货币(quoteCcy)、最小交易量(minSz)、价格精度(tickSz)、合约乘数(ctVal，适用于合约交易)等。该接口支持根据交易对类型(instType)进行过滤，常见的类型包括现货(SPOT)、永续合约(SWAP)、交割合约(FUTURES)、期权合约(OPTION)。通过此接口，开发者可以动态地获取平台支持的所有交易产品，并了解其交易规则。示例：
GET /api/v5/public/instruments?instType=SPOT -
获取市场行情 (
GET /api/v5/market/ticker)： 获取指定交易对的最新市场行情数据。这包括最新成交价(last)、最高价(high24h)、最低价(low24h)、24小时成交量(vol24h)、24小时成交额(volCcy24h)等关键指标。通过监控市场行情，开发者可以实时了解价格波动和交易活跃度。示例：
GET /api/v5/market/ticker?instId=BTC-USDT -
获取K线数据 (
GET /api/v5/market/candles)： 获取指定交易对的历史K线数据，用于技术分析和回测。开发者可以自定义时间周期(bar)，如1分钟(1m)、5分钟(5m)、15分钟(15m)、30分钟(30m)、1小时(1H)、4小时(4H)、1日(1D)、1周(1W)、1月(1M)。返回的数据包括开盘价(open)、最高价(high)、最低价(low)、收盘价(close)、成交量(vol)等。通过分析K线数据，可以识别价格趋势和潜在的交易机会。示例：
GET /api/v5/market/candles?instId=BTC-USDT&bar=1m -
获取订单簿数据 (
GET /api/v5/market/orderbook)： 获取指定交易对的实时订单簿数据，展示市场深度。订单簿包含买单(bids)和卖单(asks)的价格和数量信息。开发者可以指定订单簿的深度(sz)，即返回的订单数量，通常为前几档最优买卖盘。通过分析订单簿，可以了解市场的买卖力量和流动性。示例：
GET /api/v5/market/orderbook?instId=BTC-USDT&sz=20 -
获取历史成交数据 (
GET /api/v5/market/trades)： 获取指定交易对的历史成交记录。每条成交记录包含成交时间(ts)、成交价格(price)和成交数量(sz)等信息。通过分析历史成交数据，可以了解市场的交易活动和价格变化的细节。示例：
GET /api/v5/market/trades?instId=BTC-USDT
私有API
私有API允许开发者进行账户管理、交易操作、以及其他与账户相关的敏感功能。这些API的访问权限受到严格控制，通常需要通过API密钥和签名进行身份验证，以确保用户账户资产的安全性和数据隐私。开发者在使用私有API之前，务必仔细阅读API文档，了解安全规范和风险提示。
私有API通常用于构建自动化交易策略、量化交易系统、以及其他需要直接与交易所或平台进行交互的应用。以下是一些常用的私有API接口，涵盖了账户管理、订单管理、资金管理等关键功能：
-
获取账户余额 (GET /api/v5/account/balance)：
用于查询账户中各种加密货币的余额信息，包括可用余额、冻结余额和总余额。该接口通常支持指定币种查询，也支持查询所有币种余额的汇总信息。返回的数据格式通常包含币种代码、余额数量、以及其他相关信息。
示例：
GET /api/v5/account/balance?ccy=USDT -
下单 (POST /api/v5/trade/order)：
用于创建新的交易订单。通过该接口，可以指定交易对（例如BTC-USDT）、订单类型（例如市价单、限价单、止损单）、买卖方向（买入或卖出）、订单数量和价格。不同的订单类型有不同的参数要求，例如限价单需要指定价格，市价单则不需要。务必根据实际需求选择合适的订单类型，并正确设置相关参数。
示例：
POST /api/v5/trade/order { "instId": "BTC-USDT", "tdMode": "cash", "side": "buy", "ordType": "limit", "px": "30000", "sz": "0.01" }参数说明：
instId表示交易对，tdMode表示交易模式（例如现货cash、杠杆cross/isolated），side表示买卖方向（buy/sell），ordType表示订单类型（limit/market/stop），px表示价格（仅限价单需要），sz表示数量。 -
撤单 (POST /api/v5/trade/cancel-order)：
用于撤销尚未完全成交的订单。该接口需要指定要撤销的订单ID。撤单操作通常是即时的，但有时可能会受到网络延迟或其他因素的影响。在撤单后，应立即查询订单状态，确认撤单是否成功。
示例：
POST /api/v5/trade/cancel-order { "instId": "BTC-USDT", "ordId": "1234567890" }参数说明：
instId表示交易对，ordId表示要撤销的订单ID。 -
获取订单详情 (GET /api/v5/trade/order)：
用于查询指定订单的详细信息。返回的信息包括订单状态（例如未成交、部分成交、完全成交、已撤销）、成交数量、成交价格、下单时间等。该接口可以帮助开发者了解订单的执行情况，并进行相应的处理。
示例：
GET /api/v5/trade/order?instId=BTC-USDT&ordId=1234567890参数说明：
instId表示交易对，ordId表示要查询的订单ID。 -
获取历史订单 (GET /api/v5/trade/orders-history)：
用于查询历史订单记录。该接口通常支持根据时间范围、交易对、订单状态等条件进行过滤。开发者可以利用该接口分析历史交易数据，优化交易策略，或进行风险管理。
示例：
GET /api/v5/trade/orders-history?instId=BTC-USDT&begin=1672531200000&end=1672617600000参数说明：
instId表示交易对，begin表示起始时间戳（毫秒），end表示结束时间戳（毫秒）。
WebSocket API
WebSocket API 提供实时、双向的数据流通道，它允许开发者订阅加密货币交易所的市场数据和账户信息，无需持续轮询。 相较于传统的 REST API，WebSocket 连接能够显著降低延迟，实现毫秒级的实时更新，非常适用于构建需要高速响应的交易系统、实时监控面板、以及自动化交易机器人。 这种技术对于需要捕捉市场瞬息变化的场景至关重要。
-
订阅市场行情 (subscribe market data)：
订阅指定交易对的最新成交价、最高价、最低价、24 小时成交量、以及其他关键市场指标等行情数据。 开发者可以通过定制订阅内容，仅接收所需的数据，从而优化带宽利用率和降低系统负载。 实时行情数据对于算法交易和套利策略至关重要。
以下是一个订阅 BTC-USDT 交易对的 tickers 频道的 JSON 示例：
{ "op": "subscribe", "args": [ { "channel": "tickers", "instId": "BTC-USDT" } ] } -
订阅 K 线数据 (subscribe K-line data)：
订阅指定交易对的 K 线数据，K 线图是技术分析的基础。 可以指定不同的时间周期，例如 1 分钟 (candle1m)、5 分钟 (candle5m)、1 小时 (candle1h) 或 1 天 (candle1D) 等。 不同的时间周期适用于不同的交易策略，短周期适合日内交易，长周期适合趋势跟踪。 历史 K 线数据对于回测交易策略至关重要。
以下是一个订阅 BTC-USDT 交易对 1 分钟 K 线数据的 JSON 示例：
{ "op": "subscribe", "args": [ { "channel": "candle1m", "instId": "BTC-USDT" } ] } -
订阅订单簿数据 (subscribe orderbook data)：
订阅指定交易对的订单簿数据，包括买单和卖单的价格和数量。 订单簿数据反映了市场的买卖力量，对于高频交易者和做市商至关重要。 通过分析订单簿的深度和分布，可以预测价格的短期走势和流动性状况。 订阅的深度通常可以配置，以控制数据量。
以下是一个订阅 BTC-USDT 交易对订单簿数据的 JSON 示例：
{ "op": "subscribe", "args": [ { "channel": "books", "instId": "BTC-USDT" } ] } -
订阅账户信息 (subscribe account information)：
订阅账户余额和交易相关的更新信息，例如资金变动、可用余额、已用余额等。 为了安全起见，订阅账户信息通常需要进行身份验证，以确保只有账户所有者才能访问敏感数据。 账户信息对于监控风险和管理投资组合至关重要。
以下是一个订阅 USDT 账户信息的 JSON 示例：
{ "op": "subscribe", "args": [ { "channel": "account", "ccy": "USDT" } ] } -
订阅订单更新信息 (subscribe order updates)：
订阅订单状态的实时更新信息，包括订单创建、订单成交、订单取消等。 通过订阅订单更新，开发者可以及时掌握订单的执行情况，并根据市场变化快速调整交易策略。 订单更新通常包含订单 ID、订单价格、订单数量、订单状态、成交价格、成交数量等详细信息。
以下是一个订阅 BTC-USDT 交易对订单更新信息的 JSON 示例：
{ "op": "subscribe", "args": [ { "channel": "orders", "instId": "BTC-USDT" } ] }
身份验证
访问私有REST API和WebSocket API需要进行身份验证，以确保只有授权用户才能访问敏感数据和执行交易。身份验证过程涉及密钥管理、签名生成和请求头设置，具体步骤如下：
- 获取API密钥： 在欧易（OKX）交易所的账户安全设置或API管理页面创建API密钥。创建时务必仔细设置API密钥的权限，权限范围应根据实际需求进行最小化配置，例如交易、提现、查看账户信息等。为了安全起见，建议定期轮换API密钥。不同权限的API Key应分开管理，避免一个Key泄露导致所有权限被滥用。
- 生成签名： 使用API密钥中的Secret Key对HTTP请求或WebSocket消息的请求参数进行签名。签名算法通常采用HMAC-SHA256，但也可能根据交易所的具体要求有所不同。签名过程需要包含请求的HTTP方法（如GET, POST, PUT, DELETE）、规范化的请求路径（去除多余斜杠，并确保编码一致）、时间戳（UTC时间，通常为秒级）和请求体（如果存在）。签名的目的是验证请求的完整性和真实性，防止请求被篡改。详细的签名算法实现细节请参考欧易官方API文档。
-
添加请求头：
将API密钥的Public Key（也称为API Key）、生成的签名和时间戳添加到HTTP请求头中。对于WebSocket API，则在连接建立后，将认证信息封装在特定的JSON格式消息中发送。具体需要添加的请求头字段如下：
-
OK-ACCESS-KEY: API密钥的Public Key，用于标识请求的发送者。 -
OK-ACCESS-SIGN: 使用Secret Key生成的签名，用于验证请求的完整性和真实性。务必保证签名生成的正确性，否则请求将被拒绝。 -
OK-ACCESS-TIMESTAMP: 当前时间戳（UTC时间，精确到秒级），用于防止重放攻击。服务器会验证时间戳是否在允许的时间窗口内。 -
OK-ACCESS-PASSPHRASE: 创建API密钥时设置的Passphrase，用于增加安全性。如果创建API Key时没有设置Passphrase，则无需添加此Header。
-
例如，一个POST请求的请求头可能如下所示。请注意，这只是一个示例，实际值需要替换为你自己的API密钥、签名和时间戳：
OK-ACCESS-KEY: YOUR_API_KEY
OK-ACCESS-SIGN: YOUR_SIGNATURE
OK-ACCESS-TIMESTAMP: 1678886400
OK-ACCESS-PASSPHRASE: YOUR_PASSPHRASE
对于WebSocket API，需要在建立连接后立即发送一个认证消息。此消息必须符合交易所规定的格式，并且包含有效的API密钥、时间戳和签名。以下是一个示例：
{
"op": "login",
"args": [
{
"apiKey": "YOUR_API_KEY",
"timestamp": "1678886400",
"sign": "YOUR_SIGNATURE",
"passphrase": "YOUR_PASSPHRASE"
}
]
}
请务必仔细阅读欧易官方API文档，了解最新的身份验证要求和最佳实践。不正确的身份验证会导致请求失败，甚至可能导致账户被限制。
错误处理
在使用欧意交易所API进行交互时，开发者不可避免地会遇到各种错误。这些错误可能源于多种原因，例如网络问题、数据格式错误、权限不足或服务器故障。欧意交易所的API通常会通过返回带有特定错误码和详细错误消息的JSON对象来指示错误。开发者应充分利用这些信息，以便快速诊断和解决问题。
常见的API错误及其潜在原因：
- 400 Bad Request：请求参数错误。 这意味着发送到API的数据格式不正确、缺少必需的参数或参数值无效。例如，可能提供了非法的交易对代码，或数量超出了允许的范围。开发者应仔细检查请求的各个部分，确保所有参数都符合API文档的规范。
- 401 Unauthorized：身份验证失败。 此错误表明提供的API密钥无效或已过期。在使用API之前，需要确保已正确配置API密钥，并且密钥具有足够的权限来访问请求的资源。还需要检查是否正确计算了签名，签名是验证请求完整性和身份的关键。
- 403 Forbidden：没有权限访问该接口。 即使身份验证成功，也可能因为缺少必要的权限而无法访问某些API端点。欧意交易所的API权限控制非常精细，开发者应仔细阅读API文档，了解每个端点所需的权限，并在创建API密钥时正确配置权限。
- 429 Too Many Requests：请求频率过高，触发了限流。 为了保护系统稳定性，欧意交易所对API请求频率进行了限制。当请求频率超过允许的阈值时，API会返回此错误。开发者应实施速率限制策略，例如使用队列或令牌桶算法，以控制API请求的频率，避免触发限流。API文档通常会详细说明每个端点的请求频率限制，以及如何优雅地处理限流错误。
- 500 Internal Server Error：服务器内部错误。 此错误表明欧意交易所的服务器在处理请求时遇到了意外的错误。这通常是临时的，可能与服务器负载过高或软件故障有关。开发者可以稍后重试请求。如果错误持续发生，应联系欧意交易所的客服报告问题。
当遇到API错误时，建议采取以下步骤进行排查：
- 仔细检查请求参数： 确保所有参数都符合API文档的规定，包括数据类型、格式、范围和必填项。
- 验证API密钥的有效性： 确认API密钥是否已过期、被禁用或缺少必要的权限。
- 检查签名是否正确： 确保请求的签名是使用正确的算法和密钥计算的，并且包含了所有必需的参数。
- 评估请求频率： 确认请求频率是否超过了API的限制。可以使用延迟或队列来限制请求频率。
- 查看API文档和错误代码： 详细阅读API文档，了解错误代码的含义和可能的解决方案。
如果经过以上排查仍然无法解决问题，建议及时联系欧意交易所的客服团队，提供详细的错误信息、请求参数和相关日志，以便他们能够更好地帮助您解决问题。
最佳实践
- 安全性： API密钥是访问加密货币交易所或服务的关键凭证，务必妥善保管，避免泄露。绝对不要将API密钥硬编码到应用程序的代码中，更不要将API密钥存储在公开的代码库（如GitHub）中。考虑使用环境变量、配置文件或专门的密钥管理服务来安全地存储和访问API密钥。定期轮换API密钥，降低密钥泄露带来的风险。启用API密钥的两步验证（如果交易所支持），增加一层安全防护。
- 限流： 加密货币交易所通常会对API请求进行限流，以防止滥用和保证系统稳定性。在使用API之前，务必仔细阅读交易所的API文档，了解其限流规则（例如，每分钟允许请求的次数、每个IP地址允许请求的次数等）。根据限流规则调整你的请求频率，避免频繁请求触发限流机制。使用指数退避算法或重试机制来处理被限流的请求，避免程序崩溃或数据丢失。
- 错误处理： 在调用加密货币API时，可能会遇到各种错误情况（例如，网络连接错误、无效的API密钥、请求参数错误等）。务必完善错误处理机制，能够正确地捕获和处理这些错误。记录错误日志，方便调试和排查问题。向用户提供友好的错误提示信息，避免用户感到困惑。针对不同的错误类型，采取不同的处理方式（例如，重试、忽略、终止程序等）。
- 数据验证： 加密货币API返回的数据可能存在错误或不完整的情况（例如，价格数据错误、交易记录丢失等）。在使用API返回的数据之前，务必进行验证，确保数据的准确性和完整性。验证数据的格式是否正确、数据的取值范围是否合理、数据的一致性是否满足要求。如果发现数据存在问题，及时向交易所报告，并采取相应的措施（例如，忽略错误数据、重新请求数据等）。
- 异步处理： 调用加密货币API通常需要花费一定的时间，如果同步调用API，可能会阻塞主线程，导致程序响应缓慢甚至卡死。因此，建议使用异步处理方式来调用API。可以使用线程、协程或消息队列等技术来实现异步处理。将API调用放在后台线程或协程中执行，避免阻塞主线程。使用回调函数或Promise来处理API调用的结果。
- 监控： 对API请求进行监控，可以及时发现和解决问题。监控API请求的响应时间、错误率、请求次数等指标。使用监控工具（例如，Prometheus、Grafana等）来可视化监控数据。设置报警规则，当监控指标超过阈值时，及时发送报警通知。分析监控数据，找出API使用的瓶颈和问题，并进行优化。