Upbit API交易全攻略：新手到专家，快速上手指南！
Upbit API 如何获取
Upbit 是韩国领先的加密货币交易所，提供便捷的 API 接口，方便开发者和交易者获取实时数据、进行自动化交易和管理账户。本文将详细介绍如何获取和使用 Upbit API，并提供一些实用的代码示例。
1. 注册 Upbit 账户并进行 KYC 认证
要使用 Upbit API，必须先拥有一个经过验证的 Upbit 账户。这需要注册并完成 KYC（Know Your Customer，了解你的客户）身份验证流程。 KYC 旨在验证用户的身份，防止欺诈、洗钱等非法活动，并确保平台符合相关法律法规的要求，构建一个安全可靠的交易环境。
- 注册账户: 访问 Upbit 官方网站 ( https://upbit.com )。在首页或导航栏中找到“注册”或“Sign Up”按钮，点击进入注册页面。按照页面提示，提供有效的邮箱地址，设置安全的密码，并阅读并同意 Upbit 的服务条款和隐私政策。完成邮箱验证后，账户注册即告完成。 注意密码的强度，建议使用包含大小写字母、数字和特殊字符的复杂密码，提高账户安全性。
-
KYC 认证:
成功登录 Upbit 账户后，导航至“我的账户”、“账户设置”或类似的页面，查找“KYC 认证”、“身份验证”或相关的选项。Upbit 通常会要求用户提供以下信息和文件：
- 身份证明: 上传清晰的身份证明文件扫描件或照片，例如身份证（正反面）、护照或驾驶执照。确保证件上的姓名、照片、证件号码等信息清晰可见。
- 地址证明: 提供最近三个月内的地址证明文件，例如银行账单、水电费账单、信用卡账单或户口本。账单上必须显示用户的姓名和详细地址，并且与注册时填写的地址一致。
- 人脸识别: 按照 Upbit 的指示，使用摄像头进行人脸识别。这通常需要用户正对着摄像头，按照提示进行眨眼、摇头等动作，以确保是本人操作。
2. 创建 API 密钥
完成 KYC (了解你的客户) 身份验证流程后，就可以开始创建 API 密钥了。API 密钥本质上是一组凭证，用于验证你的身份并授权你安全地访问 Upbit API 的各项功能。通过 API 密钥，你的应用程序或脚本可以与 Upbit 交易所进行交互，执行各种操作，例如获取市场数据、下单交易或查询账户信息。
- 进入 API 管理页面: 成功登录 Upbit 账户后，导航至用户中心或账户设置页面。通常可以在“我的账户”、“个人资料”或类似的选项中找到 “API 관리 (API Management)” 或 “API 키 관리 (API Key Management)” 选项。 这个页面是管理和创建 API 密钥的中心位置。
- 创建新密钥: 在 API 管理页面，寻找并点击 “API 키 발급 (Issue API Key)” 或类似的按钮。此操作将启动创建新 API 密钥的流程。系统可能会要求你进行额外的身份验证，以确保账户安全。
-
设置权限:
创建 API 密钥的关键步骤是设置权限。 Upbit API 提供了细粒度的权限控制，允许你精确地指定 API 密钥可以执行的操作。 提供的权限类型包括：
- 주문 (Order): 此权限允许你的 API 密钥执行与交易相关的操作，包括创建新的订单 (买入或卖出)、修改现有订单以及取消订单。 拥有此权限意味着你的应用程序可以自动进行交易。
- 출금 (Withdrawal): 此权限授权 API 密钥发起加密货币提现请求。 请注意，启用此权限通常需要额外的安全验证步骤，例如双重验证 (2FA) ，以防止未经授权的提现。 出于安全考虑，应谨慎授予此权限。
- 입금 (Deposit): 启用此权限后，你的 API 密钥可以访问账户的充值历史记录和入账信息。 这对于跟踪充值状态和验证交易非常有用。
- 자산 조회 (Asset Inquiry): 此权限允许 API 密钥查询你的账户余额和资产信息。 你可以获取有关你持有的各种加密货币数量以及当前价值的实时信息。
务必根据你的特定需求谨慎选择权限。 最小权限原则 应该始终适用：即只授予 API 密钥执行其所需任务的最小权限集。 例如，如果你只需要获取市场数据，绝对不要选择 "주문 (Order)" 或 "출금 (Withdrawal)" 权限，以最大程度地降低潜在的安全风险。 错误的权限配置可能导致意外的交易或未经授权的提现。
-
确认并保存密钥:
在仔细审查并设置好所有必要的权限后，确认并生成 API 密钥。 生成的密钥包含两个关键部分：
- Access Key: Access Key 类似于用户名，用于唯一标识你的身份，并在每个 API 请求中发送。
- Secret Key: Secret Key 类似于密码，用于对 API 请求进行签名，以确保请求的完整性和真实性。 Secret Key 必须严格保密，切勿与任何人分享。 泄露 Secret Key 可能会导致你的账户被盗用。 强烈建议将 Secret Key 存储在安全的地方，例如加密的密钥库或硬件安全模块 (HSM)。
请立即安全地存储 Access Key 和 Secret Key。 Upbit 只会显示 Secret Key 一次。 如果丢失 Secret Key，你将需要重新生成 API 密钥。
3. 使用 API 密钥访问 Upbit API
在获得 API 密钥后，您便可以利用各种编程语言和开发工具，安全、高效地访问 Upbit 交易所提供的 API 服务。Upbit API 遵循 RESTful 架构设计原则，这意味着您可以通过发送标准的 HTTP 请求，如 GET、POST 和 DELETE 等，与 API 服务器进行数据交互，实现诸如查询市场行情、下单交易以及管理账户信息等功能。使用 API 密钥进行身份验证，可以确保只有经过授权的用户才能访问您的账户和执行交易，从而保护您的资产安全。
具体来说，您需要使用您的 API 密钥和 Secret 密钥来生成一个用于身份验证的签名。该签名将被包含在 HTTP 请求头中，以便 Upbit 服务器验证您的身份。不同的编程语言都有相应的库或模块，可以帮助您轻松生成签名并发送 HTTP 请求。例如，在 Python 中，您可以使用
requests
库发送 HTTP 请求，并使用
hmac
和
hashlib
库生成签名。在使用 API 时，务必仔细阅读 Upbit 官方提供的 API 文档，了解每个接口的具体参数、请求方式和返回值格式，避免出现错误。
3.1 API Endpoint
Upbit API 的基本 Endpoint 是
https://api.upbit.com/v1
。 所有 API 请求都必须以这个 Endpoint 作为 URL 的前缀， 构成完整的请求地址。 例如，要获取市场代码列表，完整的 API 请求地址应为
https://api.upbit.com/v1/market/all
。 使用该 Endpoint 可以确保与 Upbit 服务器进行安全且一致的通信，访问最新的市场数据和服务。 未包含此前缀的API调用将无法成功连接到Upbit服务器。 在构建API请求时，务必仔细检查 Endpoint 的正确性，避免出现任何拼写错误或者遗漏，确保能够准确地访问Upbit API提供的各项功能，例如交易下单、查询账户余额、获取历史K线数据等。
3.2 认证方式
Upbit API 采用业界标准的 JWT (JSON Web Token) 机制进行认证，以确保交易安全和用户身份验证。 您需要妥善保管并使用您的 Access Key 和 Secret Key，这两个密钥是您访问 Upbit API 的凭证。 具体来说，您需要使用 Access Key 和 Secret Key，通过特定的算法（通常是 HMAC-SHA256）生成一个符合 JWT 规范的字符串。 这个 JWT 字符串将作为您访问 API 的身份证明。
为了验证您的身份并授权您访问受保护的 API 资源，每一个发送到 Upbit API 的请求都必须在
Authorization
头部中包含该 JWT。 该头部的值应以 "Bearer " 开头，后跟您的 JWT 字符串，例如：
Authorization: Bearer your_jwt_token
。 服务器收到请求后，会验证 JWT 的签名和声明，以确定请求者的身份和权限。 如果 JWT 验证成功，服务器将处理该请求；否则，服务器将拒绝该请求并返回相应的错误信息。
3.3 生成 JWT (JSON Web Token)
JSON Web Token (JWT) 是一种开放标准 (RFC 7519)，它定义了一种紧凑且自包含的方式，用于在各方之间安全地作为 JSON 对象传输信息。信息可以被验证和信任，因为它是经过数字签名的。 在加密货币应用中，JWT常被用于身份验证和授权，确保只有经过授权的用户才能访问特定的资源或执行特定的操作。
以下是使用 Python 生成 JWT 的示例代码。 我们将使用 `PyJWT` 库来完成此操作。 确保你已经安装了此库： `pip install PyJWT`
import jwt import uuid import hashlib import time
access_key = "YOUR_ACCESS_KEY" # 替换为你的 Access Key，例如，你的API密钥 secret_key = "YOUR_SECRET_KEY" # 替换为你的 Secret Key，保管好此密钥，切勿泄露
def generate_jwt(access_key, secret_key): """ 生成 JWT 的函数。 Args: access_key (str): 用户的 Access Key。 secret_key (str): 用户的 Secret Key，用于签名 JWT。 Returns: str: 生成的 JWT 字符串。 """ # 构建 Payload (载荷)，Payload 包含要传递的信息 payload = { 'access_key': access_key, # 用户身份标识，可以包含用户ID或用户名 'nonce': str(uuid.uuid4()), # 一次性随机数，用于防止重放攻击 'timestamp': int(time.time()), # 时间戳，记录 JWT 的创建时间，可用于设置过期时间 'exp': int(time.time()) + 3600 # 可选：过期时间（Unix 时间戳），例如，设置为 1 小时后过期 }
# 使用 HS256 算法对 Payload 进行签名，生成 JWT
jwt_token = jwt.encode(payload, secret_key, algorithm="HS256")
return jwt_token
# 调用函数生成 JWT jwt_token = generate_jwt(access_key, secret_key) print(jwt_token)
该示例代码生成了一个包含 access_key 和 nonce 的 JWT。 nonce (Number used once) 是一个只使用一次的随机数，可以防止重放攻击。 为了增加安全性，Payload中还加入了时间戳以及过期时间。请务必妥善保管你的 Secret Key，避免泄露。 在实际应用中，可以将 JWT 存储在客户端（如浏览器 Cookie 或本地存储）并在后续的请求中发送到服务器进行身份验证。
3.4 发送 API 请求
与加密货币交易所的API交互是自动化交易和数据分析的关键。以下是如何使用 Python 发送 GET 请求获取 Upbit 交易所账户余额的示例代码，并对每个步骤进行详细说明。
需要安装必要的 Python 库。
jwt
用于生成 JSON Web Token (JWT)，
uuid
用于生成唯一 ID，
hashlib
用于哈希处理（虽然本例未使用，但在更复杂的 API 调用中可能用到），
requests
用于发送 HTTP 请求。
import jwt
import uuid
import hashlib
import requests
接下来，替换代码中的
YOUR_ACCESS_KEY
和
YOUR_SECRET_KEY
为你的实际 Upbit API 密钥。务必妥善保管你的 Secret Key，避免泄露。
access_key = "YOUR_ACCESS_KEY" # 替换为你的 Access Key
secret_key = "YOUR_SECRET_KEY" # 替换为你的 Secret Key
为了安全地访问 API，你需要生成一个 JWT。该 JWT 包含你的 Access Key 和一个唯一的 nonce（一次性随机数），并使用你的 Secret Key 进行签名。以下
generate_jwt
函数完成此操作。
def generate_jwt(access_key, secret_key):
payload = {
'access_key': access_key,
'nonce': str(uuid.uuid4()),
}
jwt_token = jwt.encode(payload, secret_key, algorithm="HS256")
return jwt_token
nonce
的作用是防止重放攻击。每次 API 请求都应该使用不同的
nonce
值。
jwt.encode
函数使用 HS256 算法对 payload 进行签名。
使用你的 Access Key 和 Secret Key 调用
generate_jwt
函数来生成 JWT。
jwt_token = generate_jwt(access_key, secret_key)
然后，将 JWT 放入 Authorization 请求头中。Authorization 头的格式为 "Bearer {jwt_token}"。
headers = {"Authorization": f"Bearer {jwt_token}"}
现在，可以使用
requests.get
函数向 Upbit API 发送 GET 请求。在本例中，我们访问
https://api.upbit.com/v1/accounts
接口来获取账户余额信息，并将包含 JWT 的 headers 传递给请求。
res = requests.get("https://api.upbit.com/v1/accounts", headers=headers)
打印 API 响应的内容。
res.()
方法将响应的 JSON 数据解析为 Python 字典或列表，方便你进一步处理。
print(res.())
注意：在使用 API 时，请务必遵守 Upbit 的 API 使用条款和速率限制，避免被限制访问。始终使用 HTTPS 连接来保护你的数据安全。
3.5 常用 API 接口
-
账户信息:
-
GET /accounts: 获取账户余额。返回账户中各种加密货币和法币的可用余额、已用余额和总余额。该接口通常需要进行身份验证。返回的数据格式可能包含币种代码、可用余额、冻结余额等字段。
-
-
市场数据:
-
GET /market/all: 获取所有交易市场列表。返回当前交易所支持的所有交易对的信息，例如 BTC/USDT, ETH/BTC等。返回数据一般包含交易对名称、基础货币、报价货币等。 -
GET /ticker?markets={markets}: 获取指定交易对的当前价格。{markets}需要替换为具体的交易对，例如BTC/USDT。返回数据通常包含最新成交价、最高价、最低价、成交量等信息，是进行快速市场分析的重要数据来源。可以一次查询多个交易对，用逗号分隔。 -
GET /trades/ticks?market={market}: 获取指定交易对的最近成交记录。{market}需要替换为具体的交易对，例如ETH/BTC。 返回数据包含成交时间、成交价格、成交数量、买卖方向等信息。这个接口可以用来分析市场微观结构，例如判断是否有大单成交。 -
GET /candles/{candle_type}?market={market}: 获取指定交易对的 K 线数据（例如分钟线、日线）。candle_type可以是minutes/{unit}(例如minutes/1,minutes/5表示1分钟线和5分钟线)、days、weeks、months，分别对应日线、周线和月线。{market}需要替换为具体的交易对。 K 线数据包含开盘价、收盘价、最高价、最低价和成交量，是技术分析的基础。可以设置返回K线数量的参数，通常有limit参数。
-
-
交易:
-
POST /orders: 下单。通过此接口可以提交买入或卖出订单。 请求体需要包含交易对、订单类型（市价单、限价单）、买卖方向（买入、卖出）、数量和价格（限价单需要）。 返回数据通常包含订单ID，订单状态等信息。下单前需要确保账户有足够的资金。 -
DELETE /order?uuid={uuid}: 取消订单。{uuid}需要替换为要取消的订单的唯一ID。取消订单后，交易所会释放被占用的资金。如果订单已经成交，则无法取消。 -
GET /order?uuid={uuid}: 查询订单状态。{uuid}需要替换为要查询的订单的唯一ID。返回数据包含订单的详细信息，例如订单类型、订单价格、订单数量、已成交数量、订单状态（未成交、部分成交、完全成交、已取消）等。 -
GET /orders?market={market}: 查询指定交易对的订单列表。{market}需要替换为具体的交易对。返回数据包含该交易对的所有未成交或历史订单信息。可以通过添加参数来筛选订单状态，例如只查询未成交订单。也可以设置返回订单数量的参数，例如limit参数。
-
4. 错误处理
Upbit API 交互过程中，服务器会返回 HTTP 状态码以及 JSON 格式的错误信息，用于指示请求的处理结果。 开发者必须根据这些状态码和错误信息，实现健壮的错误处理机制，以确保应用程序的稳定性和可靠性。
常见的 HTTP 错误状态码及其含义如下：
-
400 Bad Request: 此状态码表明请求中包含无效或错误的参数。 开发者应仔细检查请求的各个参数，包括参数类型、取值范围以及必填项等，确保符合 API 的规范。常见原因包括：缺少必要的参数、参数格式不正确、参数值超出有效范围等。 -
401 Unauthorized: 此状态码表示客户端未经过授权访问受保护的资源。通常情况下，这表明 JSON Web Token (JWT) 验证失败。 开发者应检查 JWT 是否有效、是否已过期、以及是否具有访问所需资源的权限。 重新获取或刷新 JWT 可能是解决此问题的关键。 -
429 Too Many Requests: 此状态码表示客户端发送的请求频率过高，超过了 Upbit API 设置的速率限制。 为了保护 API 的稳定性和可用性，Upbit 实施了速率限制策略。 开发者需要采取措施来降低请求频率，例如使用缓存、批量请求、或者实施指数退避策略。 具体速率限制的详细信息，请参考 Upbit API 的官方文档。
5. 速率限制 (Rate Limit)
Upbit API 实施了严格的速率限制机制，旨在保障整个平台的稳定性和可靠性，并防止恶意滥用行为。速率限制通过限制单位时间内允许的请求数量，来确保所有用户都能公平地访问 API 资源。
开发者在使用 Upbit API 时，务必密切关注并严格遵守官方文档中明确规定的速率限制策略。不同的 API 端点可能具有不同的速率限制阈值，因此在集成过程中需要仔细规划和调整请求频率，以避免超出限制。
如果你的应用程序触发了速率限制，API 将会返回标准的 HTTP 状态码
429 Too Many Requests
。这意味着你在短时间内发送了过多的请求，超过了允许的上限。当遇到此错误时，建议你立即采取以下措施：
- 暂停请求： 立即停止发送新的 API 请求。
- 等待： 等待一段适当的时间，具体等待时间取决于 Upbit API 的速率限制策略。
- 重试： 在等待期结束后，可以尝试重新发送请求。建议采用指数退避策略，逐渐增加重试间隔，以避免再次触发速率限制。
为了更有效地管理请求并避免触发速率限制，你可以考虑以下策略：
- 批量处理： 尽可能将多个相关的操作合并到一个 API 请求中，减少请求总数。
- 缓存数据： 将频繁访问且变化不大的数据缓存到本地，避免重复请求 API。
- 使用 WebSockets： 对于需要实时更新的数据，考虑使用 WebSockets 协议，通过长连接接收数据推送，减少轮询请求。
- 监控请求： 监控你的应用程序的 API 请求频率，及时发现并解决潜在的速率限制问题。
理解并妥善处理 Upbit API 的速率限制对于构建稳定、高效的交易应用程序至关重要。请务必参考最新的 Upbit API 文档，了解最新的速率限制规则和最佳实践。
6. 安全注意事项
- 保护你的 API 密钥: 绝对不要将你的 Secret Key（私钥）泄露给任何人。私钥是访问和控制你的Upbit账户的凭证，泄露会导致资金损失和账户被盗用。妥善保管私钥，将其视为最高机密信息。
- 设置安全的权限: 只授予 API 密钥所需的最低权限。避免授予不必要的权限，遵循最小权限原则。例如，如果你的应用只需要读取市场数据，则只授予读取权限，避免授予交易权限。可以通过 Upbit 提供的权限管理功能进行精细化设置。
- 定期更换 API 密钥: 为了安全起见，强烈建议定期更换 API 密钥。密钥更换频率取决于你的安全需求和风险承受能力。定期更换可以有效降低密钥泄露带来的风险。更换后务必更新所有使用旧密钥的应用和服务。
- 使用安全的网络连接: 使用 HTTPS 协议进行 API 请求，确保数据传输的安全性。HTTPS 使用 SSL/TLS 加密，可以防止数据在传输过程中被窃听或篡改。避免使用不安全的 HTTP 连接发送 API 请求。同时，确保你的开发环境和生产环境都配置了 HTTPS。
- 监控你的账户活动: 定期检查你的账户交易记录、API 使用情况和安全日志，及时发现异常情况。监控内容包括但不限于：异常交易、未授权访问、API 调用频率过高等。一旦发现异常，立即采取措施，例如禁用 API 密钥、修改密码等。设置告警系统可以帮助你及时发现异常情况。
以上详细介绍了 Upbit API 的安全注意事项，这些措施对于保护你的账户安全至关重要。请务必认真对待并严格遵守这些安全建议。安全是加密货币交易的基础，只有确保安全，才能安心交易。请务必参考 Upbit 官方 API 文档获取最新和最准确的安全信息。