Upbit API 调用教程：从入门到精通
准备工作：账户与API Key
在开始使用 Upbit API 之前，一个有效的 Upbit 账户和与之关联的 API Key 是必不可少的。账户注册是一个标准流程，涉及提供必要的个人信息并完成验证步骤，此处不再详细描述。获得 API Key 的详细步骤如下：
- 登录 Upbit 网站: 使用你的 Upbit 账户凭据，包括用户名和密码，登录 Upbit 官方网站。确保访问的是官方网站以避免钓鱼攻击。
- 进入 API 管理页面: 成功登录后，在用户菜单或账户设置中查找 “Open API 관리” (Open API Management) 选项。这个选项通常位于个人资料或安全设置相关的部分。点击该选项进入 API Key 管理页面。
- 创建 API Key: 在 API Key 管理页面，你需要创建一个新的 API Key。 填写 API 名称（例如 “MyTradingBot” 或 “TradingStrategy1”），这有助于你区分不同的 API Key 用途。 接下来，仔细选择所需的权限。 如果你的目的是进行交易操作，必须开启 “Trade” (交易) 权限，这将允许你的应用程序执行买入和卖出操作。 强烈建议不要开启“Withdrawal” (提现) 权限 ，这是一个重要的安全措施。 即使你的应用程序被入侵，攻击者也无法提取你的资金。 仔细阅读并理解 Upbit 的 API 使用条款和条件，确认你理解并同意这些条款后，点击 “확인” (Confirm) 按钮。
- 获取 API Key 与 Secret Key: 成功创建 API Key 后，系统将生成 API Key 和 Secret Key。 务必采取一切必要措施妥善保管你的 Secret Key，切勿将其泄露给任何第三方。 API Key 用于标识你的应用程序，而 Secret Key 则用于生成数字签名，确保你的 API 请求的真实性和完整性。 如果 Secret Key 泄露，任何拥有它的人都可以伪造你的请求，执行未经授权的操作，从而导致严重的财务损失。 将 Secret Key 存储在安全的地方，例如加密的配置文件或硬件安全模块（HSM）。 考虑使用环境变量来存储 Secret Key，避免将其直接硬编码到你的应用程序中。 定期轮换 API Key 和 Secret Key 是一种良好的安全实践，可以降低密钥泄露的风险。
环境配置：Python 与必要的库
本教程采用 Python 作为示例编程语言，详细阐述如何通过 Python 代码与 Upbit API 进行交互。为确保教程中的代码能够顺利执行，您需要预先安装 Python 3.6 或更高版本。同时，还需要安装以下几个关键的 Python 库，这些库将为 API 调用提供必要的功能支持：
- requests: 这是一个功能强大且易于使用的 HTTP 库，它允许 Python 程序向服务器发送各种类型的 HTTP 请求，例如 GET、POST、PUT、DELETE 等。在本教程中，`requests` 库将用于向 Upbit API 发送请求，并接收 API 返回的数据。
- uuid: 该库用于生成通用唯一标识符 (UUID)。在某些 Upbit API 的调用过程中，可能需要提供一个唯一的 ID 作为请求参数，`uuid` 库可以方便地生成这种唯一 ID。
- hashlib: 此库提供了多种哈希算法的实现，包括 SHA512。Upbit API 的某些接口可能要求对请求参数进行哈希处理，以确保数据的完整性和安全性。`hashlib` 库中的 SHA512 算法将用于计算哈希值。
- jwt: 即 JSON Web Token 库，用于生成符合 JWT 标准的令牌。为了进行身份验证和授权，Upbit API 通常需要客户端提供 JWT 令牌。`jwt` 库允许您使用私钥对声明进行签名，生成有效的 JWT 令牌。
为了方便起见，您可以使用 Python 的包管理工具 pip 来安装上述所有必需的库。只需在命令行终端中执行以下命令即可完成安装：
bash
pip install requests uuid hashlib pyjwt
执行上述命令后，pip 将会自动从 Python Package Index (PyPI) 下载并安装 `requests`、`uuid`、`hashlib` 和 `pyjwt` 库及其依赖项。安装完成后，您就可以在 Python 代码中导入这些库，并开始使用 Upbit API 了。
API 调用：获取 Upbit 市场代码
Upbit API 采用 RESTful 架构，通过标准的 HTTP 请求进行数据交互。通过发送特定格式的 HTTP 请求，可以获取包括市场代码在内的各种市场数据。 获取 Upbit 支持的所有交易市场代码是使用 API 的第一步。
以下 Python 代码展示了如何通过
requests
库向 Upbit API 发送请求，获取市场代码列表：
import requests
url = "https://api.upbit.com/v1/market/all"
querystring = {"isDetails":"false"}
response = requests.request("GET", url, params=querystring)
print(response.text)
这段代码使用 Python 的
requests
库构造并发送一个 GET 请求到
https://api.upbit.com/v1/market/all
这个 Upbit API 的端点。查询字符串
{"isDetails":"false"}
被添加到 URL 中，作为参数传递给 API。
参数
isDetails=false
用于指定 API 只返回简要的市场代码信息，包括市场代码 (market) 和市场名称 (korean_name, english_name)，而不包含交易市场更详细的元数据，比如支持的交易类型或交易费用等信息。 省略此参数或将其设置为
true
将返回包含更详细信息的市场数据结构。
response = requests.request("GET", url, params=querystring)
执行实际的 HTTP GET 请求，并将服务器的响应存储在
response
对象中。
response.text
包含了服务器返回的原始 JSON 字符串。 你需要使用 Python 的
模块将其解析为 Python 字典或列表，以便进一步处理和使用，例如：
import
market_data = .loads(response.text)
print(market_data)
解析后的
market_data
变量将包含一个 Python 列表，其中每个元素代表一个交易市场，包含了该市场的代码和名称等信息。 例如，你可以通过遍历这个列表来获取所有市场的代码：
for market in market_data:
print(market['market'])
API 调用：获取账户信息
本节演示如何通过API调用获取账户信息。访问Upbit API需要身份验证，此过程依赖于您的 API Key 和 Secret Key。请务必妥善保管您的密钥信息。
import jwt
import uuid
import hashlib
import requests
access_key = "YOUR_ACCESS_KEY" # 替换成你的 Access Key
secret_key = "YOUR_SECRET_KEY" # 替换成你的 Secret Key
请将
YOUR_ACCESS_KEY
和
YOUR_SECRET_KEY
替换为您在Upbit平台申请到的真实密钥。Access Key 用于标识您的身份，Secret Key 用于生成签名，验证请求的完整性。
payload = {
"access_key": access_key,
"nonce": str(uuid.uuid4())
}
payload
字典包含了构建JWT（JSON Web Token）所需的信息。
access_key
字段是您的API访问密钥。
nonce
字段是一个随机生成的唯一字符串，用于防止重放攻击，确保每次请求的唯一性。 使用
uuid.uuid4()
函数生成一个UUID，并将其转换为字符串类型。
jwt_token = jwt.encode(payload, secret_key, algorithm="HS256")
authorize_token = f"Bearer {jwt_token}"
使用
jwt.encode()
函数对
payload
进行签名，生成 JWT Token。该函数接收三个参数：
payload
（包含数据的字典）、
secret_key
（您的Secret Key）和
algorithm
（加密算法）。 这里使用的算法是
HS256
，即 HMAC-SHA256。生成的
jwt_token
将作为身份验证的凭证。
authorize_token
变量将JWT token格式化为 "Bearer " + jwt_token，符合HTTP Authorization Header的规范。
headers = {"Authorization": authorize_token}
创建 HTTP 请求头
headers
，并将
Authorization
字段设置为
authorize_token
。该字段告知服务器，客户端正在使用 Bearer Token 认证方式，并将 JWT Token 传递给服务器进行验证。
url = "https://api.upbit.com/v1/accounts"
定义API请求的URL。
https://api.upbit.com/v1/accounts
是Upbit API的账户信息接口地址，用于获取用户的账户余额等信息。
response = requests.get(url, headers=headers)
使用
requests.get()
函数发送GET请求到指定的URL，并将包含身份验证信息的
headers
传递给服务器。
response
对象包含了服务器返回的响应数据，包括状态码、响应头和响应内容。
print(response.text)
打印服务器返回的响应内容。
response.text
属性包含了服务器返回的文本数据，通常是JSON格式的账户信息。您可以解析此JSON数据，提取所需的账户信息，如账户余额、币种等。
这段代码演示了如何使用 API Key 和 Secret Key 通过 JWT (JSON Web Token) 认证机制安全地访问 Upbit API。
payload
构造了包含
access_key
和
nonce
（随机数）的认证信息。
nonce
通过确保每个请求的唯一性，有效防御重放攻击。
jwt.encode()
函数利用 HS256 算法对
payload
进行签名，生成 JWT Token，保障数据的完整性和真实性。随后，JWT Token 被置于 HTTP 请求头的
Authorization
字段中，并向
https://api.upbit.com/v1/accounts
发送 GET 请求。 Upbit 服务器接收到请求后，会对 JWT Token 的合法性进行严格校验。 验证通过后，服务器将返回与该 API Key 关联的账户信息，允许用户安全地获取其账户详情。
API 调用：下单交易
下单交易的API调用过程，同样需要使用 API Key 和 Secret Key 进行身份验证，以确保交易请求的合法性和安全性。
import jwt
import uuid
import hashlib
import requests
import time
access_key = "YOUR_ACCESS_KEY" # 替换成你的 Access Key
请将
YOUR_ACCESS_KEY
替换为你实际的 Upbit 账户 Access Key。Access Key 用于标识你的账户，务必妥善保管。
secret_key = "YOUR_SECRET_KEY" # 替换成你的 Secret Key
同样，需要将
YOUR_SECRET_KEY
替换为你实际的 Secret Key。Secret Key 用于对请求进行签名，确保请求的完整性和真实性，切勿泄露。
market = "KRW-BTC" # 市场代码，例如 KRW-BTC (韩元交易比特币)
market
变量定义了交易的市场。
KRW-BTC
表示韩元（KRW）交易比特币（BTC）。其他市场代码也有效，例如
BTC-ETH
(比特币交易以太坊)，具体取决于交易所支持的交易对。
side = "bid" # 交易类型，buy (买入) 或 sell (卖出)
side
变量指定交易的方向。
"bid"
代表买入，也可用
"ask"
代表卖出。请根据实际的交易意图设置此变量。
volume = "0.0001" # 交易数量
volume
变量定义了交易的数量。单位取决于所交易的市场，例如在
KRW-BTC
市场，单位为 BTC。需要根据实际需求设置交易数量。
price = "100000" # 交易价格
price
变量指定了交易的价格。此价格仅在限价单 (
limit
) 中有效。单位取决于所交易的市场，例如在
KRW-BTC
市场，单位为 KRW。
order_type = "limit" # 订单类型，limit (限价单) 或 market (市价单)
order_type
变量定义了订单的类型。
"limit"
表示限价单，即以指定的价格进行交易。
"market"
表示市价单，即以当前市场最优价格进行交易。选择合适的订单类型至关重要，特别是对于时间敏感的交易。
query = {
"market": market,
"side": side,
"volume": volume,
"price": price,
"ord_type": order_type
}
query
字典包含了所有订单相关的参数，这些参数会被用于生成请求的签名，确保请求未被篡改。
query_string = "&".join([f"{k}={v}" for k, v in query.items()]).encode()
这行代码将
query
字典转换为 URL 编码的字符串。例如，如果
query
字典是
{"market": "KRW-BTC", "side": "bid", "volume": "0.0001", "price": "100000", "ord_type": "limit"}
, 那么
query_string
将会是
"market=KRW-BTC&side=bid&volume=0.0001&price=100000&ord_type=limit"
. 编码是为了后续计算哈希值做准备。
m = hashlib.sha512()
m.update(query_string)
query_hash = m.hexdigest()
这段代码使用 SHA512 算法计算
query_string
的哈希值。哈希值用于验证请求的完整性，防止中间人攻击。 SHA512 是一种安全的哈希算法，能生成唯一的哈希值。
payload = {
"access_key": access_key,
"nonce": str(uuid.uuid4()),
"query_hash": query_hash,
"query_hash_alg": "SHA512",
}
payload
字典包含了用于生成 JWT (JSON Web Token) 的信息。
access_key
用于标识用户，
nonce
是一个随机的 UUID，用于防止重放攻击。
query_hash
是订单参数的哈希值，
query_hash_alg
指定了哈希算法。
jwt_token = jwt.encode(payload, secret_key, algorithm="HS256")
authorize_token = f"Bearer {jwt_token}"
这段代码使用
secret_key
对
payload
进行签名，生成 JWT Token。 JWT Token 是一种安全的身份验证方式。 然后，将 JWT Token 添加到
Bearer
头部，用于授权 API 请求。
headers = {"Authorization": authorize_token}
headers
字典包含了 HTTP 请求的头部信息。
Authorization
头部包含了 JWT Token，用于身份验证。
url = "https://api.upbit.com/v1/orders"
url
变量定义了 Upbit API 的 endpoint，用于下单交易。 请确保使用正确的 API endpoint。
data = query
data
变量包含了订单的详细信息，将会以POST请求发送到Upbit服务器。
response = requests.post(url, headers=headers, data=data)
这行代码发送 POST 请求到 Upbit API。
url
是 API endpoint，
headers
包含了身份验证信息，
data
包含了订单信息。
requests.post
函数会发送 POST 请求并返回响应。
print(response.text)
这行代码打印 API 响应的内容。 API 响应通常是 JSON 格式，包含了订单的状态信息，例如订单 ID，订单状态等。 通过分析 API 响应，可以判断订单是否成功提交。
上述代码流程：构造包含订单信息的
query
字典，其中
market
指定交易市场，
side
指定交易方向（买入或卖出），
volume
指定交易数量，
price
指定交易价格，
ord_type
指定订单类型（限价单或市价单）。 随后，将
query
字典转换为 URL 编码的字符串，并计算其 SHA512 哈希值，以确保数据的完整性。 将哈希值添加到
payload
中，并利用 Access Key 和 Secret Key 生成 JWT Token，用于身份验证和授权。 构建包含授权信息的头部，发送 POST 请求到
https://api.upbit.com/v1/orders
API 端点，并将订单信息作为请求体发送，从而完成下单交易的请求。
query_hash 和 query_hash_alg。 query_hash 是订单参数的 SHA512 哈希值，query_hash_alg 指定哈希算法为 SHA512。 这样做是为了防止订单参数被篡改。 此外，由于Upbit 服务器时间可能存在偏差，建议在生成payload之前添加一个短暂的延时，例如 time.sleep(0.1)，这有助于避免因时间戳验证失败而导致的错误。
错误处理
在使用 Upbit API 的过程中，开发者可能会遇到各种类型的错误。这些错误通常指示请求存在问题或服务器端出现状况，妥善处理这些错误对于构建稳定可靠的应用程序至关重要。
- 400 Bad Request: 此错误表明客户端发送的请求存在问题。通常是由于请求参数无效、缺失或格式不正确引起的。例如，如果API要求特定的日期格式，而客户端提供了错误的格式，就会返回此错误。详细检查请求体、查询参数以及请求头，确保所有数据符合API的规范。
- 401 Unauthorized: 此错误表示客户端未通过身份验证。这通常是因为API密钥无效、过期或未在请求中正确提供。检查API密钥是否正确配置，并且已正确包含在请求头中。确保API密钥具有访问请求资源的必要权限。如果使用JWT (JSON Web Token) 进行身份验证，请确保token有效且未过期。
- 429 Too Many Requests: 此错误表明客户端在短时间内发送了过多的请求，超过了Upbit API的频率限制。为了保护服务器免受滥用，Upbit实施了请求频率限制。当遇到此错误时，客户端应该暂停发送请求，并在一段时间后重试。使用指数退避算法（Exponential Backoff）是一种常见的处理方式，即每次重试之间的时间间隔逐渐增加，以避免再次触发频率限制。 建议阅读Upbit API的官方文档，了解具体的频率限制策略。
当Upbit API返回错误时，错误响应通常包含一个错误代码和一条描述错误的错误信息。开发者应该根据这些信息来诊断和解决问题。例如，如果遇到 429 错误，应该实施重试机制，并根据API文档中规定的速率限制进行调整，避免再次触发限制。对于400和401错误，则需要仔细检查请求参数和身份验证信息，确保其正确无误。除了上述错误代码之外，还可能遇到其他HTTP状态码，例如500 Internal Server Error (服务器内部错误) 和 503 Service Unavailable (服务不可用)。遇到这些错误时，通常建议稍后重试，因为它们可能是临时的服务器端问题。
API 文档
完整的 Upbit API 文档可在 Upbit 官方网站上查阅。该文档提供了关于 Upbit 平台所有可用 API 接口的全面信息，是开发者集成 Upbit 服务至关重要的资源。
文档详细描述了每个 API 端点的功能，包括其用途、允许执行的操作以及预期的行为。 每个 API 的参数都进行了精确的定义，涵盖了数据类型、必需性、有效值范围以及示例值。 文档还阐明了每个 API 调用返回的数据结构，包括响应格式、数据类型以及可能出现的错误代码。
我们强烈建议开发者在使用 Upbit API 之前，仔细阅读并理解官方文档。 熟悉文档能帮助开发者避免常见的错误，优化 API 调用，并充分利用 Upbit 提供的各种功能。 通过遵循文档中的指南，开发者可以高效、安全地将 Upbit 集成到他们的应用程序和系统中。
Upbit API 文档通常包括以下关键信息：
- 身份验证： 关于如何通过 API 密钥进行身份验证，以及如何安全地管理和保护您的密钥。
- 请求方法： 每个 API 端点支持的 HTTP 请求方法 (例如 GET, POST, PUT, DELETE)。
- 请求参数： 每个 API 端点接受的参数，包括参数名称、数据类型、是否必需，以及参数的有效值范围。
- 响应格式： API 返回的数据格式 (通常为 JSON)，以及每个字段的含义和数据类型。
- 错误代码： API 调用可能返回的错误代码，以及每个错误代码的含义和建议的解决方法。
- 速率限制： API 的速率限制，以及如何避免超出限制。
- 示例代码： 使用不同编程语言（如 Python、JavaScript）调用 API 的示例代码。
定期查阅 Upbit API 文档的更新也很重要，以便及时了解新的 API 功能、参数变更或安全更新。 遵循最佳实践和安全建议，能确保您的 Upbit API 集成安全可靠。
安全建议
- API Key 和 Secret Key 的安全至关重要，切勿泄露给任何第三方。 API Key 和 Secret Key 是访问您 Upbit 账户的凭证，拥有这些密钥的人可以执行交易、查询信息，甚至可能转移您的资金。请像保护您的银行密码一样保护它们。不要在公共场所、不安全的网络或任何可能被监控的环境中使用或存储这些密钥。避免通过电子邮件、聊天工具或任何不安全的渠道传输这些信息。
- 强烈建议禁用 API Key 的“Withdrawal”（提现）权限。 即使 API Key 泄露，禁用提现权限也能有效防止资金被盗。仅在绝对必要时才开启提现权限，并在完成相关操作后立即禁用。仔细评估您是否真的需要通过 API 进行提现操作，大多数交易策略并不需要此权限。
- 通过 IP 地址限制 API Key 的访问范围，增强安全性。 限制 API Key 只能从特定的 IP 地址访问，可以有效防止未经授权的访问。只允许您的服务器或个人电脑的 IP 地址访问 API。如果您使用动态 IP 地址，请考虑使用允许 IP 地址范围的配置选项，或者定期更新 IP 地址列表。
- 定期轮换 API Key 和 Secret Key 是一个良好的安全习惯。 即使您没有发现任何可疑活动，也应该定期更换 API Key 和 Secret Key。这可以降低密钥泄露的风险，并限制潜在攻击者利用旧密钥造成的损害。建议至少每三个月更换一次密钥，或者在任何安全事件发生后立即更换。
- 密切监控您的 Upbit 账户活动，以便及时发现并应对任何异常情况。 定期检查您的交易历史、订单记录和账户余额，确保所有操作都是您授权的。设置价格提醒和交易通知，以便在发生异常交易或价格波动时立即收到通知。如果发现任何可疑活动，请立即联系 Upbit 客服并撤销相关的 API Key。
这篇教程旨在帮助您初步了解 Upbit API 的使用方法。安全始终是第一要务，请务必牢记上述建议，并采取必要的安全措施来保护您的账户。