掌握KuCoin API：解锁交易秘籍，轻松打造自动化交易策略！

日期：2025-03-07 栏目：讨论浏览：28

KuCoin API 调用指南

简介

KuCoin 提供了一套全面的应用程序编程接口 (API)，旨在为开发者提供对平台数据和功能的深度访问能力。这包括实时交易执行、全面的市场数据流、便捷的账户管理以及其他关键操作。通过利用 KuCoin API，开发者可以构建定制化的自动化交易机器人，开发复杂的数据分析和可视化工具，并将 KuCoin 平台无缝集成到各种第三方应用程序和服务中。为了帮助开发者充分利用这些功能，本文将提供 KuCoin API 调用的详细指南，涵盖身份验证机制、最常用的 API 接口以及在使用 API 时需要注意的关键事项。

KuCoin API 允许开发者程序化地与 KuCoin 交易所进行交互。这意味着可以创建自动执行交易、获取市场数据、管理账户等任务的应用程序，而无需手动登录网站。这种自动化的能力为量化交易、套利策略以及构建基于数据的交易决策系统提供了强大的支持。

本文档将重点介绍如何通过 API 密钥进行身份验证，并深入探讨诸如获取实时市场行情、下单、取消订单以及查询账户余额等常用接口的具体用法。我们还将讨论 API 使用过程中的速率限制、错误处理以及安全最佳实践，以确保开发者能够安全有效地使用 KuCoin API 。

身份验证

在使用 KuCoin API 之前，必须完成身份验证流程，这是访问 API 功能的先决条件。KuCoin 采用基于 API 密钥的身份验证机制，确保只有经过授权的开发者和交易者才能访问其交易平台的数据和功能。该身份验证系统依赖于三个关键元素： API Key 、 API Secret 和 API Passphrase 。

API Key 是一个公开的标识符，用于识别您的账户。您可以把它想象成您的用户名，它允许 KuCoin 识别哪个账户正在发出 API 请求。请注意， API Key 本身并不足以进行身份验证，还需要另外两个密钥。

API Secret 是一个私密的密钥，必须严格保密。这个密钥与 API Key 配对使用，用于生成请求签名，以验证请求的真实性和完整性。切勿与任何人分享您的 API Secret ，并将其视为密码一样安全地存储。一旦泄露，您的账户可能面临风险。

API Passphrase 是一个额外的安全层，您可以自行设置。它类似于一个密码，在每次 API 请求中都需要提供。 API Passphrase 的加入，进一步增强了安全性，即使 API Key 和 API Secret 泄露，攻击者也无法直接访问您的账户，需要同时破解 API Passphrase 才能构成威胁。

通过这三种密钥的结合使用，KuCoin API 能够确保只有经过授权的用户才能访问其服务，从而保护用户的资产和数据安全。请务必妥善保管您的 API Key 、 API Secret 和 API Passphrase ，并定期更换，以降低安全风险。

获取 KuCoin API 密钥

为了能够安全地访问和管理您的 KuCoin 账户，您需要获取 API 密钥。API 密钥允许您通过程序化方式与 KuCoin 交易所进行交互，例如进行交易、查询账户余额等。请按照以下步骤操作：

登录 KuCoin 账户。 使用您的用户名和密码登录您的 KuCoin 账户。如果您还没有账户，请先注册一个。
进入 API 管理页面。 登录后，导航至账户设置中的 API 管理页面。您通常可以在个人资料或安全设置中找到此选项。
创建 API 密钥，并设置相应的权限。 在 API 管理页面，点击“创建 API”或类似的按钮。系统会提示您为新的 API 密钥设置权限。根据您的需求，选择合适的权限，例如“交易”（允许进行买卖操作）、“查看账户信息”（允许查询余额和交易历史）等。请仔细考虑您需要的权限，并仅授予必要的权限，以确保账户安全。您还可以设置IP限制，只允许特定的IP地址访问您的API密钥。
妥善保管 API Key、API Secret 和 API Passphrase。 创建 API 密钥后，您将获得三个关键信息： API Key （API 密钥）、 API Secret （API 私钥）和 API Passphrase （API 密码）。 API Key 用于标识您的身份， API Secret 用于加密通信，而 API Passphrase 则用于解密 API Secret 。 务必将这三个信息安全地存储在安全的地方，切勿泄露给他人。 API Secret 是加密后的密钥，因此需要使用 API Passphrase 才能解密和使用。请注意备份您的 API 密钥信息，因为一旦丢失，可能需要重新创建。

重要提示： 任何拥有您的 API 密钥的人都可以访问您的 KuCoin 账户。为了您的账户安全，请务必采取以下预防措施：

不要将 API 密钥存储在公共位置，例如代码仓库或论坛。
定期轮换 API 密钥。
启用双重验证（2FA）以提高账户安全性。
监控您的账户活动，以检测任何可疑行为。

API 密钥的使用

为了安全地访问和使用我们的 API，您需要在每个 API 请求的头部中包含以下关键信息。这些信息用于验证您的身份并确保请求的完整性，从而保护您的账户和数据。

KC-API-KEY : 您的唯一标识符，即 API Key 。此密钥用于识别您的账户，类似于用户名。请务必妥善保管您的 API Key，切勿泄露给他人。
KC-API-SIGN : 使用您的 API Secret 和请求的具体内容生成的数字签名。此签名用于验证请求的真实性和完整性，防止数据在传输过程中被篡改。签名算法通常涉及哈希函数和密钥加密。
KC-API-TIMESTAMP : 请求发送的时间戳，以 Unix 时间戳格式表示，单位为秒。时间戳用于防止重放攻击，即攻击者截获并重复发送之前的有效请求。服务器会验证时间戳的有效性，拒绝过期或未来的请求。
KC-API-PASSPHRASE : 您的额外安全口令，即 API Passphrase (可选)。如果您的 API 密钥设置了 Passphrase，则必须包含此头部。 Passphrase 进一步增强了 API 密钥的安全性，类似于双重身份验证。
KC-API-KEY-VERSION : API 密钥的版本号，用于标识 API 的版本，目前为 2 。版本号的引入是为了支持 API 的更新和升级，确保客户端能够与服务器正确地交互。随着API的迭代，版本号可能会更新，因此请关注最新的API文档。

生成签名

签名是保障API请求安全的关键机制，用于验证请求的完整性和真实性。通过签名，KuCoin服务器可以确认请求确实来自授权用户，且请求内容未被篡改。KuCoin 使用 industry-standard 的 HMAC-SHA256 算法生成签名，确保安全性。

签名生成的步骤如下：

准备数据： 构造用于生成签名的消息字符串。该字符串由请求方法（GET、POST、PUT、DELETE，必须大写）、请求路径（例如：/api/v1/orders，包含版本信息）、时间戳（Unix时间戳，单位为秒）和请求体（如果是 POST 或 PUT 请求，则为JSON格式的请求体）按顺序拼接而成。务必确保各部分按照指定的顺序正确拼接。
HMAC-SHA256 加密： 使用您的 API Secret 作为密钥，对拼接后的消息字符串进行 HMAC-SHA256 加密。API Secret 必须妥善保管，切勿泄露。
Base64 编码： 将 HMAC-SHA256 加密后的二进制结果进行 Base64 编码。Base64 编码将二进制数据转换为文本格式，方便在HTTP头部传输。Base64 编码后的字符串即为最终的签名。

以下是一个使用 Python 生成签名的示例代码，展示了生成签名所需的所有步骤：

import hmac
import hashlib
import time
import base64

def generate_signature(api_secret, method, endpoint, timestamp, request_body=None):
"""
生成 KuCoin API 签名。

Args:
api_secret (str): API Secret.
method (str): 请求方法 (GET, POST, PUT, DELETE).
endpoint (str): 请求路径 (例如: /api/v1/orders).
timestamp (str): 请求的时间戳 (Unix 时间戳，单位为秒).
request_body (str, optional): 请求体 (JSON 字符串). Defaults to None.

Returns:
str: 生成的签名.
"""
if request_body:
message = timestamp + method + endpoint + request_body
else:
message = timestamp + method + endpoint
hmac_key = api_secret.encode('utf-8')
message = message.encode('utf-8')
signature = hmac.new(hmac_key, message, hashlib.sha256)
signature_b64 = base64.b64encode(signature.digest()).decode('utf-8')
return signature_b64

示例

api_secret = "YOUR_API_SECRET" # 务必将 "YOUR_API_SECRET" 替换为你账户实际的 API Secret。API Secret 用于对请求进行签名，确保请求的安全性。请妥善保管你的API Secret，切勿泄露给他人。如果泄露，恶意用户可能利用你的密钥进行非法操作，导致资金损失。

method = "GET" # 定义HTTP请求方法为 GET。 GET 方法用于从服务器请求数据。根据不同的API端点，可能需要使用 POST、PUT 或 DELETE 等其他方法。

endpoint = "/api/v1/symbols" # 指定API的端点为 "/api/v1/symbols"。这个端点用于获取交易对信息。 API端点是服务器上特定资源的位置。不同的API端点对应着不同的功能。请仔细阅读API文档，了解每个端点的用途和请求参数。

timestamp = str(int(time.time())) # 生成时间戳。 time.time() 返回当前时间的秒数。 int() 将其转换为整数， str() 将整数转换为字符串。时间戳用于确保请求的时效性，防止重放攻击。许多交易所要求在请求中包含时间戳，并且时间戳必须在一定的时间范围内（例如，前后5分钟）。

request_body = .dumps({"symbol": "BTC-USDT"}) # POST 请求示例

为了向交易所的API接口发送POST请求，我们通常需要构建一个JSON格式的请求体（request body）。这个例子展示了如何使用Python的 .dumps() 方法将一个Python字典转换成JSON字符串。字典 {"symbol": "BTC-USDT"} 指定了我们要查询或操作的交易对，在这个例子中，是比特币（BTC）对美元稳定币USDT的交易对。这个请求体随后会作为POST请求的数据发送到交易所的服务器。

signature = generate signature(api secret, method, endpoint, timestamp) #, request_body)

为了确保API请求的安全性，大多数加密货币交易所要求对请求进行签名。签名过程通常涉及使用你的API密钥（ api_secret ）以及请求的一些关键组成部分，例如HTTP方法（ method ，例如POST），API端点（ endpoint ，例如 /api/v1/order ），以及一个时间戳（ timestamp ）。有些交易所还会将请求体（ request_body ）纳入签名计算中。 generate_signature 函数是一个自定义函数，它使用特定的签名算法（例如HMAC-SHA256）来生成签名。这个签名随后会添加到请求头或请求参数中，以便交易所验证请求的真实性和完整性，防止恶意篡改。

print(f"生成的签名: {signature}")

在成功生成签名后，使用 print() 函数可以方便地在控制台中显示生成的签名值。这对于调试和验证签名算法是否正确至关重要。通过打印签名，开发者可以确认签名是否符合交易所API文档的要求，从而避免因签名错误而导致的API请求失败。 f"生成的签名: {signature}" 使用了Python的f-string格式化功能，将变量 signature 的值嵌入到字符串中，使其更易于阅读和理解。

常用 API 接口

以下介绍一些常用的 KuCoin API 接口，这些接口允许开发者与 KuCoin 交易所进行交互，获取市场数据、执行交易以及管理账户。

市场数据 API： 用于获取实时的市场行情数据，例如：

获取所有交易对行情： 提供所有交易对的最新价格、交易量、涨跌幅等信息。是构建行情展示和分析工具的基础。
获取单个交易对行情： 提供特定交易对的详细行情数据，包括最佳买卖价格、深度信息以及最近的成交记录。
获取 K 线数据： 提供指定时间周期的 K 线图数据，例如 1 分钟、5 分钟、1 小时等，用于技术分析。

交易 API： 用于进行交易操作，例如：

下单接口： 允许用户提交买单或卖单，支持市价单、限价单等多种订单类型。需要设置交易对、交易方向（买/卖）、数量和价格等参数。
撤单接口： 允许用户撤销未成交的订单。
查询订单接口： 允许用户查询订单的状态，包括未成交、部分成交和全部成交等。

账户 API： 用于管理账户信息，例如：

获取账户余额： 提供用户的资产余额信息，包括可用余额和冻结余额。
获取账户流水： 提供用户的资金变动记录，包括充值、提现和交易等。

在使用这些 API 接口之前，你需要注册一个 KuCoin 账户并创建 API 密钥。请务必妥善保管你的 API 密钥，避免泄露，并遵循 KuCoin 的 API 使用规范。

1. 获取所有交易对信息

Endpoint: /api/v1/symbols
Method: GET
用途: 获取 KuCoin 平台上所有可交易的交易对信息。此接口返回的数据涵盖了交易对的详细参数，方便用户了解市场概况和进行交易策略制定。
详细信息:
- 交易对名称 (symbol): 平台内唯一标识交易对的字符串，例如 "BTC-USDT"。
- 基本货币 (baseCurrency): 交易对中的基础货币，例如在 "BTC-USDT" 中，"BTC" 是基本货币。
- 计价货币 (quoteCurrency): 交易对中的计价货币，例如在 "BTC-USDT" 中，"USDT" 是计价货币。
- 最小交易数量 (baseMinSize): 允许交易的基础货币的最小数量，低于此数量的交易将被拒绝。此参数对于资金量较小的用户尤为重要。
- 价格精度 (priceIncrement): 价格变动的最小单位，例如 0.01 表示价格最小变动为 0.01 个计价货币单位。
- 数量精度 (quantityIncrement): 数量变动的最小单位，例如 0.001 表示数量最小变动为 0.001 个基础货币单位。
- 交易市场 (market): 标识交易对所属的市场类型，例如 "main" 或 "trade"。
- 启用状态 (enableTrading): 指示交易对是否允许交易，true 表示允许，false 表示禁止。
请求示例: 直接向 /api/v1/symbols 发送 GET 请求即可。
响应示例: 返回一个 JSON 数组，每个元素代表一个交易对的信息，包含上述详细信息。
注意事项: KuCoin 平台可能会不定期增加或移除交易对。建议定期调用此接口更新本地的交易对信息。

2. 获取单个交易对信息

Endpoint: /api/v1/symbols/
Method: GET
描述: 获取指定交易对的全面信息，包括但不限于交易对的交易状态、最小交易数量、价格精度、以及手续费比例等。此接口对于了解特定交易对的交易规则和参数至关重要。
参数:
- : 交易对名称，区分大小写。必须替换为有效的交易对代码，例如 BTC-USDT 代表比特币兑换USDT的交易对。错误的交易对代码将导致请求失败。
用途: 获取特定交易对的详细信息。通过将替换为具体的交易对名称 (例如 BTC-USDT )，可以检索该交易对的所有相关配置信息，这对于算法交易和策略开发至关重要。交易所通常会提供交易对列表，确保使用的值正确有效。
示例:
例如，要获取比特币与美元稳定币USDT的交易对信息，可以使用如下请求：
```
GET /api/v1/symbols/BTC-USDT
```
返回值:
该接口返回的JSON数据包含交易对的详细信息，例如：
- symbol : 交易对名称 (例如 BTC-USDT).
- status : 交易对当前状态 (例如 trading, halted).
- baseAsset : 基础货币 (例如 BTC).
- quoteAsset : 报价货币 (例如 USDT).
- tickSize : 价格最小变动单位.
- minQty : 最小交易数量.

3. 获取市场行情数据

Endpoint: /api/v1/market/stats
Method: GET
参数:
- symbol (可选, 字符串): 指定交易对，例如 BTC-USDT 。如果未指定，则返回所有交易对的市场统计信息。务必使用平台规定的交易对格式。
用途: 获取 KuCoin 平台上的市场行情数据，包括关键指标，例如最新成交价、24 小时成交量、24 小时最高价、24 小时最低价等。这些数据对于技术分析、风险评估和交易决策至关重要。返回的数据通常包含以下字段：
- symbol : 交易对代码，例如 BTC-USDT 。
- last : 最新成交价。
- volume : 24 小时成交量（以基础货币计价）。
- high : 24 小时最高价。
- low : 24 小时最低价。
- change : 24 小时价格变化。
- changeRate : 24 小时价格变化率。
- 其他与市场深度和流动性相关的统计数据。
开发者可以利用这些数据构建实时行情监控系统、量化交易策略和数据分析仪表板。请注意，API 调用频率可能有限制，建议阅读 KuCoin 官方 API 文档以了解速率限制和最佳实践。

4. 获取 K 线数据

Endpoint: /api/v1/market/candles
Method: GET
参数:
- symbol (必选): 交易对的唯一标识符，用于指定要查询的交易市场。例如， BTC-USDT 代表比特币兑美元泰达币的交易对。交易对的格式通常为 BASE-QUOTE ，其中 BASE 是基础货币，QUOTE 是计价货币。确保提供的交易对在交易所中存在且有效。
- type (必选): K 线的时间周期类型，决定了每个 K 线柱的持续时间。常用的类型包括 1min （1 分钟）， 5min （5 分钟）， 15min （15 分钟）， 30min （30 分钟）， 1hour （1 小时）， 4hour （4 小时）， 1day （1 天）， 1week （1 周）， 1month （1 个月）。选择合适的 K 线类型取决于交易策略的时间范围。更短的时间周期适用于日内交易，而更长的时间周期适用于长期投资分析。
- startAt (可选): 查询的起始时间点，以 Unix 时间戳（自 1970 年 1 月 1 日 00:00:00 UTC 起经过的秒数）表示。如果未提供，服务器通常会返回最近的 K 线数据。指定 startAt 可以获取特定时间段内的历史 K 线数据。
- endAt (可选): 查询的结束时间点，同样以 Unix 时间戳表示。如果未提供，服务器通常会返回到当前时间为止的 K 线数据。 startAt 和 endAt 共同定义了查询的时间范围，用于获取指定时间段内的 K 线数据。需要注意的是，某些交易所或 API 可能会对请求的时间范围大小有限制。
用途: 获取指定交易对在特定时间范围内的 K 线图数据，用于技术分析、价格趋势预测和交易策略制定。返回的数据通常包含开盘价 (Open)、最高价 (High)、最低价 (Low)、收盘价 (Close) 和成交量 (Volume) 等信息，这些数据是进行量化分析和算法交易的基础。通过分析 K 线图，可以识别价格形态、趋势线和支撑阻力位，从而辅助交易决策。

5. 创建订单

Endpoint: /api/v1/orders
Method: POST
请求体:

该请求体是一个 JSON 对象，用于指定创建订单的详细参数。以下是每个字段的详细说明：


{
  "clientOid": "YOUR_CLIENT_ORDER_ID",  // 客户端自定义订单 ID，用于唯一标识订单。强烈建议使用 UUID 等方式生成，保证唯一性，方便后续订单查询和管理。长度限制通常为 64 字符。
  "side": "buy",                      // 交易方向：`buy` (买入) 或 `sell` (卖出)。大小写敏感。
  "type": "market",                    // 订单类型：`market` (市价单)、`limit` (限价单)、`stop_market` (止损市价单)、`stop_limit` (止损限价单)。市价单会立即以当前市场最优价格成交，限价单则会以指定价格或更优价格成交。止损单在价格达到预设的止损价格时触发。
  "symbol": "BTC-USDT",                 // 交易对，例如 "BTC-USDT"、"ETH-BTC"。交易对必须是平台支持的。
  "size": "0.001",                    // 交易数量 (对于市价买单，则不需要提供此字段，而是提供 `funds` 字段)。数量必须大于平台允许的最小交易数量。
  "price": "10000",                   // 交易价格 (仅对于限价单和止损限价单有效)。如果买入，则以指定价格或更低价格成交；如果卖出，则以指定价格或更高价格成交。
  "funds": "10",                      // 交易金额 (仅对于市价买单有效)。表示希望用多少金额的计价货币来购买标的货币。
  "stop": "down",                     // 止损方向：`up` (价格高于 `stopPrice` 时触发) 或 `down` (价格低于 `stopPrice` 时触发) (仅对于止损单有效)。
  "stopPrice": "9000",                  // 止损价格 (仅对于止损单有效)。当市场价格达到此价格时，止损单会被触发，并按照指定的订单类型（市价或限价）下单。
  "timeInForce": "GTC",               // 有效时间：`GTC` (Good-Til-Canceled，直到取消)、`IOC` (Immediate-Or-Cancel，立即成交或取消)、`FOK` (Fill-Or-Kill，全部成交或取消)。`GTC` 表示订单会一直有效，直到被手动取消；`IOC` 表示订单会尝试立即以指定价格成交，剩余未成交的部分会被立即取消；`FOK` 表示订单必须全部以指定价格成交，否则会被立即取消。
  "postOnly": false,                   // 是否只挂单 (仅对于限价单有效，如果设置为 `true`，则该订单只能作为挂单，不能与现有订单成交，避免吃单)。如果设置为 `true`，则该订单如果会立即成交，则会被自动取消。
  "hidden": false,                    // 是否隐藏订单 (如果设置为 `true`，则该订单不会显示在订单簿上，成为隐藏订单)。隐藏订单可以避免被其他交易者看到，从而减少交易策略被窥探的风险。
  "iceberg": false,                   // 是否是冰山订单 (如果设置为 `true`，则该订单会以小批量分批执行，防止大额订单对市场价格产生较大影响)。
  "visibleSize": "0.0001"              // 冰山订单可见数量 (仅当 `iceberg` 为 `true` 时有效)。表示在订单簿上显示的冰山订单的可见部分数量。
}

注意事项：

所有数值类型的字段，都应该以字符串的形式传递，避免精度丢失。
不同的订单类型，需要的参数也不同。例如，市价单不需要 `price` 字段，而限价单和止损单则需要。
在创建订单之前，应该仔细检查所有参数，确保其准确无误，避免不必要的损失。
请参考API文档中关于错误码的说明，以便更好地处理创建订单可能出现的错误。
部分平台对于api调用有频率限制，请注意遵守平台的限制规则。

用途: 创建一个新的订单。

6. 取消订单

Endpoint: /api/v1/orders/
Method: DELETE
描述: 取消指定的订单。用户可以通过此接口取消尚未完全成交的挂单。一旦订单成功取消，系统将释放冻结的资金或加密货币。
参数:
- : 订单ID。这是一个必需参数，用于指定需要取消的订单。请务必使用正确的订单ID，否则可能导致取消失败或影响其他订单。订单ID通常由交易所的交易系统生成。
请求示例:
假设需要取消的订单ID为 123456789 ，则请求的URL应为：
DELETE /api/v1/orders/123456789
响应:
成功取消订单后，服务器通常会返回一个包含取消状态的JSON响应。例如：
{ "status": "cancelled", "orderId": "123456789" }
如果取消失败，服务器会返回相应的错误信息，例如：
{ "error": "Order not found" }
注意事项:
- 只有状态为“未成交”或“部分成交”的订单才能被取消。已完全成交或正在处理中的订单无法取消。
- 频繁取消订单可能会受到交易所的限制。
- 在调用取消订单接口之前，请务必确认订单ID的准确性。
- 网络延迟可能导致取消请求失败。请确保您的网络连接稳定。

7. 获取单个订单信息

Endpoint: /api/v1/orders/
Method: GET
用途: 获取指定订单的详细信息。
说明:
- 此接口允许您检索特定订单的完整数据，包括订单创建时间、订单状态、交易对、订单类型、订单数量、订单价格以及其他相关参数。
- 必须替换为实际有效的订单 ID。订单ID通常是一个唯一的字符串或者数字，由交易平台在订单创建时自动生成。
- 请确保您拥有访问此接口所需的有效 API 密钥和权限，且API密钥具有读取订单信息的权限。权限不足可能导致请求失败。
- 请求成功后，服务器将返回一个 JSON 对象，其中包含订单的所有详细信息。请根据API文档解析JSON结构，提取所需字段。
- 如果指定的不存在，服务器通常会返回一个 404 (Not Found) 错误，并附带错误信息。
请求示例:
假设要获取 ID 为 1234567890 的订单信息，则请求的 URL 为： /api/v1/orders/1234567890

响应示例 (成功):

            
            {
              "orderId": "1234567890",
              "symbol": "BTC/USDT",
              "orderType": "LIMIT",
              "side": "BUY",
              "quantity": 0.01,
              "price": 50000.00,
              "status": "FILLED",
              "timestamp": 1678886400000,
              "fee": 0.0001,
              "feeAsset": "BTC"
            }

响应示例 (失败 - 订单不存在):

            
            {
              "code": 404,
              "message": "Order not found"
            }

8. 获取账户余额

接口端点 (Endpoint): /api/v1/accounts
请求方式 (Method): GET
请求参数 (Parameters):
- currency (可选, 字符串类型): 指定要查询的币种。如果未提供此参数，将返回所有币种的账户余额信息。例如， currency=BTC 将只返回比特币账户的余额信息。
功能描述 (Purpose): 该接口用于获取您的账户余额信息。返回的数据包含可用余额 (Available Balance) 和冻结余额 (Frozen Balance)。可用余额指的是可以立即用于交易或提现的资产数量，而冻结余额指的是由于未完成的订单或其他原因而暂时无法使用的资产数量。该接口对于追踪您的账户资产状态至关重要。
返回数据结构 (Response Data Structure): 返回的是一个JSON数组，数组中的每个元素代表一个币种的账户余额信息。每个元素包含以下字段：
- currency (字符串类型): 币种代码，例如 "BTC", "ETH", "USDT"。
- available (数值类型): 可用余额，可以进行交易或提现的余额数量。
- frozen (数值类型): 冻结余额，由于未完成的订单或其他原因暂时无法使用的余额数量。
- total (数值类型): 总余额，等于可用余额加上冻结余额的总和。

示例 (Example):

请求 (Request): GET /api/v1/accounts?currency=ETH

响应 (Response):


  [
    {
      "currency": "ETH",
      "available": "1.5",
      "frozen": "0.2",
      "total": "1.7"
    }
  ]

注意事项 (Notes):
- 请确保您的API密钥拥有足够的权限来访问此接口。
- 高频请求可能会受到API限流的影响。请合理控制请求频率。
- 返回的余额数量精度取决于平台设置，请注意精度问题。
- 如果账户中没有任何余额，也可能会返回一个空数组。

错误处理

KuCoin API 的响应数据中， code 字段扮演着关键角色，它标明了请求的处理状态。开发者应重视此字段，以便程序能够准确识别并妥善处理各种情况。以下列出一些常见的错误代码及其含义，供参考：

200000 : 请求已成功处理。这意味着您的请求已顺利通过验证，服务器已成功执行操作并返回预期结果。
400000 : 客户端请求错误，通常由于以下原因导致：
- 参数错误 ：请求中包含无效或格式不正确的参数。请仔细检查请求参数的名称、类型和值，确保符合 API 文档的要求。
- 签名错误 ：请求的签名不正确。签名用于验证请求的完整性和真实性，防止数据被篡改。请检查您的 API 密钥是否正确，以及签名算法是否正确实现。
- 其他客户端错误 ：例如，请求体格式错误、缺少必要的请求头等。
401000 : 身份验证失败，表明您提供的身份验证信息无法通过验证。可能的原因包括：
- API 密钥无效 ：您提供的 API 密钥已过期、被禁用或根本不存在。请确保证您使用的 API 密钥是有效的，并且具有执行所需操作的权限。
- 签名错误 ：即使 API 密钥正确，签名错误也会导致身份验证失败。请仔细检查您的签名算法实现。
- IP 地址限制 ：如果您的 KuCoin 账户启用了 IP 地址限制，并且发起请求的 IP 地址不在允许列表中，则身份验证将会失败。
403000 : 权限不足，表示您没有执行该操作所需的权限。这通常是因为您的 API 密钥不具备相应的权限。您需要在 KuCoin 账户中为 API 密钥分配相应的权限，才能执行该操作。
429000 : 频率限制，表明您的请求频率过高，已超出 API 的限制。为了保护服务器的稳定性和可用性，KuCoin 对 API 请求的频率进行了限制。您需要降低请求频率，或使用更高级别的 API 密钥（如果可用），以获得更高的频率限制。常见的应对策略包括：
- 实施速率限制器 ：在您的应用程序中实现一个速率限制器，以控制 API 请求的频率。
- 使用批量请求 ：如果 API 支持批量请求，您可以将多个操作合并到一个请求中，以减少请求的数量。
- 缓存数据 ：对于不经常变化的数据，您可以将其缓存到本地，以减少对 API 的请求次数。
- 使用 WebSocket API ：对于需要实时更新的数据，可以考虑使用 KuCoin 的 WebSocket API，而不是轮询 API。
500000 : 服务器内部错误，表示 KuCoin 服务器在处理您的请求时发生了意外错误。这通常是由于服务器端的故障或错误引起的，您无法通过修改您的请求来解决此问题。您可以稍后重试该请求，或联系 KuCoin 的技术支持团队寻求帮助。

在编写与 KuCoin API 交互的代码时，请务必仔细检查每个 API 响应的 code 字段。根据不同的错误代码，采取相应的处理措施，例如重试请求、记录错误日志、向用户显示错误信息等。KuCoin API 响应通常还包含 msg 字段，其中包含更详细的错误信息，可以帮助您更好地理解错误的原因并采取正确的措施。在开发过程中，充分利用 code 和 msg 字段，可以显著提高程序的健壮性和用户体验。

频率限制

KuCoin API 实施频率限制机制，旨在防止恶意滥用，保障整个交易平台的稳定性及性能。不同的 API 端点（endpoint）具有不同的请求速率限制策略。当您的应用程序发送的请求超过了该限制，API 将返回一个 429000 错误代码，表明请求已被限制。

为了确保应用程序的正常运行，避免触发 API 频率限制，建议您采取以下策略：

优化应用程序设计： 仔细评估并优化您的应用程序逻辑，避免不必要的或重复的 API 调用。分析数据需求，仅在需要时才请求数据。
利用批量请求功能： 针对支持批量请求的 API 端点，尽可能地将多个操作合并为一个请求。这可以显著减少所需的请求总数，提高效率并降低触发限制的风险。
实施重试机制： 当遇到 429000 错误代码时，立即停止发送请求并等待一段适当的时间（例如，几秒到几分钟）。使用指数退避算法，逐渐增加重试间隔，以避免进一步加剧服务器负载。
查阅官方文档： 详细阅读 KuCoin 官方 API 文档，全面了解所有 API 端点的具体频率限制规则。不同端点可能具有不同的限制，务必根据实际使用情况进行调整。文档中通常会提供关于请求配额、重置时间等重要信息。
使用 WebSocket API： 对于实时数据更新的需求，优先考虑使用 KuCoin 提供的 WebSocket API。WebSocket 协议允许建立持久连接，从而减少了轮询 API 的需求，更加高效地获取数据。
缓存常用数据： 将不经常变动的 API 响应数据缓存在本地或服务器端。这可以显著减少对 API 的请求次数，特别是在用户界面展示或计算中使用静态数据时。
监控 API 使用情况： 监控应用程序的 API 请求数量和频率，可以帮助您及时发现潜在的性能问题或过度使用情况，并采取相应措施进行优化。

注意事项

安全性： API 密钥是访问 KuCoin API 的凭证，务必妥善保管，切勿泄露给任何未经授权的第三方。为了防止密钥泄露，绝对不要将 API 密钥直接硬编码到客户端代码（例如 JavaScript 或移动应用）中。推荐的做法是将 API 密钥存储在服务器端环境中，并使用安全的方式进行管理和访问，比如环境变量或加密的配置文件。定期轮换您的 API 密钥也是一种重要的安全措施，可以降低密钥泄露带来的风险。同时，启用 KuCoin 提供的双重验证（2FA）可以进一步增强账户的安全性。
数据精度： KuCoin API 返回的交易数据，特别是价格和数量，通常具有很高的精度，以确保准确反映市场信息。在处理这些数据时，需要根据应用程序的具体需求选择合适的数据类型和处理方式，避免因精度损失导致计算错误或显示问题。例如，可以使用高精度的数据类型（如 Decimal）来存储和计算价格和数量。同时，需要注意不同交易对的精度要求可能不同，需要根据 KuCoin 官方文档进行配置。
异常处理： 在调用 KuCoin API 时，可能会遇到各种异常情况，例如网络连接问题、API 服务器故障、请求参数错误、API 速率限制等。为了确保应用程序的稳定性和可靠性，务必进行全面的异常处理。可以使用 try-except 块来捕获和处理异常，并根据不同的异常类型采取相应的措施，例如重试请求、记录错误日志、向用户显示友好的错误提示等。同时，需要注意处理 API 速率限制，避免因频繁请求而被 API 服务器拒绝服务。
API 文档： KuCoin 官方 API 文档是使用 KuCoin API 的重要参考资料，包含了各个接口的详细信息、参数说明、返回值格式、错误码定义、使用示例等。在使用 KuCoin API 之前，务必仔细阅读 API 文档，了解各个接口的功能和使用方法。同时，需要关注 API 文档的更新，及时了解 API 的最新变化和最佳实践。 KuCoin 官方文档通常提供多种语言的版本，可以选择自己熟悉的语言进行阅读。
版本更新： KuCoin API 会不断更新和改进，以提供更强大的功能和更好的性能。为了保持应用程序与 KuCoin API 的兼容性，需要定期关注 KuCoin API 的版本更新，并及时更新您的应用程序。升级 API 版本可能涉及到修改代码、调整配置等，需要进行充分的测试，确保应用程序能够正常运行。 KuCoin 通常会提前发布 API 版本更新的公告，以便开发者做好准备。

示例代码

以下是一个使用 Python 调用 KuCoin API 获取交易对信息的示例代码，演示了如何进行身份验证并检索市场数据。请务必安全地存储和管理您的 API 密钥和密钥。

requests 库用于发送 HTTP 请求， time 模块用于获取时间戳，而用户定义的 generate_signature 函数负责创建请求签名。安装必要的库： pip install requests 。

import requests
import time
import 
from your_signature_function import generate_signature   # 替换为你的签名生成函数

# 替换为你的 API 凭证，务必妥善保管。
api_key = "YOUR_API_KEY"
api_secret = "YOUR_API_SECRET"
api_passphrase = "YOUR_API_PASSPHRASE"

# KuCoin API 的基础 URL 和所需接口。
base_url = "https://api.kucoin.com"
endpoint = "/api/v1/symbols"
method = "GET"
timestamp = str(int(time.time()))

# 调用签名函数生成请求签名
signature = generate_signature(api_secret, method, endpoint, timestamp, api_passphrase)

# 构造请求头，包含 API 密钥、签名、时间戳和版本信息。
headers = {
    "KC-API-KEY": api_key,
    "KC-API-SIGN": signature,
    "KC-API-TIMESTAMP": timestamp,
    "KC-API-PASSPHRASE": api_passphrase,
    "KC-API-KEY-VERSION": "2"  # 指定API版本
}

# 构建完整的 URL
url = base_url + endpoint

# 发送 GET 请求并处理响应。
try:
    response = requests.get(url, headers=headers)
    response.raise_for_status()  # 抛出 HTTPError 异常 (如果请求状态码不是 200)
    data = response.()  # 将响应内容解析为 JSON 格式
    print(.dumps(data, indent=4))   # 格式化输出 JSON 数据，方便阅读
except requests.exceptions.RequestException as e:
    print(f"请求发生错误: {e}")
except .JSONDecodeError as e:
    print(f"JSON 解码错误: {e}")
except Exception as e:
    print(f"发生未知错误：{e}")

请务必安装 requests 库。 pip install requests 。示例代码使用 KuCoin API V2 版本，确保 KC-API-KEY-VERSION 设置正确。签名生成函数的实现会依赖于具体的签名算法要求，需要根据 KuCoin 官方文档进行调整。需要处理可能出现的网络连接错误、API 调用频率限制、以及数据格式错误等情况，建议添加适当的错误处理机制，并记录日志以便调试和分析。

注意： generate_signature 函数需要你自己实现，需要根据 KuCoin 官方文档提供的签名算法生成签名。该签名函数通常需要使用你的 API Secret 和请求参数进行加密计算。请阅读 KuCoin API 文档以获取正确的签名算法实现。

上述代码仅为示例，您需要根据您的实际需求进行修改，并妥善保管你的 API 密钥和密码。在实际应用中，建议对 API 密钥进行加密存储，避免泄露。

# 上一篇：欧易一键平仓攻略：快速止损，锁定利润？必看！

# 下一篇：欧易OKX账号被冻结？别慌！恢复攻略限时速递！