Upbit API交易接口：新手如何快速入门？| 教程详解

阅读：50 分类： 资源

Upbit API 交易接口：深度解析与应用

Upbit 作为韩国领先的数字货币交易所，其 API 接口为开发者和量化交易者提供了强大的工具，能够实现自动化交易、市场数据分析以及账户管理等功能。本文将深入探讨 Upbit API 交易接口的各项功能、使用方法以及注意事项，旨在帮助读者更好地理解和应用该接口。

1. API 接口概述

Upbit API 接口遵循 RESTful 架构设计原则，通过标准的 HTTP 请求方法（GET, POST, PUT, DELETE）进行数据交互，实现与Upbit服务器的数据交换。开发者可以利用多种编程语言，包括但不限于Python、Java、Node.js、Go、C# 等，构建应用程序以调用 Upbit 提供的 API 接口。这些接口功能丰富，全面覆盖了实时市场数据获取、高效交易执行、安全账户信息查询、以及便捷的出入金管理等多个核心领域。

市场数据类 API 允许开发者获取包括实时行情、历史交易数据、订单簿深度信息等，为量化交易策略提供数据支撑。交易执行类 API 则支持开发者程序化下单、撤单，实现自动交易。账户信息查询 API 提供账户余额、交易历史、持仓情况等信息，方便用户监控账户状态。API 还提供诸如生成API密钥、管理API权限等功能，确保交易安全。

为了保障API使用的安全性与稳定性，Upbit API通常采用OAuth 2.0等身份验证机制，要求开发者进行身份验证后才能访问。 同时，API还可能实施速率限制，以防止滥用并确保所有用户的公平访问。开发者在使用API时，应详细阅读Upbit官方提供的API文档，了解各个接口的参数要求、返回数据格式、以及错误码信息，以便于高效开发和调试。

2. 认证与授权

在使用 Upbit API 接口之前，必须进行严格的身份认证和授权流程。Upbit 采用 JWT (JSON Web Token) 标准进行身份验证，确保通信安全。开发者需要在 Upbit 官方网站注册并申请 API 密钥，包括 Access Key 和 Secret Key。Access Key 用于唯一标识您的账户，类似于用户名，而 Secret Key 则作为密码，用于对请求进行签名，防止篡改和中间人攻击。务必妥善保管您的 Secret Key，避免泄露。

获得 Access Key 和 Secret Key 后，您需要在每个 API 请求的 HTTP 头部中添加 Authorization 字段，其值为 Bearer ，其中 是根据您的密钥生成的 JSON Web Token。 JWT 的生成过程包括构建 Payload、Header 和 Signature 三个主要部分。

  • Payload (数据载体): Payload 承载着有关用户的声明信息，对于 Upbit API 来说，通常包含 access_key ，用于识别用户身份，以及 nonce (随机字符串)，用于防止重放攻击。 nonce 必须是每次请求都不同的唯一值，可以使用 UUID 等方式生成。Payload 还可以包含其他自定义的声明，例如过期时间。
  • Header (头部): Header 用于指定 JWT 的元数据，包括所使用的签名算法 (例如 HMAC-SHA512 或 RS256) 以及 Token 类型 (通常为 "JWT")。Header 通常以 JSON 格式表示。
  • Signature (签名): Signature 是通过使用 Secret Key 对 Payload 和 Header 进行加密计算得到的。Upbit 官方推荐使用 HMAC-SHA512 算法生成签名，以确保数据的完整性和真实性。签名过程可以有效地防止恶意用户篡改 Payload 或 Header 中的信息。

以下是一个使用 Python 语言生成 JWT 的示例代码，展示了如何使用您的 Access Key 和 Secret Key 创建符合 Upbit API 要求的 Authorization 头部信息：

import jwt import uuid import hashlib

access key = "YOUR ACCESS KEY" # 替换为您的 Access Key secret key = "YOUR SECRET KEY" # 替换为您的 Secret Key

payload = { 'access key': access key, 'nonce': str(uuid.uuid4()), # 生成唯一的 nonce 值 }

jwt token = jwt.encode(payload, secret key, algorithm='HS256') # 使用 HS256 算法生成 JWT authorization = f"Bearer {jwt_token}" # 构建 Authorization 头部信息

print(authorization) # 打印生成的 Authorization 头部信息

3. 常用 API 接口

以下是一些常用的 Upbit API 接口及其功能，这些接口是开发者进行程序化交易、数据分析以及构建自动化交易策略的基础。理解并熟练使用这些API能够让你更高效地与Upbit交易所进行交互。

  • 市场行情 API:
    • /market/all : 获取所有市场代码。这个接口返回Upbit支持的所有交易对信息，例如 KRW-BTC (韩元对比特币), BTC-ETH (比特币对以太坊) 等。它提供了市场代码、市场名称和支持交易的功能，是程序初始化的重要数据来源。
    • /ticker : 获取指定市场的实时行情数据。该接口返回的信息包括最近成交价、24小时累计交易量、最高价、最低价、涨跌幅等关键指标。这些数据对于实时监控市场动态，进行短线交易决策至关重要。
    • /trades/ticks : 获取指定市场的历史成交记录。通过这个接口，你可以获取成交时间、成交价格、成交量等历史成交明细数据。利用历史成交数据，可以进行回测、构建量化交易模型、分析市场微观结构。
    • /candles/minutes/{unit} : 获取指定市场的分时 K 线数据。 {unit} 表示分钟数，例如 1 代表 1 分钟 K 线， 5 代表 5 分钟 K 线。K 线数据包括开盘价、收盘价、最高价和最低价，是技术分析的基础。不同时间周期的 K 线反映了不同时间跨度的市场趋势。
    • /candles/days : 获取指定市场的日 K 线数据。日 K 线反映了每日的价格波动，对于分析中长线趋势非常重要。
    • /candles/weeks : 获取指定市场的周 K 线数据。周 K 线数据可以帮助投资者了解中期市场趋势。
    • /candles/months : 获取指定市场的月 K 线数据。月 K 线数据可以帮助投资者了解长期市场趋势。
  • 交易 API:
    • /orders/chance : 查询指定市场的下单可能性信息。这个接口返回的信息包括账户可用余额、该市场最小下单数量、市场挂单费用等。在下单前，使用此接口可以确保交易顺利进行，避免因余额不足或下单量过小导致交易失败。
    • /orders : 下单接口。通过这个接口，你可以提交各种类型的订单，包括市价单、限价单和止损单。下单时，你需要指定市场代码、订单类型 ( bid 买单 / ask 卖单)、交易量，以及价格 (限价单需要)。对于止损单，还需要设置触发价格。
    • /order : 查询指定订单的详细信息。使用订单ID可以查询订单的状态（已成交、未成交、已取消等）、下单时间、成交价格和成交量等详细信息。
    • /orders/chance : 可以查询账户在该市场下单的可能性，与第一个 /orders/chance 接口功能类似，用于预先检查下单条件。
    • /orders : 可以批量查询未成交订单，也可以取消未成交订单。批量查询可以高效地获取当前挂单状态，方便管理未成交订单。取消未成交订单有助于快速调整交易策略，降低市场风险。
  • 账户 API:
    • /accounts : 查询账户资产信息。这个接口返回的信息包括账户持有的币种、可用余额、锁定余额等。可用余额是指可以用于交易的资金，锁定余额是指挂单占用的资金。通过定期查询账户信息，可以有效监控资金状况，进行风险控制。

4. 下单接口详解

下单接口是API交易的核心组成部分，用于执行买卖订单。 通过 /orders 接口，用户可以提交买入 (bid) 和卖出 (ask) 请求，实现资产的交易操作。

请求参数：

  • market : 市场代码，指定交易的市场。 例如， KRW-BTC 表示韩元 (KRW) 交易比特币 (BTC) 的市场。 其他市场代码，如 BTC-ETH (比特币交易以太坊) 也是有效的选项。
  • side : 订单类型，区分买入和卖出操作。 bid 表示买入订单，用于购买指定数量的资产。 ask 表示卖出订单，用于出售持有的资产。
  • volume : 交易量，指定要买入或卖出的资产数量，单位为对应币种。 例如，在 KRW-BTC 市场中， volume 的单位是 BTC。
  • price : 价格，指定订单的执行价格。 该参数仅在限价单 ( limit ) 中有效。 对于市价单，该参数会被忽略。
  • ord_type : 订单类型，定义订单的执行方式。 limit 表示限价单，以指定价格或更优价格成交。 price 表示市价买入，以当前市场最优价格买入指定金额的资产。 market 表示市价卖出，以当前市场最优价格卖出指定数量的资产。
  • identifier : 用户自定义的唯一订单标识符 (可选)。允许用户为每个订单分配一个唯一的ID，方便订单跟踪和管理。 该标识符必须在用户账户中是唯一的。

示例 (Python):

requests 和 jwt 是常用的Python库，用于发送HTTP请求和处理JSON Web Token (JWT)。 uuid 用于生成唯一ID， hashlib 提供哈希算法支持，确保API请求的安全性。

access_key = "YOUR_ACCESS_KEY"
secret_key = "YOUR_SECRET_KEY"
将 YOUR_ACCESS_KEY 和 YOUR_SECRET_KEY 替换为你的Upbit API密钥。 访问密钥用于标识用户，密钥用于签名请求，确保请求的完整性和真实性。
market = "KRW-BTC"
side = "bid" # 买入
volume = "0.001"
price = "50000000"
ord_type = "limit"

构造查询字符串，包含所有必要的订单参数。 对查询字符串进行哈希处理，生成一个唯一的哈希值，用于验证请求的完整性。 使用 SHA512 算法进行哈希处理，增强安全性。

query = f"market={market}&side={side}&volume={volume}&price={price}&ord_type={ord_type}"
query_hash = hashlib.sha512(query.encode('utf-8')).hexdigest()

创建 JWT payload，包含访问密钥、nonce（唯一随机数）、查询哈希和哈希算法。 nonce 用于防止重放攻击，确保每个请求都是唯一的。 query_hash_alg 指明使用的哈希算法。

payload = {
'access_key': access_key,
'nonce': str(uuid.uuid4()),
'query_hash': query_hash,
'query_hash_alg': 'SHA512',
}

使用密钥对 JWT payload 进行签名，生成 JWT token。 使用 HS256 算法进行签名。 authorization header 包含 "Bearer " 加上 JWT token。

jwt_token = jwt.encode(payload, secret_key, algorithm='HS256')
authorization = f"Bearer {jwt_token}"

指定 API 请求的 URL。 Upbit API 的基本 URL 是 https://api.upbit.com/v1 。 /orders 接口用于提交订单。

url = "https://api.upbit.com/v1/orders"

设置请求头，包含 authorization header。 authorization header 用于验证用户身份。

headers = {"Authorization": authorization}

构造请求数据，包含所有必要的订单参数。 这些参数将作为 POST 请求的 body 发送。

data = {
"market": market,
"side": side,
"volume": volume,
"price": price,
"ord_type": ord_type,
}

发送 POST 请求到 API 端点。 检查响应状态码，判断请求是否成功。 如果状态码是 200，表示请求成功。 其他状态码表示请求失败。

res = requests.post(url, headers=headers, data=data)

打印 API 响应。 API 响应包含订单的详细信息，例如订单ID、订单状态和成交信息。 可以使用 res.() 将响应转换为 JSON 格式。

print(res.())

5. 错误处理

在使用 Upbit API 接口进行数字资产交易和数据查询时，必须重视错误处理机制。Upbit API 会通过 HTTP 状态码以及 JSON 格式的错误信息来反馈请求处理结果。不同的状态码代表着不同类型的错误，开发者应该根据这些信息采取相应的应对措施，确保应用的稳定性和可靠性。

  • 400 : 客户端请求错误。此状态码表明请求中包含无效的参数或参数格式不正确。开发者需要仔细检查请求的 URL、请求头、请求体，确认所有参数都符合 Upbit API 的规范和要求，例如数据类型、取值范围等。常见原因包括缺少必要的参数、参数值超出范围、参数类型错误等。
  • 401 : 未授权 (Authentication failed)。此状态码表示身份验证失败。通常是由于 API 密钥无效、密钥过期、或签名错误造成的。开发者需要检查 API 密钥是否正确配置，以及签名算法是否正确实现。同时，需要注意 API 密钥的权限是否满足请求的要求。务必妥善保管 API 密钥，避免泄露。
  • 429 : 请求过于频繁 (Too Many Requests)。此状态码表明请求频率超过了 Upbit API 的限制。为了保护服务器的稳定性和公平性，Upbit API 对每个用户或 IP 地址的请求频率进行了限制。开发者需要根据 Upbit 官方文档的说明，合理控制请求频率，避免触发此错误。可以采用限流算法，如令牌桶或漏桶算法，来平滑请求流量。如果需要更高的请求频率，可以考虑联系 Upbit 申请更高的 API 访问权限。
  • 500 : 服务器内部错误。此状态码表明 Upbit 服务器内部发生了错误。这种情况通常不是由于客户端的错误引起的，而是 Upbit 服务器自身的故障。开发者可以稍后重试请求，或者联系 Upbit 客服报告此问题。需要注意的是，500 错误可能意味着 Upbit 交易平台出现了暂时性的问题，在依赖 API 进行交易时需要特别关注。

开发者需要根据错误状态码和错误信息，设计完善的错误处理机制，对错误进行适当的处理。例如，对于 400 错误，应该记录错误信息并通知开发者进行排查；对于 429 错误，应该采用指数退避算法进行重试，避免进一步增加服务器的压力；对于 500 错误，应该记录错误日志并进行监控，以便及时发现和解决问题。除了上述常见的错误状态码之外，Upbit API 还可能返回其他状态码，开发者应该仔细阅读 Upbit 官方文档，了解所有可能出现的错误状态码，并针对不同的错误状态码采取不同的处理策略。 良好的错误处理机制是保证 API 应用稳定运行的关键，也是构建可靠的自动化交易策略的基础。遇到无法解决的问题时，及时联系 Upbit 客服寻求帮助也是一个明智的选择。

6. API 使用注意事项

  • 频率限制: Upbit API 接口实施严格的频率限制策略，旨在保障所有用户的服务质量，防止恶意请求造成的资源过度占用。 超过频率限制可能导致您的 API 密钥被暂时封禁，影响交易和数据获取。 建议您仔细阅读 Upbit 官方 API 文档中关于频率限制的详细说明，并据此优化您的代码逻辑。 采用合理的请求频率控制机制至关重要，例如：
    • 滑动窗口限流： 实现一个滑动窗口算法，统计单位时间内请求数量，超过阈值则暂停发送请求。
    • 令牌桶算法： 使用令牌桶算法控制请求速度，匀速地向 API 发送请求。
    • 延时函数： 在代码中插入 `sleep()` 函数进行适当的延时，降低请求频率。推荐根据实际情况动态调整延时时间，避免不必要的等待。
    • 批量请求： 将多个请求合并为一个批量请求，减少请求次数，降低触发频率限制的风险。 部分API支持批量请求。
  • 安全性: 您的 Access Key 和 Secret Key 是访问 Upbit API 的凭证，务必妥善保管，避免泄露。 一旦泄露，可能导致您的账户被恶意操作，造成资金损失。 请注意以下安全事项：
    • 密钥存储： 切勿将 Access Key 和 Secret Key 直接硬编码在代码中。 建议将密钥存储在安全的地方，例如：环境变量、配置文件或加密的数据库中。
    • 权限控制： 根据实际需要，为 API 密钥分配最小权限，避免授予不必要的权限，降低风险。
    • 网络环境： 避免在公共场合或不安全的网络环境下使用 API 接口，防止密钥被窃取。 使用安全的 VPN 或代理服务器进行 API 调用。
    • 定期更换密钥： 定期更换 Access Key 和 Secret Key，增加安全性。
    • 监控异常： 密切监控 API 调用日志，及时发现异常情况，例如：不明来源的 API 调用、频繁的错误请求等。
  • 数据验证: Upbit API 返回的数据可能受到网络波动、服务器故障等因素的影响，导致数据不准确或不完整。 为保障交易决策的准确性，务必对 API 返回的数据进行严格的验证。 您可以采取以下验证措施：
    • 数据类型检查： 检查返回数据的类型是否符合预期，例如：价格是否为数字类型，数量是否为整数类型。
    • 数据范围检查： 检查返回数据的值是否在合理的范围内，例如：价格是否为正数，数量是否大于零。
    • 数据一致性检查： 验证不同 API 接口返回的数据是否一致，例如：订单信息是否与交易记录一致。
    • 签名验证： 验证返回数据的签名，确保数据未被篡改。
  • 资金安全: 加密货币交易存在风险，程序错误可能导致意外的资金损失。 在进行真实交易之前，强烈建议您先使用 Upbit 提供的模拟账户进行充分的测试，确认代码逻辑的正确性和稳定性。 模拟账户可以模拟真实的市场环境，让您在没有资金风险的情况下进行交易策略的验证和优化。 请务必注意以下事项：
    • 错误处理： 在代码中加入完善的错误处理机制，及时捕获和处理异常情况，避免程序崩溃或执行错误的交易指令。
    • 交易逻辑： 仔细检查交易逻辑，确保交易指令符合您的预期，避免因程序错误导致不必要的损失。
    • 回测： 使用历史数据对交易策略进行回测，评估策略的盈利能力和风险水平。
    • 小额交易： 在使用真实账户进行交易时，建议先进行小额交易，逐步增加交易规模，降低风险。
  • 版本更新： Upbit 官方会不定期更新 API 版本，以修复漏洞、优化性能、增加新功能。 为了确保您的代码能够正常运行，并享受到最新的 API 功能，请密切关注 Upbit 官方 API 文档，及时更新代码以适应 API 的版本更新。 请注意以下事项：
    • 阅读更新日志： 仔细阅读 Upbit 官方 API 更新日志，了解 API 版本更新的具体内容，包括新增功能、废弃功能、接口变更等。
    • 测试兼容性： 在更新代码之前，先在测试环境中进行兼容性测试，确保代码能够与新版本的 API 兼容。
    • 逐步更新： 建议逐步更新代码，避免一次性更新所有代码，降低风险。
  • 市场波动： 加密货币市场波动剧烈，价格可能在短时间内出现大幅波动。 在制定交易策略时，务必充分了解市场波动性，谨慎评估风险，避免盲目跟风。 建议您采取以下措施：
    • 风险控制： 设置止损点和止盈点，控制单笔交易的风险。
    • 仓位管理： 合理控制仓位大小，避免过度杠杆，降低爆仓风险。
    • 分散投资： 将资金分散投资于不同的加密货币，降低单一资产的风险。
    • 长期投资： 考虑长期投资策略，避免频繁交易，减少交易成本。
    • 持续学习： 持续学习加密货币市场的相关知识，提高投资水平。

7. 市场代码规范

Upbit交易所的市场代码遵循一套清晰的命名规范，旨在标准化交易对的表示方式，方便用户和开发者进行识别和操作。例如， KRW-BTC 这个市场代码，其含义是：以韩元（KRW）作为计价货币，交易比特币（BTC）。在Upbit的API文档和交易界面中，所有交易对都以这种形式呈现。

更具体地解释，市场代码的结构通常是 计价货币-交易货币 的形式。计价货币位于短划线左侧，表示购买交易货币所使用的货币；交易货币位于短划线右侧，表示实际被交易的数字资产。常见的计价货币包括KRW（韩元）、BTC（比特币）、USDT（泰达币）等，交易货币则可以是各种各样的数字货币，如ETH（以太坊）、XRP（瑞波币）、ADA（艾达币）等。例如， BTC-ETH 表示用比特币购买以太坊的交易对， USDT-XRP 表示用泰达币购买瑞波币的交易对。

理解Upbit市场代码的含义至关重要，原因如下：

  1. 正确调用API接口： 在使用Upbit API进行交易、查询行情等操作时，必须提供正确的市场代码。如果市场代码错误，API调用将会失败，导致程序无法正常运行。开发者需要仔细查阅API文档，确认所需的市场代码格式。
  2. 准确识别交易对： 市场代码能够明确地表明交易对的构成，避免混淆。例如， KRW-ETH 和 BTC-ETH 代表不同的交易对，交易的资产和计价货币都不同。
  3. 方便数据分析： 通过市场代码，可以方便地对交易数据进行分类和分析。例如，可以筛选出所有以KRW为计价货币的交易对，或者统计某个特定数字货币的交易量。

因此，在使用Upbit交易所进行交易或开发相关应用程序时，务必充分理解和掌握市场代码的含义和规范。