KuCoin自动交易API：入门精通指南与账户设置

日期：2025-03-01 栏目：文档浏览：40

KuCoin 自动交易 API 使用指南：从入门到精通

准备工作：账户设置与 API Key 获取

在开始探索 KuCoin 自动交易 API 的强大功能之前，必须进行一些必要的准备工作。需要拥有一个 KuCoin 账户。如果尚未注册，请访问 KuCoin 官方网站注册账户，并完成 KYC（了解你的客户）身份验证。KYC 验证通常需要上传身份证明文件，例如护照或身份证，并可能需要进行人脸识别，以确保账户所有者的真实身份。

账户设置完成后，下一步是生成 API Key。API Key 是访问 KuCoin API 的凭证，类似于账户的密码，但专门用于程序化交易。务必妥善保管 API Key，切勿泄露给任何第三方。泄露 API Key 可能会导致账户资金损失或其他安全问题。

生成 API Key 的详细步骤如下：

使用您的账户凭据登录 KuCoin 账户。
点击用户头像，在下拉菜单中选择“API 管理”选项，进入 API 管理页面。
在 API 管理页面，点击“创建 API”按钮，开始创建新的 API Key。
根据您的具体需求，详细设置 API 权限。KuCoin API 提供了多种权限选项，包括：
- 交易权限：允许程序执行买卖操作，例如下单、取消订单等。
- 提现权限：允许程序提取账户中的资金。 请谨慎授予此权限，并仅在绝对必要时使用。
- 只读权限：允许程序获取账户信息，例如余额、交易历史等，但不能执行任何交易操作。这是最安全的权限选项，适用于只需要监控账户数据的场景。
根据实际需求选择合适的权限组合。 强烈建议遵循最小权限原则，仅授予 API Key 完成其任务所需的最低权限，以最大限度地降低潜在的安全风险。 例如，如果您的程序只需要读取市场数据，则只需授予只读权限。
设置 API Key 的名称和描述，方便您管理和识别不同的 API Key。使用有意义的名称和描述，例如“量化交易机器人”或“监控脚本”，可以帮助您轻松区分不同的 API Key，并在将来进行管理。
输入您的 KuCoin 交易密码和 Google 验证码（如果启用了 Google 双重验证）。Google 双重验证是一种额外的安全措施，可以有效防止账户被盗。如果您尚未启用，强烈建议启用 Google 双重验证。
点击“创建”按钮，系统将生成您的 API Key。

成功生成 API Key 后，您会获得 API Key、Secret Key 和 Passphrase 三个关键值。这三个值是访问 KuCoin API 的必要凭证，务必妥善保存。

API Key：用于标识您的身份。
Secret Key：相当于您的 API Key 的密码，用于验证您的请求。 Secret Key 的保密性至关重要，一旦泄露，您的账户可能会面临严重的风险。 请勿将 Secret Key 存储在不安全的地方，例如公共代码仓库或聊天记录中。
Passphrase：您在创建 API Key 时设置的密码，用于加密您的 API 请求。Passphrase 可以增加 API 请求的安全性。

请将这三个值安全地存储在您信任的地方，例如密码管理器或加密文件中。

API 接口概览：常用功能与调用方式

KuCoin API 提供了全面的功能，覆盖现货交易、杠杆交易、合约交易，以及市场行情数据、账户资产管理等关键领域。通过这些API接口，开发者可以构建自动化交易机器人、行情分析工具、以及个性化的交易应用。以下是一些常用的 API 接口及其功能，以及简要的调用方式说明：

行情数据接口:

GET /api/v1/market/tickers : 获取所有交易对的实时 ticker 信息。此接口提供关键市场概览，包括但不限于最新成交价、24小时成交量、24小时最高价、24小时最低价，以及24小时涨跌幅。通过此接口，用户可以快速了解整个市场的动态，监测特定交易对的表现。返回的数据格式通常为JSON，包含每个交易对的详细统计数据，方便程序化交易和数据分析。
GET /api/v1/market/orderbook/level2_{depth} : 获取指定交易对的 Level 2 深度行情数据。此接口提供市场深度视图，展示买单和卖单的分布情况。 {depth} 参数控制返回的深度层数，可以是 20 或 100，分别表示返回买卖盘前20档或前100档的报价。买一价、卖一价、买一量、卖一量等关键数据均包含在内，帮助用户更准确地评估市场供需关系，进行更精细的交易决策。高频交易者和机构投资者通常依赖此接口获取实时市场深度信息。数据格式为JSON，包含价格和数量的有序列表。
GET /api/v1/market/candles : 获取指定交易对的历史 K 线数据。 K 线图是技术分析的基础工具，通过此接口可以获取不同时间周期的 K 线数据，包括开盘价、收盘价、最高价、最低价以及成交量。时间周期可以灵活指定，例如 1 分钟 (1m)、5 分钟 (5m)、15 分钟 (15m)、30 分钟 (30m)、1 小时 (1h)、4 小时 (4h)、1 天 (1d)、1 周 (1w)、1 月 (1M) 等。这些数据对于分析历史价格趋势、识别支撑位和阻力位、以及制定交易策略至关重要。返回的数据通常为JSON数组，每个元素代表一个K线，包含时间戳和价格数据。

交易接口:

POST /api/v1/orders : 创建新的订单。此接口允许用户提交订单至交易平台，参与加密货币的买卖。请求体需包含必要的订单参数，例如：
- 交易对 (Symbol) : 指定交易的币对，例如 BTC/USDT 。
- 交易类型 (Side) : 指示交易方向， BUY 表示买入， SELL 表示卖出。
- 订单类型 (Type) : 定义订单的执行方式。
  - MARKET : 市价单，以当前市场最优价格立即成交。只需指定数量，无需价格。
  - LIMIT : 限价单，指定期望的买入或卖出价格。只有当市场价格达到或优于指定价格时，订单才会成交。
- 数量 (Quantity) : 交易的加密货币数量。
- 价格 (Price) : 仅在限价单中需要，指定期望的成交价格。
- 时间有效机制（Time in Force）： 订单在交易所中有效的时间范围, 可选参数包括 GTC (Good-Til-Cancelled，直到取消)， IOC (Immediate-Or-Cancel，立即成交或取消)和 FOK (Fill-Or-Kill，完全成交或取消)
- 客户自定义订单ID（Client Order ID）： 允许用户自定义订单ID，方便后续追踪和对账。
服务端会验证请求参数的有效性，例如交易对是否存在、账户余额是否足够、价格是否合理等。成功创建订单后，返回订单ID。
GET /api/v1/orders/ : 获取指定订单的详细信息。通过提供唯一的订单ID，可以查询订单的当前状态、成交数量、平均成交价格等。订单状态可能包括 PENDING (待成交)、 PARTIALLY_FILLED (部分成交)、 FILLED (完全成交)、 CANCELED (已取消)、 REJECTED (已拒绝)。接口返回的信息一般包括订单的所有参数，成交明细，手续费等。
DELETE /api/v1/orders/ : 取消指定订单。只有状态为 PENDING 或 PARTIALLY_FILLED 的订单才能被取消。一旦订单被成功取消，其状态将变为 CANCELED 。交易所会尽快取消订单，但是可能存在极小概率订单在取消请求处理完成之前成交的情况。
GET /api/v1/orders : 获取用户的历史订单记录。此接口支持分页和过滤，允许用户根据交易对、订单状态、时间范围等条件查询历史订单。常见的过滤条件包括：
- 交易对 (Symbol) : 只返回特定交易对的订单。
- 订单状态 (Status) : 只返回特定状态的订单，例如 FILLED 或 CANCELED 。
- 起始时间 (StartTime) 和 结束时间 (EndTime) : 只返回指定时间范围内的订单。
- 分页 (Pagination) : 通过 limit 和 offset 参数控制返回结果的数量和起始位置。
返回结果通常按照时间倒序排列，方便用户查看最近的交易记录。

账户接口:

GET /api/v1/accounts : 获取用户的账户信息，涵盖所有可用币种的详细余额，包括可用余额、冻结余额以及总余额，方便用户全面了解其资产状况。
GET /api/v1/fills : 获取用户的成交历史记录，提供灵活的筛选功能，允许用户指定交易对(如 BTC-USDT)、时间范围、交易类型（买入或卖出）等条件进行精确查询，以便进行交易分析和策略回顾。

要调用 KuCoin API，开发者需要构建 HTTP 请求，常用的编程语言包括 Python (requests 库)、Java (OkHttp 或 Apache HttpClient) 和 Node.js (Axios 或 node-fetch)。每个 API 请求的构建都需细致考虑以下组成部分：

URL: API 接口的完整地址，需根据所请求的具体功能准确填写，例如现货交易、合约交易或者资金划转等。
Method: HTTP 请求方法，根据 API 的功能选择合适的请求方法。 GET 用于获取数据， POST 用于创建或更新数据， DELETE 用于删除数据。
Headers: HTTP 请求头，包含身份验证信息和可选参数，例如指定返回数据的格式 (Content-Type: application/) 或者接受的语言类型 (Accept-Language)。
Body: HTTP 请求体，以 JSON 格式传递请求参数，对于 POST、PUT 等需要提交数据的请求，必须将参数按照 API 文档的要求构建成 JSON 字符串。

身份验证信息必须安全地包含在 HTTP 请求头中，用于验证请求的合法性，确保只有授权用户才能访问 API：

KC-API-KEY : 用户的 API Key，用于标识用户的身份。
KC-API-SIGN : 使用 Secret Key 生成的请求签名，防止请求被篡改。
KC-API-TIMESTAMP : Unix 时间戳，精确到秒，用于防止重放攻击。
KC-API-PASSPHRASE : 创建 API Key 时设置的 Passphrase，进一步增强安全性。
KC-API-KEY-VERSION : API Key 的版本号，当前版本为 2 ，未来可能会有更新。

请求签名的生成过程至关重要，确保签名的准确性是 API 调用成功的关键：

将 HTTP 请求方法（例如 "GET" 或 "POST"）、完整的 API 接口路径（例如 "/api/v1/accounts"）、时间戳（Unix 时间戳的字符串形式）以及请求体（如果存在，则为 JSON 字符串；如果不存在，则为空字符串 ""）按照顺序拼接成一个字符串。
使用用户的 Secret Key 对拼接后的字符串进行 SHA256 哈希运算，生成哈希值。
将 SHA256 哈希结果进行 Base64 编码，得到最终的请求签名。在不同编程语言中，需要注意字符编码和库函数的选择，以确保签名结果一致。

代码示例：使用 Python 调用 KuCoin API

以下是一个使用 Python 调用 KuCoin API 获取账户信息的示例代码。该代码展示了如何通过 API 密钥、密钥密码和时间戳生成签名，并使用该签名向 KuCoin 服务器发送经过身份验证的请求。

import hashlib import hmac import base64 import time import requests

这段代码导入了必要的 Python 库： hashlib 用于哈希计算， hmac 用于生成基于密钥的消息认证码， base64 用于编码数据， time 用于获取当前时间戳， requests 用于发送 HTTP 请求。

使用 KuCoin API 密钥、密钥密码和 API 端点地址等必要参数：

api_key = 'YOUR_API_KEY' api_secret = 'YOUR_API_SECRET' api_passphrase = 'YOUR_API_PASSPHRASE' base_url = 'https://api.kucoin.com' endpoint = '/api/v1/accounts'

请将 YOUR_API_KEY , YOUR_API_SECRET 和 YOUR_API_PASSPHRASE 替换为你在 KuCoin 平台获取的实际值。

定义一个函数来生成 KuCoin API 请求所需的签名：

def generate_signature(timestamp, method, request_path, body, secret): message = timestamp + method + request_path + body hmac_key = base64.b64decode(secret) signature = hmac.new(hmac_key, message.encode('utf-8'), hashlib.sha256) signature_b64 = base64.b64encode(signature.digest()).decode('utf-8') return signature_b64

该函数接受时间戳、HTTP 方法、请求路径、请求体和 API 密钥作为输入，并返回一个使用 HMAC-SHA256 算法生成的 Base64 编码的签名。签名对于KuCoin API 身份验证至关重要。

构建请求头：

timestamp = str(int(time.time() * 1000)) method = 'GET' request_path = endpoint body = '' signature = generate_signature(timestamp, method, request_path, body, api_secret) headers = { 'KC-API-KEY': api_key, 'KC-API-SIGN': signature, 'KC-API-TIMESTAMP': timestamp, 'KC-API-PASSPHRASE': api_passphrase, 'KC-API-KEY-VERSION': '2', 'Content-Type': 'application/' }

这段代码创建了请求头，其中包含了API密钥（ KC-API-KEY ）、签名（ KC-API-SIGN ）、时间戳（ KC-API-TIMESTAMP ）和密钥密码（ KC-API-PASSPHRASE ）。 KC-API-KEY-VERSION 设置为 '2' 表示使用API密钥的v2版本。

发送 API 请求：

url = base_url + endpoint response = requests.get(url, headers=headers) if response.status_code == 200: print(response.()) else: print(f"请求失败，状态码：{response.status_code}, 响应内容：{response.text}")

这段代码构建了完整的 URL，并使用 requests 库发送 GET 请求。如果响应状态码为 200，则表示请求成功，并打印响应的 JSON 数据。否则，打印错误信息和状态码。

替换为你的 API Key、Secret Key 和 Passphrase

为了安全地访问 KuCoin API，你需要替换以下占位符为你自己的 API 凭证。这些凭证允许你代表你的账户执行操作，例如获取账户信息、下单交易等。

API_KEY = "YOUR_API_KEY"

SECRET_KEY = "YOUR_SECRET_KEY"

PASSPHRASE = "YOUR_PASSPHRASE"

API Key: 你的 API Key 是一个公开标识符，用于识别你的应用程序或账户。

Secret Key: 你的 Secret Key 是一个私密密钥，用于签署 API 请求。务必妥善保管此密钥，不要与他人分享，因为它允许任何人模拟你的身份。

Passphrase: 你的 Passphrase 是一个额外的安全层，用于保护你的 API 密钥。它必须在每个请求中提供，以验证你的身份。

def generate_signature(endpoint, method, timestamp, request_body):

"""生成请求签名."""

message = timestamp + method + endpoint + (request_body if request_body else "")

hmac_key = SECRET_KEY.encode('utf-8')

message_bytes = message.encode('utf-8')

signature = hmac.new(hmac_key, message_bytes, hashlib.sha256).digest()

signature_b64 = base64.b64encode(signature).decode('utf-8')

return signature_b64

generate_signature 函数是生成 KuCoin API 请求签名流程的核心。它使用你的 Secret Key 对请求的关键要素（时间戳、HTTP 方法、API 端点和请求正文）进行哈希处理，从而创建一个唯一的签名。此签名用于验证请求的完整性和真实性。

函数参数说明：

endpoint : 你要调用的 KuCoin API 端点，例如 "/api/v1/accounts"。
method : HTTP 请求方法，例如 "GET"、"POST"、"PUT" 或 "DELETE"。
timestamp : 请求发起时的时间戳，以毫秒为单位。
request_body : 如果请求包含正文（例如，POST 请求中的 JSON 数据），则此参数包含该正文。否则，它为空字符串。

签名生成步骤：

将时间戳、HTTP 方法、API 端点和请求正文连接成一个字符串。
使用你的 Secret Key 作为密钥，对该字符串进行 HMAC-SHA256 哈希处理。
将哈希结果进行 Base64 编码。
返回 Base64 编码后的签名。

def get_accounts():

"""获取账户信息."""

endpoint = "/api/v1/accounts"

method = "GET"

timestamp = str(int(time.time() * 1000))

request_body = ""

signature = generate_signature(endpoint, method, timestamp, request_body)

get_accounts 函数演示了如何调用 KuCoin API 的 /api/v1/accounts 端点来获取账户信息。此函数封装了构建请求、生成签名和处理响应的必要步骤。

函数执行流程：

定义 API 端点 ( /api/v1/accounts ) 和 HTTP 方法 ( GET )。
获取当前时间戳（以毫秒为单位）。
由于这是一个 GET 请求，因此请求正文为空。
调用 generate_signature 函数生成请求签名。

headers = {

"KC-API-KEY": API_KEY,

"KC-API-SIGN": signature,

"KC-API-TIMESTAMP": timestamp,

"KC-API-PASSPHRASE": PASSPHRASE,

"KC-API-KEY-VERSION": "2",

"Content-Type": "application/"

}

这些是发送到 KuCoin API 的 HTTP 请求头。它们包含你的 API 密钥、签名、时间戳、密码和 API 密钥版本等身份验证和授权信息。正确设置这些标头对于成功调用 API 至关重要。

标头字段说明：

KC-API-KEY : 你的 API Key。
KC-API-SIGN : 使用你的 Secret Key 生成的请求签名。
KC-API-TIMESTAMP : 请求发起时的时间戳（以毫秒为单位）。
KC-API-PASSPHRASE : 你的 Passphrase。
KC-API-KEY-VERSION : API 密钥版本。使用版本 "2"。
Content-Type : 请求体的 MIME 类型。在此示例中，假设我们发送或接收 JSON 数据。

url = "https://api.kucoin.com" + endpoint

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

此代码行使用 Python 的 requests 库向 KuCoin API 发送 GET 请求。它将 API 根 URL 与端点组合在一起以创建完整的 URL，并将包含身份验证信息的标头传递给请求。

requests.get(url, headers=headers) 函数执行以下操作：

构造一个 HTTP GET 请求。
将请求发送到指定的 URL ( https://api.kucoin.com/api/v1/accounts )。
在请求中包含指定的标头。
返回一个 response 对象，其中包含 API 响应的状态码、标头和正文。

if response.status_code == 200:

return response.()

else:

print(f"Error: {response.status_code} - {response.text}")

return None

此代码块检查 API 请求是否成功。如果响应状态码为 200（表示成功），则该函数将解析 JSON 响应并将其返回。否则，它将打印一条错误消息，其中包含状态码和响应文本，并返回 None 。

if __name__ == "__main__":

accounts = get_accounts()

if accounts:

print(.dumps(accounts, indent=4))

此代码块确保仅在将脚本作为主程序运行时才执行 get_accounts 函数。它调用该函数获取账户信息，如果成功，则以格式化的 JSON 格式打印账户信息。

if accounts: 检查 get_accounts 函数是否成功返回了账户信息（即，它没有返回 None ）。如果是，则 .dumps(accounts, indent=4) 函数会将 Python 字典 ( accounts ) 转换为 JSON 字符串，并使用 4 个空格的缩进使其更具可读性。 print() 函数随后将格式化的 JSON 字符串打印到控制台。

这段代码演示了如何使用 Python 生成 API 请求的签名，并调用 KuCoin API 获取账户信息。你需要将 YOUR_API_KEY 、 YOUR_SECRET_KEY 和 YOUR_PASSPHRASE 替换为你自己的 API Key、Secret Key 和 Passphrase。此代码段展示了与 KuCoin API 进行身份验证交互的核心方法，并提供了获取账户信息的基本框架。请确保安全地存储和管理您的 API 密钥和密码，以防止未经授权的访问。

常见问题与注意事项

API 频率限制: KuCoin API 为了保证系统的稳定性和公平性，对每个账户的请求频率都设置了限制。超出频率限制会导致 API 请求被拒绝，从而影响你的交易策略执行。务必仔细阅读 KuCoin 官方文档中关于频率限制的具体规则，例如每个 API 端点的请求次数限制、时间窗口以及超限后的处理方式（例如等待时间）。考虑实施速率限制器，在代码层面控制你的请求频率，避免触发限制。常见的策略包括令牌桶算法和漏桶算法。同时，监控你的 API 使用情况，及时调整请求频率。
错误处理: 调用 KuCoin API 过程中可能会遇到各种错误，例如网络连接问题、服务器错误、参数错误、权限错误等。API 会通过 HTTP 状态码和 JSON 格式的错误信息来指示请求失败的原因。你需要编写健壮的错误处理代码，根据不同的 HTTP 状态码和错误信息采取相应的措施，例如重试请求、记录错误日志、发出告警等。特别关注 4XX 客户端错误（例如 400 Bad Request, 401 Unauthorized, 403 Forbidden）和 5XX 服务器错误（例如 500 Internal Server Error, 503 Service Unavailable）。
资金安全: 使用 API 进行自动交易具有一定的风险，例如程序 Bug、网络攻击、市场波动等都可能导致资金损失。因此，必须对你的交易策略进行充分的测试和验证，包括回测历史数据、模拟盘交易等。设置合理的风险控制机制，例如止损单、止盈单、仓位限制等，以控制潜在的损失。定期审查和更新你的交易策略和代码，确保其安全性和有效性。不要将 API Key 泄露给他人，并定期更换 API Key。启用双重验证 (2FA) 等安全措施，保护你的 KuCoin 账户。
API 版本更新: KuCoin API 会不断更新和改进，以提供更好的功能和性能。API 版本更新可能会引入新的功能、修复 Bug、修改接口定义等。为了保证你的代码能够正常运行，你需要关注 KuCoin 官方公告和 API 文档，及时了解 API 版本的更新情况，并更新你的代码以适应新的 API 版本。通常，API 版本更新会有兼容性说明，你需要仔细阅读这些说明，了解哪些接口发生了变化，以及如何升级你的代码。
IP 限制 (可选): 为了提高 API Key 的安全性，你可以通过 KuCoin API 管理页面设置 IP 限制，只允许特定的 IP 地址访问你的 API Key。这样，即使 API Key 泄露，未经授权的 IP 地址也无法使用你的 API Key。建议对所有 API Key 都设置 IP 限制，并将允许访问的 IP 地址限制为你运行交易程序的服务器的 IP 地址。注意维护 IP 地址列表，及时添加或删除 IP 地址。
WebSocket API: KuCoin 除了提供 REST API 用于查询和交易外，还提供了 WebSocket API 用于实时推送行情数据和订单状态。WebSocket API 可以让你更快地获取市场信息，并及时响应市场变化。如果你的应用程序需要实时数据，例如高频交易、套利交易等，可以考虑使用 WebSocket API。你需要学习 WebSocket 协议，并使用相应的 WebSocket 客户端库来连接 KuCoin WebSocket API。注意处理 WebSocket 连接断开和重连的问题。
沙箱环境: KuCoin 提供了沙箱环境（也称为模拟环境或测试环境），用于测试你的 API 代码，而无需使用真实的资金。在沙箱环境中，你可以使用模拟资金进行交易，验证你的交易策略是否有效，并调试你的代码。强烈建议在将你的代码部署到真实环境之前，先在沙箱环境中进行充分的测试。注意沙箱环境的数据和真实环境的数据是隔离的，沙箱环境的交易结果不会影响你的真实账户。