欧易API接口申请及使用教程
一、API接口概述
欧易（OKX）API接口是为程序化交易者、算法交易员和开发者提供的功能强大的工具集。它允许用户通过编写代码，以编程方式安全、高效地访问欧易交易平台的各类核心功能，涵盖现货、合约、期权等多种交易产品。这些功能包括但不限于：执行限价单、市价单等各种类型的订单，查询账户余额、持仓信息、交易历史等详细的账户信息，以及实时获取包括深度数据、交易对最新价格、历史成交记录等在内的全面市场数据。借助API，用户能够构建并部署复杂的自动化交易策略，将交易策略与量化模型紧密结合，开发定制化的交易机器人，并且可以轻松地将欧易平台的功能集成到现有的交易系统中，从而实现更高效率、更低延迟、更便捷的交易体验。API的使用极大地提升了交易的灵活性和自动化程度，使得用户能够更好地把握市场机会，优化交易决策，并降低人工操作的风险。
二、API接口申请流程
1. 注册和登录欧易账户
开始使用欧易平台，你需要拥有一个已验证的欧易账户。 如果尚未注册，请访问欧易官方网站 www.okx.com ，点击“注册”按钮。 注册过程通常需要提供邮箱地址或手机号码，并设置安全的密码。 完成初步注册后，可能需要进行身份验证（KYC，了解你的客户）。 身份验证是符合监管要求，并解锁平台全部功能的重要步骤，可能需要上传身份证件照片等信息。
注册完成后，返回欧易官网，使用注册时设置的邮箱/手机号码和密码登录你的账户。 建议启用双重验证 (2FA)，例如 Google Authenticator 或短信验证，以增强账户安全性，有效防止未经授权的访问。 登录后，请务必熟悉欧易平台的用户界面，包括交易界面、资产管理、以及安全设置等，以便更好地进行加密货币交易和管理。
2. 实名认证（KYC）：保障安全，合规运营
为了遵守日益严格的全球监管法规，并全方位保障用户资产安全，欧易平台要求所有用户完成实名认证（Know Your Customer，简称KYC）。KYC认证不仅有助于防止洗钱、恐怖融资等非法活动，还能提升用户的账户安全等级，确保交易环境的透明度和公平性。
用户登录欧易账户后，可在“个人中心”或直接访问“身份认证”页面启动KYC流程。平台会清晰地引导用户逐步完成身份验证，通常需要上传有效的身份证明文件，例如身份证（正反面照片）、护照或其他政府签发的有效身份证明，并根据系统提示完成人脸识别验证。人脸识别技术能有效防止身份盗用，进一步提升账户安全。
欧易的KYC认证通常分为不同的等级，不同等级对应不同的API使用权限和交易额度。例如，初级认证可能只允许较低的交易额度，而完成更高级别的认证则能解锁更高的交易权限和更全面的API功能。强烈建议用户尽可能完成最高级别的认证，以便充分利用欧易平台提供的各项服务，并享受更高的安全保障。完成高级别认证还能在参与平台活动、获取专属优惠等方面获得更多优势。
请务必确保提交的身份信息真实、准确、有效。虚假信息或过期证件可能会导致认证失败，并影响您的交易体验。欧易平台会严格保护用户的个人信息，不会泄露给第三方。如有任何疑问，可随时联系欧易官方客服寻求帮助。
3. 创建API密钥
成功完成实名认证（KYC）后，您即可开始创建API密钥，用于自动化交易或其他与欧易平台交互的应用。
- 进入“API管理”页面：登录您的欧易账户后，导航至“个人中心”、“账户设置”或类似的页面，找到“API管理”选项。具体位置可能因欧易平台界面更新而略有变化，请留意相关提示。
-
创建新的API密钥：点击“创建API密钥”按钮，系统将引导您填写必要的配置信息，包括API名称、绑定IP地址（可选）以及设置权限等。
- API名称：为您的API密钥指定一个具有描述性的名称，例如“量化交易机器人”、“数据分析脚本”等。良好的命名习惯有助于您在拥有多个API密钥时进行有效的管理和区分。
- 绑定IP地址：为了显著提高API密钥的安全性，强烈建议将API密钥绑定到特定的IP地址或IP地址段。这意味着只有来自这些指定IP地址的请求才能成功使用该API密钥进行操作。如果您不确定需要绑定哪些IP地址，可以暂时不填写，但请务必在后续及时配置，以避免潜在的安全风险。您可以绑定您的服务器IP地址，或者您的家庭/办公网络的公网IP地址。请注意，如果您使用动态IP地址，则需要定期更新绑定信息。
-
权限设置：这是API密钥配置中最为关键的部分。您需要根据您的实际交易需求和使用场景，仔细选择并设置合适的权限。错误的权限配置可能会导致资金损失或其他安全问题。常见的权限类型及其详细说明如下：
- 只读权限（Read Only）： 此权限允许您获取账户信息（如余额、持仓情况）、历史交易记录、市场数据（如实时行情、K线数据）等信息。拥有只读权限的API密钥不能进行任何交易操作，例如下单、撤单、充值或提币。适合用于数据分析、监控或其他仅需读取数据的应用场景。
- 交易权限（Trade）： 此权限允许您进行下单（包括市价单、限价单等）、撤单、修改订单等交易操作。使用此权限的API密钥可以执行实际的交易行为。请务必谨慎授予此权限，并确保您的交易策略经过充分的测试和验证。
- 提币权限（Withdraw）： 此权限允许您从您的欧易账户提币到其他加密货币地址。 这是最敏感的权限之一，请极其谨慎授予此权限。只有在绝对必要的情况下才应使用此权限，并采取严格的安全措施，例如启用双因素认证（2FA）、设置提币白名单等。强烈建议仅在您完全信任的应用程序中使用此权限。 请注意，某些交易平台可能会对提币权限的API密钥设置额外的限制，例如提币额度限制。
-
生成API密钥：在确认所有配置信息准确无误后，点击“创建”按钮。系统将生成您的API Key（API密钥）和Secret Key（API密钥私钥）。 请务必高度重视并妥善保管您的Secret Key，因为它只会在创建时显示一次，并且不会再次显示。一旦丢失，您将需要重新生成API密钥。Secret Key相当于您的账户密码，任何持有您的Secret Key的人都可以控制您的账户。建议将其保存在安全的地方，例如使用密码管理器或硬件钱包。 切勿将您的Secret Key透露给任何人，包括欧易官方客服人员。
4. 启用API密钥
创建API密钥后，为了保障安全性并防止未经授权的访问，通常需要手动启用该密钥才能正式投入使用。这个启用过程相当于对密钥的激活，确认你已经充分了解并同意使用该密钥可能涉及的权限和风险。
在API管理平台或控制面板中，导航至API密钥管理页面。这个页面通常会列出所有已创建的API密钥，包括它们的创建时间、状态（启用/禁用）、以及可能绑定的权限范围。找到你刚刚创建的API密钥，该密钥可能会以密钥名称、ID或者创建时间等信息进行标识。
找到目标API密钥后，仔细查看其状态。如果状态显示为“禁用”、“未激活”或类似描述，则表明该密钥尚未启用。此时，应该会有一个明显的“启用”按钮或者开关选项。点击该按钮，系统可能会要求你进行二次验证，例如输入密码、验证码或进行身份验证。
点击“启用”按钮后，请务必仔细阅读可能出现的提示信息，这些信息可能包含关于密钥使用范围、访问限制、以及可能产生的费用等重要说明。确认理解并同意这些条款后，完成启用流程。启用完成后，API密钥的状态应该会更新为“启用”、“已激活”或类似描述，此时你就可以开始使用该密钥进行API调用了。请注意，有些API平台可能需要几分钟时间才能完全激活密钥，在此期间，API调用可能会暂时失败。
三、API接口使用
1. API端点
欧易API提供了一系列RESTful风格的端点，用于执行各种交易和账户管理操作。 这些端点允许开发者通过编程方式访问欧易交易所的各种功能，并构建自定义交易策略和自动化交易系统。 API交互通常涉及发送HTTP请求（如GET、POST、PUT、DELETE）到指定的端点，并解析服务器返回的JSON格式响应。
-
/api/v5/market/tickers：获取所有或指定交易对的实时行情信息。此端点返回的数据包括最新成交价、24小时最高价、24小时最低价、24小时成交量等关键指标，方便用户快速了解市场整体情况。可以通过参数指定需要查询的交易对，例如/api/v5/market/tickers?instId=BTC-USDT。 -
/api/v5/market/candles：获取指定交易对的历史K线数据。K线数据是技术分析的基础，此端点允许用户自定义K线周期（例如1分钟、5分钟、1小时、1天等），以及指定起始时间和结束时间，从而获取特定时间段内的K线数据。例如，使用/api/v5/market/candles?instId=BTC-USDT&bar=1m获取BTC-USDT的1分钟K线数据。 -
/api/v5/account/balance：查询账户余额。此端点返回用户账户中各种币种的可用余额、冻结余额以及总余额。用户需要进行身份验证才能访问此端点，确保账户安全。返回数据通常包含不同类型的账户余额信息，例如交易账户、资金账户等。 -
/api/v5/trade/order：提交新的交易订单。此端点允许用户指定交易对、交易方向（买入或卖出）、订单类型（限价单、市价单等）、委托价格和委托数量等参数，从而创建新的交易订单。 订单类型包括限价单 (limit order)、市价单 (market order) 、止损单 (stop order) 等， 并且可以设置高级选项例如只做Maker单 (Post Only) 和冰山单 (Iceberg Order)。 -
/api/v5/trade/cancel-order：撤销已提交的交易订单。此端点允许用户通过指定订单ID来取消尚未成交的订单。 使用此端点需要用户身份验证，确保用户只能取消自己的订单。 可以单个撤单， 也可以批量撤单。
完整的API文档，包括详细的参数说明、请求示例、错误代码以及使用限制，可以在欧易官方网站的开发者中心找到。 建议开发者在使用API之前仔细阅读官方文档，以便更好地理解API的使用方法，并避免潜在的问题。 文档中通常还会提供各种编程语言的SDK和示例代码，方便开发者快速上手。
2. 请求方法
欧易API遵循RESTful架构设计原则，并支持多种HTTP请求方法，以便开发者能够灵活地与交易所进行交互，实现数据的查询、创建、更新和删除等操作。常用的请求方法包括GET、POST、PUT和DELETE。
- GET: 用于从服务器检索特定资源或数据。在使用欧易API时，GET请求常用于获取市场行情、账户信息、订单状态等只读数据，不会对服务器上的数据进行修改。通常，GET请求会将参数附加在URL后面，形成查询字符串。
- POST: 用于向服务器提交数据，从而创建新的资源或更新现有资源。在欧易API中，POST请求通常用于执行需要改变服务器状态的操作，例如提交新的交易订单、进行资金划转等。POST请求会将参数放在请求体中，安全性更高。
- PUT: 用于替换服务器上的现有资源。与POST请求不同，PUT请求通常用于更新资源的全部内容。在欧易API的使用场景中，PUT请求可能用于更新账户的某些设置信息，但具体应用取决于API的实现。
- DELETE: 用于删除服务器上的指定资源。在欧易API中，DELETE请求常用于撤销未成交的订单。执行DELETE请求时需要谨慎，因为删除操作通常不可逆。
3. 请求头
在发起加密货币交易所API请求时，正确的设置请求头至关重要，它们包含了认证信息和数据格式声明，确保服务器能够正确识别和处理你的请求。
-
OK-ACCESS-KEY: 你的API Key，也称为公钥。它是你身份的标识，用于关联你的账户。务必妥善保管，避免泄露。 -
OK-ACCESS-SIGN: 签名，这是一个通过特定算法（通常是HMAC-SHA256）使用你的密钥对请求内容进行加密后的字符串。签名用于验证请求的完整性和真实性，防止数据篡改和重放攻击。签名算法的细节会根据交易所的要求而有所不同，需要仔细阅读API文档。 -
OK-ACCESS-TIMESTAMP: 时间戳，表示请求发起的时间，以秒为单位的Unix时间戳。时间戳用于防止重放攻击。服务器通常会拒绝时间戳与服务器时间相差过大的请求。 -
OK-ACCESS-PASSPHRASE: 你的Passphrase，是在创建API密钥时设置的密码短语。Passphrase用于进一步增强安全性，防止API Key被盗用后造成的损失。有些交易所强制要求设置Passphrase。 -
Content-Type:application/。指定请求体的MIME类型。对于加密货币API，JSON（JavaScript Object Notation）是最常用的数据格式，易于解析和生成。如果API支持其他格式，如application/x-www-form-urlencoded，则需要根据实际情况进行设置。
4. 签名生成
为了确保API请求的安全性和完整性，欧易平台要求所有请求都必须进行签名验证。签名是API请求不可或缺的部分，它利用您的Secret Key对请求的关键信息进行加密，从而验证请求的合法性，防止恶意篡改和重放攻击。欧易采用业界标准的HMAC-SHA256算法来生成签名，保证签名过程的安全性与可靠性。
- 准备请求体： 根据API接口的要求，将请求体（如果存在）转换为规范的JSON字符串。如果请求体为空，则使用空字符串。请务必注意请求体的格式，确保其符合API文档的规范。
- 构造签名字符串： 将时间戳（以秒为单位）、请求方法（如GET、POST、PUT、DELETE等，必须大写）、请求路径（不包含域名部分，例如：/api/v5/market/tickers）和请求体字符串按照顺序连接起来，形成用于签名的原始字符串。时间戳必须是当前时间的UTC时间戳，精度到秒。
- HMAC-SHA256加密： 使用您的Secret Key作为密钥，对构造好的签名字符串进行HMAC-SHA256加密。HMAC (Hash-based Message Authentication Code) 是一种使用哈希函数和密钥来生成消息认证码的算法，SHA256是安全散列算法的一种。
- Base64编码： 将HMAC-SHA256加密后的二进制结果转换为Base64编码的字符串。Base64是一种将二进制数据转换为ASCII字符串的编码方式，常用于在HTTP协议中传输二进制数据。
不同的编程语言都提供了相应的HMAC-SHA256加密库和Base64编码库，开发者可以根据自己使用的编程语言选择合适的库进行签名生成。选择成熟可靠的加密库能够有效避免安全漏洞，确保签名过程的安全性。
以下是一个Python示例代码，展示了如何生成欧易API签名：
import hashlib
import hmac
import base64
import time
def generate_signature(timestamp, method, request_path, body, secret_key):
"""
生成欧易API签名。
Args:
timestamp (str): 时间戳，以秒为单位。
method (str): 请求方法，如GET、POST。
request_path (str): 请求路径，如/api/v5/market/tickers。
body (str): 请求体，如果存在。
secret_key (str): 你的Secret Key。
Returns:
str: 签名。
"""
message = timestamp + method.upper() + request_path + body
mac = hmac.new(bytes(secret_key, encoding='utf8'), bytes(message, encoding='utf-8'), digestmod=hashlib.sha256)
d = mac.digest()
return base64.b64encode(d).decode('utf-8') # 添加decode('utf-8')，确保返回字符串类型
示例
时间戳 (Timestamp)：
时间戳是交易签名过程中的关键组成部分，它代表了请求发出的具体时间，通常以 Unix 时间戳的形式表示（即自 1970 年 1 月 1 日 00:00:00 UTC 起经过的秒数）。使用当前时间戳能够有效防止重放攻击，确保交易的安全性。以下代码展示了如何获取当前时间戳：
timestamp = str(int(time.time()))
HTTP 方法 (Method)：
指定发起请求所使用的 HTTP 方法。常见的 HTTP 方法包括 GET、POST、PUT 和 DELETE。不同的 API 端点可能需要不同的方法。例如，获取市场数据通常使用 GET 方法，而提交订单则可能使用 POST 方法。
method = "GET"
请求路径 (Request Path)：
请求路径是指 API 端点的具体路径，它标识了您希望访问或操作的特定资源。请求路径通常包含版本信息和资源名称。例如，
/api/v5/market/tickers?instType=SPOT
表示获取现货 (SPOT) 市场的交易对行情数据。请务必确保请求路径的准确性，否则可能导致请求失败。
request_path = "/api/v5/market/tickers?instType=SPOT"
请求体 (Body)：
请求体是指在 POST、PUT 或 PATCH 请求中发送的数据。对于 GET 请求，请求体通常为空字符串。请求体的内容格式取决于 API 的要求，常见的格式包括 JSON 和 XML。在构建签名时，需要包含请求体的完整内容。
body = ""
密钥 (Secret Key)：
密钥是用于生成签名的私有密钥。务必妥善保管您的密钥，切勿泄露给他人。密钥通常由交易所或 API 提供商提供。强烈建议将密钥存储在安全的环境中，例如环境变量或配置文件中。
secret_key = "YOUR_SECRET_KEY" # 替换为你的 Secret Key
签名生成 (Signature Generation)：
签名是将时间戳、HTTP 方法、请求路径、请求体和密钥组合在一起，通过特定的加密算法（如 HMAC-SHA256）生成的字符串。签名用于验证请求的身份和完整性。以下代码调用
generate_signature
函数生成签名，并将其打印到控制台。 请确保
generate_signature
函数已正确实现，并且使用了正确的加密算法。
signature = generate_signature(timestamp, method, request_path, body, secret_key)
print(f"Signature: {signature.decode()}")
5. 代码示例 (Python)
以下是一个使用Python发起GET请求获取所有现货交易对行情信息的示例代码。此代码示例展示了如何通过OKX API获取现货市场交易对的实时数据。务必确保您的Python环境已经安装了requests和time库，如果没有，请使用pip进行安装：
pip install requests
。
import requests
import time
import hashlib
import hmac
import base64
import
def generate_signature(timestamp, method, request_path, body, secret_key):
"""
生成API请求的数字签名。
Args:
timestamp (str): 时间戳，Unix时间。
method (str): HTTP请求方法，如GET或POST。
request_path (str): API请求路径，例如'/api/v5/market/tickers'。
body (str): 请求体，用于POST请求，GET请求通常为空字符串。
secret_key (str): 您的API密钥对应的Secret Key。
Returns:
str: 生成的数字签名。
"""
message = timestamp + method.upper() + request_path + body
mac = hmac.new(bytes(secret_key, encoding='utf8'), bytes(message, encoding='utf-8'), digestmod=hashlib.sha256)
d = mac.digest()
return base64.b64encode(d).decode()
api_key = "YOUR_API_KEY" # 替换为你的API Key
secret_key = "YOUR_SECRET_KEY" # 替换为你的Secret Key
passphrase = "YOUR_PASSPHRASE" # 替换为你的Passphrase，账户安全密码
base_url = "https://www.okx.com"
endpoint = "/api/v5/market/tickers"
inst_type = "SPOT" # 现货
url = base_url + endpoint + "?instType=" + inst_type
method = "GET"
timestamp = str(int(time.time()))
body = ""
signature = generate_signature(timestamp, method, endpoint + "?instType=" + inst_type, body, secret_key)
headers = {
"OK-ACCESS-KEY": api_key,
"OK-ACCESS-SIGN": signature,
"OK-ACCESS-TIMESTAMP": timestamp,
"OK-ACCESS-PASSPHRASE": passphrase,
"Content-Type": "application/" # 指定Content-Type为application/
}
try:
response = requests.get(url, headers=headers)
response.raise_for_status() # 检查HTTP状态码，如果不是200，则抛出异常
data = response.() # 使用response.()解析JSON格式的响应数据
print(.dumps(data, indent=4)) # 使用.dumps美化输出，方便阅读
except requests.exceptions.RequestException as e:
print(f"Error: {e}")
请务必将代码中的
YOUR_API_KEY
,
YOUR_SECRET_KEY
, 和
YOUR_PASSPHRASE
替换为你在OKX交易所创建的API密钥信息。 Passphrase 是你在创建 API 密钥时设置的安全密码。为了安全起见，请勿将您的API密钥泄露给他人，并妥善保管。另外，该示例使用了
.dumps
函数来格式化输出JSON数据，使其更易于阅读。代码中还包含了错误处理机制，当请求发生异常时，会打印错误信息。 确保你的API密钥拥有读取市场数据的权限，否则请求将会失败。 你可以通过OKX的官方文档来了解更多关于API的详细信息和使用方法。
6. 错误处理
与欧易API交互时，开发者可能会遇到各种类型的错误。为了便于问题诊断和调试，欧易API采用标准的HTTP状态码结合JSON格式的错误信息来明确地指示错误原因。理解这些错误代码和消息对于构建健壮的应用至关重要。
常见的HTTP状态码及其在欧易API上下文中的含义包括：
-
200 OK: 这表明请求已成功处理，服务器已返回预期的结果。这是最理想的情况。 -
400 Bad Request: 此错误表示客户端发送的请求存在问题，例如，缺少必需的参数、参数值无效或参数格式错误。仔细检查请求体，确保所有参数都符合API文档的要求。 -
401 Unauthorized: 此状态码指示客户端未经过身份验证。通常，这意味着API Key缺失、无效或与请求不匹配，或者签名过程出现错误。验证API Key是否已正确配置，并且签名算法的实现是否与欧易的要求一致。请特别注意时间戳的同步问题，因为签名通常包含时间戳以防止重放攻击。 -
403 Forbidden: 客户端已通过身份验证，但没有足够的权限访问所请求的资源。这可能是由于API Key的权限设置不正确，或者账户本身没有执行特定操作的权限（例如，交易权限）。检查API Key的权限设置，并确保账户已启用必要的权限。 -
429 Too Many Requests: 客户端发送的请求过于频繁，触发了欧易API的速率限制。为了保护服务器的稳定性和公平性，API会限制每个IP地址或API Key在一定时间内可以发送的请求数量。实施重试机制，并使用指数退避算法来避免短时间内再次触发速率限制。查看API文档中关于速率限制的具体规定。 -
500 Internal Server Error: 此错误表明服务器内部出现了问题，无法完成请求。这通常不是客户端错误，而是欧易服务器的问题。如果频繁出现此错误，请联系欧易的技术支持团队。在重试之前，建议等待一段时间，以避免加重服务器的负担。 -
502 Bad Gateway: 作为网关或代理角色的服务器，从上游服务器接收到了无效响应。可能表示上游服务器暂时不可用。 -
503 Service Unavailable: 服务器当前无法处理请求，可能是由于维护或过载。客户端可以稍后重试。
当收到非200的错误响应时，开发者应该仔细分析响应体中的JSON格式错误信息。这些信息通常包含详细的错误代码和错误描述，可以帮助开发者定位问题。根据错误信息，检查请求参数、身份验证信息、权限设置和速率限制，并采取相应的纠正措施。 建议记录错误日志，以便于问题追踪和分析。
四、注意事项
- 安全第一： 绝对保证API Key和Secret Key的安全至关重要。 将它们视为高敏感信息，切勿以任何形式泄露给他人。 为了进一步增强安全性，强烈建议将API Key绑定到特定的IP地址，限制未经授权的访问。 定期更换API密钥是预防潜在安全风险的有效措施。 通过这些措施，可以最大限度地减少密钥泄露的风险，保护您的交易安全。
- 速率限制： 欧易API对请求频率设有速率限制，旨在维护系统的稳定性和公平性。 请务必仔细阅读并严格遵守欧易官方发布的速率限制规则。 若请求频率超出限制，您的访问可能会被暂时或永久禁止。 合理规划API调用策略，避免短时间内发送大量请求，是确保API访问顺畅的关键。
- 仔细阅读文档： 在开始使用任何欧易API接口之前，务必花费足够的时间深入研究官方API文档。 理解每个接口的详细参数说明、预期返回值格式以及可能出现的错误代码至关重要。 只有充分理解API的运作方式，才能编写出稳定、高效且不易出错的应用程序。
- 测试环境： 在将您的交易策略部署到真实市场之前，强烈建议先在欧易提供的测试环境（sandbox）中进行充分的模拟测试。 测试环境允许您在不承担真实资金风险的情况下，验证您的代码逻辑是否正确，以及交易策略是否能够按照预期执行。 这是一个发现和修复潜在bug，优化交易策略的宝贵机会。
- 及时更新： 加密货币市场和交易所的API都在不断发展。 欧易API会定期进行更新和升级，以改进功能、增强安全性和提升性能。 为了确保您的应用程序始终能够正常工作，并充分利用最新的API特性，请密切关注欧易官方发布的公告和更新日志，并及时更新您的代码。