Upbit API：通往韩国加密货币市场的钥匙

Upbit，作为韩国领先的数字资产交易所，为开发者和交易者提供了强大的应用程序编程接口（API），允许他们以编程方式访问市场数据、管理账户和执行交易。理解和有效利用 Upbit API 是深入韩国加密货币市场，构建自动化交易策略，以及开发创新金融工具的关键。

API 的基本结构

Upbit API 采用 RESTful 架构设计，这是一种广泛应用于 Web API 开发的标准。RESTful API 利用标准的 HTTP 方法，如 GET (用于检索资源), POST (用于创建新资源), PUT (用于更新现有资源), 和 DELETE (用于删除资源)，来执行对资源的各种操作。每个操作都通过发送 HTTP 请求到特定的 URL 端点来触发。

为了确保安全性，所有 Upbit API 请求都需要进行身份验证。身份验证过程通常涉及使用 API 密钥（API Key）和秘密密钥（Secret Key）。API 密钥类似于用户名，用于标识请求的发送者；秘密密钥则类似于密码，用于验证请求的真实性。这些密钥必须妥善保管，避免泄露，以防止未经授权的访问。通过 API 密钥和秘密密钥，Upbit 可以验证每个请求的来源，并确定请求者是否具有执行特定操作的权限。身份验证通常通过在 HTTP 请求头中添加 Authorization 字段来实现，该字段包含使用 API 密钥和秘密密钥生成的签名。

Upbit API 的基本 URL 是 https://api.upbit.com/v1 。这是所有 API 请求的根路径，不同的 API 端点会附加到此基本 URL 上，形成完整的 API 请求地址。例如，要获取所有交易市场的信息，您需要访问的端点可能是 /markets ，完整的 URL 则是 https://api.upbit.com/v1/markets 。API 文档会详细列出所有可用的端点及其功能，以及每个端点所需的请求参数和返回的数据格式。

身份验证：安全的访问保障

Upbit API 采用 JWT (JSON Web Token) 进行身份验证，确保只有授权用户才能访问其资源。JWT 是一种开放标准 (RFC 7519)，它定义了一种紧凑且自包含的方式，用于在各方之间安全地传输 JSON 对象作为令牌。在 Upbit API 的上下文中，这意味着你需要使用你的 API 密钥（Access Key）和秘密密钥（Secret Key）生成一个 JWT token，并将其包含在每个 API 请求的 Authorization 头中。服务器接收到请求后，会验证 JWT 的有效性，从而确认用户的身份。

生成 JWT token 的过程通常涉及以下步骤：

1. 获取 API 密钥和秘密密钥： 你需要在 Upbit 交易所的账户设置中获取你的 API 密钥（Access Key）和秘密密钥（Secret Key）。这些密钥是访问 Upbit API 的凭证。
2. 选择 JWT 库： 选择一个适合你的编程语言的 JWT 库。常见的 JWT 库包括 Java 的 JJWT，Python 的 PyJWT，以及 Node.js 的 webtoken。
3. 构建 JWT Header： 创建一个包含算法 ( alg ) 和类型 ( typ ) 的 JSON 对象。Upbit API 通常使用 HMAC-SHA512 算法，因此 alg 字段应设置为 HS512 ， typ 字段应设置为 JWT 。
4. 构建 JWT Payload： 创建一个包含声明（claims）的 JSON 对象。这些声明可以包括但不限于：
   • access_key ：你的 API 密钥（Access Key）。
   • nonce ：一个随机字符串，用于防止重放攻击。每次生成 JWT 时都应该生成一个新的随机字符串。可以使用时间戳或者 UUID。
   • iat (Issued At)：JWT 的签发时间，表示 JWT 何时被创建。
5. 签名 JWT： 根据 Upbit 提供的算法（通常是 HMAC-SHA512）和规范，使用你的秘密密钥（Secret Key）对 JWT 的 Header 和 Payload 进行签名。签名过程会生成一个唯一的签名，该签名与 Header 和 Payload 组合在一起形成完整的 JWT。
6. 构造 Authorization Header： 将生成的 JWT token 放在 HTTP 请求的 Authorization 头中，格式为 Authorization: Bearer <JWT Token> 。

需要特别注意的是，保护你的 API 密钥和秘密密钥至关重要。切勿将它们公开分享或存储在不安全的地方，例如版本控制系统、公共论坛或客户端代码中。建议使用环境变量、密钥管理服务或者加密存储的方式来保护你的密钥。 泄露的密钥可能导致账户被盗用、未经授权的交易和资金损失。定期轮换你的 API 密钥和秘密密钥也是一种良好的安全实践。务必仔细阅读 Upbit 的 API 文档，了解所有关于身份验证和授权的详细信息。

主要 API 端点及功能

Upbit API 提供了全面的接口，允许开发者访问和集成 Upbit 交易所的各项功能。这些功能涵盖了广泛的领域，包括但不限于实时市场数据检索、个人账户管理、自动化交易执行以及订单查询等。以下是一些关键 API 端点及其核心功能的详细概述：

• 市场数据 API：
  • /ticker : 提供所有或指定交易对的当前市场行情快照，包括最新成交价、最高价、最低价、成交量等关键指标，适用于实时监控市场动态。
  • /trades/ticks : 获取指定交易对的实时成交记录，可用于分析市场微观结构和成交活跃度。
  • /candles : 提供不同时间粒度的K线数据（例如分钟线、小时线、日线），用于技术分析和趋势预测。支持自定义K线类型和时间范围。
  • /orderbook : 显示指定交易对的实时订单簿信息，包括买单和卖单的价格及数量，有助于评估市场深度和流动性。
• 账户管理 API：
  • /accounts : 查询用户账户的资产信息，包括持有的币种、可用余额、冻结余额等。
  • /api_keys : 管理用户的API密钥，包括创建、删除和查询API密钥。API密钥是访问Upbit API的凭证，务必妥善保管。
  • /withdraws : 用于提交提币请求，将数字资产从Upbit交易所转移到外部钱包地址。需要验证用户身份并符合提币规则。
  • /deposits : 查询用户的充币记录，了解数字资产何时以及如何存入Upbit交易所。
• 交易 API：
  • /orders : 用于下单（买入或卖出），支持市价单和限价单等多种订单类型。可以指定交易对、订单数量和价格。
  • /order : 查询指定订单的详细信息，包括订单状态、成交数量、成交均价等。
  • /orders/chance : 获取指定交易对的下单可能性，包括最小下单数量、最大下单数量等限制条件。
  • /orders/cancel : 用于取消未成交的订单。

1. 市场数据 API

• /markets : 获取所有交易市场的详细列表，包含市场代码（例如：`KRW-BTC`）、市场名称以及适用的交易警告类型。此接口提供 Upbit 交易所支持的所有交易对信息，对于了解 Upbit 提供的交易选择至关重要。警告类型可能包括交易对的风险提示或特殊状态。
• /candles/{market} : 获取指定交易市场的蜡烛图数据。蜡烛图类型可选择分钟级别（例如：`minutes/1`, `minutes/5`, `minutes/15`, `minutes/30`, `minutes/60`, `minutes/240`），以及日线、周线和月线级别（`days`, `weeks`, `months`）。用户可以自定义时间间隔和数据数量，从而满足不同时间跨度的技术分析需求。蜡烛图数据是技术分析的基础工具，通过展示开盘价、收盘价、最高价和最低价，帮助交易者识别市场趋势、支撑位、阻力位，并预测价格变动方向。例如，你可以获取过去 200 个 5 分钟 K 线图，以便进行短期交易分析。
• /trades/ticks : 获取指定市场的最新成交记录（逐笔成交数据）。成交记录提供关于市场实时交易活动的详细信息，包含成交价格、成交数量、成交时间戳以及买卖方向。通过分析成交记录，交易者可以了解市场深度、价格波动的微观结构，以及大单交易对价格的影响。该接口可以用于高频交易策略和实时风险监控。
• /ticker : 获取指定市场的当前价格信息快照。此接口返回的关键数据包括：最新成交价（`trade_price`）、最高价（`high_price`）、最低价（`low_price`）、累计交易量（`acc_trade_volume`）、24 小时累计交易额（`acc_trade_price_24h`）、最高买价（`bid_price`）、最低卖价（`ask_price`）等。这些实时数据是快速了解市场行情、制定交易决策的重要依据。 通过轮询此接口，可以实时追踪市场动态。

2. 账户 API

• /accounts : 获取用户账户的详细信息。此API端点提供以下关键数据：
  • 账户余额（Balance） : 显示账户中持有的特定加密货币的总量。
  • 可用余额（Available Balance） : 指示可以用于交易或提现的加密货币数量。这通常会低于总余额，因为部分资金可能被用于挂单或其他操作而暂时冻结。
  • 冻结余额（Frozen Balance） : 显示由于挂单或其他平台机制而被暂时冻结的加密货币数量。理解冻结余额对于管理交易策略至关重要。
  准确掌握这些信息对于有效管理您的资金、制定交易决策和监控您的资产至关重要。
• /withdraws/chance : 预估提现的可能性和相关费用。在使用提现功能之前，建议先调用此API，它允许你查询：
  • 提现限额（Withdrawal Limits） : 确定单次提现的最小和最大金额。
  • 提现手续费（Withdrawal Fees） : 了解提现操作所需支付的费用，这会影响你最终收到的金额。手续费可能因加密货币类型和网络拥堵情况而异。
  通过预先检查提现可能性，您可以避免因超出限额或手续费预期之外而导致的问题。
• /withdraws : 提交加密货币提现请求。调用此API时，你需要提供以下信息：
  • 货币类型（Currency） : 明确指定你要提现的加密货币种类，例如BTC、ETH等。
  • 提现数量（Amount） : 输入你要提现的具体数量。请务必仔细核对，确保数量准确无误。
  • 提现地址（Address） : 提供接收加密货币的外部钱包地址。请务必仔细检查地址的正确性，错误的地址可能导致资金永久丢失。
  在提交提现请求后，请注意查收平台的确认信息，并跟踪提现状态。
• /deposits/coin_address : 获取指定加密货币的充币地址。每个加密货币都有一个唯一的充币地址，用于接收来自外部钱包的转账。
  • 货币类型（Currency） : 指定你要获取充币地址的加密货币种类。
  • 地址类型（Address Type） : 部分平台可能支持不同的地址类型（例如，ETH的ERC20地址）。请根据你的钱包兼容性选择正确的地址类型。
  请务必使用平台提供的充币地址，并将外部钱包的提现地址设置为此地址。切勿使用错误的地址进行充币，否则可能导致资金丢失。 每次充值前都应通过API获取最新的充币地址，避免地址过期或变更造成损失。

3. 交易 API

• /orders/chance : 获取指定市场的下单可能性评估。 此端点允许用户在实际下单前，预先评估其交易的可行性。 通过查询账户的可用资金余额和特定市场的交易限制，API能够返回一个下单概率的预估值。 这包括验证是否有足够的资金或代币来完成交易，以及订单是否符合交易所设置的最小交易量、价格步长等规则。 例如，在尝试购买特定数量的代币之前，可以调用此API来确认账户余额足以支付，并且订单数量满足市场要求。
• /orders : 创建新的订单（买入或卖出）。 此端点是执行实际交易的核心。 用户需要提供必要的参数，包括：
  • 市场代码 (market) : 指定交易的市场，例如 "BTC/USDT"。
  • 订单类型 (side) : 指示是买入 (buy) 还是卖出 (sell)。
  • 订单类型 (ord_type) : 定义订单的执行方式，主要包括：
    • 市价单 (market) : 以当前市场最优价格立即执行。
    • 限价单 (limit) : 只有当市场价格达到或超过指定价格时才执行。
  • 价格 (price) : 仅限价单需要，指定订单的期望成交价格。
  • 数量 (volume) : 指定买入或卖出的资产数量。
  成功调用此API会创建一个新的订单，并将其提交到交易所的订单簿中。
• /order : 查询指定订单的详细状态信息。 通过提供订单的唯一ID，此端点可以返回订单的完整信息，包括：
  • 订单状态 (state): 例如 "待处理 (pending)"、"已完成 (done)"、"已取消 (canceled)"。
  • 已成交数量 (executed_volume): 订单已成功交易的数量。
  • 平均成交价格 (avg_price): 订单的平均成交价格。
  • 下单时间 (created_at): 订单创建的时间戳。
  • 更新时间 (updated_at): 订单最后一次更新的时间戳。
  此API对于监控订单执行情况至关重要。
• /orders/cancel : 取消指定的未完成订单。 通过提供要取消的订单的ID，此端点可以取消尚未完全成交的订单。 一旦成功取消，订单将从订单簿中移除，并且账户中预留的资金或代币将被释放。 请注意，只有状态为“待处理”或部分成交的订单才能被取消。

使用 API 的注意事项

• 速率限制 : Upbit API 实施速率限制机制，旨在保障所有用户的服务质量和系统稳定性。速率限制规定了在特定时间段内（例如，每分钟或每秒）允许的API请求数量上限。超出此限制的请求可能会被服务器拒绝，并返回错误代码。开发者应仔细查阅Upbit的官方文档，了解具体的速率限制规则，并在应用程序中实现相应的逻辑，例如使用排队或延迟机制，以避免超出限制。违反速率限制可能导致临时或永久性的API访问权限被禁用。同时，请关注Upbit发布的任何速率限制变更通知。
• 数据格式 : Upbit API 主要以 JSON（JavaScript Object Notation）格式返回数据。JSON是一种轻量级的数据交换格式，易于阅读和解析。开发者需要使用与其编程语言相兼容的JSON解析库，例如Python的``模块、JavaScript的`JSON.parse`函数等，将API返回的JSON字符串转换为程序可以处理的数据结构，如字典或对象。正确解析JSON数据是成功使用API的关键步骤，也是提取所需信息的必要前提。
• 错误处理 : 在使用Upbit API时，API请求并非总是成功。当发生错误时，Upbit API会返回一个包含错误代码和错误消息的JSON响应。错误代码通常是一个数字或字符串，用于标识错误的类型，例如无效的API密钥、权限不足、参数错误等。错误消息则提供了关于错误的更详细的描述。开发者必须在代码中实现完善的错误处理机制，例如使用`try-except`块捕获异常，检查API响应中的错误代码，并根据不同的错误类型采取相应的措施，例如重试请求、记录错误日志、通知用户等。忽略错误处理可能导致程序崩溃或产生不可预测的结果。
• 安全 : 网络安全至关重要，所有与Upbit API的通信必须通过HTTPS（Hypertext Transfer Protocol Secure）协议进行。HTTPS使用SSL/TLS加密技术，可以有效防止数据在传输过程中被窃听或篡改，保障数据的机密性和完整性。永远不要使用不安全的HTTP协议进行API请求。绝对禁止在客户端代码（例如，浏览器端的JavaScript代码）中硬编码API密钥和秘密密钥。客户端代码容易被反编译或泄露，将API密钥暴露在客户端会带来极大的安全风险，可能导致账户被盗用或资金损失。应将API密钥存储在安全的服务器端，并通过服务器端代码来调用Upbit API。使用环境变量或配置文件来管理API密钥也是一种常见的安全实践。

示例：使用 Python 获取 Upbit 市场数据

本示例展示如何使用 Python 编程语言获取韩国数字货币交易所 Upbit 的市场实时数据。该示例代码片段详细说明了如何构建 API 请求、进行身份验证以及解析返回的数据，以便在量化交易、数据分析或其他相关应用中使用。

导入必要的 Python 库，包括 jwt 用于生成 JSON Web Token (JWT) 进行身份验证， uuid 用于生成唯一标识符， hashlib 用于哈希处理（尽管在此示例中未使用，但在某些API交互中可能需要），以及 urllib.parse 中的 urlencode 用于构建 URL 查询字符串，最后使用 requests 库发送 HTTP 请求。

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

import requests

请务必替换以下占位符为您在 Upbit 交易所注册后获得的真实 API 密钥。 access_key 是您的访问密钥，用于标识您的账户； secret_key 是您的安全密钥，用于对请求进行签名，保证请求的安全性。务必妥善保管您的密钥，避免泄露。

access_key = "YOUR_ACCESS_KEY"
secret_key = "YOUR_SECRET_KEY"

get_tickers 函数用于获取指定市场代码的交易行情。 markets 参数是一个包含市场代码的字符串，多个市场代码之间用逗号分隔。函数内部使用 urlencode 方法将市场代码构建为 URL 查询字符串，并将其添加到 API 请求的 URL 中。

def get_tickers(markets):
query = urlencode({"markets": markets})

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

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

headers = {"Authorization": authorization_token}

url = "https://api.upbit.com/v1/ticker?" + query
response = requests.get(url, headers=headers)

return response.()

上述代码片段展示了构建身份验证 payload 的过程。 access_key 用于标识身份， nonce 是一个唯一字符串，防止请求重放攻击。 query 包含了请求的具体参数。 使用您的 secret_key 和 HS256 算法对 payload 进行签名，生成 JWT token。 将 JWT token 添加到请求头中的 Authorization 字段，格式为 "Bearer [JWT token]"。 使用 requests.get 方法发送 GET 请求，并将包含身份验证信息的 headers 传递给服务器。 使用 response.() 方法将服务器返回的 JSON 格式的数据解析为 Python 对象，方便后续处理。 返回的数据包含了指定市场的当前交易信息，例如最新成交价、成交量等。 请注意，您需要安装 requests 和 PyJWT 库才能运行此示例。 可以使用 pip install requests PyJWT 命令进行安装。

获取 BTC-KRW 和 ETH-KRW 的实时价格信息

以下代码示例演示了如何通过 Upbit API 获取比特币韩元 (BTC-KRW) 和以太坊韩元 (ETH-KRW) 交易对的当前价格信息。 该示例使用 get_tickers 函数，并打印返回的结果。

    
tickers = get_tickers("BTC-KRW,ETH-KRW")
print(tickers)
    

要成功运行此代码，请确保已安装 Upbit API 的 Python SDK，并已配置有效的 API 密钥和 Secret 密钥。 你需要将 YOUR_ACCESS_KEY 和 YOUR_SECRET_KEY 替换为你自己的 Upbit API 密钥和 Secret 密钥。 这些密钥用于生成 JSON Web Token (JWT)，该 Token 用于身份验证，并允许你访问 Upbit API 的受保护资源。

此代码段的核心功能是构建一个包含市场代码（例如 "BTC-KRW,ETH-KRW"）的查询字符串，然后使用你的 API 密钥和 Secret 密钥生成一个 JWT token。 该 JWT token 被添加到 HTTP 请求的 Authorization 头部，以证明请求的合法性。 通过发送带有身份验证信息的 GET 请求到 Upbit API 的相应端点，你可以获取包含指定交易对实时价格信息的 JSON 响应。 该 JSON 响应会被打印出来，以便你可以查看返回的市场数据。

这个示例提供了一个使用 Upbit API 获取市场数据的基本框架。 你可以根据你的具体需求进行修改和扩展，例如：指定其他交易对、使用不同的 API 端点（如获取历史数据或订单簿信息）、以及对返回的数据进行进一步处理和分析。 Upbit API 提供了丰富的接口，可以满足各种交易和数据分析的需求。

应用场景

Upbit API 的应用场景极其广泛，涵盖了加密货币交易和数据分析的多个方面。它不仅能提升交易效率，还能为投资者提供更深入的市场洞察。

• 自动化交易 : 通过 API 构建高度定制化的自动化交易机器人，使其能够根据预先设定的交易策略和算法，全天候不间断地监控市场动态并执行买卖操作。这些策略可以基于技术指标、市场情绪或其他自定义规则。自动化交易减少了人为情绪的影响，提高了交易效率和执行速度。
• 数据分析 : 利用 Upbit API 提供的实时和历史市场数据，进行深入的数据挖掘和分析。这包括价格走势分析、交易量分析、订单簿分析等。通过识别市场趋势、价格模式、交易信号和异常波动，为投资者提供数据驱动的交易决策依据，从而优化投资策略并降低风险。
• 投资组合管理 : 使用 API 集成 Upbit 账户数据，实现投资组合的自动化管理和监控。这包括资产配置、盈亏计算、风险评估和绩效报告等功能。API 可以帮助投资者更有效地跟踪投资表现，并根据市场变化动态调整投资组合，以实现最佳回报。
• 金融工具开发 : 基于 Upbit API 开发各种创新的金融工具和应用程序，例如量化交易平台、风险管理系统、数据可视化工具和投资组合模拟器。这些工具可以帮助投资者更好地理解市场、管理风险并优化投资决策。同时，开发者还可以利用 API 提供的功能，开发出满足特定需求的定制化解决方案。

精通 Upbit API 将极大地助力您深入理解并充分利用韩国加密货币市场的潜力，从而能够开发各种具备实际价值的应用程序，并在这个快速发展的领域中获得竞争优势。这不仅限于个人交易者，也包括机构投资者、金融科技公司和研究人员。