攻克Upbit API：新手指南，解锁程序化交易的秘密！

Upbit 交易所 API 使用方法

Upbit 是韩国领先的数字资产交易所，提供丰富的交易对和高效的交易体验。 对于希望通过程序化方式进行交易、获取市场数据或管理账户的用户，Upbit 提供了强大的 API (Application Programming Interface)。 本文将详细介绍 Upbit API 的使用方法，帮助开发者快速上手。

1. 准备工作

在使用 Upbit API 之前，为了确保顺利对接和安全使用，需要进行以下准备工作：

• 注册 Upbit 账户： 如果您尚未拥有 Upbit 账户，请访问 Upbit 官方网站 (upbit.com) 进行注册。请务必使用有效的电子邮件地址，并设置强密码以保护您的账户安全。
• 完成身份验证 (KYC)： 为了符合监管要求和保障用户资产安全，Upbit 要求用户完成 KYC (Know Your Customer) 身份验证才能使用 API 功能。身份验证通常需要提供身份证明文件（如护照或身份证）以及居住地址证明。请按照 Upbit 的指示完成身份验证流程。
• 创建 API 密钥： 成功登录 Upbit 账户后，前往 API 管理页面 (通常位于账户设置或安全设置中)。在此页面，您可以创建 API 密钥。API 密钥由 Access Key 和 Secret Key 组成，它们是您访问 Upbit API 的凭证。请务必妥善保管您的 API 密钥，切勿将其泄露给他人。强烈建议启用 IP 访问限制功能，仅允许特定的 IP 地址访问 API，以增加安全性。 Access Key 用于标识您的身份，Secret Key 用于签名您的 API 请求，确保请求的安全性。启用两步验证 (2FA) 可以进一步保护您的 API 密钥。
• 深入了解 API 文档： 详细阅读 Upbit 官方 API 文档至关重要。Upbit API 文档是您了解 API 功能、使用方法和限制的唯一权威来源。文档中包含了所有可用的 API 端点、请求参数说明、响应格式、错误代码以及速率限制等重要信息。Upbit API 文档通常提供韩语和英语版本。如果您不熟悉韩语，可以使用在线翻译工具辅助理解英文文档。请务必仔细阅读文档，理解每个 API 端点的作用和参数，避免因参数错误或使用不当导致 API 调用失败。
• 选择编程语言和搭建开发环境： Upbit API 可以通过多种编程语言进行访问，包括但不限于 Python、Java、JavaScript、Go 和 PHP。选择您最熟悉且具有相应开发经验的编程语言。选择好编程语言后，需要搭建相应的开发环境，包括安装必要的开发工具包 (SDK) 和库。例如，如果您选择 Python，可以使用 `requests` 库发送 HTTP 请求，使用 `` 库处理 JSON 格式的数据。您还需要配置好 API 密钥，并设置相应的环境变量或配置文件，以便在代码中访问 API 密钥。

2. API 认证

Upbit API 采用 JWT (JSON Web Token) 作为其主要的认证机制。这意味着每个与 Upbit API 的交互都需要通过验证，以确保请求的合法性和安全性。为了成功地与 API 进行通信，您需要在每个 API 请求的 HTTP 头部中包含一个有效的 JWT token。

JWT token 的生成是一个多步骤的过程，它涉及到构建 Payload，对 Payload 进行签名，以及将 Payload 和签名组合成最终的 JWT token。详细步骤如下：

1. 构建 Payload： Payload 是一个 JSON 对象，它包含了有关请求的必要信息，例如您的身份验证信息和请求参数。以下是 Payload 中需要包含的关键字段：
   • access_key : 这是您的 Upbit Access Key，用于标识您的账户。请务必妥善保管您的 Access Key。
   • nonce : 这是一个随机生成的字符串，其主要作用是防止重放攻击。每次发起 API 请求时，都必须生成一个新的 nonce 值，确保每个请求的唯一性。可以使用 UUID (Universally Unique Identifier) 来生成随机字符串。
   • query (可选): 仅用于 GET 请求。当您需要传递查询参数时，可以将这些参数包含在 query 字段中。查询参数应该被 URL 编码。
   • query_hash (可选)：当没有查询参数时，用于GET请求。对空字符串使用SHA512算法进行哈希处理，确保即使没有参数也能提供安全性。
   • body (可选): 仅用于 POST/PUT 请求。如果您的请求需要发送请求体（例如，JSON 数据），则可以将请求体的内容放在 body 字段中。
2. 使用 Secret Key 签名： 在构建 Payload 之后，需要使用您的 Upbit Secret Key 对 Payload 进行签名。签名过程使用一种哈希算法（通常是 SHA512 或 HS256）。Secret Key 用于验证 Payload 的完整性，确保它在传输过程中没有被篡改。请务必妥善保管您的 Secret Key，不要将其泄露给任何第三方。
3. 生成 JWT Token： 将 Payload 和签名组合成一个完整的 JWT token。JWT token 通常由三部分组成：Header、Payload 和 Signature。这三部分用点号（.）分隔。生成的 JWT token 将作为 Authorization 头的值发送到 Upbit API 服务器。

以下 Python 代码示例演示了如何使用 jwt 库生成 JWT token：

为了方便理解，我们提供了一个使用 Python 的示例代码，该代码演示了如何生成符合 Upbit API 要求的 JWT token。请确保您已经安装了必要的 Python 库，例如 jwt 和 uuid 。 您可以使用 pip install pyjwt 命令来安装 jwt 库。

urllib.parse 用于处理 URL 编码， hashlib 用于计算SHA512哈希值。

access_key 和 secret_key 变量需要替换为您自己的 Upbit Access Key 和 Secret Key。

generate_jwt_token 函数接受您的 Access Key、Secret Key 和可选的查询参数作为输入，并返回生成的 JWT token。

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

access_key = "YOUR_ACCESS_KEY"
secret_key = "YOUR_SECRET_KEY"

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

    if query:
        payload['query'] = urlencode(query)
    else:
        query_hash = hashlib.sha512("".encode()).hexdigest()
        payload['query_hash'] = query_hash

    jwt_token = jwt.encode(payload, secret_key, algorithm="HS256")
    return jwt_token

Example Usage:

为了安全地与服务器或应用程序交互，你需要生成一个JSON Web Token (JWT)。这个JWT将用于身份验证和授权。以下代码展示了如何使用访问密钥 ( access_key ) 和秘密密钥 ( secret_key ) 来生成JWT。

jwt_token = generate_jwt_token(access_key, secret_key)

在这个例子中， generate_jwt_token 是一个函数，它接受你的 access_key 和 secret_key 作为输入。 访问密钥用于标识你的应用程序或用户，而秘密密钥则用于对JWT进行签名，确保其完整性和真实性。请务必妥善保管你的秘密密钥，切勿泄露。

生成的 JWT 随后被赋值给变量 jwt_token 。这个 token 是一个经过编码的字符串，包含了声明（claims），通常包括用户身份信息、权限等。

print(jwt_token)

这条语句会将生成的 JWT 打印到控制台。你可以将这个 JWT 传递给需要进行身份验证或授权的服务。请注意，实际的 generate_jwt_token 函数实现会依赖于你所使用的编程语言和JWT库。 例如，在Python中，你可能会使用 PyJWT 库。 实际代码会包含设置 header、payload，并使用秘密密钥对 header 和 payload 进行签名，生成最终的JWT。

带有查询参数的示例：

在加密货币API交互中，经常需要传递查询参数以指定请求的具体内容。例如，获取特定市场的交易数据，或者限制返回的数据条数。以下展示了如何使用查询参数生成JWT (JSON Web Token)。

query_params = { 'market': 'KRW-BTC', 'count': 10 }

上述代码定义了一个字典 query_params ，用于存储查询参数。 'market': 'KRW-BTC' 指定了要查询的市场为 KRW-BTC（韩元计价的比特币）。 'count': 10 指定了希望返回的数据条数为 10 条。 在实际应用中，你可以根据API的要求修改这些参数。

jwt_token_with_query = generate_jwt_token(access_key, secret_key, query=query_params)

这行代码调用 generate_jwt_token 函数来生成 JWT。它接收三个参数： access_key （访问密钥）、 secret_key （秘密密钥） 和 query 。 access_key 和 secret_key 用于身份验证，而 query 参数则传递了之前定义的查询参数字典。 generate_jwt_token 函数内部会将这些查询参数整合到JWT的payload中，并使用 secret_key 对JWT进行签名。

print(jwt_token_with_query)

这行代码将生成的 JWT 打印出来。 这个 JWT 包含了身份验证信息以及查询参数。你可以将这个 JWT 作为请求头发送到API服务器，以便服务器验证你的身份并根据查询参数返回相应的数据。通常情况下，JWT会被添加到HTTP请求的Authorization头部，例如： Authorization: Bearer YOUR_JWT_TOKEN 。

3. 常用 API 端点

Upbit API 提供了丰富的端点，覆盖了全面的市场数据、高效的交易执行和便捷的账户管理功能。开发者可以利用这些端点获取实时信息，构建自动化交易策略，并进行账户管理操作。以下是一些常用的 API 端点，并对其功能进行更详细的说明：

• 市场数据：
  • /v1/market/all : 获取所有交易市场信息，包括市场代码、市场名称、英文名称以及警告信息等，可以用于构建市场概览和选择交易对。
  • /v1/candles/minutes/{unit} : 获取指定时间间隔的分时 K 线数据，用于技术分析和图表绘制。 {unit} 可以是 1, 3, 5, 15, 30, 60, 240 分钟。 通过调整时间单位，可以满足不同时间维度的分析需求。返回的数据包括开盘价、收盘价、最高价、最低价、成交量等。
  • /v1/candles/days : 获取日线 K 线数据，用于中长期趋势分析和投资决策。 返回的数据同样包括开盘价、收盘价、最高价、最低价、成交量等。
  • /v1/trades/ticks : 获取最新的成交记录，包括成交时间、成交价格、成交量、成交方向等，可以用于实时监控市场动态和捕捉交易机会。
  • /v1/ticker : 获取当前市场行情快照，包括当前价格、24 小时成交额、24 小时涨跌幅等，可以用于快速了解市场整体表现。
  • /v1/orderbook : 获取当前订单簿信息，包括买单和卖单的价格和数量，可以用于分析市场深度和判断价格趋势。 该接口返回的数据是实时变化的，反映了市场供需关系。
• 交易：
  • /v1/orders : 下单、查询订单。 通过该端点可以提交市价单、限价单等多种订单类型，并可以查询订单状态、成交明细等信息。 订单参数包括市场代码、订单类型、价格、数量等。
  • /v1/order : 查询单个订单的详细信息，包括订单状态、成交明细、下单时间等。通过订单 UUID 进行查询。
  • /v1/order/cancel : 取消指定订单，可以通过订单 UUID 进行取消。只有未成交或部分成交的订单才能被取消。
• 账户管理：
  • /v1/accounts : 查询账户信息，包括账户余额、可用余额、冻结余额等，支持查询多种币种的账户信息。
  • /v1/deposits/generate_coin_address : 为指定币种生成充币地址，用于接收外部转入的加密货币。 每次生成的地址都是唯一的。
  • /v1/withdraws/coin : 申请提币，将账户中的加密货币转移到外部地址。 需要提供目标地址、提币数量等信息，并可能需要进行安全验证。

4. 发起 API 请求

与加密货币交易所或服务进行交互，通常需要通过应用程序编程接口 (API) 发起请求。 这些请求允许你以编程方式检索数据、执行交易和管理你的账户。 可以使用各种编程语言提供的 HTTP 客户端库来实现这一点。 选择合适的库取决于你的编程语言偏好和项目需求。

以下 Python 代码示例展示了如何使用流行的 requests 库来获取Upbit交易所的账户信息。 此示例演示了构建身份验证标头、发送 GET 请求和处理响应的基本步骤。 务必安装 requests 和 pyjwt 库，它们可以通过 pip 包管理器轻松安装： pip install requests pyjwt 。

import requests
import jwt
import uuid

# 替换为你的实际凭据
access_key = "YOUR_ACCESS_KEY"
secret_key = "YOUR_SECRET_KEY"
server_url = "https://api.upbit.com"

def get_accounts(access_key, secret_key):
""" 使用 JWT 身份验证从 Upbit API 获取账户信息。 """
payload = {
'access_key': access_key,
'nonce': str(uuid.uuid4()), # 确保每个请求都有唯一的 nonce 值，防止重放攻击
}
jwt_token = jwt.encode(payload, secret_key, algorithm="HS256")
authorize_token = f"Bearer {jwt_token}"
headers = {"Authorization": authorize_token}

# 发起 GET 请求，并传递身份验证标头
res  =  requests.get(server_url + "/v1/accounts",  headers=headers)

# 检查响应状态码
if res.status_code == 200:
    return res.() # 将响应解析为 JSON 格式
else:
    print(f"API 请求失败，状态码：{res.status_code}")
    return None

accounts = get_accounts(access_key, secret_key)
if accounts: print(accounts) # 打印账户信息 else: print("获取账户信息失败。")

重要提示： 请务必妥善保管你的 access_key 和 secret_key ，不要将其暴露给任何未经授权的方。 将它们视为敏感凭据，并采取适当的安全措施来保护它们。 永远不要将它们硬编码到你的代码中，而是使用环境变量或安全配置管理解决方案。

在生产环境中，你需要处理 API 请求可能出现的错误，例如网络问题、身份验证错误和速率限制。 添加适当的错误处理逻辑可以使你的应用程序更健壮和可靠。 请务必仔细阅读Upbit API文档，了解速率限制和其他使用条款，以避免被封禁或受到其他处罚。

关键步骤：

1. 构造请求 URL： 根据 API 文档，仔细确定需要访问的 API 端点。 确保 URL 路径、查询参数（如果有）与文档描述完全一致。 错误的 URL 将导致请求失败，例如404错误。 API 端点通常包含版本信息，务必使用正确的版本号。
2. 添加请求头： 在 HTTP 请求头中添加 Authorization 字段，并设置其值为 Bearer {JWT_TOKEN} 。 {JWT_TOKEN} 必须替换为您根据相关规范生成的有效 JWT（JSON Web Token）。 JWT 用于身份验证和授权，服务端会验证 JWT 的签名和声明，以确认请求的合法性。 JWT 通常包含用户身份、权限等信息。
3. 设置请求参数： 根据 API 文档，精确设置所有必要的请求参数。对于 GET 请求，参数通常以查询字符串的形式附加到 URL 之后，例如： /api/resource?param1=value1&param2=value2 。 对于 POST 、 PUT 、 PATCH 等请求，参数通常放置在请求体中，并使用 application/ 的 Content-Type 标头。 请求体应使用 JSON 格式进行序列化，确保参数名和参数值与 API 文档的定义相符。 注意数据类型，例如字符串、数字、布尔值等。
4. 发送请求： 使用可靠的 HTTP 客户端库（例如 Python 的 requests , JavaScript 的 fetch 或 axios ）发送 API 请求。 设置适当的超时时间，以避免请求长时间挂起。 对于需要身份验证的 API，确保在请求头中正确设置 Authorization 字段。 根据 API 的要求，设置其他必要的请求头，例如 Content-Type , Accept 等。
5. 处理响应： 解析 API 响应，并根据 HTTP 状态码和响应内容采取相应的处理措施。 状态码 200 通常表示请求成功， 201 表示资源创建成功。 4xx 状态码表示客户端错误，例如 400 (Bad Request)、 401 (Unauthorized)、 403 (Forbidden)、 404 (Not Found)。 5xx 状态码表示服务器错误，例如 500 (Internal Server Error)、 502 (Bad Gateway)、 503 (Service Unavailable)。 响应内容通常为 JSON 格式的数据，需要进行反序列化。 根据响应内容中的错误代码和错误消息，进行相应的错误处理和重试机制（如果适用）。

5. 错误处理

在使用 Upbit API 进行交易或数据查询时，开发者可能会遇到各种错误。 为了确保应用程序的稳定性和可靠性，充分理解并有效处理这些错误至关重要。常见的错误及其原因包括：

• 400 Bad Request（错误请求）： 此错误通常表示客户端发送的请求存在问题，例如，请求参数格式不正确、缺少必要的参数、参数值超出允许范围等。 开发者需要仔细检查请求的参数，确保其符合 Upbit API 的规范要求。 可以使用 API 文档提供的示例请求作为参考，仔细比对。
• 401 Unauthorized（未授权）： 此错误表明 API 认证失败。 这通常是因为 API 密钥（Access Key）或安全密钥（Secret Key）不正确，或者没有在请求头中正确地包含认证信息。 开发者需要检查 API 密钥是否已正确配置，并且确保在使用密钥进行签名时，算法和参数设置正确无误。 刷新API密钥可以有效解决密钥泄露的风险。
• 403 Forbidden（禁止访问）： 此错误表示客户端没有权限访问特定的 API 端点。 这可能是因为 API 密钥没有被授权访问该端点，或者 API 账户受到限制。 开发者需要检查 API 密钥的权限设置，确保其拥有访问所需端点的权限。请确认API账户是否因违反Upbit的条款而被限制访问。
• 429 Too Many Requests（请求过多）： 此错误表明客户端在短时间内发送了过多的请求，超出了 Upbit API 的频率限制。 为了避免此错误，开发者需要实施速率限制策略，控制请求的发送频率。 可以使用滑动窗口算法或令牌桶算法来实现速率限制。 同时，应该仔细阅读 Upbit API 的文档，了解不同 API 端点的频率限制，并根据实际情况进行调整。
• 500 Internal Server Error（内部服务器错误）： 此错误表明Upbit服务器在处理请求时遇到了问题。 这通常是服务器端的错误，客户端无法直接解决。此时，建议开发者稍后重试请求，或者联系Upbit的技术支持团队寻求帮助。
• 503 Service Unavailable（服务不可用）： 此错误表明Upbit服务器目前无法处理请求，通常是由于服务器维护或过载造成的。 开发者应该稍后重试请求，或者监控Upbit的服务状态，以便及时发现和处理问题。

在编写 API 客户端代码时，必须充分考虑各种可能的错误情况，并制定相应的错误处理策略，以便能够及时发现和解决问题，确保应用程序的稳定性和可靠性。 可以根据 API 响应状态码和响应内容，进行相应的错误处理。 例如，可以使用 try-except 块捕获异常，记录详细的错误日志（包括时间戳、请求参数、响应内容等），或者实施重试机制（例如，使用指数退避算法）以应对偶发性的错误。 还应考虑向用户提供友好的错误提示信息，帮助用户了解问题所在，并采取相应的措施。

6. API 使用限制

Upbit API 为了保障系统稳定性和公平性，对请求频率和请求数量施加了明确的限制。因此，务必仔细研读官方 Upbit API 文档，透彻理解各项具体的使用限制，例如每分钟或每秒钟允许的请求次数，以及每日请求总量的上限。若请求超出这些限制，Upbit 服务器可能会返回错误代码 (例如 429 Too Many Requests)，并暂时拒绝后续的 API 请求。违规严重时，甚至可能导致 API 密钥被暂时或永久禁用，影响正常的交易和数据获取。

为避免超出 API 限制，确保应用能够持续稳定地访问 Upbit 的服务，可以采取以下关键策略：

• 控制请求频率，实施速率限制： 在代码中实施严格的速率限制机制，避免在极短时间内发送大量并发请求。可以采用令牌桶算法或漏桶算法等流量整形技术，平滑请求发送速率。监控 API 响应头部中的 X-RateLimit-Remaining 和 X-RateLimit-Reset 等字段，实时了解剩余请求配额和重置时间，动态调整请求频率。
• 有效缓存数据，降低请求冗余： 对于价格信息、交易对列表等不经常变动的数据，应采用本地缓存或分布式缓存（如 Redis、Memcached）进行存储。设置合理的缓存过期时间，避免频繁从 Upbit API 获取重复数据，从而显著减少 API 请求次数。缓存更新时，需考虑缓存一致性问题，避免使用陈旧数据。
• 采用 WebSocket 订阅，优化实时数据获取： 对于需要实时更新的交易行情、订单簿变化等数据，强烈建议使用 Upbit 提供的 WebSocket API。WebSocket 是一种持久化的双向通信协议，允许 Upbit 服务器主动推送数据到客户端，避免了客户端频繁轮询 API 带来的额外请求开销。通过订阅相关频道，可以实时接收数据更新，保证数据的及时性和准确性。