Upbit API使用教程：探索韩国交易所数据

Upbit API 接口使用教程：深入探索韩国领先交易所的数据宝藏

Upbit 作为韩国领先的加密货币交易所，为开发者提供了强大的 API 接口， permettant de accéder à un large éventail de données temps réel et historiques. 本教程旨在深入剖析 Upbit API 的使用方法，帮助开发者轻松获取所需数据，构建创新应用。

准备工作

在使用 Upbit API 之前，为了确保顺利对接和数据安全，你需要完成以下准备步骤：

1. 注册 Upbit 账户

   访问 Upbit 官方网站，按照指示完成账户注册流程。你需要提供有效的身份信息并完成身份验证，这是使用 Upbit API 的前提。

2. 创建 API 密钥

   登录 Upbit 账户后，进入 API 管理页面。在这里，你可以创建用于访问 API 的密钥。务必仔细阅读 Upbit 关于 API 密钥权限的说明，并根据你的应用程序需求选择合适的权限范围，例如交易、查询等。创建完成后，你会获得一个访问密钥（Access Key）和一个安全密钥（Secret Key）。

3. 了解 API 文档

   详细阅读 Upbit 官方提供的 API 文档，熟悉各个接口的功能、参数、请求方式（如 GET、POST）以及返回数据的格式（通常为 JSON）。理解 API 的使用限制，例如请求频率限制，避免因超出限制而被阻止访问。

4. 安装必要的开发环境

   根据你选择的编程语言（如 Python、Java、Node.js 等），安装相应的开发环境和必要的库，例如用于发送 HTTP 请求的库。确保你的开发环境能够正常运行，并且能够连接到互联网。

5. 风险提示与安全措施

   在使用 API 进行交易时，务必充分了解数字货币交易的风险，并采取必要的安全措施。不要将 API 密钥泄露给他人，妥善保管你的密钥。建议使用环境变量或配置文件来存储密钥，避免硬编码在代码中。同时，对 API 返回的数据进行严格的验证，防止潜在的安全漏洞。

注册 Upbit 账户： 如果你还没有 Upbit 账户，请前往 Upbit 官网注册一个账户。

创建 API 密钥： 登录 Upbit 账户后，进入“我的页面” -> “开放 API 管理”页面，申请 API 密钥。你需要设置 API 密钥的访问权限，例如只读权限或者交易权限。请务必妥善保管你的 API 密钥，不要泄露给他人。

了解 API 文档： Upbit 提供了详细的 API 文档，其中包含了所有可用接口的描述、请求参数、响应格式以及错误代码等信息。你可以通过以下链接访问 Upbit API 文档：https://docs.upbit.com/ 仔细阅读 API 文档是掌握 Upbit API 的关键。

身份验证

Upbit API 采用基于 JWT（JSON Web Token）标准的身份验证机制。为了确保安全通信，所有API请求都需要携带有效的JWT。 您必须使用您的 Access Key （API 密钥）和 Secret Key （密钥）生成符合规范的JWT，并通过 HTTP 请求的 Authorization 头部传递此Token。 Authorization 头部的值应以 Bearer 开头，后跟一个空格和生成的JWT。

以下是使用 Python 语言生成 JWT 的示例代码，其中使用了 PyJWT 库。您可能需要先安装该库： pip install PyJWT 。

import jwt
import uuid
import hashlib

access_key = "你的 Access Key"
secret_key = "你的 Secret Key"

payload = {
    'access_key': access_key,
    'nonce': str(uuid.uuid4()),  # 建议使用 UUID 作为 nonce，确保唯一性
}

jwt_token = jwt.encode(payload, secret_key, algorithm='HS256')
authorization_token = 'Bearer {}'.format(jwt_token)

print(authorization_token)

代码解释：

• access_key ：您的 Upbit API 访问密钥，用于标识您的账户。
• secret_key ：您的 Upbit API 密钥，用于签名 JWT。 务必妥善保管此密钥，切勿泄露。
• payload ：一个包含声明的 JSON 对象，例如您的 access_key 和一个随机的 nonce 值。 nonce 是一个一次性使用的随机字符串，用于防止重放攻击。
• jwt.encode(payload, secret_key, algorithm='HS256') ：使用 secret_key 和 HS256 算法对 payload 进行签名，生成 JWT。 HS256 是一种常用的对称加密算法。
• authorization_token ：最终用于 Authorization 头部的值。

请务必将示例代码中的 你的 Access Key 和 你的 Secret Key 替换为您在 Upbit 平台申请到的真实 API 密钥和密钥。 另外，请注意保管好您的 Secret Key，避免泄露，一旦泄露请立即更换。

除了 Python，您还可以使用其他编程语言和相应的 JWT 库来生成 JWT。 关键在于生成符合 JWT 规范的Token，并使用您的 Secret Key 进行正确的签名。

常用 API 接口

以下是一些常用的 Upbit API 接口，以及如何通过这些接口获取市场数据、管理账户和执行交易：

市场数据 API

市场数据 API 允许开发者获取各种加密货币的市场信息，例如实时价格、交易量和历史数据。

• 行情查询 (Ticker) : 用于获取指定加密货币的当前价格、交易量、涨跌幅等实时信息。通过指定市场代码（例如： KRW-BTC 表示韩元计价的比特币），可以快速获取最新市场动态。
• 市场代码查询 : 列出 Upbit 支持的所有市场代码及其详细信息，包括市场名称、警告类型等。这对于动态构建交易界面和管理交易对非常有用。
• K线数据查询 : 获取指定时间段内的K线数据，包括开盘价、最高价、最低价、收盘价和交易量。通过调整时间单位（分钟、日、周、月），可以进行不同时间尺度的技术分析。
• 交易历史查询 : 获取指定市场最近的交易历史记录，包括交易时间、交易价格和交易数量。这有助于了解市场的实时交易活动和价格波动情况。

账户 API

账户 API 用于管理用户的 Upbit 账户，包括查询余额、获取交易记录等。 使用账户API需要进行身份验证，确保账户安全。

• 账户余额查询 : 获取用户在 Upbit 账户中持有的所有加密货币和法币的余额信息。这对于跟踪投资组合和评估盈亏非常重要。
• 交易历史查询 : 获取用户的交易历史记录，包括买入、卖出等操作的详细信息。可以根据市场代码、交易状态等条件进行过滤查询。
• 委托信息查询 : 查询用户当前挂单的委托信息，包括委托价格、委托数量和委托状态。可以用于监控委托执行情况和进行委托管理。

交易 API

交易 API 允许用户在 Upbit 平台上进行买入和卖出操作。 使用交易 API 需要进行身份验证，并且需要仔细考虑交易策略和风险管理。

• 下单 : 提交买入或卖出订单，指定市场代码、交易类型（市价单、限价单）、交易数量和交易价格。需要仔细核对订单参数，避免错误交易。
• 取消订单 : 取消尚未成交的委托订单。可以根据委托 UUID 或市场代码取消指定订单。
• 下单信息查询 : 查询特定订单的详细信息，包括订单状态、成交数量和剩余数量。用于监控订单执行情况和进行交易分析。

注意 : 在使用 Upbit API 之前，请务必阅读官方文档，了解 API 的使用限制、请求频率限制和错误代码。 确保您的应用程序能够正确处理 API 返回的错误信息，并采取适当的措施，以避免账户风险。

1. 行情 API

• 实时行情数据： 提供加密货币交易所的实时交易数据，包括最新成交价、最高价、最低价、成交量等关键指标，支持多种交易对。API 通常采用 WebSocket 或 RESTful 接口，以满足不同应用场景的需求。
• 历史行情数据： 访问历史交易数据，包括日线、周线、月线等时间粒度，用于技术分析和趋势预测。数据通常以时间序列的形式提供，并包含开盘价、收盘价、最高价和最低价（OHLC）等信息。
• 深度数据： 获取交易所的买单和卖单深度信息，展示市场供需关系。深度数据有助于理解市场微观结构，并为高频交易和算法交易提供支持。API 通常提供不同深度的订单簿快照，例如 Top 10 买卖单。
• 聚合行情数据： 从多个交易所聚合行情数据，提供更全面和稳定的市场价格。聚合数据可以减少单一交易所异常波动的影响，并提供更准确的价格参考。
• 指数数据： 提供加密货币指数数据，例如市值加权指数或特定板块指数。指数数据可以反映整体市场或特定领域的发展趋势。
• 交易对信息： 获取交易所支持的交易对列表，以及每个交易对的交易规则和手续费信息。这些信息对于构建交易应用至关重要。
• 资金费率数据： 对于永续合约等衍生品，API 提供资金费率数据，反映多空双方的资金成本。资金费率对于评估持仓成本和风险至关重要。
• 波动率数据： 提供加密货币的波动率数据，例如隐含波动率和历史波动率。波动率是衡量市场风险的重要指标。

获取市场代码： /market/all 接口可以获取所有 Upbit 市场代码。例如：KRW-BTC 代表韩国交易所的比特币市场。

import requests

url = "https://api.upbit.com/v1/market/all"

headers = {"Accept": "application/"}

response = requests.get(url, headers=headers)

print(response.())

获取最近成交价： /ticker 接口可以获取指定市场代码的最近成交价。你需要通过 markets 参数指定市场代码。例如：markets=KRW-BTC。

import requests

url = "https://api.upbit.com/v1/ticker?markets=KRW-BTC"

headers = {"Accept": "application/"}

response = requests.get(url, headers=headers)

print(response.())

获取最近成交列表： /trades/ticks 接口可以获取指定市场代码的最近成交列表。你需要通过 market 参数指定市场代码。例如：market=KRW-BTC。 你还可以通过 count 参数指定返回的成交数量。

import requests

url = "https://api.upbit.com/v1/trades/ticks?market=KRW-BTC&count=10"

headers = {"Accept": "application/"}

response = requests.get(url, headers=headers)

print(response.())

获取分时K线： /candles/minutes/{unit} 接口可以获取指定市场代码的分时K线数据。你需要通过 market 参数指定市场代码，并通过 {unit} 指定分钟数。例如：market=KRW-BTC&unit=1 获取一分钟K线。 你还可以通过 count 参数指定返回的K线数量。

import requests

url = "https://api.upbit.com/v1/candles/minutes/1?market=KRW-BTC&count=10"

headers = {"Accept": "application/"}

response = requests.get(url, headers=headers)

print(response.())

2. 账户 API

• 2.1 账户信息检索： 提供接口用于获取用户的账户基本信息，包括但不限于账户ID、账户类型（例如：现货账户、合约账户）、账户创建时间、账户状态（例如：正常、冻结）等。该接口通常需要用户身份验证，确保只有账户所有者或授权方才能访问敏感信息。
• 2.2 账户余额查询： 允许用户查询其账户中各种加密货币或法币的可用余额、冻结余额以及总余额。余额信息对于用户了解资产状况至关重要，并经常被用于交易决策。API通常支持按币种筛选，并可能提供历史余额快照查询功能。
• 2.3 账户交易历史查询： 提供检索用户账户交易历史记录的功能。这包括充值、提现、买入、卖出、手续费扣除等所有交易活动。返回的数据通常包含交易时间戳、交易类型、交易数量、交易价格、交易状态（例如：已完成、待处理、已取消）以及相关交易ID。高级API可能支持分页、排序和过滤，以便用户更有效地查找特定交易。
• 2.4 账户充值地址生成/查询： 允许用户生成或查询其用于接收加密货币充值的地址。每个币种通常会对应一个或多个充值地址。API需要确保生成的地址是唯一的，并与用户的账户关联。部分平台可能支持为每个充值生成新的地址，以提高隐私性。
• 2.5 账户提现请求： 允许用户提交加密货币或法币的提现请求。用户需要指定提现金额、提现地址（对于加密货币）或银行账户信息（对于法币）。API需要进行安全验证，例如双重身份验证，以防止未经授权的提现。提现请求通常需要经过审核，才能最终完成。API也会返回提现请求的状态，例如：待审核、已批准、已拒绝、已完成。
• 2.6 账户安全设置： 提供管理账户安全设置的功能，例如修改密码、启用或禁用双重身份验证（2FA）、设置API密钥、管理授权设备等。这些设置对于保护账户免受未经授权的访问至关重要。
• 2.7 子账户管理 (可选): 某些平台支持创建子账户，允许用户将其资金和交易活动进行隔离管理。API可以提供创建、查询、更新和删除子账户的功能，以及在主账户和子账户之间转移资金的功能。

查询账户信息： /accounts 接口可以查询你的 Upbit 账户信息，包括账户余额、可用余额等。 你需要在请求头中携带 JWT token 进行身份验证。

import requests import jwt import uuid

accesskey = "你的 Access Key" secretkey = "你的 Secret Key"

payload = { 'accesskey': accesskey, 'nonce': str(uuid.uuid4()), }

jwttoken = jwt.encode(payload, secretkey, algorithm='HS256') authorizationtoken = 'Bearer {}'.format(jwttoken)

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

headers = {"Accept": "application/", "Authorization": authorization_token}

response = requests.get(url, headers=headers)

print(response.())

3. 交易 API

• 概述 ：交易 API 允许用户程序化地执行交易操作，包括下单、撤单、查询订单状态等。它是连接交易平台和自动化交易策略的关键接口。
• 功能 ：
  • 下单 ：提交买入或卖出订单，指定交易对、数量、价格和订单类型（市价单、限价单等）。
  • 撤单 ：取消尚未完全成交的订单。
  • 查询订单 ：获取指定订单的详细信息，如状态、成交量、平均成交价格等。
  • 查询账户余额 ：获取账户中各种加密货币的可用余额和冻结余额。
  • 查询历史成交记录 ：获取历史交易记录，包括成交时间、价格、数量等。
• 认证 ：通常需要使用 API 密钥进行身份验证，确保只有授权用户才能访问交易 API。 API 密钥一般包含 API Key 和 Secret Key，Secret Key 用于对请求进行签名，防止篡改。需要妥善保管 API 密钥，避免泄露。
• 请求方式 ：通常使用 RESTful API 或 WebSocket API。RESTful API 基于 HTTP 协议，适用于请求量较小的场景。WebSocket API 提供双向通信，适用于实时性要求较高的场景，例如实时行情推送和订单状态更新。
• 数据格式 ：通常使用 JSON 格式传递数据。
• 错误处理 ：API 会返回错误码和错误信息，开发者需要根据错误码进行相应的处理，例如重试、记录日志或通知用户。
• 频率限制 ：为了防止滥用，API 通常会设置频率限制，例如每分钟最多请求多少次。超出频率限制可能会导致请求被拒绝。开发者需要合理控制请求频率。
• 安全 considerations :
  • 防止重放攻击 ：通过添加时间戳参数和签名机制来防止重放攻击。
  • 使用 HTTPS ：使用 HTTPS 协议进行通信，确保数据传输的安全性。
  • 输入验证 ：对用户输入进行严格的验证，防止注入攻击。

下单： /orders 接口可以进行下单操作，包括市价单和限价单。 你需要在请求体中指定订单类型、市场代码、订单数量、订单价格等参数。 同样，需要在请求头中携带 JWT token 进行身份验证。

import requests import jwt import uuid import

accesskey = "你的 Access Key" secretkey = "你的 Secret Key"

payload = { 'accesskey': accesskey, 'nonce': str(uuid.uuid4()), }

jwttoken = jwt.encode(payload, secretkey, algorithm='HS256') authorizationtoken = 'Bearer {}'.format(jwttoken)

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

headers = {"Content-Type": "application/", "Authorization": authorization_token}

data = { "market": "KRW-BTC", "side": "bid", # 买入 "ask" 卖出 "volume": "0.0001", "price": "1000000", # 限价单价格 "ord_type": "limit" # "limit" 限价单 "price" 市价买入 "market" 市价卖出 }

response = requests.post(url, headers=headers, data=.dumps(data))

print(response.())

查询订单： /order 接口可以查询指定订单的信息。 你需要通过 uuid 参数指定订单的 UUID。 同样，需要在请求头中携带 JWT token 进行身份验证。

import requests import jwt import uuid

accesskey = "你的 Access Key" secretkey = "你的 Secret Key"

payload = { 'accesskey': accesskey, 'nonce': str(uuid.uuid4()), }

jwttoken = jwt.encode(payload, secretkey, algorithm='HS256') authorizationtoken = 'Bearer {}'.format(jwttoken)

url = "https://api.upbit.com/v1/order?uuid=你的订单UUID" #替换为实际订单UUID

headers = {"Accept": "application/", "Authorization": authorization_token}

response = requests.get(url, headers=headers)

print(response.())

错误处理

Upbit API 通过标准 HTTP 状态码和详细的 JSON 格式错误响应来报告请求处理结果。开发者应充分利用这些信息，准确判断API调用是否成功，并据此制定相应的错误处理策略。以下是一些常见的HTTP状态码及其对应含义，以及在处理Upbit API时应注意的细节：

• 400 Bad Request : 此状态码表明客户端发送的请求包含无效或错误的参数。可能的原因包括：参数缺失、参数格式不正确、参数值超出有效范围等。开发者应仔细检查请求参数，确保其符合API文档的规定。常见错误场景包括：订单数量为负数、价格精度超出限制、交易市场代码错误等。详细的错误信息通常会在JSON响应体中提供，例如，具体哪个参数出错以及出错的原因。
• 401 Unauthorized : 此状态码指示客户端未通过身份验证或身份验证失败。在使用Upbit API时，通常是由于API密钥（Access Key）或安全密钥（Secret Key）配置错误，或者密钥未正确签名请求。请确保API密钥已正确配置，并且请求头中包含正确的`Authorization`字段，其中包含了使用安全密钥对请求进行HMAC-SHA512签名后的结果。请检查API密钥是否已过期或被禁用。
• 429 Too Many Requests : 此状态码表示客户端在短时间内发送了过多的请求，触发了Upbit的频率限制（Rate Limiting）机制。Upbit为了保护服务器的稳定性和可用性，对API的调用频率进行了限制。开发者应仔细阅读Upbit API文档，了解具体的频率限制规则，并采取相应的措施，例如：使用指数退避算法（Exponential Backoff）进行重试、缓存数据以减少API调用次数、或者使用WebSocket API进行实时数据订阅，以避免频繁轮询。 响应头中通常会包含 `Retry-After` 字段，指示客户端应该在多少秒后重试。

速率限制

Upbit API 为了保障系统稳定性和公平性，实施了严格的速率限制策略。您必须仔细控制对 Upbit API 的请求频率，以避免超出限制并触发错误。 违反速率限制可能会导致您的应用程序暂时无法访问 API。

Upbit API 的具体速率限制规则详细记录在官方 API 文档中，请务必查阅该文档以了解不同 API 端点的限制情况。速率限制可能基于多种因素，包括但不限于：每分钟请求次数、每秒请求次数、每个 IP 地址的请求次数以及每个 API 密钥的请求次数。不同 API 端点可能具有不同的速率限制，务必针对您使用的每个端点进行评估。

当您的应用程序触发速率限制时，Upbit API 将返回 HTTP 状态码 429 Too Many Requests 错误。此错误表明您已超过允许的请求频率。在收到此错误后，您应该采取以下措施：

• 停止发送新的 API 请求： 立即停止发送新的 API 请求，以避免进一步违反速率限制。
• 等待一段时间： 在一段时间后重试您的请求。 429 Too Many Requests 响应通常包含 Retry-After 头部，该头部指示您应该等待的秒数，然后再重试。请务必遵守 Retry-After 头部的值。
• 实施指数退避策略： 为了更有效地处理速率限制，您可以实施指数退避策略。这意味着在每次重试失败后，您会逐渐增加等待的时间。例如，您可以先等待 1 秒，如果重试仍然失败，则等待 2 秒，然后等待 4 秒，依此类推。
• 检查您的代码： 仔细检查您的代码，确保您没有意外地发送过多的 API 请求。查看是否有循环或重复执行的代码段导致请求频率过高。
• 优化您的 API 使用： 考虑优化您的 API 使用方式，以减少所需的请求次数。例如，您可以尝试批量请求数据，而不是一次请求一条数据。

请注意，持续违反速率限制可能会导致您的 API 密钥被暂时或永久禁用。因此，务必认真对待速率限制，并采取必要的措施来避免触发错误。

其他注意事项

• 安全至上： 务必采取最高级别的安全措施来保管你的 Upbit API 密钥和私钥。切勿以任何方式（包括但不限于公共代码仓库、论坛、社交媒体等）泄露给任何第三方。密钥泄露可能导致资产损失。
• 精读文档： 在使用 Upbit API 之前，请务必完整、仔细地阅读官方 API 文档。文档中详细描述了所有可用接口的功能、请求参数的类型和格式、响应数据的结构以及各种可能的错误代码及其含义。理解文档是成功使用 API 的前提。
• 速率限制管理： Upbit API 对每个 IP 地址或用户在单位时间内可以发送的请求数量有限制，称为速率限制。请务必了解并遵守这些限制，合理设计你的程序逻辑，避免频繁发送请求而触发速率限制，导致 API 调用失败。可以采用如延迟、队列等机制来平滑请求速率。
• 安全编程实践： 编写代码时，采用最佳的安全编程实践，例如：
  • 不要在代码中硬编码 API 密钥，而是从环境变量或配置文件中读取。
  • 使用安全的存储方式（例如加密存储）来保存 API 密钥。
  • 对所有 API 请求和响应数据进行验证，防止恶意注入。
  • 定期轮换 API 密钥。
• 充分的测试： 在使用 API 进行任何真实的交易操作之前，务必在一个模拟环境（如 Upbit 提供的沙箱环境）中进行充分的测试。测试应涵盖所有可能的场景，包括正常情况和异常情况，以确保你的程序能够正确处理各种情况，并防止因程序错误而导致的资金损失。
• 风险控制： 了解并设置合理的风险控制策略。使用API进行自动化交易时，务必设置止损、止盈等机制，避免市场剧烈波动带来的损失。
• API版本更新： 定期关注Upbit API的版本更新和变更通知。及时更新你的代码，以适应新的API版本，并利用新的功能。
• 错误处理： 完善的错误处理机制至关重要。你的程序应该能够捕获并处理各种API调用可能返回的错误代码，并采取相应的措施，例如重试、报警等。