Upbit API掘金指南：新手也能轻松玩转！

Upbit API 接口接入指南

Upbit 作为韩国领先的加密货币交易所，为用户提供了功能强大的 API 接口，允许开发者集成 Upbit 的交易、行情等数据到自己的应用程序或交易策略中。本文将详细介绍 Upbit API 接口的接入流程和关键步骤。

1. API 密钥申请

要开始使用 Upbit API 进行自动化交易、数据分析或其他相关操作，您需要先申请 API 密钥。API 密钥是您访问 Upbit API 的凭证，它允许您的应用程序以编程方式与 Upbit 交易所进行交互。请按照以下详细步骤操作：

1. 登录 Upbit 账户： 访问 Upbit 官方网站 (upbit.com)。使用您的用户名和密码安全地登录您的 Upbit 账户。请确保您访问的是官方网站，谨防钓鱼网站。如果您还没有账户，您需要先注册一个账户并完成必要的身份验证流程。
2. 进入 API 管理页面： 成功登录后，导航到您的账户设置或 “我的页面” 区域。通常，您可以在用户头像下找到相关选项，例如 “开放 API 管理”、“API 密钥管理” 或类似的命名。点击该选项进入 API 管理页面。
3. 创建 API 密钥： 在 API 管理页面，您需要创建一个新的 API 密钥。
   • 密钥用途描述： 提供一个清晰的描述，说明您计划如何使用此 API 密钥。这将帮助您管理和跟踪不同的密钥，尤其是在您有多个应用程序需要访问 Upbit API 时。
   • 权限选择： 选择您需要的 API 权限。Upbit 提供了细粒度的权限控制，允许您精确地指定您的应用程序可以执行哪些操作：
     • 交易权限 (Trade API)： 授予您的应用程序进行买入和卖出交易的权限。如果您计划开发自动交易机器人或交易策略，则需要此权限。请务必谨慎使用，并仔细审查您的交易逻辑，以避免意外损失。
     • 查询权限 (View API)： 允许您的应用程序获取各种市场数据，例如实时行情、历史交易数据、订单簿深度等。您还可以使用此权限查询您的账户余额、交易历史等信息。这对于数据分析、监控和报告非常有用。
     • 提币权限 (Withdraw API)： 授予您的应用程序从您的 Upbit 账户提取数字货币的权限。这是一个非常敏感的权限，强烈建议您仅在完全信任您的应用程序并且确有提币需求时才启用。启用此权限后，请务必密切监控您的账户活动，以防止未经授权的提币行为。
4. IP 白名单设置： 为了增强安全性，Upbit 强制要求您设置 IP 白名单。这意味着只有来自您指定的 IP 地址的请求才会被 Upbit API 接受。
   • 服务器 IP 地址： 如果您的应用程序运行在服务器上，请将您的服务器的公网 IP 地址添加到白名单中。
   • 本地开发环境 IP 地址： 如果您正在本地开发和测试您的应用程序，请将您的本地计算机的公网 IP 地址添加到白名单中。您可以使用在线 IP 查询工具来获取您的公网 IP 地址。
   • IP 地址范围： 您可以指定单个 IP 地址或 IP 地址范围。请注意，错误的 IP 白名单设置可能会导致您的应用程序无法正常工作。
5. 生成 API 密钥： 仔细检查您填写的信息和选择的权限。确认无误后，点击 “生成 API 密钥” 或类似的按钮。系统将生成两个关键字符串： access_key (访问密钥) 和 secret_key (私钥)。
   • access_key ： 用于标识您的应用程序。它相当于您的用户名，可以公开使用。
   • secret_key ： 用于对您的 API 请求进行签名，以验证请求的真实性和完整性。它相当于您的密码，必须严格保密。
   • 安全提示： 请将您的 secret_key 存储在安全的地方，例如加密的配置文件或密钥管理系统。切勿将 secret_key 存储在您的代码库中或以任何方式泄露给他人。如果您怀疑您的 secret_key 已经泄露，请立即撤销该密钥并生成一个新的密钥。

2. API 文档查阅

Upbit 交易所为其用户和开发者提供了详尽的 API 文档，该文档是集成 Upbit 交易平台功能和获取市场数据的关键资源。您可以通过访问 Upbit 开放平台 (developers.upbit.com) 访问这些文档。API 文档不仅包含了所有可用的 API 接口的完整说明，还详细阐述了每个接口的功能、使用方法以及预期行为，从而确保开发者能够有效地利用 Upbit 的 API。

• 请求方法 (GET, POST, DELETE, PUT, PATCH)： 定义了与 API 交互时所使用的 HTTP 方法。 GET 用于检索数据， POST 用于创建新资源， DELETE 用于删除资源， PUT 用于完全更新现有资源， PATCH 用于部分更新现有资源。 选择正确的请求方法对于确保 API 调用符合预期操作至关重要。
• 请求 URL (Endpoint)： 指定了 API 接口的具体访问地址或端点。该 URL 包含了服务器地址和资源路径，开发者需要准确使用该 URL 才能连接到特定的 API 功能。 例如，不同的 URL 可能对应于获取交易对列表、查询账户余额或下单等操作。
• 请求参数 (Parameters)： 指定了 API 接口运行时需要传递的参数。参数可以是必需的或可选的，并且每个参数都有特定的名称、数据类型（例如字符串、整数、布尔值）和用途。 文档会详细说明每个参数的含义、取值范围和验证规则，以便开发者构建正确的 API 请求。 缺少必要的参数或提供无效的参数可能会导致 API 调用失败。
• 响应格式 (Response Format)： 定义了 API 接口返回数据的结构和格式。 Upbit API 通常使用 JSON (JavaScript Object Notation) 作为响应格式，因为它易于解析和处理，且具有良好的跨平台兼容性。 文档会描述 JSON 响应中包含的字段及其数据类型，以便开发者能够正确地解析和使用 API 返回的数据。
• 错误代码 (Error Codes)： 列出了 API 接口可能返回的错误代码及其对应的含义。 错误代码用于指示 API 调用过程中出现的各种问题，例如参数错误、权限不足、服务器错误等。 通过查阅错误代码列表，开发者可以快速定位和解决 API 调用失败的原因，从而提高开发效率和应用程序的稳定性。 文档通常还会提供关于如何处理特定错误的建议。

为了确保成功地调用 Upbit API 并构建可靠的应用程序，务必仔细阅读并理解 API 文档的每一个细节。 了解每个接口的具体用法，包括其输入参数、预期输出、错误处理机制以及相关的安全注意事项，是至关重要的。

3. API 调用认证

Upbit API 采用基于 JWT (JSON Web Token) 的认证机制来保障接口安全。这意味着每个请求都需要在 Authorization 请求头中携带一个有效的 JWT Token，以此证明请求方的身份和权限。

要生成有效的 JWT Token，需要遵循以下步骤：

1. 构造 Payload（有效载荷）： Payload 是一个 JSON 对象，它包含了需要进行签名的数据，也就是服务器用来验证客户端身份和请求合法性的信息。不同 API 接口对 Payload 的内容要求可能不同。 常见的 Payload 组成部分包括：
   • access_key ：您的 Upbit API 访问密钥，用于标识您的账户。
   • nonce ：一个随机字符串，必须是唯一的。这个参数的主要作用是防止重放攻击，即攻击者截获并重复发送之前的请求。 通常使用 UUID (Universally Unique Identifier) 来生成。
   • API 请求所需的其他参数：如果调用的 API 接口需要传递额外的参数，例如订单 ID、交易数量等，这些参数也需要包含在 Payload 中。这些参数将根据 API 文档的具体要求进行设置。
2. 使用 Secret Key 进行 HMAC-SHA512 签名： 使用您的 secret_key (Upbit API 密钥) 对上一步构造的 Payload 进行 HMAC-SHA512 签名。HMAC-SHA512 是一种常用的哈希消息认证码算法，它结合了密钥和哈希函数，能够有效地验证数据的完整性和来源。 这个过程将 Payload 和您的 Secret Key 结合起来，生成一个唯一的签名，这个签名是 JWT Token 的关键组成部分。 建议使用专门的加密库来执行此步骤，以确保安全性和正确性。
3. 生成 JWT Token： 将 access_key (访问密钥), 签名后的 Payload 和签名算法（例如 HS256 或 HS512）等信息按照 JWT 的标准格式组装成一个完整的 JWT Token。 JWT Token 通常由三个部分组成，它们分别是：
   • Header (头部)： 包含 Token 的类型和所使用的哈希算法。
   • Payload (有效载荷)： 包含声明（claims），例如访问密钥 (access_key) 和 nonce。
   • Signature (签名)： 通过 Secret Key 对 Header 和 Payload 进行加密生成的。
   这三个部分通过 Base64 编码后，用点号 ( . ) 连接起来，形成最终的 JWT Token。

您可以使用各种编程语言提供的 JWT 库来简化 JWT Token 的生成过程。以下是一个 Python 示例，使用了 pyjwt 库：

import jwt
import uuid
import hashlib

access_key = "YOUR_ACCESS_KEY"  # 替换为您的访问密钥
secret_key = "YOUR_SECRET_KEY"  # 替换为您的密钥

payload = {
    'access_key': access_key,
    'nonce': str(uuid.uuid4()),  # 生成唯一的 nonce
}

jwt_token = jwt.encode(payload, secret_key, 'HS256')  # 使用 HS256 算法签名
authorize_token = 'Bearer {}'.format(jwt_token) # 构造 Authorization Header 的值

print(authorize_token)

注意：

• 请务必妥善保管您的 access_key 和 secret_key 。不要将它们泄露给任何人，更不要将它们硬编码到您的应用程序中。 建议将它们存储在安全的环境变量或配置文件中。
• nonce 必须是唯一的，每次 API 调用都应该生成一个新的 nonce 。
• 根据 Upbit API 的文档，选择正确的签名算法。常用的算法包括 HS256 和 HS512。
• 在发送 API 请求时，请确保将 authorize_token 正确地设置在 Authorization 请求头中。 请求头的值应该以 "Bearer " 开头，后跟您的 JWT Token。 例如: Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

4. API 接口调用示例

以下是一些常用的 Upbit API 接口调用示例，这些示例展示了如何通过编程方式与 Upbit 交易所进行交互，获取市场数据或执行交易操作。

Upbit API 提供了多种功能，涵盖了行情查询、账户管理、订单操作等多个方面。开发者可以利用这些 API 构建自动化交易程序、数据分析工具或者集成到现有的金融应用中。

在进行 API 调用前，请务必仔细阅读 Upbit 官方 API 文档，了解每个接口的具体参数、返回值以及频率限制。同时，为了保障账户安全，强烈建议使用 API 密钥进行身份验证，并妥善保管您的密钥信息。

API 调用通常需要编程语言的支持，例如 Python、Java、JavaScript 等。以下示例仅为概念性的说明，具体的代码实现会根据您选择的编程语言和库而有所不同。

请注意，API 接口的可用性和参数可能会根据 Upbit 的更新而发生变化，请定期查阅官方文档以获取最新的信息。

获取账户余额：

在加密货币交易中，获取账户余额是至关重要的步骤，允许用户实时掌握其资产状况。以下代码展示了如何使用Python的 requests 库与Upbit交易所的API交互，检索您的账户余额信息。

确保您已安装 requests 库。如果尚未安装，请使用pip进行安装： pip install requests

导入 requests 库：

import requests

接下来，定义API请求的URL和所需的头部信息。

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

headers = {"Authorization": authorize_token}

其中， url 变量指定了Upbit API的账户信息端点。 headers 变量包含了授权令牌（ authorize_token ），这是访问Upbit API的必要凭证。请务必将 authorize_token 替换为您自己的有效API密钥。API密钥通常需要在交易所网站上创建，并需要进行身份验证，以确保账户安全。授权令牌的正确格式取决于交易所的要求，通常是一个包含API密钥和秘密密钥的签名字符串。

然后，使用 requests.get() 方法发送GET请求到指定的URL，并将头部信息传递给服务器。

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

服务器的响应将存储在 response 对象中。该对象包含了响应状态码、头部信息和响应体等数据。响应状态码可以用来判断请求是否成功（例如，200表示成功，401表示未授权）。

打印响应内容，通常是包含账户余额信息的JSON字符串。

print(response.())

response.() 方法将响应体解析为JSON格式，使其易于阅读和处理。输出结果将包含您在Upbit交易所的各个币种的余额信息，例如可用余额、锁定余额等。

获取市场行情 (KRW-BTC)：

在Python中，可以使用 requests 库来发起HTTP请求，从而获取Upbit交易所提供的KRW-BTC交易对的市场行情数据。

import requests

此行代码导入了 requests 库，该库允许你发送各种类型的HTTP请求，例如GET和POST请求。在后续的代码中，我们将使用它来获取Upbit API的响应。

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

response = requests.get(url)

这部分代码定义了Upbit API的URL，用于查询KRW-BTC交易对的ticker信息。 requests.get(url) 函数发送一个GET请求到指定的URL，并将服务器的响应存储在 response 对象中。 此处的 v1/ticker 是Upbit API的版本1的ticker端点， markets=KRW-BTC 参数指定了要查询的交易对为韩元兑比特币。

print(response.text)

这行代码打印服务器返回的响应内容。 response.text 属性包含了服务器响应的文本数据，通常是JSON格式的数据，其中包括当前KRW-BTC交易对的最新价格、交易量、最高价、最低价等信息。开发者需要解析这个JSON数据，才能提取出具体的价格信息并进行后续处理。使用 response.() 可以直接将返回的JSON文本转换为Python字典，方便进一步操作。注意检查响应状态码，确保请求成功（状态码为200）。

下单买入 (KRW-BTC)：

此示例演示如何使用Python的 requests 库，通过Upbit API以限价方式下单购买比特币（BTC）。请务必替换示例中的授权令牌(authorize_token)为你自己的有效令牌。

import requests

导入Python的 requests 库，该库用于发送HTTP请求。如果未安装，请使用 pip install requests 命令进行安装。

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

定义Upbit API的下单endpoint URL。所有订单请求都将发送到此URL。

payload = { 'market': 'KRW-BTC', 'side': 'bid', 'volume': '0.001', 'price': '50000000', 'ord_type': 'limit'}

构建包含订单参数的payload字典。各个参数含义如下：

• market : 交易市场，这里是 KRW-BTC ，表示韩元交易比特币。
• side : 订单方向， bid 表示买入（购买比特币）。
• volume : 订单数量，这里是 0.001 ，表示购买0.001个比特币。
• price : 订单价格，这里是 50000000 ，表示以50,000,000韩元的价格购买。
• ord_type : 订单类型， limit 表示限价单。

headers = {"Authorization": authorize_token}

设置HTTP请求头，其中 Authorization 字段包含你的API授权令牌。你需要将 authorize_token 替换为你的实际令牌。该令牌用于身份验证和授权。

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

使用 requests.post() 方法向Upbit API发送POST请求，以下单。 url 是API endpoint， headers 包含授权信息， data 是订单参数。请注意，此处将 payload 传递给 data 参数， requests 库会自动将其编码为 application/x-www-form-urlencoded 格式。使用 =payload 也可以，这样 requests 库会将其编码为 application/ 格式，但Upbit API更倾向于 application/x-www-form-urlencoded 格式的数据。

print(response.text)

打印API的响应文本。响应文本通常包含订单的执行结果或错误信息。可以通过检查 response.status_code 来判断请求是否成功（200表示成功）。可以增加错误处理，例如，如果 response.status_code 不是200，则打印错误信息并退出。

5. 错误处理

在使用 Upbit API 进行交易或数据查询时，可能会遇到各种错误。理解并正确处理这些错误对于构建稳定可靠的应用程序至关重要。常见的错误类型包括：

• 400 Bad Request： 指示客户端发送的请求存在问题。这通常意味着请求参数不符合 API 的规范，例如缺少必要的参数、参数格式错误、参数值超出范围等。仔细检查请求的 URL、请求头和请求体，确保所有参数都已正确设置并符合 API 文档中的要求。常见原因包括无效的订单类型、不正确的交易量或价格，以及无效的货币对。
• 401 Unauthorized： 表明客户端没有提供有效的身份验证凭据，或者提供的凭据已过期或被吊销。通常是因为 API 密钥不正确、缺失或者未被正确配置。请确保您已正确设置 API 密钥和密钥，并且 API 密钥具有执行相应操作的权限。如果密钥最近被重置，请更新应用程序中的密钥信息。也可能是IP没有加入白名单。
• 429 Too Many Requests： 说明客户端在短时间内发送了过多的请求，超过了 Upbit API 的速率限制。为了维护服务器的稳定性和公平性，Upbit 对每个 API 密钥的请求频率进行了限制。遇到此错误时，建议采用指数退避策略，即在每次重试前逐渐增加等待时间，避免对服务器造成过大的压力。同时，检查应用程序的请求逻辑，优化请求频率，避免不必要的 API 调用。建议监控 API 的响应头，其中通常会包含有关剩余请求次数和重置时间的信息。
• 500 Internal Server Error： 表示 Upbit 服务器在处理请求时遇到了内部错误。这通常是 Upbit 方面的问题，客户端无法直接解决。如果遇到此错误，建议稍后重试。如果错误持续存在，请联系 Upbit 的技术支持团队，并提供详细的错误信息，以便他们进行调查和修复。
• 502 Bad Gateway： 表明 Upbit 服务器作为网关或代理，从上游服务器接收到无效的响应。 这通常表明 Upbit 的服务器端存在临时问题。 建议稍后重试请求。 如果问题仍然存在，请联系 Upbit 支持部门以获得进一步的帮助。
• 503 Service Unavailable： 指示 Upbit 服务器当前无法处理请求，可能是由于服务器过载或正在进行维护。 这是一种临时情况，建议稍后重试您的请求。 您还可以检查 Upbit 的状态页面或社交媒体频道，以获取有关服务中断的更新。

针对不同的错误代码，您需要采取不同的处理措施。例如，对于 429 错误，您可以通过引入延迟机制来减缓请求频率；对于 500 错误，您可以稍后重试，或者联系 Upbit 的技术支持寻求帮助。更重要的是，在应用程序中加入适当的错误处理逻辑，例如记录错误日志、向用户显示友好的错误信息等，可以提高应用程序的健壮性和用户体验。

6. 速率限制

Upbit为了维护系统的稳定性和公平性，对API请求的频率进行了严格的限制，以防止恶意滥用和过度请求。这些速率限制旨在确保所有用户都能获得公平的API访问体验，并防止任何单个应用程序或用户过度消耗系统资源。

为了避免您的应用程序被速率限制，请务必仔细阅读Upbit API的官方文档，特别关注每个具体接口的速率限制说明。API文档会详细说明每个端点允许的每分钟、每秒或每天的请求数量。不同的API端点可能具有不同的速率限制策略，因此请务必针对您正在使用的特定接口进行核查。

开发者应当在应用程序中实施适当的错误处理机制，以应对速率限制错误。当您的应用程序遇到速率限制时，API通常会返回一个包含HTTP状态码（例如429 Too Many Requests）的错误响应，以及一个描述剩余重试时间的头部字段。您的应用程序应该能够检测到这些错误，并采取适当的措施，例如暂停发送请求一段时间，或者使用指数退避算法来逐渐减少请求频率，直到可以再次发送请求为止。

除了遵守官方文档中指定的速率限制外，开发者还应该遵循最佳实践，例如缓存API响应以减少不必要的请求，以及优化API请求的频率。通过仔细设计您的应用程序并遵循Upbit的速率限制策略，您可以确保您的应用程序能够可靠地访问Upbit API，而不会遇到中断或错误。

7. 安全建议

• 妥善保管 API 密钥： 绝对不要将您的 secret_key (私钥) 泄露给任何个人或实体。私钥是访问您的账户和执行操作的关键凭证，泄露会导致资金损失和其他安全风险。将其视为高度机密信息，像保护您的银行密码一样保护它。确保您的私钥存储在安全的地方，例如硬件钱包或加密的密钥管理器中。不要通过电子邮件、聊天消息或任何不安全的渠道共享您的私钥。
• 使用 IP 白名单： 通过配置 IP 白名单，可以严格限制只有来自预先批准的特定 IP 地址的请求才能访问您的 API 接口。这可以有效地防止未经授权的访问，即使攻击者获得了您的 API 密钥。考虑将您的服务器或应用程序的 IP 地址添加到白名单中。定期审查和更新您的 IP 白名单，以确保只有授权的 IP 地址可以访问您的 API。请注意，动态 IP 地址可能会影响 IP 白名单的有效性，因此请使用静态 IP 地址或动态 DNS 服务。
• 谨慎使用提币权限： 除非您对您的应用程序的安全性有充分的信心，否则强烈建议不要授予提币权限。提币权限允许应用程序从您的账户转移资金。如果您的应用程序受到攻击或存在漏洞，攻击者可能会利用提币权限窃取您的资金。如果您必须授予提币权限，请务必采取额外的安全措施，例如设置提币限额和实施多重身份验证。定期审计具有提币权限的应用程序，并监控其活动。
• 定期审查 API 权限： 养成定期检查您授予的 API 权限的习惯，并删除任何不再需要的权限。随着时间的推移，您可能已经授予了某些应用程序或服务超出其需求的权限。通过删除不必要的权限，您可以降低潜在的安全风险。例如，如果一个应用程序只需要读取您的账户余额，则不要授予它交易或提币权限。定期审查您的 API 密钥列表，并撤销任何不再使用或不再信任的密钥。
• 监控 API 调用： 持续监控您的应用程序的 API 调用情况，以便及时发现并响应任何异常或可疑行为。例如，如果您注意到来自未知 IP 地址的大量 API 调用，或者 API 调用模式与正常行为不符，则可能表明您的账户正在受到攻击。实施日志记录和警报机制，以便在发生异常事件时立即收到通知。分析 API 调用日志可以帮助您识别安全漏洞并改进您的安全策略。考虑使用安全信息和事件管理 (SIEM) 系统来集中监控和分析 API 调用数据。