futures-trading

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

KuCoin Futures Trading Skill

KuCoin期货交易Skill

Futures trading on KuCoin using authenticated and public API endpoints. Requires API Key, API Secret, and Passphrase for authenticated endpoints. Return the result in JSON format.

Note: This skill only supports Classic REST API GET endpoints (read-only operations).

通过已认证和公开的API端点在KuCoin上进行期货交易。已认证端点需要提供API Key、API Secret和Passphrase。返回结果为JSON格式。

注意： 本Skill仅支持Classic REST API的GET端点（只读操作）。

Quick Reference

快速参考

Classic Futures -- Market Data

经典期货——市场数据

Base URL:

https://api-futures.kucoin.com

Endpoint	Description	Required	Optional	Authentication
`/api/v1/timestamp` (GET)	Get Server Time	None	None	No
`/api/v1/status` (GET)	Get Service Status	None	None	No
`/api/v1/mark-price/{symbol}/current` (GET)	Get Mark Price	symbol (path)	None	No
`/api/v1/contracts/{symbol}` (GET)	Get Symbol (contract info)	symbol (path)	None	No
`/api/v1/contracts/active` (GET)	Get All Symbols (all tradable contracts)	None	None	No
`/api/v1/ticker` (GET)	Get Ticker	symbol	None	No
`/api/v1/allTickers` (GET)	Get All Tickers	None	None	No
`/api/v1/level2/snapshot` (GET)	Get Full OrderBook	symbol	None	No
`/api/v1/level2/depth{size}` (GET)	Get Part OrderBook (20 or 100 levels)	size (path: 20 or 100), symbol	None	No
`/api/v1/trade/history` (GET)	Get Trade History (last 100 trades)	symbol	None	No
`/api/v1/kline/query` (GET)	Get Klines (candlestick data)	symbol, granularity	from, to	No
`/api/v1/index/query` (GET)	Get Spot Index Price	symbol	startAt, endAt, reverse, offset, forward, maxCount	No
`/api/v1/interest/query` (GET)	Get Interest Rate Index	symbol	startAt, endAt, reverse, offset, forward, maxCount	No
`/api/v1/premium/query` (GET)	Get Premium Index	symbol	startAt, endAt, reverse, offset, forward, maxCount	No
`/api/v1/trade-statistics` (GET)	Get 24hr Stats (platform futures volume). Must use Classic Futures base URL ( `https://api-futures.kucoin.com` ).	None	None	Yes

基础URL：

https://api-futures.kucoin.com

端点	描述	必填参数	可选参数	认证要求
`/api/v1/timestamp` (GET)	获取服务器时间	无	无	否
`/api/v1/status` (GET)	获取服务状态	无	无	否
`/api/v1/mark-price/{symbol}/current` (GET)	获取标记价格	symbol（路径参数）	无	否
`/api/v1/contracts/{symbol}` (GET)	获取交易对（合约信息）	symbol（路径参数）	无	否
`/api/v1/contracts/active` (GET)	获取所有交易对（所有可交易合约）	无	无	否
`/api/v1/ticker` (GET)	获取行情ticker	symbol	无	否
`/api/v1/allTickers` (GET)	获取所有行情ticker	无	无	否
`/api/v1/level2/snapshot` (GET)	获取完整订单簿	symbol	无	否
`/api/v1/level2/depth{size}` (GET)	获取部分订单簿（20或100档）	size（路径参数：20或100）、symbol	无	否
`/api/v1/trade/history` (GET)	获取交易历史（最近100笔交易）	symbol	无	否
`/api/v1/kline/query` (GET)	获取K线数据（蜡烛图数据）	symbol、granularity	from、to	否
`/api/v1/index/query` (GET)	获取现货指数价格	symbol	startAt、endAt、reverse、offset、forward、maxCount	否
`/api/v1/interest/query` (GET)	获取利率指数	symbol	startAt、endAt、reverse、offset、forward、maxCount	否
`/api/v1/premium/query` (GET)	获取溢价指数	symbol	startAt、endAt、reverse、offset、forward、maxCount	否
`/api/v1/trade-statistics` (GET)	获取24小时统计数据（平台期货交易量）。必须使用经典期货基础URL ( `https://api-futures.kucoin.com` )。	无	无	是

Classic Futures -- Order Queries

经典期货——订单查询

Base URL:

https://api-futures.kucoin.com

Endpoint	Description	Required	Optional	Authentication
`/api/v1/stopOrders` (GET)	Get Stop Order List	None	symbol, side, type, startAt, endAt, currentPage, pageSize	Yes
`/api/v1/orders/{order-id}` (GET)	Get Order By OrderId	order-id (path)	None	Yes
`/api/v1/orders/byClientOid` (GET)	Get Order By ClientOid	clientOid	None	Yes
`/api/v1/recentDoneOrders` (GET)	Get Recent Closed Orders (last 24h)	None	symbol	Yes
`/api/v1/openOrderStatistics` (GET)	Get Open Order Value	symbol	None	Yes
`/api/v1/recentFills` (GET)	Get Recent Trade History (last 24h fills)	None	symbol	Yes

基础URL：

https://api-futures.kucoin.com

端点	描述	必填参数	可选参数	认证要求
`/api/v1/stopOrders` (GET)	获取止损订单列表	无	symbol、side、type、startAt、endAt、currentPage、pageSize	是
`/api/v1/orders/{order-id}` (GET)	通过订单ID查询订单	order-id（路径参数）	无	是
`/api/v1/orders/byClientOid` (GET)	通过ClientOid查询订单	clientOid	无	是
`/api/v1/recentDoneOrders` (GET)	获取最近已平仓订单（过去24小时）	无	symbol	是
`/api/v1/openOrderStatistics` (GET)	获取未平仓订单价值	symbol	无	是
`/api/v1/recentFills` (GET)	获取最近成交历史（过去24小时成交记录）	无	symbol	是

Classic Futures -- Position Queries

经典期货——仓位查询

Base URL:

https://api-futures.kucoin.com

Endpoint	Description	Required	Optional	Authentication
`/api/v2/position/getMarginMode` (GET)	Get Margin Mode	symbol	None	Yes
`/api/v2/position/getPositionMode` (GET)	Get Position Mode	None	None	Yes
`/api/v2/getMaxOpenSize` (GET)	Get Max Open Size	symbol, price, leverage	None	Yes
`/api/v2/position` (GET)	Get Position Details	symbol	None	Yes
`/api/v1/positions` (GET)	Get Position List	None	currency	Yes
`/api/v1/history-positions` (GET)	Get Positions History	None	symbol, from, to, limit, pageId	Yes
`/api/v1/margin/maxWithdrawMargin` (GET)	Get Max Withdraw Margin	symbol	positionSide	Yes
`/api/v2/getCrossUserLeverage` (GET)	Get Cross Margin Leverage	symbol	None	Yes
`/api/v2/batchGetCrossOrderLimit` (GET)	Get Cross Margin Risk Limit	symbol	totalMargin, leverage	Yes
`/api/v1/contracts/risk-limit/{symbol}` (GET)	Get Isolated Margin Risk Limit	symbol (path)	None	No

基础URL：

https://api-futures.kucoin.com

端点	描述	必填参数	可选参数	认证要求
`/api/v2/position/getMarginMode` (GET)	获取保证金模式	symbol	无	是
`/api/v2/position/getPositionMode` (GET)	获取仓位模式	无	无	是
`/api/v2/getMaxOpenSize` (GET)	获取最大可开仓量	symbol、price、leverage	无	是
`/api/v2/position` (GET)	获取仓位详情	symbol	无	是
`/api/v1/positions` (GET)	获取仓位列表	无	currency	是
`/api/v1/history-positions` (GET)	获取历史仓位	无	symbol、from、to、limit、pageId	是
`/api/v1/margin/maxWithdrawMargin` (GET)	获取最大可提取保证金	symbol	positionSide	是
`/api/v2/getCrossUserLeverage` (GET)	获取逐仓杠杆	symbol	无	是
`/api/v2/batchGetCrossOrderLimit` (GET)	获取逐仓风险限额	symbol	totalMargin、leverage	是
`/api/v1/contracts/risk-limit/{symbol}` (GET)	获取隔离保证金风险限额	symbol（路径参数）	无	否

Classic Futures -- Funding Fees

经典期货——资金费用

Base URL:

https://api-futures.kucoin.com

Endpoint	Description	Required	Optional	Authentication
`/api/v1/funding-rate/{symbol}/current` (GET)	Get Current Funding Rate	symbol (path)	None	No
`/api/v1/contract/funding-rates` (GET)	Get Public Funding History	symbol, from, to	None	No
`/api/v1/funding-history` (GET)	Get Private Funding History	symbol	startAt, endAt, reverse, offset, forward, maxCount	Yes

基础URL：

https://api-futures.kucoin.com

端点	描述	必填参数	可选参数	认证要求
`/api/v1/funding-rate/{symbol}/current` (GET)	获取当前资金费率	symbol（路径参数）	无	否
`/api/v1/contract/funding-rates` (GET)	获取公开资金费率历史	symbol、from、to	无	否
`/api/v1/funding-history` (GET)	获取个人资金费率历史	symbol	startAt、endAt、reverse、offset、forward、maxCount	是

Parameters

参数

Common Parameters

通用参数

symbol: Symbol of the contract (e.g.,
```
XBTUSDTM
```
,
```
ETHUSDTM
```
). Path or query parameter depending on endpoint.
clientOid: User-defined unique order ID, max 40 characters.
startAt / from: Begin time in milliseconds.
endAt / to: End time in milliseconds.
pageSize: Number of records per page. Default varies by endpoint (typically 50, max 200).
currentPage: Current page number for paginated queries. Default: 1.
side: Order side filter:
```
buy
```
|
```
sell
```
type: Order type filter:
```
limit
```
|
```
market
```
currency: Currency code filter (e.g.,
```
USDT
```
,
```
XBT
```
).
reverse: Boolean. Reverse the order of results.
offset: Start offset for pagination.
forward: Boolean.
```
true
```
for forward lookup (default),
```
false
```
for backward.
maxCount: Displayed size per page. Default 50.
granularity: Candlestick interval in minutes:
```
1
```
,
```
5
```
,
```
15
```
,
```
30
```
,
```
60
```
,
```
120
```
,
```
240
```
,
```
480
```
,
```
720
```
,
```
1440
```
,
```
10080
```
positionSide: Position side filter:
```
BOTH
```
|
```
LONG
```
|
```
SHORT
```
price: Price parameter for max open size query.
leverage: Leverage parameter for max open size and risk limit queries.
totalMargin: Total margin for cross margin risk limit query.

symbol：合约交易对（例如
```
XBTUSDTM
```
、
```
ETHUSDTM
```
）。根据端点不同，作为路径参数或查询参数。
clientOid：用户自定义的唯一订单ID，最多40个字符。
startAt / from：起始时间（毫秒级时间戳）。
endAt / to：结束时间（毫秒级时间戳）。
pageSize：每页记录数。默认值因端点而异（通常为50，最大200）。
currentPage：分页查询的当前页码。默认值：1。
side：订单方向筛选：
```
buy
```
|
```
sell
```
type：订单类型筛选：
```
limit
```
|
```
market
```
currency：货币代码筛选（例如
```
USDT
```
、
```
XBT
```
）。
reverse：布尔值。反转结果顺序。
offset：分页起始偏移量。
forward：布尔值。
```
true
```
表示正向查询（默认），
```
false
```
表示反向查询。
maxCount：每页显示的记录数。默认值50。
granularity：K线时间间隔（分钟）：
```
1
```
、
```
5
```
、
```
15
```
、
```
30
```
、
```
60
```
、
```
120
```
、
```
240
```
、
```
480
```
、
```
720
```
、
```
1440
```
、
```
10080
```
positionSide：仓位方向筛选：
```
BOTH
```
|
```
LONG
```
|
```
SHORT
```
price：最大可开仓量查询的价格参数。
leverage：最大可开仓量和风险限额查询的杠杆参数。
totalMargin：逐仓风险限额查询的总保证金参数。

Enums

枚举值

side:
```
buy
```
|
```
sell
```
type:
```
limit
```
|
```
market
```
positionSide:
```
BOTH
```
(One-Way mode) |
```
LONG
```
(Hedge mode long) |
```
SHORT
```
(Hedge mode short)
marginMode:
```
ISOLATED
```
|
```
CROSS
```
positionMode:
```
0
```
(One-Way mode) |
```
1
```
(Hedge mode)
status (order):
```
open
```
|
```
done
```
serverStatus:
```
open
```
|
```
close
```
|
```
cancelonly
```
granularity (minutes):
```
1
```
|
```
5
```
|
```
15
```
|
```
30
```
|
```
60
```
|
```
120
```
|
```
240
```
|
```
480
```
|
```
720
```
|
```
1440
```
|
```
10080
```

side：
```
buy
```
（买入） |
```
sell
```
（卖出）
type：
```
limit
```
（限价） |
```
market
```
（市价）
positionSide：
```
BOTH
```
（单向模式） |
```
LONG
```
（对冲模式多头） |
```
SHORT
```
（对冲模式空头）
marginMode：
```
ISOLATED
```
（隔离保证金） |
```
CROSS
```
（逐仓保证金）
positionMode：
```
0
```
（单向模式） |
```
1
```
（对冲模式）
status（订单状态）：
```
open
```
（未成交） |
```
done
```
（已成交）
serverStatus：
```
open
```
（开放） |
```
close
```
（关闭） |
```
cancelonly
```
（仅允许撤销）
granularity（分钟）：
```
1
```
|
```
5
```
|
```
15
```
|
```
30
```
|
```
60
```
|
```
120
```
|
```
240
```
|
```
480
```
|
```
720
```
|
```
1440
```
|
```
10080
```

Authentication

认证

For endpoints that require authentication, you will need to provide KuCoin API credentials.

Required credentials:

API Key: Your KuCoin API key
API Secret: Your KuCoin API secret (for signing)
API Passphrase: Your KuCoin API passphrase (set when creating the API key)

IMPORTANT -- Base URL:

Classic Futures API:
```
https://api-futures.kucoin.com
```
-- Used for all Classic Futures REST endpoints (
```
/api/v1/...
```
,
```
/api/v2/...
```
,
```
/api/v3/...
```
)

对于需要认证的端点，您需要提供KuCoin API凭证。

所需凭证：

API Key：您的KuCoin API密钥
API Secret：您的KuCoin API密钥（用于签名）
API Passphrase：您的KuCoin API密码（创建API密钥时设置）

重要提示——基础URL：

经典期货API：
```
https://api-futures.kucoin.com
```
—— 用于所有经典期货REST端点（
```
/api/v1/...
```
、
```
/api/v2/...
```
、
```
/api/v3/...
```
）

Security

安全

Share Credentials

共享凭证

Users can provide KuCoin API credentials by sending a file where the content is in the following format:

api_key_value
api_secret_value
api_passphrase_value

用户可通过发送文件提供KuCoin API凭证，文件内容格式如下：

api_key_value
api_secret_value
api_passphrase_value

Never Disclose API Key and Secret

切勿泄露API Key和Secret

Never disclose the location of the API key and secret file.

Never send the API key and secret to any website other than the official KuCoin API base URLs.

切勿泄露API密钥和Secret文件的存储位置。

切勿将API密钥和Secret发送至KuCoin官方API基础URL以外的任何网站。

Never Display Full Secrets

切勿显示完整密钥

When showing credentials to users:

API Key: Show first 5 + last 4 characters:
```
abcde...wxyz
```
API Secret: Always mask, show only last 5:
```
***...s1k2y
```
Passphrase: Always fully masked:
```
***...
```

Example response when asked for credentials: Account: main API Key: abcde...wxyz Secret: ***...s1k2y Passphrase: ***... Environment: Production

向用户展示凭证时：

API Key：显示前5位+后4位：
```
abcde...wxyz
```
API Secret：始终掩码，仅显示最后5位：
```
***...s1k2y
```
Passphrase：始终完全掩码：
```
***...
```

询问凭证时的示例回复：账户：main API Key：abcde...wxyz Secret：...s1k2y Passphrase：... 环境：生产环境

Listing Accounts

账户列表

When listing accounts, show names and environment only -- never keys: KuCoin Accounts:

main (Production)
test-account (Production)

列出账户时，仅显示名称和环境——绝不显示密钥： KuCoin账户：

main（生产环境）
test-account（生产环境）

Transactions Confirmation

交易确认

When performing trading operations (placing orders, canceling orders, modifying positions), always confirm with the user before proceeding by asking them to write "CONFIRM" to proceed.

执行交易操作（下单、撤单、修改仓位）时，必须先请求用户确认，要求用户输入“CONFIRM”后再继续。