欧易API文档接口信息解读教程
前言
本文旨在深度解读欧易（OKX）API文档中的关键接口信息，旨在帮助开发者迅速、高效地理解并熟练运用欧易API进行包括现货、合约交易在内的各类交易活动，以及深度市场数据获取、账户管理等操作。我们将从API的整体架构设计、安全机制入手，逐步深入剖析具体接口的请求参数、响应数据结构、错误代码含义以及实际使用示例。力求以逻辑清晰、通俗易懂的方式呈现，并辅以代码示例，提升开发效率，避免常见问题。
API文档的理解往往是成功接入的关键一步。本文将着重阐述认证机制、频率限制、常用请求方法等基础知识，同时对交易接口的下单、撤单、查询订单状态，以及行情数据接口的Ticker、深度数据、K线数据等进行详细讲解。特别地，我们将关注websocket接口的使用，以实现实时数据推送和低延迟交易。
API整体架构
欧易API构建于RESTful架构之上，提供了一套全面的编程接口，赋能开发者以程序化的方式与欧易平台互动，获取实时数据并执行交易指令。该API体系被清晰地划分为两类：公开API和私有API。
- 公共接口 (Public API) : 此类接口无需任何形式的身份验证，即可自由访问。其主要功能在于提供市场行情快照、交易对的详细信息、历史K线数据以及其他与市场深度和广度相关的信息。这些数据对于算法交易者、市场分析师和数据科学家至关重要，他们可以利用这些信息来构建交易策略、进行市场建模和预测。
- 私有接口 (Private API) : 与公共API不同，私有API需要通过严格的身份验证才能访问。它们允许用户执行诸如创建和管理订单、查询账户余额和交易历史记录、发起提款请求等敏感操作。为了确保账户安全，访问私有API需要有效的API密钥和密钥，并且每次请求都需要进行签名验证。
所有与欧易API的通信都必须通过HTTPS协议进行加密传输。HTTPS协议采用SSL/TLS加密技术，能够有效地保护数据在传输过程中免受窃听和篡改，从而确保用户数据和交易信息的安全性。使用HTTPS是保障API通信安全性的基本要求，也是防止中间人攻击的重要手段。
认证 (Authentication)
访问欧易等加密货币交易所的私有API接口，必须进行严格的身份验证，以确保账户安全和交易数据的完整性。欧易API采用API Key、Secret Key和Passphrase三重认证机制，构建安全可靠的访问通道。
- API Key : 相当于你的用户ID，用于唯一标识你在欧易平台的身份。每个API Key都与特定的权限集合相关联，例如交易权限、账户信息访问权限等。妥善保管API Key，避免泄露。
- Secret Key : 这是用于对API请求进行签名的密钥，确保请求在传输过程中没有被篡改。Secret Key必须高度保密，一旦泄露，可能导致未经授权的交易或其他恶意操作。请务必将其存储在安全的地方，切勿明文存储或通过不安全的渠道传输。
- Passphrase : 这是一个可选但强烈建议使用的安全措施。Passphrase可以看作是API Key的密码，增加了额外的安全层。即使API Key泄露，没有Passphrase，攻击者也无法使用该API Key发起有效的请求。设置一个复杂且难以猜测的Passphrase是保护API Key的关键。
进行身份验证的一般流程如下：
- 构建请求参数 : 准备需要发送给API接口的所有参数，包括查询参数、请求体数据等。根据API文档的要求，对参数进行格式化和编码。
-
生成签名
: 使用Secret Key对请求参数进行签名，以验证请求的真实性和完整性。 签名算法通常采用HMAC-SHA256，这是一种广泛使用的哈希消息认证码算法。 签名过程包括：
- 将所有请求参数按照一定的规则（例如字母顺序）排序并拼接成字符串。
- 使用Secret Key作为密钥，对拼接后的字符串进行HMAC-SHA256哈希运算。
- 将哈希运算的结果转换为十六进制字符串，作为最终的签名。
-
添加请求头
: 将API Key、签名、时间戳和Passphrase添加到HTTP请求头中。这些请求头信息会被服务器用来验证你的身份和请求的合法性。
-
OK-ACCESS-KEY: 你的API Key。 -
OK-ACCESS-SIGN: 使用Secret Key生成的签名。 -
OK-ACCESS-TIMESTAMP: 当前时间戳，以Unix时间戳格式表示（秒）。时间戳用于防止重放攻击，即攻击者截获你的请求并重复发送。服务器会验证时间戳的有效性，例如，拒绝超过一定时间范围的请求。 -
OK-ACCESS-PASSPHRASE: 你设置的Passphrase。如果未设置Passphrase，则不需要添加此请求头。
-
常用接口解读
接下来，我们将深入解读几个常用的API接口，它们是加密货币交易和信息获取的关键入口，包括无需授权即可访问的公共接口，以及需要身份验证才能访问的私有接口。
公共接口： 这类接口允许开发者和用户无需提供个人身份验证信息即可访问，通常用于获取市场数据、交易对信息、历史价格、区块链信息等公开数据。例如，获取当前比特币（BTC）对美元（USD）的最新价格、查询特定区块链地址的余额、或获取特定交易对的历史交易记录。使用公共接口时，需要注意API的使用频率限制，避免因过度请求而被服务器限制访问。
私有接口： 与公共接口不同，私有接口需要用户通过身份验证才能访问，通常用于执行交易、管理账户、查询个人交易历史等敏感操作。身份验证通常通过API密钥（API Key）和密钥签名（Signature）来实现，以确保只有授权用户才能访问其账户信息和执行交易。私有接口的使用需要格外小心，务必妥善保管API密钥，并采取必要的安全措施，如IP地址白名单、二次验证等，以防止密钥泄露导致资产损失。同时，需要仔细阅读API文档，了解各个接口的请求参数和返回值格式，确保交易操作的准确性和安全性。
1. 获取交易对信息 (GET /api/v5/public/instruments)
- 用途 : 获取欧易（OKX）交易平台上所有交易对的详细信息。这些信息对于理解市场结构、进行交易策略分析以及构建自动化交易系统至关重要。该接口提供的信息包括但不限于交易对名称、基币、计价币、最小交易数量、合约乘数等。
-
请求参数
:
-
instType: String，必填参数，用于指定交易产品类型。不同的产品类型具有不同的交易规则和合约特性。有效值包括：-
SPOT: 币币交易，指现货交易。 -
SWAP: 永续合约交易，一种没有到期日的合约。 -
FUTURES: 交割合约交易，有明确到期日的合约。 -
OPTION: 期权交易，赋予买方在特定日期或之前以特定价格买入或卖出资产的权利。
-
-
uly: String，非必填参数，仅适用于交割/永续/期权合约。该参数用于指定标的指数，例如BTC-USD。在使用交割、永续或期权产品类型时，如果需要查询特定标的指数的交易对，则需要提供此参数。 -
instId: String，非必填参数，用于指定具体的交易产品ID，例如BTC-USDT。如果已知具体的交易对ID，可以通过此参数直接查询该交易对的信息，从而提高查询效率。
-
-
返回值
: JSON数组，包含每个交易对的详细信息。返回的JSON数组中的每个元素都代表一个交易对，并包含该交易对的各项属性信息。
-
instId: String，产品ID，是交易对的唯一标识符，例如BTC-USDT。 -
instType: String，产品类型，指示交易对所属的产品类型，例如SPOT。 -
uly: String，标的指数，适用于交割/永续/期权合约。 -
baseCcy: String，交易币，即交易对中的基础货币，例如BTC-USDT中的BTC。 -
quoteCcy: String，计价币，即交易对中的计价货币，例如BTC-USDT中的USDT。 -
ctVal: String，合约面值，仅适用于合约交易，表示每张合约代表的标的资产数量。 -
lotSz: String，交易数量，表示一次交易的合约数量单位。 -
minSz: String，最小下单数量，表示允许的最小交易数量，对于交易策略的制定至关重要。
-
-
示例
:
使用GET方法请求
/api/v5/public/instruments接口，并指定instType参数为SPOT，以获取所有现货交易对的信息。GET /api/v5/public/instruments?instType=SPOT
2. 获取K线数据 (GET /api/v5/market/candles)
- 用途 : 获取指定交易对的历史K线数据，常用于加密货币交易的技术分析，帮助用户识别趋势、支撑位和阻力位，从而制定交易策略。
-
请求参数
:
-
instId: String 必填，产品ID，明确指定需要查询的交易对。例如，BTC-USDT 代表比特币兑泰达币的交易对。务必提供有效的交易对，否则将无法获取正确的数据。 -
bar: String 非必填，K线的时间粒度，决定了每根K线代表的时间周期。常见的粒度包括：1m (1分钟), 5m (5分钟), 15m (15分钟), 30m (30分钟), 1h (1小时), 4h (4小时), 1d (1天), 1w (1周), 1M (1月), 3M (3个月), 6M (6个月), 1Y (1年)。默认值为 1m，即分钟级别。 选择合适的粒度取决于你的交易策略和时间框架。更小的时间粒度提供更详细的价格波动信息，而更大的时间粒度则更能反映长期趋势。 -
after: String 非必填，请求特定时间戳之后（不包含该时间戳）的K线数据，用于分页查询。Unix 时间戳以毫秒为单位，例如 1597026383085。该参数通常与limit参数一起使用，以便逐步获取大量历史数据。 -
before: String 非必填，请求特定时间戳之前（不包含该时间戳）的K线数据，同样用于分页查询。Unix 时间戳格式与after参数相同，为毫秒级。 -
limit: String 非必填，限制返回的K线数据数量，最大值为 100。默认值为 100。如果需要获取更多数据，可以使用after或before参数进行分页。 注意，频繁请求大量数据可能会受到API的速率限制。
-
-
返回值
: JSON数组，数组中的每个元素代表一个独立的K线数据。每一根K线通常包含以下信息:
- 时间戳: K线对应的时间，通常是K线周期的起始时间，以Unix时间戳表示（毫秒）。
- 开盘价: K线周期开始时的价格。
- 最高价: K线周期内的最高价格。
- 最低价: K线周期内的最低价格。
- 收盘价: K线周期结束时的价格。
- 交易量: 在该K线周期内的总交易量，通常以基础货币的数量表示。
- 示例 :
bash GET /api/v5/market/candles?instId=BTC-USDT&bar=1h
3. 下单 (POST /api/v5/trade/order)
- 用途 : 在指定交易对创建并提交交易订单，支持多种订单类型，包括但不限于市价单、限价单等。此接口是执行交易的核心环节。
-
请求参数
:
-
instId: String， 必填 。产品ID，用于指定交易的标的资产。例如，BTC-USDT表示比特币兑美元的交易对。此参数必须准确填写，否则订单无法正确执行。 -
tdMode: String， 必填 。交易模式，定义了保证金的使用方式。可选值包括：-
cash: 现货交易，直接使用账户中的可用余额进行交易。 -
cross: 逐仓杠杆交易，保证金在所有仓位之间共享，风险相对较高。 -
isolated: 全仓杠杆交易，每个仓位有独立的保证金，风险相对可控。选择合适的交易模式至关重要。
-
-
side: String， 必填 。买卖方向，指定交易的方向。-
buy: 买入，表示希望以指定的价格或市价购买一定数量的标的资产。 -
sell: 卖出，表示希望以指定的价格或市价出售一定数量的标的资产。正确设置买卖方向是交易的基础。
-
-
ordType: String， 必填 。订单类型，定义了订单的执行方式。-
market: 市价单，以当前市场最优价格立即成交。 -
limit: 限价单，以指定的价格或更优的价格成交。如果市场价格未达到指定价格，订单将不会立即执行，而是进入订单簿等待成交。 -
post_only: 只挂单，该类型订单只有在能进入订单簿成为 maker 的情况下才会提交，如果会立即被吃单（taker），则该订单会被自动取消。可以避免吃单手续费。
-
-
sz: String， 必填 。下单数量，指定购买或出售的标的资产的数量。数量必须大于交易所允许的最小交易单位。 -
px: String，非必填。限价单价格，只有当ordType为limit时才需要填写。指定希望成交的价格。如果未达到指定价格，订单将不会成交。 -
clOrdId: String，非必填。客户自定义ID，允许用户为订单设置自定义的ID，方便跟踪和管理订单。该ID不会影响订单的执行，仅用于用户内部识别。 -
tag: String，非必填。订单标签，允许用户为订单添加自定义标签，方便进行订单分类和统计。该标签不会影响订单的执行，仅用于用户内部管理。
-
-
返回值
: JSON对象，包含订单相关信息，例如订单ID、客户自定义ID等。
-
ordId: String，订单ID，由交易所生成的唯一订单标识符。用于查询订单状态和取消订单。 -
clOrdId: String，客户自定义ID，与请求参数中的clOrdId对应。 -
sCode: String，订单结果代码，"0"表示成功，其他代码表示失败。 -
sMsg: String，订单结果信息，成功时为空字符串，失败时包含错误信息。
-
- 示例 :
bash POST /api/v5/trade/order { "instId": "BTC-USDT", "tdMode": "cash", "side": "buy", "ordType": "limit", "sz": "0.01", "px": "30000" }
4. 查询订单信息 (GET /api/v5/trade/order)
- 用途 : 检索特定订单的详细信息。此端点允许用户通过订单ID或客户端自定义ID查询订单的具体状态和执行情况。
-
请求参数
:
-
instId: String 必填。指明交易的标的资产。产品ID，用于指定交易对，例如BTC-USDT代表比特币兑泰达币的交易对。请确保instId与实际交易对相符。 -
ordId: String 必填。交易所分配的唯一订单标识符，用于精确查询特定订单。这是系统生成的ID，在创建订单时返回。 -
clOrdId: String 可选。客户端自定义订单ID，允许用户使用自定义的ID来跟踪订单。如果提供，将优先使用此ID进行查询。如果未提供，则仅使用ordId查询。使用客户端自定义ID可以方便用户在自己的系统中跟踪订单状态。
-
-
返回值
: JSON对象，包含订单的完整信息。返回的JSON对象包含以下字段：
-
ordId: String 订单ID。交易所生成的唯一订单标识符。 -
clOrdId: String 客户端自定义ID。用户设置的自定义订单标识符。如果订单创建时设置了此值，则会返回。 -
instId: String 产品ID。交易对的标识符，如BTC-USDT。 -
px: String 委托价格。用户设定的订单委托价格。表示用户希望以该价格或更好的价格成交。 -
sz: String 委托数量。订单委托的资产数量。表示用户希望交易的资产数量。 -
avgPx: String 平均成交价格。订单的平均成交价格。如果订单部分成交，则此价格为所有成交的加权平均价格。如果订单尚未成交，则此字段可能为空。 -
state: String 订单状态。订单的当前状态，例如canceled（已取消）、live（未成交/挂单中）、filled（已完全成交）、partially_filled(部分成交)。其他可能的状态包括pending(待成交)。 -
side: String 订单方向，Buy或者Sell. -
ordType: String 订单类型，如market(市价单), limit(限价单). -
fee: String 交易手续费 -
feeCcy: String 手续费币种 -
tradeId: String 最后成交的ID -
ts: String 订单创建时间戳
-
- 示例 :
bash GET /api/v5/trade/order?instId=BTC-USDT&ordId=123456789
5. 获取账户信息 (GET /api/v5/account/balance)
- 用途 : 用于查询您账户的余额详情，包括不同加密货币的可用余额、已冻结余额以及账户权益。此接口允许您监控资产的分布情况，并了解账户的整体财务状况。
-
请求参数
:
-
ccy: String (非必填)。 指定要查询的币种。例如，如果您只想查询比特币(BTC)的余额，则设置ccy=BTC。如果未指定此参数，API将返回您账户中所有币种的余额信息。
-
-
返回值
: 返回一个JSON对象，其中包含了账户余额的详细信息。JSON对象包含以下字段：
-
bal: String。 当前币种的账户余额总量，包括可用余额和冻结余额的总和。 -
ccy: String。 币种类型，例如 "BTC", "ETH", "USDT" 等。 -
eq: String。 账户权益，通常指折算成指定计价货币（如USD）的总价值。这能帮助您快速了解账户的总价值。 -
cashBal: String。 现货账户的可用余额，即可用于交易或提现的部分。 -
frozenBal: String。 冻结余额，指由于挂单、锁仓或其他原因而被冻结的资金，暂时无法使用。
-
- 示例 :
请求示例如下，使用GET方法请求
/api/v5/account/balance
接口，并指定
ccy=BTC
参数来查询BTC的账户余额。
GET /api/v5/account/balance?ccy=BTC
错误处理
与欧易API交互时，您的应用程序可能会遇到各种类型的错误。这些错误可能源于多种因素，包括但不限于：请求参数不正确、API密钥未正确配置或已过期、网络连接问题、超出API调用频率限制，以及欧易服务器端的临时故障。为了确保应用程序的健壮性和可靠性，必须妥善处理这些错误。
-
HTTP状态码
: HTTP状态码是服务器响应客户端请求时返回的标准代码，用于指示请求的处理结果。成功的请求通常返回200状态码。以下是一些与欧易API相关的常见错误状态码及其含义：
- 200 OK : 请求成功。但请注意，即使HTTP状态码为200，JSON返回值中可能仍然包含错误代码，因此务必检查JSON响应体。
- 400 Bad Request : 通常表示客户端发送的请求存在问题，例如缺少必需的参数、参数值无效或格式错误。仔细检查请求参数，确保符合API文档的要求。
- 401 Unauthorized : 表示客户端未经过身份验证，通常是因为API密钥无效、未提供或权限不足。检查API密钥是否正确配置，并确保具有执行所需操作的权限。
- 403 Forbidden : 表示服务器拒绝了请求，即使客户端已通过身份验证。这可能是因为IP地址不在白名单中、账户被禁用或缺少特定权限。
- 429 Too Many Requests : 表示客户端在短时间内发送了过多的请求，触发了API调用频率限制。建议实施重试机制，并遵循欧易的频率限制策略。使用指数退避算法可以有效地避免再次触发频率限制。
- 500 Internal Server Error : 表示欧易服务器遇到了内部错误，无法完成请求。这通常是临时性问题，稍后重试可能成功。
- 503 Service Unavailable : 表示欧易服务器当前不可用，可能是由于维护或过载。稍后重试。
-
JSON返回值
: 当API调用返回错误时，欧易API通常会在JSON响应体中提供更详细的错误信息。常见的错误信息字段包括：
- code : 错误代码，是一个数字或字符串，用于标识特定类型的错误。查阅欧易API文档，了解每个错误代码的含义。
- msg : 错误信息，是一个人类可读的字符串，提供了关于错误的更详细描述。该信息有助于快速定位和解决问题。
-
data
: 在某些情况下，错误响应中可能包含
data字段，提供与错误相关的额外信息。
为了有效地处理API错误，开发者应采取以下措施：捕获HTTP状态码和JSON返回值，并根据错误代码和错误信息进行相应的处理。实施重试机制以处理瞬时错误，例如网络问题或服务器过载。记录所有错误，以便进行调试和分析。向用户提供有意义的错误消息，以便他们了解发生了什么以及如何解决问题。对于身份验证错误，检查API密钥的有效性。对于参数错误，仔细检查请求参数。对于频率限制错误，实施退避策略。通过周密的错误处理策略，可以提高应用程序的稳定性和用户体验。
频率限制 (Rate Limit)
为保障系统稳定性和公平使用，欧易API实施了频率限制策略，旨在防止恶意滥用和过度请求。这意味着每个API接口都设有请求次数的上限，超过此限制的请求将被自动拒绝，从而维护整个平台的可用性和性能。频率限制的执行通常基于两个主要维度：用户的IP地址和API Key。基于IP地址的限制旨在防止单一网络来源的过度请求，而基于API Key的限制则针对特定用户的API调用行为进行约束，确保所有开发者都能在公平的环境下使用API。
开发者在使用欧易API时，必须高度重视并严格遵守各项频率限制规定。未能遵守这些限制可能导致API请求被拒绝，影响应用程序的功能。为了避免触发频率限制，建议开发者采取以下措施：仔细阅读并理解API文档中关于频率限制的具体说明，包括不同接口的限制标准和重置周期。实施有效的请求队列管理机制，控制并发请求的数量，避免短时间内发送大量请求。可以考虑使用第三方频率控制库或自定义算法，根据API的返回状态动态调整请求频率。开发者应监控API返回的HTTP状态码和头部信息，特别是与频率限制相关的状态码（如429 Too Many Requests）和
X-RateLimit-Remaining
、
X-RateLimit-Limit
、
X-RateLimit-Reset
等头部，以便及时调整请求策略。具体的频率限制信息，包括每个接口的限制标准、重置时间和相关头部字段的说明，都可以在欧易API的官方文档中找到，开发者应定期查阅更新，确保应用程序的正常运行。
