Upbit API对接教程：构建你的加密货币交易应用

生成 JWT 代码示例 (Python)：

本代码示例展示了如何使用 Python 生成 JSON Web Token (JWT)，用于身份验证和授权。JWT 是一种紧凑且自包含的方式，用于安全地在各方之间传输信息，常用于 API 身份验证。

import jwt
import uuid
import hashlib
import os

导入必要的 Python 库。 jwt 库用于 JWT 的编码和解码。 uuid 库用于生成唯一标识符（UUID），以确保每次生成的 JWT 都是唯一的。 hashlib 用于计算哈希值（虽然在此示例中未使用，但在实际应用中可能用于密码存储等安全目的）。 os 库用于访问环境变量，以便安全地存储和检索 API 密钥。

access_key = os.environ["UPBIT_OPEN_API_ACCESS_KEY"] # 从环境变量获取 Access Key
secret_key = os.environ["UPBIT_OPEN_API_SECRET_KEY"] # 从环境变量获取 Secret Key

从环境变量中获取 Access Key 和 Secret Key。强烈建议不要将密钥硬编码到代码中，而是使用环境变量或更安全的密钥管理方案。将密钥存储在环境变量中可以提高安全性，并允许在不同的环境中轻松更改密钥，而无需修改代码。

payload = {
'access_key': access_key,
'nonce': str(uuid.uuid4()) # UUID 用于确保每次生成的 JWT 都是唯一的
}

创建一个 payload 字典，其中包含要放入 JWT 中的信息。在此示例中，payload 包含 access_key 和 nonce 。 access_key 用于标识请求的来源。 nonce 是一个随机数或唯一字符串，用于防止重放攻击。每次生成 JWT 时都应该生成一个新的 nonce 值。 使用 uuid.uuid4() 生成一个 UUID，并将其转换为字符串。这确保了即使使用相同的 access_key ，每次生成的 JWT 也是不同的。

jwt_token = jwt.encode(payload, secret_key, algorithm='HS256') # 使用 HS256 算法对 payload 进行加密

使用 jwt.encode() 函数对 payload 进行编码，生成 JWT。该函数接受三个参数：payload、secret key 和 algorithm。在此示例中，使用 HS256 算法进行加密。HS256 是一种对称加密算法，这意味着用于加密和解密的密钥是相同的。 secret_key 用于对 JWT 进行签名，以确保 JWT 的完整性。确保妥善保管 secret_key ，不要泄露给未经授权的方。 选择合适的加密算法至关重要，HS256、RS256 等都是常见的选择，应根据安全需求和性能考虑进行权衡。 其他更高级的算法可能包括非对称加密，例如使用公钥/私钥对。

authorization_token = f"Bearer {jwt_token}" # 构造 Authorization Header

构造 Authorization Header。在 HTTP 请求中，通常使用 Authorization Header 来传递 JWT。Authorization Header 的格式为 "Bearer "，其中 是生成的 JWT 字符串。此header将用于在使用API​​时进行身份验证。完整的HTTP请求可能包括以下内容：

headers = {
'Authorization': authorization_token,
'Content-Type': 'application/'
}

注意事项：

• 密钥安全至关重要： 务必妥善保管 Access Key（访问密钥）和 Secret Key（私有密钥），切勿泄露。强烈建议将它们存储在安全的环境变量中，而不是直接硬编码在应用程序代码中。硬编码密钥会显著增加安全风险，一旦泄露可能导致严重的资产损失或数据泄露。考虑使用密钥管理服务或硬件安全模块 (HSM) 进一步提高安全性。
• Nonce 的作用： nonce （随机数）在身份验证过程中扮演着关键角色，主要用于防御重放攻击。重放攻击是指攻击者截获并重新发送有效的身份验证请求，从而在未经授权的情况下访问系统资源。为防止此类攻击，每次生成 JSON Web Token (JWT) 时，都必须生成一个唯一的、不可预测的 nonce 值。推荐使用 UUID (Universally Unique Identifier) 作为 nonce ，因为它能够保证在全球范围内的唯一性。确保每次请求都使用不同的 nonce ，以确保即使攻击者截获了请求，也无法重复使用它。

3. 发送 API 请求：查询账户信息示例

成功生成 JWT (JSON Web Token) 之后，你现在可以利用该令牌向受保护的 API 端点发起请求了。以下示例将详细说明如何使用 JWT 查询账户信息，展示了构建和发送 API 请求的完整流程。

• 请求头 (Headers) 设置： 在发送 API 请求时，必须在 HTTP 请求头中包含 JWT。通常，JWT 会被添加到 Authorization 头部，采用 Bearer 方案。这意味着你需要设置请求头为： Authorization: Bearer <你的JWT令牌> 。 务必确保令牌前包含 "Bearer "（注意空格），以便服务器正确识别并验证令牌。

• 请求方法 (HTTP Method)： 根据 API 的设计，查询账户信息通常使用 GET 请求。 GET 请求适用于从服务器检索数据，而不会对服务器状态进行任何修改。

• API 端点 (Endpoint)： 确定查询账户信息的具体 API 端点。这通常是一个 URL，例如 /api/v1/accounts/{account_id} ，其中 {account_id} 是你要查询的特定账户的ID。请务必查阅 API 文档以获取正确的端点。

• 发送请求： 使用你选择的编程语言或工具（例如 curl 、 Python 的 requests 库、JavaScript 的 fetch API 等）发送带有正确请求头和端点的 GET 请求。确保你的代码能够处理 API 的响应，包括成功响应（通常是 HTTP 状态码 200 OK）和错误响应（例如 401 Unauthorized，表示 JWT 无效或已过期）。

• 处理响应： 如果 API 请求成功，服务器将返回包含账户信息的 JSON 数据。你的代码需要解析这个 JSON 数据，并提取所需的信息，例如账户余额、账户类型等。同时，也要考虑处理可能出现的错误情况，例如网络错误、服务器错误等，并向用户提供适当的反馈。

发送请求代码示例 (Python)：

使用 Python 的 requests 库可以轻松地向 Upbit API 发送请求。该库允许你设置请求头，并处理 API 返回的 JSON 数据。

import requests

此行代码导入 requests 库，使你能够使用其提供的 HTTP 请求方法，例如 GET 、 POST 等。

server_url = "https://api.upbit.com"

server_url 变量存储 Upbit API 的根 URL。所有的 API 请求都将基于这个 URL 构建。

endpoint = "/v1/accounts"

endpoint 变量定义了特定的 API 端点，此处为 /v1/accounts ，用于获取用户账户信息。不同的端点对应不同的功能。

url = server_url + endpoint

将 server_url 和 endpoint 拼接在一起，形成完整的 API 请求 URL。这是向 Upbit API 发送请求的完整地址。

headers = {"Authorization": authorization_token}

headers 字典包含 HTTP 请求头。其中 Authorization 头用于传递身份验证令牌。 authorization_token 变量需要替换为实际的 Upbit API 密钥。

注意：确保将 authorization_token 替换为有效的 JWT (JSON Web Token) 令牌。可以使用 Upbit 提供的 API 密钥和 Secret 密钥生成 JWT 令牌。

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

使用 requests.get() 方法向指定的 URL 发送 GET 请求。 headers 参数用于传递请求头，包含身份验证信息。 res 变量存储服务器返回的响应对象。

print(res.())

使用 res.() 方法将服务器返回的 JSON 格式数据解析为 Python 字典或列表。 print() 函数用于将解析后的 JSON 数据打印到控制台。

请务必妥善保管你的 API 密钥和 Secret 密钥，避免泄露。不要在客户端代码中硬编码 API 密钥，应使用环境变量或配置文件来管理密钥。

代码解释：

• server_url ：Upbit API 的基础 URL，通常指向 Upbit 提供的公共 API 服务器地址，例如： https://api.upbit.com/v1 。它作为所有 API 端点的前缀，确保客户端能够正确地定位到 Upbit 的 API 服务。
• endpoint ：API 端点的具体路径，定义了要请求的特定资源或功能。例如， /ticker 端点用于获取指定交易对的最新成交价信息。此路径会附加到 server_url 之后，形成完整的 API 请求地址。
• url ：完整的 API 请求 URL，通过将 server_url 和 endpoint 拼接而成。例如，如果 server_url 是 https://api.upbit.com/v1 且 endpoint 是 /ticker?markets=KRW-BTC ，那么 url 将会是 https://api.upbit.com/v1/ticker?markets=KRW-BTC ，这是实际发送网络请求的目标地址。
• headers ：请求头，是一个包含了元数据信息的字典，这些信息会随着 HTTP 请求一起发送给服务器。其中关键的是 Authorization Header ，用于进行身份验证和授权。对于 Upbit API，通常使用 JWT（JSON Web Token）作为 Bearer Token 放在 Authorization 字段中，格式为 "Authorization": "Bearer " ， access_key需要替换成有效的密钥。其他常见的请求头还包括 Content-Type （指定请求体的MIME类型）和 Accept （指定客户端可以接受的响应MIME类型）。
• requests.get(url, headers=headers) ：使用 Python 的 requests 库发送一个 HTTP GET 请求。 url 参数指定了请求的目标地址， headers 参数包含了请求头信息。GET 请求常用于从服务器检索数据，并且是幂等的，即多次执行相同的 GET 请求应该返回相同的结果。
• res.() ：将 API 返回的 JSON 格式数据解析为 Python 字典（dictionary）。 res 对象是 requests.get() 方法返回的响应对象，它包含了服务器返回的状态码、响应头和响应体。 .() 方法会将响应体中的 JSON 数据自动解码并转换为 Python 的数据结构，方便后续的数据处理和分析。如果响应体不是有效的 JSON 格式，则会抛出异常。

4. 常用 API 功能：下单、查询订单、获取行情数据

Upbit API 提供了全面的功能，方便开发者进行交易和数据分析。下面详细介绍一些常用的 API 功能，并提供更深入的解释：

• 下单 (Placing Orders): Upbit API 允许用户通过程序化方式提交各种类型的订单。这包括市价单 (Market Order)，即以当前市场最优价格立即成交的订单；限价单 (Limit Order)，即用户指定一个价格，只有当市场价格达到或超过该价格时才成交的订单；止损单 (Stop Order)，即当市场价格达到预设的止损价格时，系统自动提交一个市价单；以及止损限价单 (Stop-Limit Order)，它结合了止损和限价的特性，在触发止损价后，会以设定的限价或更优的价格挂单。用户可以指定买入或卖出，订单数量，以及更高级的参数，如 Time-in-Force (TIF)，用于控制订单的有效期，例如 Good-Til-Canceled (GTC，直到被取消)、Immediate-Or-Cancel (IOC，立即成交或取消) 和 Fill-Or-Kill (FOK，完全成交或立即取消)。
• 查询订单 (Order Query): 查询订单的功能至关重要，它允许用户检索所有历史订单和当前未完成的订单信息。通过 API，可以根据订单 ID、交易对、订单状态（例如，待处理、已成交、已取消）和时间范围等条件进行筛选。返回的信息包括订单类型、下单时间、成交价格、成交数量、手续费以及其他详细信息，帮助用户监控交易活动和评估交易策略的有效性。
• 获取行情数据 (Market Data Retrieval): Upbit API 提供了实时的市场数据，包括但不限于：当前价格 (Current Price)，代表最新的交易价格；最高价 (High Price)，指在特定时间段内达到的最高交易价格；最低价 (Low Price)，指在特定时间段内达到的最低交易价格；成交量 (Volume)，指在特定时间段内交易的总数量；以及交易深度 (Order Book)，显示了买单和卖单的挂单情况，提供了市场供需的实时视图。除了实时数据，API 还提供历史数据 (Historical Data)，例如日线图、周线图、月线图等，方便用户进行技术分析和趋势预测。这些数据对于制定交易策略、风险管理和量化分析至关重要。