Upbit API 使用指南：开启你的量化交易之旅
Upbit 作为韩国领先的加密货币交易所，凭借其强大的 API 接口，为开发者和量化交易者提供了便捷的自动化交易和数据获取途径。本文将深入探讨如何有效利用 Upbit API，构建属于你的自动化交易系统。
准备工作
在使用 Upbit API 之前，充分的准备工作至关重要，它将直接影响到你后续开发和交易的效率与安全。 以下是详细的准备步骤：
-
Upbit 账号与实名认证： 确保你已经注册并拥有一个 Upbit 账号。 访问 Upbit 官方网站，按照指引完成注册流程。 实名认证（KYC）是必须完成的步骤，它不仅能提升你的账户安全级别，也是使用某些高级 API 功能的前提条件，例如进行交易操作。未完成实名认证，你可能只能访问部分只读API，无法进行实际的资产管理和交易。
-
API 密钥的申请与管理： 登录你的 Upbit 账号后，找到“API 开放平台”、“Open API”或类似的入口。 Upbit 界面可能因版本更新而有所不同，但通常在“账户设置”、“安全设置”或“开发者中心”等区域可以找到。 进入 API 管理页面，你可以创建新的 API 密钥。 在创建过程中，务必仔细设置 API 密钥的权限。 一般来说，API 权限包括只读权限（查询账户信息、市场行情等）和交易权限（下单、撤单等）。 请务必根据你的实际需求，授予最小必要的权限。 如果你只需要获取市场数据，强烈建议只授予只读权限。 API 密钥的安全至关重要！ 就像你的银行卡密码一样，一旦泄露，可能导致资产损失。 请务必采取以下安全措施：
- 妥善保管： 将 API 密钥保存在安全的地方，不要以明文形式存储在代码中，避免上传到公共代码仓库（如 GitHub）。
- 定期更换： 定期更换 API 密钥，例如每月或每季度更换一次。
- 启用 IP 白名单： Upbit 提供了 IP 白名单功能，允许你限制只有来自特定 IP 地址的请求才能使用该 API 密钥。 强烈建议开启此功能，并将你的服务器 IP 地址添加到白名单中。 这可以有效防止 API 密钥被盗用。
- 监控 API 使用情况： 密切关注 API 的使用情况，如果发现异常请求或未经授权的访问，立即禁用该 API 密钥并采取相应的安全措施。
-
选择合适的编程环境： 根据你的编程经验和项目需求，选择合适的编程语言和开发环境。 Python 凭借其丰富的库和框架，成为量化交易和 API 开发的首选语言。以下是一些常用的 Python 库：
- requests： 用于发送 HTTP 请求，与 Upbit API 进行交互。
- pandas： 用于数据处理和分析，方便你对从 Upbit API 获取的数据进行清洗、转换和分析。
- ccxt： 一个统一的加密货币交易所 API 接口库，支持包括 Upbit 在内的众多交易所。 使用 ccxt 可以简化 API 交互，并方便你切换到其他交易所。
- NumPy： 用于科学计算，特别是处理大型数组和矩阵，在量化分析中非常有用。
- TA-Lib： 一个技术分析库，提供了各种技术指标的计算方法，例如移动平均线、相对强弱指数（RSI）等。
除了 Python，你也可以使用其他编程语言，例如 Java、JavaScript、Go 等。选择哪种语言取决于你的个人偏好和项目需求。 确保你的开发环境已经安装了必要的库和依赖项。
API 认证
Upbit API 采用基于 JWT (JSON Web Token) 的身份验证机制，确保通信安全。使用 API 之前，您必须生成一个有效的 JWT。生成 JWT 需要您的 API 访问密钥 (Access Key) 和密钥 (Secret Key)。请妥善保管您的 Secret Key，避免泄露。
以下 Python 代码示例展示了如何使用
jwt
库生成符合 Upbit API 要求的 JWT：
import jwt
import uuid
import hashlib
access_key = "您的 Access Key" # 替换为您的 Access Key
secret_key = "您的 Secret Key" # 替换为您的 Secret Key
def generate_jwt():
"""
生成用于 Upbit API 身份验证的 JWT。
"""
payload = {
'access_key': access_key,
'nonce': str(uuid.uuid4()), # 确保 nonce 的唯一性
}
jwt_token = jwt.encode(payload, secret_key, algorithm='HS256')
return jwt_token
jwt_token = generate_jwt()
print(jwt_token)
代码详解：
-
jwt：用于 JWT 编码和解码的标准 Python 库。 -
uuid：用于生成唯一 ID (Universally Unique Identifier)，这里用于生成nonce值。 -
access_key和secret_key：替换为您的 Upbit API 密钥。请务必妥善保管您的secret_key。 -
payload：包含需要进行签名的声明的 JSON 对象。对于 Upbit API，payload必须包含您的access_key和一个唯一的nonce。 -
nonce：一个随机数，用于防止重放攻击。每次生成 JWT 时，nonce值都必须是唯一的。uuid.uuid4()可以生成一个随机的 UUID 作为nonce。 -
jwt.encode(payload, secret_key, algorithm='HS256')：使用HS256算法和您的secret_key对payload进行签名，生成 JWT。HS256是一种常用的对称加密算法。
特别说明：
-
请确保已安装
jwt库。您可以使用pip install pyjwt命令安装。 - 为了提高安全性，建议定期更换您的 API 密钥。
生成的 JWT 必须添加到 HTTP 请求头的
Authorization
字段中，格式如下：
Authorization: Bearer <JWT>例如：
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJaccess_keyIjoibXlfYWNjZXNzX2tleSIsIm5vbmNlIjoiMTIzNDU2Nzg5MCJ9.signature
请将
<JWT>
替换为您实际生成的 JWT 字符串。 在发送API 请求时，请务必包含此头部信息，以便 Upbit 服务器验证您的身份。
常用 API 接口
Upbit API 提供全面的 RESTful 接口，便于开发者获取市场数据、执行交易、管理账户信息等。 这些接口遵循标准的 HTTP 请求方法，并以 JSON 格式返回数据。下面列出常用 API 接口，并详细说明其功能和使用方法：
-
市场行情：
-
GET /v1/market/all: 获取 Upbit 支持的所有交易市场信息。 返回的JSON数据包含交易市场代码 (market)， 例如 "KRW-BTC" 表示韩元-比特币交易对； 交易市场名称 (korean_name,english_name)， 提供韩语和英语两种语言的名称。 此接口无需身份验证。可以通过此接口动态获取所有可交易的币种列表。 -
GET /v1/candles/minutes/{unit}: 获取指定分钟周期的 K 线数据。unit参数指定 K 线的时间周期，可选项包括 1, 3, 5, 15, 30, 60 和 240 分钟。market查询参数用于指定交易市场， 例如market=KRW-BTC获取韩元-比特币交易对的 K 线数据。to参数指定查询的结束时间， 格式为 ISO 8601。count参数限制返回的数据条数， 默认为 1， 最大值为 200。 K 线数据包含开盘价、最高价、最低价、收盘价、成交量等信息。 -
GET /v1/candles/days: 获取日 K 线数据。 使用market,to, 和count参数的方式与分钟 K 线数据接口相同。 日 K 线数据对分析长期趋势非常有用。 该接口还支持convertingPriceUnit参数，用于指定计价货币单位。 -
GET /v1/ticker: 获取指定交易市场的当前价格信息。markets参数允许同时查询多个交易市场的信息， 例如markets=KRW-BTC,KRW-ETH同时查询韩元-比特币和韩元-以太坊的当前价格。 返回的数据包含当前价格、最高价、最低价、成交量等信息。 -
GET /v1/trades/ticks: 获取指定交易市场的最近成交记录。market参数指定交易市场。to参数指定查询的结束时间， 格式为 ISO 8601。count参数控制返回的成交记录数量， 默认为 1， 最大值为 200。 成交记录包含成交时间、成交价格、成交数量、买卖方向等信息。 该接口可以实时监控市场动态。
-
-
交易：
-
POST /v1/orders: 提交新的交易订单。 需要提供以下参数：market(交易市场，例如 "KRW-BTC"),side(买/卖方向， "bid" 表示买入， "ask" 表示卖出),volume(交易数量，对于市价卖单可以不指定),price(交易价格，仅限价单需要指定),ord_type(订单类型， "limit" 表示限价单， "price" 表示市价买单， "market" 表示市价卖单)。 高级订单类型包括 "stop_limit" (止损限价单) 和 "stop_market"(止损市价单)。 还可以指定identifier参数，用于标识订单，方便后续查询。 该接口需要身份验证，并且需要 API 密钥和 Secret 密钥。 -
GET /v1/order: 查询指定订单的详细信息。 需要提供订单的 UUID (Universally Unique Identifier)， 订单 UUID 在下单成功后返回。 返回的信息包括订单状态、订单类型、交易数量、交易价格、成交数量、剩余数量等。 订单状态可能包括 "wait" (等待成交), "done" (完全成交), "cancel" (已取消) 等。 -
DELETE /v1/order: 取消指定订单。 需要提供订单的 UUID。 只有未完全成交的订单才能取消。 取消成功后，会返回订单的 UUID 和订单状态。 -
GET /v1/orders/chance: 获取指定交易市场的下单可能性。market参数指定交易市场。 返回的信息包括账户余额、锁仓余额、平均购买价格、可下单数量、最小下单数量限制等。 在下单之前调用此接口，可以预先检查账户余额是否足够，避免下单失败。
-
-
账户：
-
GET /v1/accounts: 获取账户信息。 返回用户所有币种的余额信息， 包括可用余额 (balance) 和冻结余额 (locked)。 冻结余额通常是由于挂单未成交导致。 该接口需要身份验证。
-
代码示例 (Python)
以下是一个 Python 示例，演示如何从 Upbit 交易所获取比特币 (KRW-BTC) 的 1 分钟 K 线数据。此示例使用了 Upbit 开放的 API 接口，并展示了如何解析返回的 JSON 数据。
import requests
此行代码导入 Python 的
requests
库，该库允许你发送 HTTP 请求，例如从 API 获取数据。
def get_minute_candle(market="KRW-BTC", unit=1, count=200):
url = f"https://api.upbit.com/v1/candles/minutes/{unit}?market={market}&count={count}"
headers = {"Accept": "application/"}
response = requests.get(url, headers=headers)
这段代码定义了一个名为
get_minute_candle
的函数，用于获取指定交易对 (market) 的 K 线数据。
unit
参数指定 K 线的时间单位（这里是 1 分钟），
count
参数指定要获取的 K 线数量（默认为 200）。 函数构建 Upbit API 的 URL，并设置请求头
Accept
为
application/
，表明期望接收 JSON 格式的响应。 然后，它使用
requests.get()
方法向 API 发送 GET 请求。
if response.status_code == 200:
return response.()
else:
print(f"Error: {response.status_code} - {response.text}")
return None
此代码块检查 API 请求是否成功。如果
response.status_code
是 200 (OK)，则表示请求成功，函数使用
response.()
方法将响应内容解析为 JSON 格式并返回。如果请求失败，则打印错误信息（包含状态码和错误文本），并返回
None
。
data = get_minute_candle()
此行代码调用
get_minute_candle()
函数，并将返回的 K 线数据存储在
data
变量中。
if data:
for candle in data:
print(f"Open: {candle['opening_price']}, High: {candle['high_price']}, Low: {candle['low_price']}, Close: {candle['trade_price']}")
这段代码检查
data
变量是否包含有效数据。如果包含，则遍历 K 线数据，并打印每个 K 线的开盘价 (
opening_price
)、最高价 (
high_price
)、最低价 (
low_price
) 和收盘价 (
trade_price
)。
candle
变量是字典类型，可以通过键访问对应的值。
下单示例：
以下代码演示了如何使用 Upbit API 下达限价单。 此示例需要你的 Upbit API 访问密钥 (access key) 和安全密钥 (secret key)，请务必妥善保管你的密钥。
import requests
import uuid
import jwt
import hashlib
这些代码行导入必要的 Python 库。
uuid
用于生成唯一 ID，
jwt
用于生成 JSON Web Token (JWT)，
hashlib
用于哈希处理（虽然此示例中未使用）。
access_key = "你的 Access Key"
secret_key = "你的 Secret Key"
请替换
"你的 Access Key"
和
"你的 Secret Key"
为你的实际 Upbit API 密钥。请注意，直接在代码中硬编码密钥是不安全的，建议使用环境变量或配置文件来存储密钥。
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，用于身份验证。 JWT 的 payload 包含
access_key
和一个随机生成的
nonce
（一次性使用的随机数）。 使用你的
secret_key
和 HS256 算法对 payload 进行编码，生成 JWT。
def place_limit_order(market="KRW-BTC", side="bid", volume="0.0001", price="1000000", ord_type="limit"):
url = "https://api.upbit.com/v1/orders"
jwt_token = generate_jwt()
headers = {"Authorization": f"Bearer {jwt_token}"}
data = {
"market": market,
"side": side,
"volume": volume,
"price": price,
"ord_type": ord_type
}
response = requests.post(url, headers=headers, =data)
此函数用于下达限价单。
market
参数指定交易对，
side
参数指定买卖方向（
"bid"
表示买入，
"ask"
表示卖出），
volume
参数指定数量，
price
参数指定价格，
ord_type
参数指定订单类型（
"limit"
表示限价单）。 函数首先调用
generate_jwt()
函数生成 JWT，然后构建包含 JWT 的 Authorization header。 然后，它构造包含订单信息的 JSON payload，并使用
requests.post()
方法向 Upbit API 的
/v1/orders
接口发送 POST 请求。 注意，这里使用了
=data
而不是
data=data
，确保数据以 JSON 格式发送。
if response.status_code == 201:
return response.()
else:
print(f"Error: {response.status_code} - {response.text}")
return None
此代码块检查 API 请求是否成功。 如果
response.status_code
是 201 (Created)，则表示订单已成功创建，函数使用
response.()
方法将响应内容解析为 JSON 格式并返回。 如果请求失败，则打印错误信息（包含状态码和错误文本），并返回
None
。
order_result = place_limit_order()
此行代码调用
place_limit_order()
函数，并将返回的订单结果存储在
order_result
变量中。
if order_result:
print(f"Order placed successfully. Order UUID: {order_result['uuid']}")
这段代码检查
order_result
变量是否包含有效数据。 如果包含，则打印订单已成功下单的消息，并打印订单的 UUID (
uuid
)，UUID 是订单的唯一标识符。
错误处理
Upbit API 接口在与客户端交互过程中，可能会由于多种原因返回不同类型的错误代码。为了确保应用程序的稳定性和可靠性，务必在代码中实现完善的错误处理机制，针对不同的错误代码采取相应的应对措施。以下列出一些常见的错误类型及其详细说明：
-
400 Bad Request (错误请求):
此错误表明客户端发送的请求格式不正确或者缺少必要的参数。具体原因可能包括：
- 请求参数的类型不符合API文档的要求。
- 缺少必要的请求参数。
- 请求参数的值不在允许的范围内。
- 请求体（request body）的格式不正确，例如JSON格式错误。
-
401 Unauthorized (未授权):
此错误表示客户端未通过身份验证，通常是由于以下原因：
- API 密钥 (API Key) 或 Secret 密钥 (Secret Key) 不正确。请仔细核对您的密钥信息，确保正确无误。
- 用于身份验证的 JWT (JSON Web Token) 生成不正确或已过期。重新生成有效的 JWT 并确保其包含正确的声明（claims）。
-
请求头中缺少必要的身份验证信息，例如
Authorization头。 - 您尝试访问的API端点需要更高的权限，而当前使用的API密钥不具备相应的权限。
Authorization信息。 -
429 Too Many Requests (请求过多):
此错误表示客户端在短时间内发送了过多的请求，超过了 Upbit API 的请求频率限制 (Rate Limit)。为了保护服务器资源，Upbit API 会对请求频率进行限制。
- 在指定的时间窗口内发送了超出限制数量的请求。
-
没有正确地处理 Upbit API 返回的
Retry-After响应头，该响应头指示了在再次发送请求之前需要等待的时间。
Retry-After响应头，在再次发送请求之前等待指定的时间。 -
500 Internal Server Error (服务器内部错误):
此错误表示 Upbit 服务器在处理请求时遇到了内部错误。这通常是由于服务器端的代码错误、数据库连接问题或其他未知的服务器故障引起的。
- 服务器端的代码存在缺陷，导致请求处理失败。
- 服务器无法连接到数据库或数据库出现故障。
- 服务器资源耗尽，例如内存不足或 CPU 占用率过高。
进阶技巧
- 使用 Websocket API: Upbit 提供了 Websocket API，用于实时推送市场数据，包括最新成交价、深度行情等。与传统的 REST API 相比，Websocket API 通过建立持久连接，显著降低数据延迟，实现毫秒级的实时更新，这对于高频交易策略至关重要。通过订阅特定的市场频道，可以仅接收所需数据，减少带宽占用和处理负担。同时，需要关注Upbit Websocket API的连接限制和消息频率限制，合理设计程序逻辑，避免被断开连接。
- 使用 ccxt 库: ccxt (CryptoCurrency eXchange Trading Library) 是一个强大的加密货币交易所 API 集成库，它封装了与众多交易所（包括 Upbit）进行交互的复杂性。使用 ccxt 库，可以通过统一的接口访问Upbit的各种功能，如获取市场数据、下单、查询账户余额等。这极大地简化了代码编写，提高了开发效率，并且便于将交易策略移植到其他交易所。ccxt 还处理了不同交易所API的认证、请求格式和错误处理等差异，降低了开发难度。使用前请仔细阅读ccxt的官方文档，了解各个接口的使用方法和参数说明。
- 回测你的策略: 在部署任何量化交易策略到真实市场之前，必须使用历史市场数据进行充分的回测。回测能够模拟策略在过去一段时间内的表现，帮助评估其盈利能力、风险水平和稳定性。选择具有代表性的历史数据，例如不同市场周期（牛市、熊市、震荡市）的数据，以检验策略在不同市场环境下的适应性。除了简单的盈亏分析，还应关注最大回撤、夏普比率等风险指标。回测结果仅供参考，不能保证未来收益，但它可以帮助发现策略的潜在问题，并进行优化。常见的量化回测平台包括Backtrader、Zipline等。
请注意，量化交易涉及固有风险。在进行实盘交易之前，务必全面深入地理解市场动态和Upbit交易规则，严谨评估个人的风险承受能力，并制定完善的风险管理策略，例如设置止损点、控制仓位大小等。时刻关注市场变化，并根据实际情况调整交易策略。
