Upbit API调用教程：量化交易入门指南
Upbit API 调用教程：开启量化交易之门
Upbit 作为韩国领先的加密货币交易所之一，为开发者提供了强大的 API 接口，方便构建自动化交易程序、数据分析工具等。本文将深入探讨 Upbit API 的调用方法，助你踏入量化交易的世界。
1. 准备工作：API 密钥的获取与认证
使用 Upbit API 的首要步骤，也是至关重要的一环，是获取并妥善配置 API 密钥。这不仅是访问 Upbit 平台数据和执行交易的前提，更是保障账户安全的关键。你需要访问 Upbit 官方网站，使用你的账户凭据进行安全登录，随后导航至 API 管理页面。在此页面，你可以创建新的 API 密钥，并为其设置适当的权限。务必仔细阅读并理解每个权限的含义，仅授予 API 密钥所需的最少权限，以降低潜在的安全风险。API 密钥通常包含一个访问密钥（Access Key）和一个安全密钥（Secret Key）。访问密钥用于标识你的账户，而安全密钥则用于对 API 请求进行签名，以验证请求的来源。请务必妥善保管你的安全密钥，切勿将其泄露给他人，也不要将其存储在不安全的地方。一旦 API 密钥创建完成，你需要将其配置到你的应用程序或脚本中，以便能够通过 API 与 Upbit 平台进行交互。API 密钥的认证过程通常涉及到使用安全密钥对 API 请求进行签名，Upbit 平台会验证签名的有效性，以确认请求的合法性。
重要提示： 为了保障资金安全，强烈建议只授予 API 密钥只读权限，除非你的交易策略需要程序自动下单。 在创建 API 密钥时，请务必设置 IP 白名单，只允许指定的 IP 地址访问 API，以防止密钥泄露带来的风险。创建 API 密钥后，你将获得 Access Key 和 Secret Key。请妥善保管这些密钥，切勿泄露给他人。
2. API 认证原理：HMAC SHA512 签名
Upbit API 采用 HMAC SHA512 算法对请求进行签名认证，这是一种消息认证码（MAC）算法，利用哈希函数和密钥来验证消息的完整性和真实性，从而有效确保 API 请求的安全性，防止篡改和伪造。它基于共享密钥机制，只有拥有正确密钥的客户端才能生成有效的签名。
HMAC (Hash-based Message Authentication Code) 结合了密钥和消息本身来生成哈希值，使其比仅使用哈希更安全。 SHA512 则是安全散列算法（Secure Hash Algorithm）家族中的一员，提供 512 位的哈希输出，提供高强度的安全性。
-
构建待签名字符串:
这一步的目的是将所有影响请求的参数整理成一个标准化的字符串，以便后续的签名过程能产生一致的结果。 将请求参数按照字母顺序排序，这是为了确保即使参数的顺序不同，最终生成的签名也是相同的，防止因为参数顺序变化导致的签名验证失败。然后将参数名和参数值用等号连接，形成键值对，再用
&符号连接所有参数，形成一个长字符串。 例如，对于参数market=KRW-BTC和count=10，待签名字符串为count=10&market=KRW-BTC。对于包含数组或复杂对象的参数，需要将其序列化为字符串形式。如果请求体是 JSON 格式，则直接将整个 JSON 字符串作为待签名字符串，注意要保持JSON字符串的原始格式，包括空格和换行符。 -
使用 Secret Key 进行 HMAC SHA512 加密:
这一步使用你的
Secret Key作为密钥，这密钥应妥善保管，切勿泄露。 使用Secret Key对待签名字符串进行 HMAC SHA512 加密，生成一个固定长度的哈希值，该哈希值是请求的数字签名。Secret Key和待签名字符串的结合使用，使得只有拥有Secret Key的人才能生成正确的签名，从而保证了请求的真实性。 HMAC SHA512 算法确保了即使修改了请求中的任何部分（包括参数），生成的哈希值也会完全不同，从而使得篡改变得不可行。 -
将哈希值进行 Base64 编码:
将加密后的哈希值（通常是二进制数据）进行 Base64 编码。 Base64 编码将二进制数据转换为 ASCII 字符串，使其能够在 HTTP 请求头中安全传输。 得到最终的签名字符串后，将其添加到 HTTP 请求头中，通常以
Authorization字段的形式传递，Upbit 服务器会使用相同的算法和你的Secret Key验证签名，以确认请求的合法性。
3. 常用 API 接口详解：行情查询、交易下单
Upbit API 提供了强大的功能，涵盖了市场数据的实时获取、交易指令的执行以及账户信息的全面管理。它允许开发者构建自动交易机器人、行情分析工具和用户友好的交易界面。以下将详细介绍几个常用的 API 接口，助您快速上手：
3.1 行情查询 API
行情查询 API 允许您获取各种交易对的实时市场数据，包括当前价格、成交量、最高价、最低价等关键指标。您可以使用这些数据进行市场分析、制定交易策略和监控市场动态。
-
获取所有市场代码：
此接口用于检索 Upbit 上所有可交易的市场代码，例如
KRW-BTC（韩元-比特币）。 -
获取市场行情：
通过指定市场代码，您可以获取该市场的实时行情信息，包括当前价格 (
trade_price)、最高价 (high_price)、最低价 (low_price)、成交量 (trade_volume) 等。 - 获取最近成交记录： 您可以查询指定市场最近发生的成交记录，包括成交时间、成交价格、成交量等。
3.2 交易下单 API
交易下单 API 允许您在 Upbit 交易所执行买入或卖出订单。您可以通过 API 指定交易对、订单类型、价格和数量，实现自动化交易。
-
下单：
此接口用于提交买入或卖出订单。您需要指定市场代码 (
market)、订单类型 (side，bid为买入，ask为卖出)、订单类型 (ord_type，例如limit为限价单，market为市价单)、价格 (price，仅限价单需要) 和数量 (volume)。 - 取消订单： 如果您需要取消已提交的订单，可以使用此接口。您需要提供订单的 UUID。
3.3 账户信息查询 API
账户信息查询 API 允许您获取您的 Upbit 账户余额、交易历史和已成交订单等信息。这有助于您监控您的交易活动和管理您的资产。
- 获取账户信息： 此接口返回您的账户余额信息，包括各种币种的可用余额和锁定余额。
- 获取交易历史： 您可以查询您的交易历史记录，包括已成交的订单和未成交的订单。
3.1. 行情查询：获取最新成交价
在加密货币交易中，实时获取最新成交价是至关重要的。该接口允许开发者和用户查询指定市场的最新行情信息，为交易决策提供数据支持。
-
接口:
GET /v1/ticker - 描述: 该接口用于获取指定加密货币交易对的实时行情数据，包括但不限于最新成交价格、成交量、最高价、最低价等信息。 对于需要快速响应和实时数据的应用场景，该接口是理想选择。
-
参数:
-
markets(required): 这是一个必选参数，用于指定需要查询的市场代码。市场代码通常由交易对的两个币种代码组成，例如KRW-BTC,KRW-ETH。多个市场代码之间使用逗号分隔。例如，要同时查询韩元-比特币（KRW-BTC）和韩元-以太坊（KRW-ETH）的行情，则参数应设置为KRW-BTC,KRW-ETH。 注意，不同交易所的市场代码命名规则可能有所不同，需要根据具体交易所的API文档进行调整。 如果 markets 参数无效，API 将返回错误信息。
-
-
返回值:
该接口返回 JSON (JavaScript Object Notation) 格式的数据，包含所请求市场的详细行情信息。 JSON 格式是一种轻量级的数据交换格式，易于解析和处理。返回值中通常包含以下字段：
-
market: 市场代码，例如KRW-BTC。 -
trade_date: 最新成交日期，格式通常为 YYYYMMDD。 -
trade_time: 最新成交时间，格式通常为 HHMMSS。 -
trade_price: 最新成交价格。 -
trade_volume: 最新成交量。 -
high_price: 当日最高成交价。 -
low_price: 当日最低成交价。 -
prev_closing_price: 前一日收盘价。 -
change: 价格变动方向 (例如 "RISE", "FALL", "EVEN")。 -
change_price: 价格变动金额。 -
change_rate: 价格变动百分比。 -
signed_change_price: 含符号的价格变动金额，上涨为正数，下跌为负数。 -
signed_change_rate: 含符号的价格变动百分比，上涨为正数，下跌为负数。 -
ask_bid: 卖单/买单状态。 -
timestamp: 时间戳，通常为 Unix 时间戳。
-
示例代码 (Python):
本示例展示了如何使用Python与Upbit交易所的API进行交互，获取指定交易对的Ticker信息。代码使用了requests库发送HTTP请求，hashlib库进行哈希运算，base64库进行编码，jwt库生成JSON Web Token (JWT)，以及uuid库生成唯一ID。
import requests
import hashlib
import base64
import jwt
import uuid
导入必要的Python库。
requests
用于发送HTTP请求，
hashlib
用于计算SHA512哈希值，
jwt
用于创建和编码JWT，
uuid
用于生成唯一的nonce值。
access_key = "YOUR_ACCESS_KEY"
secret_key = "YOUR_SECRET_KEY"
请替换
YOUR_ACCESS_KEY
和
YOUR_SECRET_KEY
为您的Upbit API密钥。这两个密钥用于身份验证和授权。
def get_ticker(markets):
query = f"markets={markets}"
query_hash = hashlib.sha512(query.encode('utf-8')).hexdigest()
定义一个名为
get_ticker
的函数，该函数接受一个名为
markets
的参数，该参数指定要查询的交易对。 函数首先构建查询字符串，并使用SHA512算法对查询字符串进行哈希处理。
query.encode('utf-8')
确保查询字符串使用UTF-8编码后再进行哈希运算，避免编码问题导致哈希值不一致。
payload = {
'access_key': access_key,
'nonce': str(uuid.uuid4()),
'query_hash': query_hash,
'query_hash_alg': 'SHA512',
}
jwt_token = jwt.encode(payload, secret_key, algorithm='HS256')
authorize_token = f'Bearer {jwt_token}'
headers = {"Authorization": authorize_token}
url = f"https://api.upbit.com/v1/ticker?{query}"
res = requests.get(url, headers=headers)
return res.()
构建JWT Payload，包括
access_key
，一个唯一的
nonce
(防止重放攻击)，查询参数的SHA512哈希值(
query_hash
)，以及哈希算法的指定(
query_hash_alg
)。
nonce
使用
uuid.uuid4()
生成，确保每次请求的唯一性。
jwt.encode
函数使用
secret_key
和HS256算法对Payload进行签名，生成JWT Token。然后，将JWT Token添加到Authorization header中，并使用
requests.get
函数发送GET请求到Upbit API的
/v1/ticker
端点。
res.()
将返回的JSON格式的响应数据解析为Python字典。
ticker_data = get_ticker("KRW-BTC,KRW-ETH")
print(ticker_data)
调用
get_ticker
函数，传入
"KRW-BTC,KRW-ETH"
作为
markets
参数，获取韩元计价的比特币和以太坊的Ticker数据，并将结果打印到控制台。您可以修改此参数以查询其他交易对的信息。
3.2. 交易下单：买入/卖出指定数量的加密货币
-
接口:
POST /v1/orders - 描述: 此接口允许用户提交新的买入或卖出加密货币订单。通过指定市场代码、订单类型、数量和价格，用户可以灵活地控制其交易行为。该接口支持限价单和市价单等多种订单类型，满足不同交易策略的需求。
-
参数:
-
market(required): 市场代码，指定要交易的加密货币市场。例如，KRW-BTC表示韩元 (KRW) 交易比特币 (BTC) 的市场。不同的交易所可能使用不同的市场代码，请参考交易所的API文档获取准确的市场代码列表。 -
side(required): 订单方向，指示是买入还是卖出。bid表示买入订单，即以指定价格或更低的价格购买加密货币。ask表示卖出订单，即以指定价格或更高的价格出售加密货币。 -
volume(required): 订单数量，指定要买入或卖出的加密货币数量。数量必须大于零，并且通常需要满足交易所规定的最小交易单位。请注意，数量的精度可能受到交易所的限制。 -
price(required): 订单价格，指定买入或卖出加密货币的价格。对于限价单，这是订单执行的目标价格。对于市价单，该参数可能被忽略，因为市价单会以当前市场最优价格立即成交。 -
ord_type(required): 订单类型，定义订单的执行方式。-
limit(限价单): 限价单允许用户指定一个价格，只有当市场价格达到或超过指定价格时，订单才会被执行。如果市场价格没有达到指定价格，订单将保持挂单状态，直到被取消。 -
market(市价单): 市价单会以当前市场上可用的最佳价格立即执行。用户只需指定要买入或卖出的数量，交易所会自动匹配合适的订单进行成交。市价单通常能保证快速成交，但成交价格可能与预期价格存在差异。
-
-
-
示例:
一个提交限价买入比特币的请求示例:
此示例表示以5000万韩元的价格购买0.01个比特币。POST /v1/orders { "market": "KRW-BTC", "side": "bid", "volume": "0.01", "price": "50000000", "ord_type": "limit" } - 注意事项: 在提交订单之前，请务必仔细检查所有参数，确保其准确无误。错误的参数可能导致订单无法执行或以意外的价格成交。同时，请关注交易所的交易规则和手续费政策。
示例代码 (Python):
本示例演示如何使用 Python 通过 Upbit API 下订单。 它使用
requests
库发送 HTTP 请求，
hashlib
库计算消息摘要，
base64
库进行 Base64 编码（尽管在本例中未使用），
jwt
库生成 JSON Web Token (JWT)，以及
uuid
库生成唯一 ID。
requests
库简化了发送 HTTP 请求的过程。
hashlib
库提供了各种哈希算法，包括 SHA512，用于确保数据的完整性。 虽然本例未使用，但
base64
库通常用于编码二进制数据，以便通过文本协议（如 HTTP）传输。
jwt
库允许创建和验证 JWT，这是一种在各方之间安全传输信息的标准方法。
uuid
库用于生成通用唯一标识符 (UUID)，这在需要唯一标识订单或其他数据时非常有用。
导入所需的库:
import requests
import hashlib
import base64
import jwt
import uuid
接下来，定义您的访问密钥和秘密密钥。 务必妥善保管您的密钥，不要将它们泄露给任何人。 访问密钥用于标识您的账户，秘密密钥用于对您的请求进行签名。 将以下占位符替换为您实际的 Upbit API 密钥:
access_key = "YOUR_ACCESS_KEY"
secret_key = "YOUR_SECRET_KEY"
现在，定义
place_order
函数，该函数接受以下参数：
-
market: 交易对，例如 "KRW-BTC"。 -
side: 订单类型，"bid" (买入) 或 "ask" (卖出)。 -
volume: 订单数量。 -
price: 订单价格。 -
ord_type: 订单类型，例如 "limit" (限价单), "price" (市价指定价格订单), "market" (市价单)。
place_order
函数会构造查询字符串，对其进行哈希处理，生成 JWT，并发送 POST 请求到 Upbit API。
def place_order(market, side, volume, price, ord_type):
query = {
'market': market,
'side': side,
'volume': volume,
'price': price,
'ord_type': ord_type
}
以下代码将查询参数转换为字符串并进行 SHA512 哈希处理，以确保请求的完整性。 哈希值将包含在后续的 JWT 负载中。
query_string = "&".join([f"{k}={v}" for k, v in query.items()]).encode()
m = hashlib.sha512()
m.update(query_string)
query_hash = m.hexdigest()
以下代码构造 JWT 负载。
access_key
用于标识 API 调用者。
nonce
是一个随机字符串，用于防止重放攻击。
query_hash
是之前计算的查询字符串的 SHA512 哈希值。
query_hash_alg
指定了用于计算哈希的算法。
payload = {
'access_key': access_key,
'nonce': str(uuid.uuid4()),
'query_hash': query_hash,
'query_hash_alg': 'SHA512',
}
使用您的秘密密钥和 HS256 算法对 JWT 负载进行签名。 然后，将 JWT 放入 Authorization 标头中。
jwt_token = jwt.encode(payload, secret_key, algorithm='HS256')
authorize_token = f'Bearer {jwt_token}'
headers = {"Authorization": authorize_token}
使用
requests.post
函数发送 POST 请求到 Upbit API 的
/v1/orders
端点。
headers
参数包含 Authorization 标头，
data
参数包含查询参数。
url = "https://api.upbit.com/v1/orders"
data = query
res = requests.post(url, headers=headers, data=data)
return res.()
下一个限价买单
在加密货币交易中，限价买单允许交易者以指定的价格或更低的价格购买资产。以下代码示例展示了如何使用某个交易平台的API提交一个限价买单，以在韩国交易所（KRW-BTC）以5000万韩元的价格购买0.001个比特币。
order_result = place_order("KRW-BTC", "bid", "0.001", "50000000", "limit")
其中，
place_order
函数是交易平台API提供的下单函数，各个参数的含义如下：
-
"KRW-BTC": 指定交易对，即用韩元 (KRW) 购买比特币 (BTC)。不同的交易平台支持不同的交易对。 -
"bid": 表示买单。 在交易中，"bid" 指的是买入报价，即购买者愿意支付的最高价格。 相对的， "ask" 指的是卖出报价，即出售者愿意接受的最低价格。 -
"0.001": 表示购买数量。 这里表示购买0.001个比特币。最小交易单位取决于交易所的规定。 -
"50000000": 表示限价。 只有当比特币价格低于或等于5000万韩元时，该买单才会成交。 设置合理的价格是限价单的关键。 -
"limit": 指定订单类型为限价单。 限价单确保交易以指定的价格或更好的价格执行，但不能保证立即成交。 如果市场价格未达到指定价格，订单将保持挂单状态。
函数执行后，
order_result
变量将包含订单执行的结果，其中包含了订单的各种状态信息，如订单ID、订单状态、成交数量等等。这些信息对于跟踪订单执行情况至关重要。
print(order_result)
这行代码用于打印订单结果，方便开发者查看订单是否成功提交，以及获取订单的详细信息，用于后续的交易管理和分析。 通过检查
order_result
的内容，可以确定订单是否被交易所接受，以及在特定市场条件下订单的执行情况。 在实际应用中，应该对订单结果进行错误处理，例如，如果订单提交失败，则需要进行重试或者通知用户。
3.3. 账户信息查询：查看账户余额
-
接口:
GET /v1/accounts -
描述:
此接口用于获取用户的账户余额信息。通过发送一个简单的GET请求到
/v1/accounts端点，用户可以查询到自己账户中各种加密货币的余额。 - 参数: 无。 该接口不需要任何请求参数。调用时只需确保用户已通过身份验证。
-
请求头:
建议包含
Authorization头部，用于身份验证，通常采用Bearer Token的方式。 - 返回值: JSON 格式的账户信息，包含账户余额等。返回的JSON数据将详细列出用户账户中持有的每种加密货币的余额。
-
返回值示例:
{ "accounts": [ { "currency": "BTC", "balance": "1.23456789", "available": "1.0", "hold": "0.23456789" }, { "currency": "ETH", "balance": "10.0", "available": "8.0", "hold": "2.0" } ] } -
返回值字段解释:
-
currency: 加密货币的币种代码，例如 "BTC" 代表比特币，"ETH" 代表以太坊。 -
balance: 账户中的总余额。 -
available: 可用余额，即可立即用于交易或提现的余额。 -
hold: 冻结余额，通常是由于挂单或其他原因被暂时冻结的余额。
-
- 错误处理: 如果请求失败，例如身份验证失败或服务器错误，接口将返回相应的HTTP状态码和错误信息。常见错误码包括401 (Unauthorized) 和 500 (Internal Server Error)。
示例代码 (Python):
本示例展示了如何使用Python与Upbit交易所的API进行交互，获取用户账户信息。它利用了`requests`库发送HTTP请求，`hashlib`库进行数据哈希，`base64`库进行编码，`jwt`库生成JSON Web Token (JWT) 用于身份验证，以及`uuid`库生成唯一ID。
import requests
import hashlib
import base64
import jwt
import uuid
access_key
和
secret_key
是您在Upbit交易所获得的API密钥。请务必妥善保管您的
secret_key
，切勿泄露给他人。
access key = "YOUR ACCESS KEY" # 替换为您的Access Key secret key = "YOUR SECRET KEY" # 替换为您的Secret Key
get_accounts()
函数用于获取用户账户信息。它首先构造一个包含
access_key
和
nonce
(随机数) 的payload。
nonce
用于防止重放攻击，确保每次请求的唯一性。
def get
accounts():
payload = {
'access
key': access_key,
'nonce': str(uuid.uuid4()),
}
然后，使用
jwt.encode()
函数，使用HS256算法对payload进行签名，生成JWT token。
secret_key
用于对payload进行签名，确保token的真实性。
jwt_token = jwt.encode(payload, secret_key, algorithm='HS256')
authorize_token = f'Bearer {jwt_token}'
headers = {"Authorization": authorize_token}
url = "https://api.upbit.com/v1/accounts"
res = requests.get(url, headers=headers)
return res.()
构造包含
Authorization
头的HTTP请求，其中
Authorization
的值为
Bearer {jwt_token}
。该头信息用于身份验证。使用
requests.get()
函数向Upbit API发送GET请求，获取用户账户信息。
res.()
函数将响应内容解析为JSON格式。
调用
get_accounts()
函数获取账户信息，并将结果打印到控制台。
account
info = get
accounts()
print(account_info)
4. 错误处理：常见的错误代码及解决方案
在使用 Upbit API 进行数据交互时，可能会遇到各种错误情况。这些错误可能源于多种因素，例如请求格式不正确、权限验证失败或服务器端问题。以下是一些常见的 HTTP 状态错误代码及其对应的解决方案，帮助开发者更好地调试和处理 API 调用过程中的异常：
-
400 Bad Request (错误请求):
此错误表明客户端发送的请求包含无效的参数。这可能是由于以下原因造成的：
- 请求缺少必需的参数。
- 参数值格式不正确（例如，使用了错误的日期格式、数值超出范围等）。
- 请求体包含无效的 JSON 或 XML 格式。
-
401 Unauthorized (未授权):
此错误表示客户端未经授权尝试访问受保护的资源。通常，这意味着 API 密钥无效、缺失或与请求不匹配。
- API 密钥未包含在请求头中。
- API 密钥已过期或被撤销。
- 使用的 API 密钥没有访问该资源的权限。
- API 密钥或签名计算错误。
Authorization字段，并采用Bearer {YOUR_ACCESS_KEY}的格式。签名校验务必正确，注意时间戳的有效性。 -
429 Too Many Requests (请求过多):
此错误表示客户端在给定的时间段内发送了过多的请求，超过了 Upbit API 的速率限制。API 限流旨在保护服务器免受滥用和拒绝服务攻击。
- 在短时间内发送大量请求。
- 未遵循 Upbit 官方文档中规定的速率限制。
-
500 Internal Server Error (服务器内部错误):
此错误表示服务器在处理请求时遇到了意外错误。这通常不是客户端的问题，而是 Upbit 服务器端的问题。
- 服务器代码存在错误。
- 服务器资源不足。
- 服务器正在进行维护。
请参考 Upbit 官方 API 文档，以获取更详细的错误代码信息、错误原因以及相应的解决方案。理解并正确处理这些错误代码，能够提高应用程序的稳定性和可靠性，并确保顺利完成与 Upbit 交易所的数据交互。
5. WebSocket 实时行情推送：显著提升数据获取效率
Upbit 不仅提供 REST API，还提供 WebSocket 接口，专门用于实时推送市场行情数据。与传统的 REST API 请求-响应模式不同，WebSocket 允许建立持久的双向通信连接。这意味着一旦建立连接，服务器可以主动向客户端推送数据，无需客户端频繁发起 HTTP 请求轮询。这种机制在需要实时更新数据的场景下，例如高频交易或实时监控，可以显著提高数据获取的效率，并降低延迟。
使用 WebSocket 可以有效减少服务器的负载，因为它避免了重复建立和关闭 HTTP 连接的开销。WebSocket 协议的设计更轻量级，减少了数据传输的额外开销。对于对数据实时性要求极高的应用，WebSocket 是一个更优的选择。
关于 Upbit WebSocket API 的详细使用方法，包括连接建立、订阅频道、数据格式等，请务必参考 Upbit 官方文档。官方文档会提供最准确和最新的信息，帮助你正确地集成和使用 WebSocket 接口，从而获得稳定和高效的实时行情数据流。请注意，不同交易对或市场的行情数据可能需要订阅不同的频道。同时，理解 Upbit 的数据格式对于正确解析和利用实时行情至关重要。