欧易OKX API交易数据获取指南：K线与成交明细，量化交易必备！

时间：2025-03-07 阅读数：19人阅读

欧易交易所如何利用API获取历史交易数据

在加密货币交易领域，获取历史交易数据对于量化交易、策略回测、市场分析至关重要。欧易（OKX）交易所提供了强大的API接口，允许开发者和交易者高效、便捷地获取所需的历史交易数据。本文将详细介绍如何利用欧易API获取历史交易数据，并提供必要的代码示例和注意事项。

准备工作

在使用欧易API之前，为了确保顺利进行并保障账户安全，需要进行以下准备工作：

注册欧易账户并完成身份认证: 访问欧易官方网站（ https://www.okx.com/ ）注册账户。身份认证是使用API的关键步骤，不同等级的认证会影响API的使用权限和交易限额。请务必按照欧易的要求，提供真实有效的身份信息，完成KYC（Know Your Customer）流程，以确保账户的合法性和合规性。
创建API Key: 登录欧易账户，找到API管理或API设置页面（通常位于账户设置或安全中心）。创建一个新的API Key，并仔细设置其权限。通常情况下，需要开启“读取”权限才能获取市场数据和账户信息；如果需要进行交易操作，必须谨慎地开启“交易”权限。强烈建议开启IP限制，只允许特定的IP地址访问API，以增强安全性。生成API Key时，会同时生成API Key和Secret Key。 务必妥善保管API Key和Secret Key，切勿以任何方式泄露给他人。 建议将Secret Key保存在安全的地方，例如使用密码管理器进行加密存储。一旦泄露，请立即吊销该API Key并重新生成。
安装必要的开发环境: 根据你选择的编程语言，安装相应的开发环境和依赖库。例如，如果选择Python，需要安装Python解释器（建议使用Python 3.6或更高版本），并使用pip安装requests库（ pip install requests ）。根据需要，可能还需要安装其他库，例如用于处理JSON数据的库，以及用于数据分析的 pandas 库。如果使用其他编程语言，例如Java或Node.js，则需要安装相应的SDK或库，并配置开发环境。

API接口介绍

欧易（OKX，以前称为OKEx）提供了丰富的API接口，方便开发者获取历史交易数据，进行量化分析、策略回测等操作。在众多接口中，以下两个接口在获取历史数据方面尤为重要：

获取历史K线数据 (Candlesticks): 该接口允许用户请求指定交易对的历史K线（也称为OHLCV数据）数据。K线数据是技术分析的基础，包含了开盘价(Open)、最高价(High)、最低价(Low)、收盘价(Close)以及成交量(Volume)五个关键信息。通过指定时间周期参数，可以获取1分钟、3分钟、5分钟、15分钟、30分钟、1小时、2小时、4小时、6小时、12小时、日线、周线、月线等多种时间粒度的K线数据。还可以通过参数控制返回数据的起始时间和结束时间，实现对特定时间段内K线数据的精确获取。不同的API版本，参数命名和格式会有差异，需要仔细阅读官方文档。
获取历史成交明细 (Trades): 该接口提供指定交易对的历史成交明细数据，每一条成交明细记录了单笔交易的具体信息，包括成交价格、成交数量、成交方向（买入或卖出）以及成交时间（精确到毫秒甚至微秒级别）。此接口适用于高频交易策略的研究和分析，可以还原更细粒度的市场微观结构。使用时需要注意，由于成交数据量巨大，可能需要分页请求或使用时间范围过滤，以避免数据量过大导致请求失败。同时，交易所会对历史数据的保留时间有限制，较早的历史数据可能无法获取。

本文将重点介绍如何高效、准确地使用“获取历史K线数据”接口，并提供一些实践技巧和注意事项，帮助开发者更好地利用该接口进行量化交易研究和分析。

获取历史K线数据 (Candlesticks)

API Endpoint: /api/v5/market/history-candles 。此端点用于检索特定交易对在指定时间范围内的历史K线数据，为技术分析和回测提供基础数据支撑。
请求方式: GET。使用GET方法发送HTTP请求，以便从服务器获取K线数据。确保客户端能够正确处理服务器返回的JSON格式数据。

请求参数:

参数名	类型	是否必须	描述
instId	String	是	交易对ID，用于指定需要查询的交易品种。例如， `BTC-USDT` 表示比特币兑USDT的交易对。确保交易对ID的准确性，否则将无法获取正确的数据。
after	String	否	起始时间戳，以UTC milliseconds格式表示。该参数定义了K线数据的起始时间。默认情况下，API返回最近的历史数据。若不指定 `after` 和 `before` ，则返回最近的K线数据。最大时间跨度为最近1440条数据。
before	String	否	结束时间戳，以UTC milliseconds格式表示。该参数定义了K线数据的结束时间。默认情况下，API返回最近的历史数据。若不指定 `after` 和 `before` ，则返回最近的K线数据。最大时间跨度为最近1440条数据。
limit	String	否	返回的数据条数，默认为100。可以通过调整该参数来控制返回的数据量。最大值为1440，超过该值将会被截断。合理设置 `limit` 可以优化API请求的效率。
bar	String	是	K线的时间粒度，决定了每根K线的时间跨度。例如： `1m` 表示1分钟K线， `1H` 表示1小时K线， `1D` 表示1天K线。支持的时间粒度包括： `1m` , `3m` , `5m` , `15m` , `30m` , `1H` , `2H` , `4H` , `6H` , `8H` , `12H` , `1D` , `1W` , `1M` , `3M` , `1Y` 。根据分析需求选择合适的时间粒度。

返回数据:

API返回一个JSON数组，数组中的每个元素代表一根K线，包含了该时间段内的开盘价、最高价、最低价、收盘价和成交量等信息。这些数据是进行技术分析和制定交易策略的重要依据。

字段	类型	描述
time	String	K线的时间戳，以UTC milliseconds格式表示。该时间戳标志了该K线对应的时间段。例如， `1678886400000` 。
open	String	该K线时间段内的开盘价。反映了市场在该时间段开始时的价格。
high	String	该K线时间段内的最高价。反映了市场在该时间段内达到的最高价格。
low	String	该K线时间段内的最低价。反映了市场在该时间段内达到的最低价格。
close	String	该K线时间段内的收盘价。反映了市场在该时间段结束时的价格。收盘价是判断价格趋势的重要指标。
vol	String	成交量。对于币本位合约，表示成交的币数量；对于交割合约，表示成交的合约张数。成交量是衡量市场活跃度的重要指标。
volCcy	String	成交额（计价货币单位）。对于币本位合约，表示成交的计价货币数量；对于交割合约，通常不提供此字段，成交量已经代表成交合约张数。
volCcyQuote	String	成交额（计价货币单位）。对于币本位合约，表示成交的计价货币数量；对于交割合约，通常不提供此字段，成交量已经代表成交合约张数，与 `volCcy` 意义相同，不同平台可能命名有差异。

代码示例 (Python)

以下是一个使用Python获取欧易（OKX）交易所历史K线数据的示例代码，它展示了如何通过OKX API v5接口获取指定交易对的历史行情数据。使用 requests 库发送HTTP请求，并使用 time 库处理时间戳。

import requests import time

def get_okx_history_candles(instId, bar, limit=100, after=None, before=None): """ 获取欧易历史K线数据.

Args:
    instId (str): 交易对ID，指定要查询的交易品种，例如 'BTC-USDT'（比特币兑USDT）。
    bar (str): K线的时间粒度，表示每根K线的时间周期，例如 '1m'（1分钟），'5m'（5分钟），'1H'（1小时），'1D'（1天）。  具体参考OKX API文档。
    limit (int): 返回K线数据的数量上限，默认为100，最大允许值为1440。 调整此参数可以在单次请求中获取更多数据，但需注意API的限制。
    after (int): 起始时间戳，用于指定查询的起始时间，以UTC毫秒为单位。  K线数据仅返回大于此时间戳的数据。
    before (int): 结束时间戳，用于指定查询的结束时间，以UTC毫秒为单位。 K线数据仅返回小于此时间戳的数据。

Returns:
    list: K线数据列表，每个元素是一个包含开盘价、最高价、最低价、收盘价、成交量等信息的列表。  如果请求失败，返回 None。 K线数据的具体字段和含义请参考OKX API文档。
    """

url = 'https://www.okx.com/api/v5/market/history-candles'
params = {
    'instId': instId,
    'bar': bar,
    'limit': limit
}
if after:
    params['after'] = after
if before:
    params['before'] = before

try:
    response = requests.get(url, params=params)
    response.raise_for_status()  # 检查HTTP状态码，如果不是200，表示请求失败，抛出异常。 确保API请求成功。

    data = response.()
    if data['code'] == '0':
        return data['data']
    else:
        print(f"API请求失败: {data['msg']}")
        return None
except requests.exceptions.RequestException as e:
    print(f"请求异常: {e}")
    return None

示例用法:

在实际应用中，您可以通过以下代码示例，使用 get_okx_history_candles 函数获取指定交易对的历史K线数据。以下示例演示了如何获取BTC-USDT交易对最近一小时的1分钟K线数据。

instId = 'BTC-USDT' ：定义交易对ID，此处设置为BTC-USDT，表示比特币兑美元泰达币。

bar = '1m' ：定义K线周期，此处设置为'1m'，表示1分钟K线。您可以根据需求选择其他周期，例如'5m'（5分钟）、'15m'（15分钟）、'1H'（1小时）、'1D'（1天）等。

limit = 100 ：定义单次请求获取的最大K线数量。OKX API对单次请求的数量有限制，通常不超过100根K线。您可以根据需要调整此参数，但建议不要超过API的限制。

now = int(time.time() * 1000) ：获取当前时间戳（毫秒）。 time.time() 返回当前时间的秒数，乘以1000将其转换为毫秒，并使用 int() 函数转换为整数。

one_hour_ago = now - 60 * 60 * 1000 ：计算一小时前的时间戳（毫秒）。60 * 60 * 1000表示一小时的毫秒数，从当前时间戳中减去它即可得到一小时前的时间戳。 after 和 before 参数都需要毫秒级别的时间戳。

candles = get_okx_history_candles(instId, bar, limit, after=one_hour_ago, before=now) ：调用 get_okx_history_candles 函数，传入交易对ID、K线周期、K线数量限制、起始时间戳和结束时间戳，获取历史K线数据。

在获取数据之后，进行数据处理和分析：

if candles: ：检查是否成功获取到K线数据。如果 candles 列表不为空，表示获取到数据；否则，表示未能获取到数据。

print(f"获取到 {len(candles)} 条 {instId} 的 {bar} K线数据:") ：打印获取到的K线数量和交易对信息。

for candle in candles: print(candle) ：遍历 candles 列表，打印每一根K线的数据。每一根K线通常包含开盘价、最高价、最低价、收盘价、交易量等信息。您可以根据需要提取和使用这些数据。

else: print("未能获取到K线数据.") ：如果未能获取到K线数据，则打印相应的提示信息。这可能是由于网络问题、API限制、时间范围错误等原因导致的。

代码解释:

导入必要的库: 程序伊始，需引入多个Python库以支持数据获取和处理。 requests 库是关键，它允许程序发送HTTP请求，例如从欧易（OKX）交易所的API获取数据。库用于解析API返回的JSON格式数据，将其转换为Python可操作的对象。 time 库则提供获取当前时间戳的功能，时间戳在构建API请求参数时经常用到，比如指定起始时间。
定义 get_okx_history_candles 函数: 此函数封装了获取欧易历史K线数据的全部逻辑。函数接受诸如交易对（例如"BTC-USDT"）、时间粒度（例如"1m"表示1分钟K线）等参数，并负责构造API请求、发送请求、处理响应，最终返回解析后的K线数据。采用函数封装有利于代码的模块化和重用，方便在程序的其他部分调用。
构造API请求URL和参数: 为了从欧易API获取数据，必须构造一个符合API文档要求的URL。该URL通常包含API的端点地址以及查询参数，例如交易对ID、时间粒度、起始时间和结束时间等。这些参数必须按照API文档规定的格式进行编码。准确的URL和参数是成功获取数据的关键。例如，URL可能类似于： https://www.okx.com/api/v5/market/history-candles?instId=BTC-USDT&bar=1m&limit=100 。
发送HTTP请求: 利用 requests.get 方法向欧易API发送GET请求。GET请求常用于获取数据。在发送请求时，可以将构造好的URL和参数传递给 requests.get 方法。 requests 库会自动处理HTTP连接、请求头等底层细节，简化了网络请求的编程。
处理API响应: 收到API的响应后，需要进行一系列处理。检查HTTP状态码。状态码200表示请求成功。如果状态码不是200，则表明请求失败，可能是由于网络问题、API错误或参数错误等原因。如果状态码为200，则进一步解析JSON数据。API通常以JSON格式返回数据。使用 .loads 方法将JSON字符串转换为Python字典或列表。然后，检查JSON数据中的 code 字段。如果 code 为 0 ，则表示API请求成功，可以提取K线数据。否则，根据 code 和错误信息进行相应的错误处理，例如打印错误信息或记录日志。
示例用法: 为了演示 get_okx_history_candles 函数的使用方法，可以设置一些示例参数，例如交易对ID（ instId ）、时间粒度（ bar ）、数量（ limit ）等。然后，调用 get_okx_history_candles 函数，并将这些参数传递给它。函数将返回K线数据列表。可以将K线数据打印出来，或者将其用于进一步的分析和处理。例如，可以计算移动平均线、绘制K线图等。

注意事项

频率限制： 欧易API为了保障系统稳定性和公平性，对API请求的频率做了严格限制。务必仔细阅读并严格遵守欧易API官方文档中关于频率限制的详细规定，不同API接口可能有不同的频率限制策略。超出频率限制可能会触发熔断机制，导致您的API Key被暂时或永久禁用。在编写代码时，应考虑到并发请求量，并采取适当的限流措施。例如，可以使用令牌桶算法或漏桶算法来控制请求速度。同时，建议实现完善的错误处理机制，使用 try-except 语句捕获因频率限制引发的异常（如HTTP状态码429 Too Many Requests），并添加适当的延时（如使用 time.sleep() 函数）。动态调整延时时间，例如使用指数退避策略，可以更好地适应API服务器的压力情况。
数据精度： 欧易API返回的数据通常具有较高的精度，尤其是在交易相关的数据中，微小的精度误差可能会导致交易结果的偏差。为了避免浮点数运算的精度问题，强烈建议使用Python的 Decimal 类型或类似的任意精度数字类型来处理API返回的数值数据。 Decimal 类型可以精确表示十进制数，从而避免浮点数舍入误差。在进行数学运算时，也应使用 Decimal 类型进行计算，并设置合适的精度（通过 decimal.getcontext().prec 设置）以满足业务需求。
时间戳： 欧易API统一使用UTC milliseconds（协调世界时毫秒）格式的时间戳来表示时间。这意味着从1970年1月1日00:00:00 UTC到特定时刻的毫秒数。在构建API请求或解析API返回数据时，必须注意时间戳的单位和时区。如果您从其他时区或以其他格式（例如，秒或datetime对象）获取时间数据，则需要将其转换为UTC milliseconds格式。可以使用Python的 time 和 datetime 模块进行转换，并确保使用 timezone.utc 来指定UTC时区。例如，可以使用 int(datetime.datetime.now(tz=datetime.timezone.utc).timestamp() * 1000) 获取当前的UTC milliseconds时间戳。
错误处理： 在实际应用中，务必构建健壮的错误处理机制，以应对各种潜在的错误情况。这些错误可能包括网络连接错误（例如， requests.exceptions.ConnectionError ）、API请求超时（例如， requests.exceptions.Timeout ）、HTTP状态码错误（例如，400 Bad Request、401 Unauthorized、500 Internal Server Error）以及API返回的自定义错误码。对于每种错误情况，都应该有相应的处理逻辑，例如重试请求（对于瞬时错误）、记录错误日志、发送告警通知或采取其他补救措施。详细的错误处理可以提高应用程序的稳定性和可靠性，并帮助您快速定位和解决问题。考虑使用断路器模式来防止因API调用失败而导致的级联故障。
API Key安全： API Key和Secret Key是访问欧易API的凭证，拥有最高权限。务必采取一切必要措施来保护您的API Key和Secret Key，切勿将其泄露给任何未经授权的第三方。不要将API Key和Secret Key硬编码到代码中，也不要将其提交到公共代码仓库（例如，GitHub）。建议将API Key和Secret Key存储在安全的地方，例如环境变量、配置文件或密钥管理服务（例如，HashiCorp Vault）。在应用程序启动时，从安全存储中读取API Key和Secret Key。定期轮换API Key可以进一步提高安全性。如果怀疑API Key已泄露，请立即撤销并生成新的API Key。
分页处理： 如果需要从欧易API获取大量的历史数据（例如，历史交易记录、K线数据），API通常会采用分页机制来限制单次返回的数据量。在这种情况下，您需要进行分页处理，即循环请求API，每次请求获取一部分数据，直到获取所有所需的数据。欧易API通常使用 after 和 before 参数来控制数据的起始时间和结束时间，或者使用 limit 和 offset 参数来控制返回的数据条数和偏移量。仔细阅读API文档，了解具体的分页参数和分页逻辑。在循环请求API时，需要记录上次请求的最后一个数据的时间戳或ID，并将其作为下次请求的 after 或 before 参数。注意处理API返回的数据条数小于 limit 的情况，这通常表示已经到达数据的末尾。为了提高效率，可以考虑使用多线程或异步编程来并发请求API，但要注意控制并发请求的数量，避免触及频率限制。

其他API

除了获取历史K线数据，交易所还提供其他API用于获取历史交易数据，例如获取历史成交明细、订单簿快照等。选择合适的API接口应基于实际需求和数据精度要求。例如，成交明细提供微观的交易信息，而订单簿快照则反映市场深度和流动性。

获取历史成交明细 (Trades)

API Endpoint: /api/v5/market/history-trades
请求方式: GET

参数与K线数据类似，关键参数是


  instId

（交易对ID）和数量


  limit

。还可以使用


  after

和


  before

参数进行时间范围过滤，从而获取特定时间段内的成交明细数据。注意，频繁请求可能触发速率限制，合理设置请求间隔至关重要。

以下是一个使用Python requests 库获取欧易历史成交明细的示例代码：

Python

import requests
import 

def get_okx_history_trades(instId, limit=100, after=None, before=None):
    """
    获取欧易历史成交明细。

    Args:
        instId (str): 交易对ID, 例如 'BTC-USDT'。
        limit (int): 返回的数量, 默认 100, 最大 400。
        after (int): 起始时间戳, UTC milliseconds格式。用于指定查询起始点，返回晚于此时间戳的数据。
        before (int): 结束时间戳, UTC milliseconds格式。用于指定查询结束点，返回早于此时间戳的数据。

    Returns:
        list: 成交明细数据列表, 每个元素是一个包含价格、数量、成交时间等信息的字典。
              如果请求失败, 返回 None。

    Raises:
        requests.exceptions.RequestException: 当HTTP请求发生错误时抛出。
        .JSONDecodeError: 当解析JSON响应失败时抛出。
    """

    url = 'https://www.okx.com/api/v5/market/history-trades'
    params = {
        'instId': instId,
        'limit': limit
    }
    if after:
        params['after'] = after
    if before:
        params['before'] = before

    try:
        response = requests.get(url, params=params)
        response.raise_for_status()  # 检查HTTP状态码, 如果不是200, 抛出异常

        data = response.()  # 使用.()方法解析JSON响应
        if data['code'] == '0':
            return data['data']
        else:
            print(f"API请求失败: {data['msg']}")
            return None
    except requests.exceptions.RequestException as e:
        print(f"请求异常: {e}")
        return None
    except .JSONDecodeError as e:
        print(f"JSON解析错误: {e}")
        return None

代码解释：该函数向欧易API发送GET请求，获取指定交易对的历史成交明细。 instId 参数指定交易对， limit 参数指定返回的数量。 after 和 before 参数用于指定时间范围。函数首先构建请求URL和参数，然后使用 requests 库发送请求。如果请求成功，函数解析JSON响应并返回成交明细数据列表。如果请求失败，函数打印错误信息并返回 None 。该代码还包括了异常处理，以捕获HTTP请求错误和JSON解析错误。

示例用法:

在量化交易或数据分析中，获取历史成交明细数据至关重要。以下示例展示如何使用 get_okx_history_trades 函数获取 OKX 交易所指定交易对的历史成交记录。

参数设置:

instId = 'BTC-USDT' : 指定要查询的交易对，此处为比特币兑 USDT (BTC-USDT)。 instId 代表 instrument ID，是 OKX 交易所用来唯一标识交易对的字符串。确保 instId 的格式与 OKX 交易所的规范一致。不同的交易对，例如 ETH-USDT、LTC-USDT 等，只需修改此参数即可。

limit = 100 : 设置每次 API 调用返回的最大成交记录数量。 limit 参数用于控制返回的数据量，以避免一次性获取过多数据导致程序运行缓慢或超出 API 限制。OKX 交易所通常对每次请求的数据量有限制，务必查阅 API 文档了解具体的限制值。常见的 limit 取值范围为 1 到 200。

调用函数:

trades = get_okx_history_trades(instId, limit) : 调用 get_okx_history_trades 函数，传入交易对 ID ( instId ) 和数量限制 ( limit ) 作为参数。该函数会连接 OKX 交易所的 API，并获取指定交易对的成交明细数据。返回的结果 trades 是一个包含成交记录的列表。

结果处理:

if trades: : 检查 trades 列表是否为空。如果列表不为空，说明成功获取到成交明细数据。

print(f"获取到 {len(trades)} 条 {instId} 的成交明细数据:") : 打印获取到的成交记录数量和交易对信息。 len(trades) 返回列表中的元素个数，即成交记录的数量。使用 f-string 格式化字符串，将变量的值嵌入到字符串中。

for trade in trades: : 遍历 trades 列表，逐条打印成交记录的详细信息。每一条 trade 通常是一个包含成交价格、成交数量、成交时间等信息的字典或对象。

print(trade) : 打印单条成交记录的信息。

else: : 如果 trades 列表为空，说明未能获取到成交明细数据，可能是由于网络连接问题、API 密钥错误或交易所没有提供相关数据等原因。

print("未能获取到成交明细数据.") : 打印未能获取到数据的提示信息。建议检查网络连接、API 密钥以及交易对 ID 是否正确，并重试操作。

本文详细介绍了如何利用欧易API获取历史交易数据，包括注册API Key、了解API接口、编写代码示例和注意事项。通过掌握这些知识，可以方便地获取所需的历史交易数据，用于量化交易、策略回测、市场分析等应用。

上一篇: 火币网新手必看：7步玩转交易，躺赚攻略大公开！

下一篇: Bitget充值卡疑难杂症终结者：常见问题与解决方案全解析！