欧易全球站API接口文档 - 实时交易数据与账户管理

时间：2025-02-07 03:05:14 分类：知识库阅读：79

欧易全球站API接口文档

一、API概述

欧易全球站（OKX）为用户提供了功能全面、灵活高效的API接口，旨在简化用户的程序化交易和数据获取过程，提升交易效率。通过API接口，用户可以实时获取交易平台的数据，包括市场行情、历史交易记录、账户余额等信息，同时还可以执行各类交易操作，如买入、卖出、查询订单状态等。这些API接口设计精细，能够满足不同用户的需求，从个人投资者到机构客户都可以通过API接口实现自动化交易和数据分析。

欧易API接口遵循RESTful风格，支持HTTP协议，易于与各类编程语言和开发框架兼容，确保广泛的适用性和可操作性。API接口支持GET、POST、DELETE等常见的HTTP方法，能够灵活应对不同的操作需求。在进行API请求时，用户通过OAuth2.0协议进行身份认证，确保交易和数据请求的安全性与隐私保护。API在响应时返回的数据格式为JSON，便于开发者进行解析和处理。

为了提供高效的服务，欧易API接口提供了多个端点，用户可以根据自己的需求选择不同的接口来获取市场数据、进行资金管理、处理订单等。同时，接口设计考虑到高并发场景，具备快速响应的能力，支持大规模的自动化交易系统和算法交易平台。平台还提供详细的API文档，包括参数说明、请求示例和错误处理信息，帮助开发者轻松集成并解决可能出现的问题。

欧易API接口的广泛应用场景包括但不限于高频交易、量化策略执行、数据分析与监控、交易策略的自动化执行等。借助这些接口，用户可以根据实时行情做出决策，最大化交易收益。同时，API接口还支持对账户余额、订单信息、交易历史等进行全面管理，帮助用户更好地进行风险控制和资金调度。

2.3 请求方式

所有API请求均通过HTTPS协议进行传输，以确保数据的加密与安全性。每个请求必须在请求头中包含API Key和Signature，以验证请求的合法性与完整性，同时防止未经授权的访问和篡改。API Key是唯一的身份标识符，代表特定用户或应用程序，并用于对请求进行身份认证。Signature是基于API Key、请求参数和私钥生成的加密签名，用于确保请求未被篡改，并验证请求者的合法性。Timestamp是请求的时间戳，用于防止重放攻击。

请求头应当包含以下字段：
Content-Type: application/
API-KEY:
Signature:
Timestamp:
注意：其中，Content-Type表示请求的内容类型，通常为application/，除非API文档中明确指定其他格式；API-KEY用于标识API请求者，Signature是通过特定算法（如HMAC-SHA256）基于API Key、请求体内容、Timestamp以及私钥生成的哈希值；Timestamp用于确保请求在特定时间范围内有效。

3.1 市场数据接口

欧易全球站为用户提供了一系列市场数据接口，涵盖实时市场行情、历史交易数据和深度数据等信息，满足不同用户的需求。实时市场行情接口能够提供包括各类数字货币的最新价格、涨跌幅、成交量等实时数据，这些数据帮助用户监控市场动态并作出及时决策。历史数据接口允许用户查询特定时间范围内的市场走势，数据包括开盘价、收盘价、最高价、最低价等关键交易指标，适用于技术分析和历史趋势回测。深度数据接口则提供了交易所的订单簿信息，包括买卖挂单价格和数量，使得用户能够实时了解市场流动性及价格波动情况。这些接口支持高频数据请求，确保数据的及时性和准确性，适合算法交易、量化分析等高要求应用。

3.1.1 获取最新市场行情

接口地址：

GET /api/v5/market/ticker

请求参数：

| 参数名 | 类型 | 必填 | 说明 | |--------------|--------|-------|-------------------------------| | instId | string | 是 | 交易对的唯一标识符，表示交易对的名称，例如 BTC-USDT，USDT是美元稳定币，BTC是比特币。 | | uly | string | 否 | 合约对的标识符，用于指定合约市场的相关信息，若为空则默认查询现货市场数据。此参数适用于期货及永续合约市场。此字段非必需，只有在需要查询特定合约的市场数据时使用。 |

返回示例：

{ "code": "0", "data": [ { "instId": "BTC-USDT", "last": "45000.00", "high24h": "46000.00", "low24h": "44000.00", "vol24h": "1500.0" } ] }

返回字段说明：

| 字段名 | 类型 | 说明 | |------------|--------|--------------------------------| | instId | string | 交易对的标识符，例如 BTC-USDT，指示交易对的名称。此字段帮助识别查询的数据属于哪个交易对。 | | last | string | 最新成交价格，表示当前交易对的最新市场价格。例如，BTC-USDT的last为45000.00时，说明比特币的最新成交价格为45000 USDT。 | | high24h | string | 过去24小时内的最高交易价格，反映市场在最近24小时内的最高交易价。对于BTC-USDT，假设为46000.00，说明该交易对在过去24小时内的最高交易价格为46000 USDT。 | | low24h | string | 过去24小时内的最低交易价格，反映市场在最近24小时内的最低交易价。若BTC-USDT的low24h为44000.00，表示在过去24小时内最低成交价格为44000 USDT。 | | vol24h | string | 过去24小时内的交易量，表示过去24小时内交易对的总成交数量。例如，BTC-USDT的vol24h为1500.0，意味着在过去24小时内共成交了1500个比特币。 |

注意事项：

1. 返回的价格数据为精确到小数点后两位的浮动值。
2. 返回的数据会根据交易所的实时行情更新，因此，数据可能会有波动，实时价格可能与提供的24小时数据有所差异。
3. 如果请求的交易对在市场中不可用或未开启，接口将返回相应的错误码和错误信息，开发者可以根据返回的错误码进行适当的处理。
4. 在使用此接口时，务必确保提供正确的交易对ID（instId），否则可能无法获取有效的行情数据。 |

3.1.2 获取历史K线数据

接口地址：

GET /api/v5/market/candles

请求参数：

| 参数名 | 类型 | 必填 | 说明 | |--------------|--------|-------|-------------------------------------------------| | instId | string | 是 | 交易对的ID，用于指定要查询的市场交易对。例如，BTC-USDT代表比特币与USDT的交易对。 | | bar | string | 是 | K线数据的时间周期，支持多种周期设置，如1m（1分钟）、5m（5分钟）、1h（1小时）、1d（日线）等。| | after | string | 否 | 从某个特定时间戳开始获取数据，时间戳以毫秒为单位。如果未指定，则默认返回最新的K线数据。 | | before | string | 否 | 获取某个特定时间戳之前的数据，时间戳以毫秒为单位。如果未指定，则默认返回最新的K线数据。此参数与“after”参数不能同时使用。|

返回示例：

成功响应示例：

{ "code": "0", "data": [ { "timestamp": "1622125200000", "open": "45000.00", "high": "46000.00", "low": "44000.00", "close": "45500.00", "vol": "100.0" } ] }

返回参数说明：

| 参数名 | 类型 | 说明 | |--------------|---------|-------------------------------------------| | timestamp | string | K线的时间戳，单位为毫秒。表示该K线对应的时间点。| | open | string | K线的开盘价，表示该时间周期开始时的交易价格。| | high | string | K线的最高价，表示该时间周期内的最高成交价格。| | low | string | K线的最低价，表示该时间周期内的最低成交价格。| | close | string | K线的收盘价，表示该时间周期结束时的交易价格。| | vol | string | 该时间周期内的交易量，单位为基础货币。例如，BTC的交易量。|

错误响应示例：

{ "code": "400", "msg": "参数错误：参数instId不能为空" }

错误响应说明：

当请求参数不符合要求时，接口会返回错误信息。例如，如果缺少必要的“instId”参数，返回类似于以下内容：

{ "code": "400", "msg": "缺少必要的参数instId" }

3.2 账户信息接口

用户可以通过API接口获取账户的详细信息，包括账户余额、历史订单记录、已完成的交易历史、挂单情况等。该接口提供了多种查询功能，允许用户实时查看自己的资产状况。具体功能包括获取不同类型资产的可用余额和冻结余额，查询不同币种的交易记录、订单状态以及手续费详情。用户可以通过该接口轻松管理个人账户的所有交易活动，帮助用户及时了解资金流动、挂单执行状态、以及未结算订单的具体情况。账户信息接口的设计提供了灵活的数据筛选选项，支持按时间、交易对、订单类型等多种条件筛选，确保用户能够快速获取到所需的详细数据。

3.2.1 获取账户余额

接口地址：

GET /api/v5/account/balance

请求参数：

| 参数名 | 类型 | 必填 | 说明 | |--------------|--------|-------|--------------------------------------------------------------| | ccy | string | 否 | 币种，指定查询余额的币种，例如USDT、BTC等。如果不传该参数，接口将返回账户中所有支持的币种的余额信息。 |

返回示例：

{ "code": "0", "data": [ { "ccy": "USDT", "avail": "1000.00", "frozen": "0.00" }, { "ccy": "BTC", "avail": "0.5", "frozen": "0.0" } ] }

返回参数说明：

| 参数名 | 类型 | 说明 | |--------------|--------|------------------------------------------------------------| | code | string | 响应码，0表示请求成功，其他值表示请求失败或出现错误。 | | data | array | 返回的账户余额信息数组，包含每个币种的余额数据。 | | ccy | string | 币种的名称，如USDT、BTC等。 | | avail | string | 可用余额，表示该币种可供交易、提现等操作的余额数量。 | | frozen | string | 冻结余额，表示该币种由于某些原因（如未完成的交易）暂时无法使用的余额。 |

详细说明：

此接口用于获取账户的余额信息，支持指定币种或返回所有支持币种的余额。通过传入"ccy"参数，用户可以查询特定币种的余额。如果未提供币种参数，接口将返回账户中所有支持的币种余额信息，包括可用余额（avail）和冻结余额（frozen）。可用余额是指可以用于交易、提取等操作的余额，而冻结余额是指由于某些操作而暂时无法使用的余额。冻结余额可能包括未完成的订单、保证金要求或其他系统限制。根据返回的响应码（code），用户可以判断接口请求是否成功，若返回code为"0"则表示请求成功，若为其他值则表示请求失败或发生错误。|

3.2.2 获取账户资金流水

接口地址：

GET /api/v5/account/ledger

请求参数：

| 参数名 | 类型 | 必填 | 说明 | |--------------|--------|-------|------------------------------------------------| | ccy | string | 否 | 币种，默认值为USDT。用于指定查询的资金流水的币种。如果不传入该参数，将默认返回USDT的相关流水数据。 | | after | string | 否 | 用于指定获取数据的起始时间，格式为时间戳（毫秒级）。从该时间戳之后的资金流水数据将会被返回。 | | before | string | 否 | 用于指定获取数据的结束时间，格式为时间戳（毫秒级）。返回该时间戳之前的所有资金流水数据。 | | limit | integer | 否 | 用于限制返回的结果数量，默认为100，最大值为200。指定返回的资金流水的最大条数。 | | cursor | string | 否 | 用于分页查询，返回上一页的游标值。结合 `limit` 参数使用，可以进行分页请求。 | | type | string | 否 | 用于过滤返回的资金流水类型，可选值为：`deposit`（充值）、`withdrawal`（提现）、`transfer`（内部转账）。如果未传入该参数，默认返回所有类型的资金流水。 | | subAccount | string | 否 | 子账户标识符，若指定子账户，则仅返回该子账户的资金流水数据。 | | instType | string | 否 | 币种类型，可选值为：`SPOT`（现货），`FUTURES`（期货），`MARGIN`（保证金账户），`SWAP`（永续合约）。用于指定查询的账户类型，若未提供，则返回所有类型的资金流水。 |

返回示例：

{ "code": "0", "data": [ { "ccy": "USDT", "amt": "1000.00", "transId": "1234567890", "ts": "1622125200000", "type": "deposit", "fee": "0.00", "status": "success" } ] }

字段说明：

ccy: 资金流水对应的币种。例如，USDT 表示该交易涉及的是 USDT。此字段有助于区分不同币种的流水记录。
amt: 资金流水的金额。表示账户发生的交易或转账金额，单位与币种一致。
transId: 交易的唯一标识符。每个资金流水都会生成一个唯一的交易 ID，可以用于追踪和查询详细的交易信息。
ts: 时间戳，单位为毫秒，表示资金流水的发生时间。可通过该时间戳进行数据排序和筛选。
type: 资金流水的类型，常见的类型有 `deposit`（充值）、`withdrawal`（提现）、`transfer`（内部转账）。根据类型可以区分资金的流向。
fee: 手续费，表示本次交易的相关手续费。如果没有手续费，则为 `0.00`。
status: 交易的状态，通常包括 `success`（成功）、`failed`（失败）等。用于表示该资金流水是否成功执行。

注意事项：

时间戳字段（`ts`）遵循毫秒级格式，使用时应确保正确转换为实际时间，便于进一步分析和处理。
根据请求参数的 `limit`、`after`、`before` 以及 `cursor` 配合使用，可以高效地进行分页查询，避免单次请求返回过多数据。
对于高频交易或者大额交易，务必根据实际需求设置合理的查询范围，避免过多无关数据干扰分析结果。
若返回数据较大或查询条件过于宽泛，可能导致接口响应时间变长，请根据实际情况调整查询条件。

3.3 交易接口

欧易全球站为用户提供多种交易接口，满足不同交易需求，涵盖现货交易、杠杆交易和期货交易等多个交易品种。现货交易接口支持用户进行各种数字资产的即时交易，能够实现资产的即时交割和结算，提供低延迟的交易体验。杠杆交易接口为用户提供了更高的资金使用效率，支持多倍杠杆，允许用户在市场波动中通过借贷资金扩大交易规模，进行更具风险性和高回报的投资策略。期货交易接口则提供了更多的衍生品交易功能，支持用户通过买卖期货合约进行资产的价格预测和风险管理，提供灵活的杠杆操作与自动化交易功能。所有交易接口均具备高频交易能力，具有强大的API支持，确保用户在高交易量环境下依旧能够稳定、快速地执行交易操作，满足专业交易者和机构用户的需求。

3.3.1 下单接口

接口地址：

POST /api/v5/trade/order

请求参数：

| 参数名 | 类型 | 必填 | 说明 | |--------------|--------|-------|---------------------------------------------------------| | instId | string | 是 | 交易对的ID，用于标识交易市场。例如，BTC-USDT 代表比特币和美元的交易对。| | tdMode | string | 是 | 交易模式，确定订单所执行的交易类型。现货交易使用“cash”，杠杆交易使用“cross”。| | side | string | 是 | 订单方向，定义交易的买入或卖出行为。买入操作为“buy”，卖出操作为“sell”。 | | ordType | string | 是 | 订单类型，用于定义订单的执行方式。市价单使用“market”，限价单使用“limit”。 | | sz | string | 是 | 订单数量，表示买入或卖出的资产数量。在市价单中，这个参数是必须的，而在限价单中，可以根据价格灵活调整。 | | px | string | 否 | 限价单的价格，仅在订单类型为“limit”时有效。此参数用于指定买入或卖出的限价价格。如果订单类型为“market”，则不需要提供此参数。|

返回示例：

{ "code": "0", "data": [ { "ordId": "9876543210", "instId": "BTC-USDT", "side": "buy", "sz": "0.1", "px": "45000.00" } ] }

返回说明：

返回的JSON对象包含以下字段：

code: 返回状态码，成功时为“0”，表示请求成功。
data: 返回数据，包含订单详情的数组。每个订单对象包含：

ordId: 订单ID，唯一标识该订单。
instId: 交易对的ID，指明该订单涉及的交易对。例如，BTC-USDT。
side: 订单方向，买入为“buy”，卖出为“sell”。
sz: 订单的数量，表示此次交易的买入或卖出资产数量。
px: 订单价格，仅在限价单中提供。对于市价单，这个字段可能为空。

错误码：

如果请求失败，返回的“code”字段将包含非“0”的错误码。常见错误码如下：

10001: 参数错误，通常是因为必填参数缺失或格式不正确。
10002: 账户余额不足，无法执行交易。
10003: 交易对不存在，确保提供正确的交易对ID。
10004: 交易所无法处理该请求，可能是由于交易模式或订单类型不支持。

注意事项：

1. 对于市价单，用户不需要提供“px”参数，系统将自动根据市场价格执行交易。

2. 对于限价单，若提供的“px”价格不合理（例如，过高或过低），交易可能会失败或未能完全成交。

3. 在杠杆模式下（tdMode 为“cross”），需确保账户的杠杆额度和余额足够支持该交易。

4. 下单接口的返回结果中将提供订单的基本信息，但可能需要进一步查询订单状态以获取更详细的交易结果。

3.3.2 查询订单状态

接口地址：

GET /api/v5/trade/order

请求参数：

| 参数名 | 类型 | 必填 | 说明 | |--------------|--------|-------|-----------------------------------------------| | instId | string | 是 | 交易对的唯一标识符，用于标识所交易的数字资产对。例如 BTC-USDT，其中 "BTC" 代表比特币，"USDT" 代表泰达币。 | | ordId | string | 是 | 订单的唯一标识符，每个订单都会生成一个唯一的订单ID，供用户查询订单状态时使用。该ID在创建订单时由系统分配。 |

返回示例：

{ "code": "0", "data": [ { "ordId": "9876543210", "instId": "BTC-USDT", "side": "buy", "sz": "0.1", "px": "45000.00", "state": "filled" } ] }

返回字段说明：

| 字段名 | 类型 | 说明 | |-----------|---------|---------------------------------------------------------------| | ordId | string | 订单ID，唯一标识一个订单，用于与用户的订单记录进行匹配。 | | instId | string | 交易对的ID，表示该订单涉及的交易市场对，例如 BTC-USDT。 | | side | string | 订单的类型，表示该订单是买单（buy）还是卖单（sell）。 | | sz | string | 订单的交易数量，表示用户希望买入或卖出的数量。 | | px | string | 订单价格，表示用户设置的交易价格。 | | state | string | 订单的当前状态，表示订单是否已被完全填充、部分填充或未被填充。常见的状态包括 'filled'（已完全填充）、'partially_filled'（部分填充）、'open'（未填充）。 |

返回状态码说明：

| 状态码 | 说明 | |---------|-------------------------------------------------------| | 0 | 请求成功，返回的数据包含查询到的订单信息。 | | 10001 | 请求失败，可能是由于传递的参数无效或格式不正确。 | | 10002 | 未知错误，可能是系统问题导致的错误。 |

该接口用于查询特定订单的详细信息，并提供订单状态、数量、价格等关键数据。根据返回的订单状态，用户可以判断其订单是否已完全执行、部分执行或还未处理。此接口常用于交易策略监控和订单执行情况的跟踪。

四、错误处理

在调用API时，开发者可能会遇到多种错误情况，这些错误可能来源于请求参数的格式不正确、权限不足、API服务器故障、网络问题等。为了帮助开发者快速定位和修复问题，API接口会返回详细的错误码和错误信息。这些错误码通常遵循一定的标准，以便开发者能够根据返回的代码类型做出合理的错误处理和调试。

常见的错误码包括但不限于：400（请求错误）、401（未授权）、403（禁止访问）、404（资源未找到）、500（服务器内部错误）、502（网关错误）、503（服务不可用）。每个错误码通常伴随有一段具体的错误描述，帮助开发者明确错误发生的原因和解决方向。

在一些情况下，错误信息可能还包含更具体的描述，例如缺少必填参数、请求超时或请求频率过高等，这些信息可以有效地指导开发者在修复错误时提供必要的上下文。API通常会提供详细的错误日志或调试信息，帮助开发者排查问题。

为了保证系统的稳定性和可用性，开发者应当根据不同的错误类型采取不同的处理策略。对于可恢复的错误（如请求参数错误），开发者可以提示用户修改参数并重新发送请求；对于不可恢复的错误（如服务器故障），开发者可以尝试重新请求或者使用备用方案进行处理。

4.1 错误码说明

| 错误码 | 错误信息 | |--------|------------------------------| | 10000 | 请求参数错误。表示客户端在向API发起请求时，传递的参数存在问题，可能是缺少必要参数、参数格式错误或者参数值不符合要求。此错误通常需要开发者检查并确保API请求参数的正确性，包括检查参数名称、类型、范围等是否符合API文档要求。 | | 10001 | API权限不足。表示当前用户没有访问所请求的资源或执行特定操作的权限。这可能是由于API密钥未授权、账户权限不足或者API访问控制规则限制了访问。解决此问题可能需要检查用户的API权限配置或更新API密钥。 | | 10002 | 请求超时。此错误表示客户端的请求在规定的时间内未得到响应，通常是由于网络问题、服务端处理延迟或请求过载造成的。用户可以尝试增加请求的超时时间，或者检查网络连接状况，并确认服务端没有出现性能瓶颈。 | | 10003 | 身份认证失败。表示在访问受保护资源时，提供的身份认证信息（如API密钥、令牌等）无效或过期。此错误通常发生在用户没有正确提供有效的认证信息，或者认证信息已被撤销或失效。用户需要确保身份认证信息是最新且有效的，并重新尝试认证。 |

4.2 错误响应示例

{ "code": "10000", "msg": "请求参数错误", "details": "请求中包含无效、缺失或格式错误的参数，导致服务器无法正确处理该请求。常见的参数错误包括参数类型不匹配、必填参数未提供、参数值超出预期范围等。在这种情况下，客户端需要检查请求的构造，确保所有传入的参数符合API文档要求的格式和类型。如果错误仍然存在，可以通过进一步检查错误日志或联系API提供方获取更多帮助。", "suggestion": "请检查请求中的所有参数，确保它们符合API要求的格式、类型和范围，并重新发送请求。参考API文档以获取更多参数说明和限制条件。" }