Upbit API 获取

1. 概述

Upbit 作为韩国加密货币交易市场的领头羊，以其卓越的流动性、广泛的交易对选择以及用户友好的界面而闻名。除了提供便捷的网页和移动应用程序交易体验外，Upbit 还提供了强大的应用程序编程接口 (API)，这为经验丰富的交易者、机构投资者以及致力于量化交易策略开发的开发者打开了方便之门。通过 Upbit API，用户可以自动化交易流程、访问实时市场数据、执行复杂的交易策略，并集成 Upbit 的功能到自定义应用程序中。本文旨在提供一份详尽的指南，指导用户如何安全地获取 Upbit API 访问权限，并深入探讨关键 API 端点的使用方法，从而使开发者能够充分利用 Upbit API 的强大功能进行程序化交易和数据分析。

2. 申请 API 密钥

要开始使用 Upbit API，您需要一个有效的 Upbit 账户并完成实名认证流程。实名认证是 Upbit 平台安全措施的重要组成部分，旨在确保账户的合法使用。完成身份验证后，您可以按照以下详细步骤申请专属的 API 密钥：

1. 登录 Upbit 账户: 访问 Upbit 官方网站（ https://upbit.com ）并使用您的用户名和密码安全地登录您的账户。 确保您在安全的网络环境下操作，以防止您的凭据泄露。
2. 进入 API 管理页面: 成功登录后，在用户中心或者账户设置区域寻找 "Open API" 或 "API 密钥管理" 等类似命名的入口链接。 这些链接通常位于账户设置的安全性或开发人员选项中。仔细查看用户界面，必要时可以查阅Upbit官方帮助文档。
3. 创建 API 密钥: 点击 "创建 API 密钥" 按钮，系统将引导您填写与 API 密钥用途相关的描述信息。 详细描述 API 密钥的用途，例如 "自动化交易机器人" 或 "实时数据分析工具"。 清晰的描述有助于您在以后更好地管理和识别不同的 API 密钥。
4. 设置 API 权限: Upbit 提供了精细化的 API 权限管理机制，包括交易权限（下单、取消订单）、账户信息查询权限（余额查询、交易历史）、市场行情数据获取权限（实时价格、K线数据）以及委托查询等。 务必根据您的应用程序的实际需求，精确选择所需的权限。 强烈建议您遵循最小权限原则，仅授予 API 执行其功能所需的最低权限。 例如，如果您的应用程序仅需获取市场行情数据以进行分析，则绝对不要授予不必要的交易权限，以最大限度地降低潜在的安全风险。这样做可以有效防止API密钥泄露后可能造成的损失。
5. 生成 API 密钥: 仔细核对您填写的所有信息，包括 API 密钥的描述和权限设置，确保准确无误。 然后，点击 "生成 API 密钥" 按钮。 Upbit 系统将为您生成一对唯一的密钥： Access Key （访问密钥）和 Secret Key （私密密钥）。 请务必妥善保管您的 Secret Key ，切勿将其泄露给任何人，更不要将其存储在不安全的地方，例如公共代码仓库或未经加密的配置文件中。 Access Key 用于标识您的 API 密钥，而 Secret Key 用于对您的 API 请求进行签名，以验证请求的合法性。 Secret Key 的泄露可能导致您的账户被盗用，造成资金损失。建议定期更换API密钥，并启用Upbit提供的两步验证等安全措施。

重要提示:

• Access Key 类似于用户名，是您访问API服务的身份标识，用于唯一标识您的 API 账户。它允许系统识别并追踪您的API请求来源。
• Secret Key 类似于密码，但比传统密码更为敏感。它是用于验证您的 API 请求的密钥，确保请求的真实性和完整性，防止未经授权的访问。
• 请务必妥善保管您的 Secret Key ，切勿以任何方式泄露给任何第三方。 一旦 Secret Key 泄露，恶意行为者可以完全模拟您的身份，使用您的 API 权限执行任意操作，可能导致严重的财产损失、数据泄露或其他安全风险。请像对待您的银行账户密码一样，高度重视 Secret Key 的安全性。
• 强烈建议将 Secret Key 存储在极其安全的地方，例如经过高强度加密的配置文件、专门的密钥管理系统(KMS)或者硬件钱包等物理安全设备中。 定期轮换 Secret Key 也是一种重要的安全措施，可以降低密钥泄露带来的潜在风险。同时，启用多因素身份验证(MFA)可以进一步增强您的账户安全性。

3. API 接口介绍

Upbit API 提供了一套全面的 RESTful API 接口，旨在赋能开发者高效地访问市场数据、进行账户管理以及执行交易活动。这些接口遵循 REST 架构原则，易于使用且与多种编程语言兼容。以下列出了一些常用的 API 接口，并对它们的功能进行了详细说明：

3.1 获取市场行情

• GET /v1/market/all: 获取所有交易对的信息。
  • 该接口返回所有 Upbit 支持的交易对的详细信息，包括市场代码（Market Code，例如 "KRW-BTC"），交易对名称（Market Name，例如 "Bitcoin/KRW"），警告类型（例如 "NONE"），以及该交易对是否受支持等。Market Code 是交易 API 中交易对的唯一标识符。
  • 通过该接口可以了解 Upbit 平台支持的所有加密货币交易对及其交易属性。例如，可以根据报价货币类型（Quoting Currency）进行筛选，只获取以韩元（KRW）为报价货币的交易对，或者进一步筛选只获取 BTC 交易对。该接口返回的数据结构包含多个字段，可以用于构建交易对列表或进行更深入的市场分析。
• GET /v1/ticker: 获取指定交易对的当前价格。
  • 需要提供交易对的市场代码作为参数，例如 KRW-BTC 。该代码是 Upbit 交易所的唯一标识符，用于指定具体的交易市场。
  • 该接口返回指定交易对的详细实时行情数据，包括但不限于：最新成交价（Trade Price）、最高价（High Price，当日最高价）、最低价（Low Price，当日最低价）、成交量（Trade Volume，当日累计成交量）、24 小时累计成交额（24H Accumulated Trade Value）、上一个交易日的收盘价（Prev Closing Price）等信息。通过该接口，可以实时掌握交易对的市场动态。
• GET /v1/trades/ticks: 获取指定交易对的成交记录。
  • 需要提供交易对的市场代码作为参数，例如 KRW-BTC 。
  • 可以指定查询的时间范围和成交记录数量。时间范围可以通过设置 `to` 参数（结束时间）和 `count` 参数（返回记录数量）来实现。可以指定返回的排序方式，按照时间升序或者降序排列。
  • 该接口返回指定交易对的成交历史记录，包括成交时间（Trade Time）、成交价格（Trade Price）、成交量（Trade Volume）、买卖类型（Bid/Ask，表示是买单成交还是卖单成交）等信息。这些信息对于分析市场趋势、进行交易策略回测至关重要。
• GET /v1/candles/: 获取K线数据
  • 可以获取分钟线（Minute Candles，例如 1 分钟线、5 分钟线、15 分钟线等）、日线（Day Candles）、周线（Week Candles）、月线（Month Candles）等不同时间粒度的数据。
  • 需要指定交易对的市场代码和K线类型作为参数。K线类型包括 `minutes/{unit}` (分钟线，unit 可以是 1, 3, 5, 15, 30, 60, 240), `days` (日线), `weeks` (周线), `months` (月线)。
  • 该接口返回指定时间范围内的 K 线数据，包括开盘价（Opening Price）、收盘价（Closing Price）、最高价（High Price）、最低价（Low Price）、成交量（Trade Volume）、以及 K 线生成的时间戳（Timestamp）等信息。K 线数据是技术分析的基础，可以用于识别市场趋势、支撑位、阻力位等关键信息。

3.2 账户管理

• GET /v1/accounts: 获取账户信息。
  • 该接口用于查询您在 Upbit 交易所的账户资产信息，详细展示您所持有的各种加密货币的余额。包括可用余额 (available balance) 和锁定余额 (locked balance)。可用余额是指您可以立即用于交易的资产数量，而锁定余额通常是指您已挂单但尚未成交的订单所占用的资产数量。通过此接口，您可以全面了解您的资金状况，从而做出更明智的交易决策。
  • 此接口的安全至关重要，因此必须使用您的 Access Key 和 Secret Key 进行身份验证。请务必妥善保管您的 API 密钥，切勿泄露给他人，以防止账户资产遭受风险。Access Key 用于标识您的身份，Secret Key 用于生成数字签名，验证请求的合法性。
• GET /v1/orders/chance: 获取指定交易对的交易机会。
  • 为获取特定交易对（如 KRW-BTC ，即韩元与比特币的交易对）的交易机会，您需要提供该交易对的市场代码作为参数。市场代码是 Upbit 交易所用来唯一标识每个交易对的字符串。
  • 此接口返回您账户在该特定交易对上的交易相关信息，包括可以用于买入的最大数量以及可以用于卖出的最大数量。还可能包含该交易对的手续费率、最小交易单位等信息。通过分析这些数据，您可以更好地评估交易风险，把握市场机会。例如，如果可用买入数量较低，可能意味着市场供应紧张，价格可能上涨。

3.3 交易

• POST /v1/orders: 下单。创建新的交易订单，允许用户买入或卖出加密货币。
  • 可以创建多种订单类型，包括：
    • 市价单 (Market Order): 立即以当前市场最佳可用价格执行的订单。
    • 限价单 (Limit Order): 只有当市场价格达到或超过指定价格时才会执行的订单。用户可以设置买入或卖出的价格上限/下限。
    • 止损单 (Stop Order): 当市场价格达到指定的止损价格时，订单变为市价单并执行。常用于限制潜在损失。
    • 止损限价单 (Stop-Limit Order): 当市场价格达到指定的止损价格时，订单变为限价单，并以设定的限价或更好的价格执行。
  • 需要提供以下关键信息：
    • 交易对 (Market Code): 指定要交易的加密货币对，例如 BTC/USD 或 ETH/BTC。
    • 订单类型 (Order Type): 指明订单是市价单、限价单、止损单还是其他类型的订单。
    • 交易方向 (Side): 指定是买入 (Buy) 还是卖出 (Sell)。
    • 数量 (Quantity): 指定要交易的加密货币数量。
    • 价格 (Price): 对于限价单和止损限价单，需要指定订单的价格。
    • 高级参数 (Advanced Parameters): 部分平台支持高级参数，如有效期 (Time-in-Force, TIF)，指定订单在未成交情况下的有效时间。常见的 TIF 类型包括：GTC (Good-Til-Canceled，直到取消)、IOC (Immediate-Or-Cancel，立即执行或取消) 和 FOK (Fill-Or-Kill，全部执行或取消)。
  • 成功提交订单后，API 会返回一个唯一的订单 UUID (Universally Unique Identifier)。此 UUID 用于后续跟踪订单状态、修改订单或取消订单。
• GET /v1/order: 查询订单状态。检索特定订单的当前状态信息。
  • 必须提供要查询的订单的 UUID 作为参数。
  • API 返回的订单状态可能包括：
    • 待成交 (Pending): 订单已提交但尚未完全或部分执行。
    • 部分成交 (Partially Filled): 订单已部分执行，但仍有部分数量未成交。
    • 完全成交 (Filled): 订单已完全执行。
    • 已取消 (Canceled): 订单已被用户或系统取消。
    • 已过期 (Expired): 订单已超过有效期且未成交。
    • 已拒绝 (Rejected): 订单由于某种原因被交易所拒绝，例如账户余额不足或订单参数无效。
  • 除了订单状态，API 通常还会返回其他相关信息，例如已成交数量、平均成交价格、手续费等。
• DELETE /v1/order: 取消订单。撤销尚未完全执行的订单。
  • 需要提供要取消的订单的 UUID 作为参数。
  • 只有状态为“待成交”或“部分成交”的订单才能被取消。已经“完全成交”、“已取消”、“已过期”或“已拒绝”的订单无法取消。
  • 取消订单请求成功后，API 通常会返回一个确认消息，并更新订单状态为“已取消”。
  • 注意：部分交易所可能对取消订单收取一定的手续费。

4. API 使用示例 (Python)

以下是一个使用 Python 编程语言访问 Upbit API 获取 BTC/KRW 交易对最新交易价格的示例，展示了身份验证和数据请求的关键步骤。这个例子使用了标准的 Python 库，如 jwt （JSON Web Token）、 uuid （通用唯一识别码）、 hashlib （安全哈希与消息摘要）和 requests （HTTP 客户端）。

import jwt import uuid import hashlib from urllib.parse import urlencode

import requests

access_key = "YOUR_ACCESS_KEY" secret_key = "YOUR_SECRET_KEY"

请务必将 YOUR_ACCESS_KEY 和 YOUR_SECRET_KEY 替换为您在 Upbit 交易所申请的实际 API 密钥。这两个密钥是访问 Upbit API 的凭证，务必妥善保管，避免泄露。

server_url = "https://api.upbit.com"

query = { 'markets': 'KRW-BTC', } query_string = urlencode(query)

这里定义了 API 请求的查询参数，指定要获取 KRW-BTC 交易对的信息。 urlencode 函数用于将 Python 字典转换为 URL 查询字符串，例如 markets=KRW-BTC 。通过修改 markets 字段，可以查询其他交易对的数据。

m = hashlib.sha512() m.update(query_string.encode('utf-8')) query_hash = m.hexdigest()

这段代码使用 SHA512 算法对查询字符串进行哈希处理，生成 query_hash 。这是 Upbit API 安全验证机制的一部分，用于确保请求的完整性，防止篡改。创建一个 SHA512 哈希对象；然后，使用 UTF-8 编码对查询字符串进行编码，并将其更新到哈希对象中；调用 hexdigest() 方法获取哈希值的十六进制表示。

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

构造 JWT（JSON Web Token）的 payload，包含以下字段： access_key （API 访问密钥）、 nonce （一个随机的 UUID，用于防止重放攻击）、 query_hash （查询字符串的哈希值）和 query_hash_alg （哈希算法，这里是 SHA512）。 nonce 的作用是确保每次请求的唯一性，即使请求内容相同，由于 nonce 不同，签名也会不同，从而防止攻击者重放之前的请求。

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

使用 jwt.encode 函数对 payload 进行签名，生成 JWT。签名算法使用 HS256（HMAC SHA256），密钥是您的 secret_key 。然后，将 JWT 封装到 Authorization header 中，格式为 Bearer {jwt_token} 。 Authorization header 用于向 Upbit API 验证您的身份。

headers = { 'Authorization': authorization }

创建一个包含 Authorization header 的字典，用于发送 HTTP 请求。

res = requests.get(f'{server_url}/v1/ticker?{query_string}', headers=headers)

使用 requests.get 函数向 Upbit API 发送 GET 请求，获取 KRW-BTC 交易对的 ticker 信息。请求 URL 包含 API 端点 /v1/ticker 和查询字符串。 headers 参数用于传递身份验证信息。

print(res.())

打印 API 响应的 JSON 内容。Upbit API 会返回包含最新交易价格和其他相关信息的 JSON 数据。

代码说明:

1. 导入必要的库:

   本示例代码需要引入以下 Python 库，它们分别承担着不同的重要职责。

   • jwt : 用于生成 JSON Web Token (JWT)。JWT 是一种开放标准 (RFC 7519)，它定义了一种紧凑且自包含的方式，用于在各方之间安全地传输信息，作为 JSON 对象。 在本例中，用于安全地传递身份验证信息到 Upbit API。
   • uuid : 用于生成通用唯一标识符 (UUID)。 UUID 通常用于生成唯一的 ID，在分布式系统中尤其有用。这里可能用于请求的唯一标识，增强安全性。
   • hashlib : 提供各种哈希算法，如 SHA256，用于数据加密和完整性校验。 Upbit API 可能使用哈希算法来确保请求的安全性。
   • urllib.parse : 用于解析和构建 URL。 用于构造 API 请求的 URL，包括查询参数。
   • requests : 用于发送 HTTP 请求。简化了向 Upbit API 发送 GET 或 POST 请求的过程。
2. 设置 API 密钥:

   在使用 Upbit API 之前，需要从 Upbit 平台获取 API 密钥，包括 YOUR_ACCESS_KEY (访问密钥) 和 YOUR_SECRET_KEY (安全密钥)。

   重要提示： 请务必妥善保管您的 API 密钥，切勿泄露给他人。 建议将 API 密钥存储在环境变量中，而不是直接硬编码在代码中，以提高安全性。

3. 设置 API 请求参数:

   通过设置 markets 参数，可以指定需要查询的交易对。 例如， markets=“KRW-BTC” 表示查询韩元 (KRW) 和比特币 (BTC) 之间的交易对信息。 您可以根据需要设置多个交易对，以逗号分隔。

4. 生成 JWT 令牌:

   Upbit API 使用 JWT (JSON Web Token) 进行身份验证，这是一种比传统 API 密钥验证更为安全的方式。 代码使用 Access Key 和 Secret Key 生成 JWT 令牌。 JWT 令牌包含了身份验证信息，API 服务器会验证该令牌的有效性，以确认请求的来源是否合法。

   JWT 令牌的生成过程通常包括以下步骤：

   1. 创建包含声明 (claims) 的 JSON 对象，例如 API 密钥、过期时间等。
   2. 使用 Secret Key 和指定的哈希算法 (如 SHA256) 对 JSON 对象进行签名。
   3. 将签名后的 JSON 对象编码为 JWT 字符串。
5. 设置请求头:

   将生成的 JWT 令牌添加到 HTTP 请求的 Authorization 请求头中。 Authorization 请求头用于传递身份验证凭据。 在本例中，将 JWT 令牌添加到 Authorization 请求头中，并以 "Bearer" 开头，表示使用 Bearer 令牌验证方式。 例如： Authorization: Bearer {JWT 令牌} 。

6. 发送 API 请求:

   使用 requests.get() 方法发送 GET 请求到 Upbit API 的指定 URL。 您需要构造包含 API 接口地址和请求参数的完整 URL。 例如： https://api.upbit.com/v1/ticker?markets=KRW-BTC 。

   requests.get() 方法会向指定的 URL 发送 GET 请求，并返回一个 Response 对象，包含了 API 服务器的响应信息，例如状态码、响应头和响应内容。

7. 处理 API 响应:

   使用 res.() 方法将 API 响应 ( Response 对象) 解析为 JSON 格式。 API 服务器通常会以 JSON 格式返回数据。 res.() 方法会将 JSON 字符串转换为 Python 字典或列表，方便后续的数据处理。

   您还可以通过 res.status_code 属性获取 API 请求的状态码，以判断请求是否成功。 例如，状态码 200 表示请求成功，状态码 400 表示请求参数错误，状态码 401 表示未授权等。

8. 打印 API 响应:

   将解析后的 API 响应 (JSON 数据) 打印到控制台。 这有助于开发者查看 API 返回的数据，进行调试和验证。

   在实际应用中，您可以将 API 响应数据存储到数据库、进行数据分析、展示到用户界面等。

这个示例展示了如何使用 Python 访问 Upbit API 并获取 BTC/KRW 交易对的最新价格。 您可以根据您的需求修改代码，访问其他 API 接口，例如查询账户余额、下单交易、获取历史数据等。

5. 错误处理

在使用 Upbit API 进行交易或获取数据时，开发者可能会遇到各种错误。妥善处理这些错误对于构建稳定可靠的应用程序至关重要。 以下列举了一些常见的错误类型及相应的应对策略：

• 400 Bad Request: 请求参数错误

  此错误通常表示您的请求格式不正确或包含无效的参数。例如，可能缺少必需的参数，或者参数值不符合 Upbit API 的要求。 检查您的请求参数，确保其符合 Upbit API 文档的规范。 仔细核对参数类型、取值范围以及格式要求。

• 401 Unauthorized: 身份验证失败

  这表明您的身份验证信息（通常是 Access Key 和 Secret Key）不正确或已过期。 请务必仔细检查您的 Access Key 和 Secret Key 是否正确无误，并且拥有足够的权限执行您尝试的操作。 您可以访问 Upbit 官方网站或联系 Upbit 客服来验证或重新生成您的密钥。

• 429 Too Many Requests: 请求频率过高

  Upbit API 为了保障服务器的稳定性和公平性，对每个用户的请求频率都有限制。当您在短时间内发送过多的请求时，就会收到此错误。 请务必阅读 Upbit API 文档，了解具体的频率限制。建议您实施适当的请求节流策略，例如使用队列或延迟函数来控制请求发送的速度。 考虑使用缓存机制来减少对 API 的重复调用。

• 500 Internal Server Error: Upbit 服务器内部错误

  此错误表明 Upbit 服务器自身出现了问题。这通常不是由于您的代码引起的，而是 Upbit 方面的问题。 当遇到此错误时，您可以稍后重试您的请求。 如果问题持续存在，请联系 Upbit 客服寻求帮助。 您也可以关注 Upbit 的官方公告，以了解是否有已知的服务器问题。

在实际开发过程中，对这些潜在的错误进行妥善处理至关重要。 建议使用 try-except 语句来捕获可能发生的异常，并采取相应的措施，例如重试失败的请求（设置最大重试次数和退避策略），记录详细的错误日志以便于调试和排查问题，或者向用户显示友好的错误提示信息。 Upbit 的 API 文档中通常会提供详细的错误代码说明，以及针对特定错误的建议处理方法。 请务必仔细阅读并参考这些文档，以便更好地处理各种 API 错误。

6. 其他注意事项

• API 文档: Upbit 官方 API 文档是您使用 Upbit API 的权威指南。务必仔细研读，了解 API 提供的所有功能、参数、数据格式以及错误代码。理解文档中的细节对于成功调用 API 至关重要。文档通常包含 API 终结点、请求示例、响应示例以及各个参数的详细描述。
• 请求频率限制: 为了保护服务器资源和确保所有用户的服务质量，Upbit API 对请求频率设置了严格的限制。 您需要仔细阅读 API 文档，了解不同 API 终结点的请求频率限制。超过限制可能会导致您的 API 密钥被临时或永久封禁。 建议您实施合理的请求队列管理和错误处理机制，以避免超出限制。使用指数退避算法处理 429 错误（请求过多）是一种常见的做法。
• 数据安全: 保护您的 API 密钥至关重要，因为密钥是访问 Upbit API 的凭证。不要将 API 密钥存储在公开的代码库中，例如 GitHub。 将 API 密钥存储在安全的地方，例如环境变量或专门的密钥管理系统中。 同时，注意保护从 API 获取的用户数据，避免泄露用户隐私信息。 遵守数据保护法规，例如 GDPR 或 CCPA。
• 合规性: 在使用 Upbit API 进行交易时，您必须遵守韩国以及您所在地区的适用法律法规。 这包括了解 KYC/AML（了解你的客户/反洗钱）合规要求，并确保您的交易行为符合这些规定。 如果您不确定您的交易行为是否合法，请咨询法律专业人士。 Upbit 可能会要求您提供额外的身份验证信息以符合合规性要求。

本文档旨在帮助您了解 Upbit API 访问权限的获取流程，并提供一些关键的使用注意事项。 遵循这些指南，您应该能够安全、高效地使用 Upbit API，并开发出满足需求的加密货币应用程序。请务必持续关注 Upbit 官方公告和 API 文档更新，以便及时了解最新的 API 功能、限制和合规性要求。