Upbit API 掘金：Python 自动化交易实战指南！

2025-03-08 04:48:20 65

Upbit 平台如何设置并使用 API 接口

Upbit 作为韩国领先的加密货币交易所，为用户提供了强大的 API (Application Programming Interface) 接口，方便用户进行程序化交易、数据分析和自动化操作。本文将详细介绍如何在 Upbit 平台上设置并使用 API 接口。

1. 准备工作

在使用 Upbit API 之前，务必完成以下准备工作，以确保您能够顺利、安全地访问和使用 Upbit 的各项功能：

注册 Upbit 账户并完成身份验证 (KYC)： 您需要在 Upbit 平台注册一个账户，并且通过 KYC (Know Your Customer) 身份验证流程。这通常包括提供您的身份证明文件、地址证明以及其他必要的信息。完成 KYC 认证后，您才能获得访问 Upbit API 的权限，并遵守相关的监管要求。
启用 2FA (Two-Factor Authentication) 双重验证： 强烈建议您启用 2FA 双重验证，以增强账户的安全性。双重验证要求您在登录时除了输入密码外，还需要提供一个来自验证器应用程序 (如 Google Authenticator、Authy 或其他 TOTP 应用) 的动态验证码。这可以有效防止即使密码泄露，攻击者也无法轻易访问您的账户。请妥善保管您的 2FA 密钥或备份码。
深入了解 Upbit API 使用规则与文档： 在开始编写代码并调用 Upbit API 之前，请务必仔细阅读并理解 Upbit 官方提供的 API 文档。文档中包含了关于 API 的详细信息，包括：可用的 API 端点、请求参数、响应格式、数据类型、认证方式、调用频率限制、IP 限制以及错误代码等。通过阅读 API 文档，您可以更好地了解 API 的工作原理，编写出高效、稳定且符合 Upbit 要求的应用程序，从而避免触发 API 限制或出现意外错误。请特别关注API的速率限制（Rate Limit），以防止因频繁调用而被暂时禁用。

2. 获取 Upbit API 密钥

要通过 Upbit API 访问和使用其服务，您需要生成一对 API 密钥：Access Key 和 Secret Key。Access Key 用于标识您的应用程序，而 Secret Key 则用于对您的请求进行签名，验证您的身份。请按照以下详细步骤安全地获取您的 API 密钥：

登录 Upbit 官方网站： 确保您访问的是 Upbit 的官方网站，以防止钓鱼攻击。使用您的 Upbit 账户凭据登录。建议启用两步验证 (2FA) 以增强账户安全性。
进入 API 管理页面： 登录后，寻找 "我的页面"、"账户设置" 或类似的导航选项。通常，API 密钥管理相关的链接位于 "安全设置" 或 "API 开放平台" 部分。仔细查找 "API 密钥管理" 或类似的选项。
创建新的 API 密钥： 在 API 管理页面，点击 "新增 API 密钥"、"创建 API 密钥" 或类似的按钮，开始密钥创建流程。部分交易所可能要求您在创建密钥之前阅读并同意相关条款和条件。
配置 API 密钥权限： 创建 API 密钥时，至关重要的是仔细设置权限。您可以选择不同的权限级别，例如：
- 只读权限 (Read-Only)： 允许您查询账户余额、历史交易记录、市场行情数据 (如价格、成交量等)，但不能进行任何交易操作。适用于数据分析、监控等场景。
- 交易权限 (Trade)： 允许您执行买入、卖出订单，取消订单等交易操作。授予交易权限时务必谨慎。
- 提现权限 (Withdraw)： 允许您将资金从 Upbit 账户提取到其他地址。 强烈建议不要授予提现权限，除非您明确需要通过 API 实现自动提现功能，并充分了解相关风险。
安全提示： 始终遵循最小权限原则。仅授予您的应用程序所需的最低权限。例如，如果您的应用程序只需要查询市场数据，则只授予 "只读" 权限。避免授予不必要的权限，以降低账户安全风险。仔细阅读 Upbit 提供的权限说明，了解每种权限的具体含义和潜在影响。
输入 API 密钥名称： 为您的 API 密钥指定一个易于识别且具有描述性的名称，例如 "MyTradeBot_v1"、"DataAnalysis_Daily" 或 "PortfolioTracker"。良好的命名习惯可以帮助您区分不同的 API 密钥，方便管理和审计。
完成 2FA 身份验证： 为了确保安全性，Upbit 通常会要求您输入通过 Google Authenticator 或其他 2FA 应用程序生成的验证码，以确认您是 API 密钥创建操作的授权者。这是防止未经授权创建 API 密钥的重要安全措施。
保存 Access Key 和 Secret Key： 成功创建 API 密钥后，Upbit 将显示您的 Access Key 和 Secret Key。 Access Key 会显示在页面上，而 Secret Key 只会显示一次。务必立即将 Secret Key 复制并安全地存储在您的计算机或密码管理器中。 强烈建议使用强密码管理器，例如 LastPass、1Password 或 KeePass，以安全地存储您的 Secret Key。 切勿将 Secret Key 存储在明文文件中，例如文本文件或电子表格中。 不要通过电子邮件、聊天工具或其他不安全的方式发送 Secret Key。 如果您的 Secret Key 泄露，请立即撤销该 API 密钥，并创建一个新的密钥。 Secret Key 类似于您的银行密码，必须严格保密。一旦泄露，攻击者可以使用您的 Secret Key 执行未经授权的交易，导致资金损失。

3. 使用 API 进行身份验证

在使用 Upbit API 发送请求时，必须进行身份验证以确保请求的合法性和安全性。 Upbit 采用基于 JWT (JSON Web Token) 的身份验证机制。您需要利用您的 Access Key 和 Secret Key 生成符合 Upbit 规范的 JWT，并在请求头中携带该 JWT。

Access Key 和 Secret Key 是您在 Upbit 交易所创建 API 密钥时获得的，请务必妥善保管，切勿泄露。泄露您的 Access Key 和 Secret Key 可能导致您的账户资产面临风险。

以下是一个使用 Python 语言生成 JWT 的示例代码，方便您理解 JWT 的生成过程：

import jwt import uuid

access_key = "YOUR_ACCESS_KEY" # 替换成你的 Access Key secret_key = "YOUR_SECRET_KEY" # 替换成你的 Secret Key

def generate_jwt(): payload = { 'access_key': access_key, 'nonce': str(uuid.uuid4()), } jwt_token = jwt.encode(payload, secret_key, algorithm="HS256") return jwt_token

jwt_token = generate_jwt() print(jwt_token)

代码解释：

import jwt : 导入 Python 的 JWT 库，用于生成和验证 JWT。您需要使用 pip install pyjwt 安装该库。
import uuid : 导入 Python 的 UUID 库，用于生成唯一的 nonce 值。
access_key = "YOUR_ACCESS_KEY" 和 secret_key = "YOUR_SECRET_KEY" : 请务必将 YOUR_ACCESS_KEY 和 YOUR_SECRET_KEY 替换成您真实的 Access Key 和 Secret Key。
payload : payload 是 JWT 的核心部分，包含声明。在此示例中，payload 包含两个声明： access_key (您的 Access Key) 和 nonce (一个唯一的随机字符串)。 nonce 用于防止重放攻击。
jwt.encode(payload, secret_key, algorithm="HS256") : 使用您的 Secret Key 和 HS256 算法对 payload 进行签名，生成 JWT。 HS256 是一种常用的对称加密算法。
print(jwt_token) : 打印生成的 JWT。

请注意，这只是一个简单的示例代码。在实际应用中，您可能需要根据 Upbit API 的具体要求，添加或修改 payload 中的声明。您可以在 Upbit 的官方 API 文档中找到关于 JWT 生成的详细说明。

说明：

YOUR_ACCESS_KEY 和 YOUR_SECRET_KEY 必须替换为您在交易所或服务提供商处获得的实际的 Access Key 和 Secret Key。 Access Key 用于标识您的身份，而 Secret Key 则用于对您的请求进行签名，保障安全性。请务必妥善保管您的Secret Key，避免泄露，因为它具有访问您账户的权限。
nonce 是一个随机生成的、唯一的字符串，其主要作用是防止重放攻击。重放攻击是指攻击者截获并重复发送合法的请求，以此来达到欺骗系统的目的。通过在每个请求中包含一个唯一的 nonce 值，服务器可以识别并拒绝重复的请求，从而有效防止此类攻击。建议 nonce 值的生成使用高强度的随机数生成器，并保证其在一定时间范围内具有唯一性。
jwt.encode() 函数使用 HS256（HMAC SHA256）算法对 payload（负载）进行签名。 HS256 是一种对称加密算法，这意味着加密和解密使用相同的密钥（即您的 Secret Key）。 JWT（JSON Web Token）是一种行业标准的用于在各方之间安全地传输信息的开放标准 (RFC 7519)。通过使用您的 Secret Key 对 JWT 进行签名，可以验证 JWT 的完整性和真实性，确保信息在传输过程中没有被篡改。payload 包含您需要传递的数据，例如时间戳、用户ID 或其他自定义信息。

4. 发送 API 请求

生成 JSON Web Token (JWT) 之后，您可以使用任何 HTTP 客户端（例如 cURL、Postman 或编程语言中的 HTTP 库）来发送 API 请求。身份验证的关键在于 Authorization 请求头，其值为 Bearer 。 Bearer 方案是一种广泛使用的授权协议，指示服务器客户端已通过 JWT 进行了身份验证。

以下是一个使用 Python 的 requests 库发送 API 请求的示例代码。请确保已安装 requests 库 ( pip install requests )。这段代码演示了如何构建包含 JWT 的请求头并发送 GET 请求到 Upbit 交易所的 API 端点。您需要根据实际的 API 文档调整 URL 和请求方法。

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

access_key = "YOUR_ACCESS_KEY"  # 替换成你的 Access Key
secret_key = "YOUR_SECRET_KEY"  # 替换成你的 Secret Key

def generate_jwt():
    """生成 JWT 令牌."""
    payload = {
        'access_key': access_key,
        'nonce': str(uuid.uuid4()),
    }
    jwt_token = jwt.encode(payload, secret_key, algorithm='HS256')
    return jwt_token

jwt_token = generate_jwt()

headers = {"Authorization": f"Bearer {jwt_token}"}

url = "https://api.upbit.com/v1/accounts"  # 查询账户信息的 API 端点
response = requests.get(url, headers=headers)

print(response.status_code)
print(response.())

需要注意的是，实际的 JWT 生成过程比示例代码更复杂，通常涉及使用私钥对payload进行签名。示例代码中 generate_jwt() 函数是一个占位符，需要根据您所使用的 API 的具体要求进行填充。通常, payload包含access_key, nonce(随机字符串)和query（可选）。nonce 用于防止重放攻击。请务必参考对应API文档的JWT生成部分。

在使用 API 时，务必处理可能出现的各种 HTTP 状态码。例如， 200 表示成功， 401 表示未授权（JWT 无效或过期）， 403 表示禁止访问， 429 表示请求过多（需要进行速率限制处理）， 500 表示服务器内部错误。根据状态码采取适当的措施，例如重试请求、刷新 JWT 或联系 API 提供商。

API请求返回的数据通常是JSON格式。使用 response.() 方法可以方便地将响应内容解析为 Python 字典或列表，方便进一步处理和使用。

说明：

url 变量定义了与 Upbit API 进行交互的关键入口点，即API端点。 API端点是特定功能的访问地址，务必依据您要调用的具体API功能，选择与之对应的正确端点。 Upbit 官方 API 文档详尽地罗列了所有可用的API端点及其详细说明，强烈建议查阅该文档以确保端点选择的准确性。每个端点对应着不同的功能，例如获取市场行情、下单交易、查询账户信息等。
headers 字典在HTTP请求中扮演着至关重要的角色，它包含了诸如 Authorization 等用于身份验证的关键字段。 Authorization 字段通常包含您的API密钥，用于验证您的身份并授权您访问受保护的API资源。正确的配置 headers 字典是成功调用Upbit API的前提。通常，你需要将你的访问密钥（access key）和安全密钥（secret key）按照特定的格式组合成一个Token，并将其添加到 Authorization 头部中。
requests.get() 函数是 Python requests 库提供的核心功能之一，用于向指定的 url 发送 HTTP GET 请求。 GET 请求主要用于从服务器获取数据，通常不用于修改服务器上的数据。除了 requests.get() ， requests 库还提供了 requests.post() 、 requests.put() 、 requests.delete() 等函数，用于发送其他类型的 HTTP 请求，例如 POST（用于创建资源）、PUT（用于更新资源）和 DELETE（用于删除资源）。选择合适的HTTP方法取决于您希望执行的操作类型。
response.status_code 属性提供了关于 HTTP 请求结果的重要信息，它返回一个数值型的 HTTP 状态码。 HTTP 状态码是服务器对请求的响应状态的数字表示。一个值为 200 的 HTTP 状态码表示请求已成功处理，服务器成功返回了请求的数据。常见的状态码还包括 400 (错误请求)、401 (未授权)、403 (禁止访问)、404 (未找到) 和 500 (服务器内部错误)等。通过检查状态码，您可以了解请求是否成功，以及如果失败的原因。
response.() 方法用于解析 API 响应，并将响应数据转换为 Python 字典或列表，这使得您可以方便地访问和处理 API 返回的数据。 API 响应通常采用 JSON（JavaScript Object Notation）格式，这是一种轻量级的数据交换格式，易于阅读和解析。通过调用 response.() ，您可以将 JSON 格式的响应数据转换为 Python 对象，从而可以轻松地访问和操作其中的数据。请注意，只有当服务器返回的响应是有效的 JSON 格式时，此方法才能成功执行。

5. 常见 API 使用示例

以下是一些常见的 Upbit API 使用示例，展示了如何通过 API 与 Upbit 交易所进行交互：

查询账户信息： 获取您的 Upbit 账户详细信息，包括可用余额、冻结金额、持仓加密货币种类和数量等。这些信息对于了解您的资产状况和风险敞口至关重要。您可以根据返回的数据进行投资决策，例如调整仓位或执行再平衡策略。
查询市场行情： 获取指定交易对的实时市场数据，包括最新成交价格、最高价、最低价、24 小时成交量、深度行情（买一/卖一价）等。K 线图数据允许您分析历史价格走势，识别趋势和支撑阻力位，辅助技术分析。实时行情数据对于高频交易和套利策略至关重要。
下单： 通过 API 提交买入或卖出指定交易对加密货币的订单。可以设置订单类型，如市价单（以当前市场价格立即成交）或限价单（指定价格，等待市场价格达到该价格时成交）。下单时需要指定交易对、买卖方向、数量和价格（限价单）。
取消订单： 取消尚未完全成交的挂单。在市场波动剧烈时，取消未成交订单可以避免因价格剧烈波动而造成的损失。通过 API 取消订单可以实现自动化风控。
查询订单历史： 获取您的历史订单记录，包括订单类型、下单时间、成交时间、成交价格、成交数量、手续费等详细信息。这些数据可以用于追踪交易表现、分析交易策略的有效性，以及进行税务申报。

请务必参考 Upbit 官方 API 文档 (https://docs.upbit.com/)，详细了解每个 API 的具体参数、请求方法（GET/POST）、请求频率限制、身份验证方式、以及可能的错误代码和返回值。官方文档是您使用 Upbit API 的最权威指南，包含最新信息和最佳实践。熟悉官方文档有助于您更高效地利用 Upbit API 进行开发和交易。

6. 错误处理

在使用 Upbit API 进行交易或数据查询时，可能会遇到各种类型的错误。为了确保您的应用程序的稳定性和可靠性，实施全面的错误处理机制至关重要。有效的错误处理能够帮助您快速识别问题、诊断原因，并采取适当的措施进行恢复或补救，避免数据丢失或交易失败。

常见的错误类型包括：

400 Bad Request（错误请求）： 此错误表示您发送的请求存在问题，通常是由于请求参数不正确或缺失导致的。检查请求参数的类型、格式和取值范围是否符合 Upbit API 的要求。例如，检查必填参数是否已提供，参数值是否为有效的格式（如日期格式、货币单位等）。
401 Unauthorized（未授权）： 此错误表明您的身份验证失败。这通常是因为您提供的 Access Key 和 Secret Key 不正确、过期，或者 JWT (JSON Web Token) 无效。请务必仔细检查您的 Access Key 和 Secret Key 是否正确配置，并确保 JWT 尚未过期。如果使用 API 密钥进行身份验证，请确认您已启用相应的权限。
429 Too Many Requests（请求过多）： Upbit API 具有调用频率限制，用于防止滥用和维护系统稳定性。当您在短时间内发送过多的请求时，会收到此错误。解决此问题的最佳方法是降低您的 API 调用频率。您还可以考虑实施请求队列或使用指数退避算法，以便在达到频率限制后等待一段时间再重试。详细的频率限制信息请参考 Upbit API 的官方文档。
500 Internal Server Error（服务器内部错误）： 此错误表示 Upbit 服务器遇到了内部问题，导致无法完成您的请求。这通常是临时的，建议您稍后重试。如果该错误持续发生，请联系 Upbit 技术支持以获取帮助。

当您的应用程序收到错误响应时，应立即采取适当的措施。仔细检查 response.status_code 以确定 HTTP 状态码，它能指示错误的类别。然后，解析 response.text 或 response.() 中的错误信息，这些信息通常包含更详细的错误描述和错误代码，有助于您精确地诊断错误原因。根据错误原因，您可以采取相应的处理措施，例如重新构造请求、更新 API 密钥、降低调用频率或稍后重试。建议您将错误信息记录到日志中，以便进行问题追踪和分析。

7. 注意事项

安全： 务必采取最严格的安全措施保管您的 Access Key 和 Secret Key，切勿以任何形式泄露给任何第三方。密钥泄露可能导致严重的资金损失和账户安全风险。除了避免硬编码，还应考虑使用专门的密钥管理服务（例如 HashiCorp Vault）进行更高级别的保护。定期轮换 API 密钥是降低潜在风险的关键环节，建议设置自动化的密钥轮换机制。
频率限制： 严格遵守 Upbit 官方发布的 API 调用频率限制，超出限制可能导致您的 API 访问被暂停。为了避免触发限制，可以采用更精细的 API 调用策略，例如批量请求、延迟执行等。使用缓存机制能够有效减少对 Upbit API 的直接调用，而使用消息队列则可以实现更平滑的请求处理，避免突发流量对 API 服务造成压力。
数据准确性： Upbit API 返回的数据可能存在一定的延迟，并且在极端情况下可能出现误差，这是由市场数据传输和处理过程中的固有特性决定的。因此，在使用 API 数据进行交易决策时，务必保持谨慎，并结合其他数据来源进行交叉验证。建议采用多种数据源，并对数据进行清洗和预处理，以降低误差带来的影响。
API 版本： Upbit 可能会不定期更新 API 版本，以优化功能或修复安全漏洞。密切关注 Upbit 官方渠道（如官方网站、开发者社区）发布的公告，以便及时了解 API 版本的更新情况。当 API 版本发生变化时，请务必及时更新您的代码，以确保与最新版本的 API 兼容，并充分利用新版本提供的功能。

通过严格遵循以上注意事项，您将能够更安全、更高效地使用 Upbit API 接口，并最大程度地降低潜在风险。我们期望您在使用 Upbit API 进行程序化交易和数据分析的过程中，能够获得良好的体验。