margin-trading

KuCoin Margin Trading Skill

Margin trading on KuCoin using authenticated API endpoints. Supports cross margin and isolated margin market data, HF order queries, stop order queries, OCO order queries, borrow/repay history queries, lending queries, and risk limits. 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).

Quick Reference

Classic Margin Market Data

Endpoint	Description	Required	Optional	Authentication
/api/v3/margin/symbols (GET)	Get Symbols - Cross Margin (trading pair config)	None	symbol	No
/api/v1/isolated/symbols (GET)	Get Symbols - Isolated Margin (trading pair config)	None	None	No
/api/v3/etf/info (GET)	Get ETF Info (leveraged token info)	None	currency	No
/api/v1/mark-price/{symbol}/current (GET)	Get Mark Price Detail (current mark price for a margin pair)	symbol (path)	None	No
/api/v1/margin/config (GET)	Get Margin Config (cross margin config, currency list)	None	None	No
/api/v3/mark-price/all-symbols (GET)	Get Mark Price List (current mark price for all margin pairs)	None	None	No
/api/v3/margin/collateralRatio (GET)	Get Margin Collateral Ratio	None	currencyList	No
/api/v3/margin/available-inventory (GET)	Get Market Available Inventory (platform borrowable amount)	None	currency	No

Classic Margin HF Order Queries

Endpoint	Description	Required	Optional	Authentication
/api/v3/hf/margin/orders/{orderId} (GET)	Get Order By OrderId	orderId (path), symbol (query)	None	Yes
/api/v3/hf/margin/orders/client-order/{clientOid} (GET)	Get Order By ClientOid	clientOid (path), symbol (query)	None	Yes
/api/v3/hf/margin/order/active/symbols (GET)	Get Symbols With Open Order	tradeType	None	Yes
/api/v3/hf/margin/orders/active (GET)	Get Open Orders	symbol, tradeType	None	Yes
/api/v3/hf/margin/orders/done (GET)	Get Closed Orders	symbol, tradeType	side, type, lastId, limit, startAt, endAt	Yes
/api/v3/hf/margin/fills (GET)	Get Trade History	symbol, tradeType	orderId, side, type, lastId, limit, startAt, endAt	Yes

Classic Margin Stop Order Queries

Endpoint	Description	Required	Optional	Authentication
/api/v3/hf/margin/stop-orders (GET)	Get Stop Orders List (paginated, untriggered)	None	symbol, side, type, tradeType, startAt, endAt, currentPage, orderIds, pageSize, stop	Yes
/api/v3/hf/margin/stop-order/orderId (GET)	Get Stop Order By OrderId	orderId	None	Yes
/api/v3/hf/margin/stop-order/clientOid (GET)	Get Stop Order By ClientOid	clientOid	None	Yes

Classic Margin OCO Order Queries

Endpoint	Description	Required	Optional	Authentication
/api/v3/hf/margin/oco-order/orderId (GET)	Get OCO Order By OrderId	orderId	None	Yes
/api/v3/hf/margin/oco-order/clientOid (GET)	Get OCO Order By ClientOid	clientOid	None	Yes
/api/v3/hf/margin/oco-order/detail/orderId (GET)	Get OCO Order Detail By OrderId (includes sub-orders)	orderId	None	Yes
/api/v3/hf/margin/oco-orders (GET)	Get OCO Order List (paginated)	pageSize, currentPage	symbol, startAt, endAt, orderIds, tradeType	Yes

Classic Debit Queries (Borrowing and Repaying)

Endpoint	Description	Required	Optional	Authentication
/api/v3/margin/borrowRate (GET)	Get Borrow Interest Rate	None	vipLevel, currency	Yes
/api/v3/margin/borrow (GET)	Get Borrow History	currency	isIsolated, symbol, orderNo, startTime, endTime, currentPage, pageSize	Yes
/api/v3/margin/repay (GET)	Get Repay History	currency	isIsolated, symbol, orderNo, startTime, endTime, currentPage, pageSize	Yes
/api/v3/margin/interest (GET)	Get Interest History	None	currency, isIsolated, symbol, startTime, endTime, currentPage, pageSize	Yes

Classic Credit Queries (Lending)

Endpoint	Description	Required	Optional	Authentication
/api/v3/project/list (GET)	Get Loan Market (currencies available for lending)	None	currency	Yes
/api/v3/project/marketInterestRate (GET)	Get Loan Market Interest Rate (past 7 days)	currency	None	Yes
/api/v3/purchase/orders (GET)	Get Purchase Orders (paginated)	status	currency, purchaseOrderNo, currentPage, pageSize	Yes
/api/v3/redeem/orders (GET)	Get Redeem Orders (paginated)	status	currency, redeemOrderNo, currentPage, pageSize	Yes

Classic Risk Limit

Endpoint	Description	Required	Optional	Authentication
/api/v3/margin/currencies (GET)	Get Margin Risk Limit (config and risk limit info per currency/symbol)	None	isIsolated, currency, symbol	Yes

---

Parameters

Common Parameters

• clientOid: Client Order ID. Unique identifier created by the user (UUID recommended). Max length: 40 characters.
• symbol: Trading pair symbol (e.g., BTC-USDT)
• side: Order side filter: buy | sell
• type: Order type filter: limit | market
• orderId: Order ID for query
• isIsolated: true for isolated margin, false for cross margin. Default is false.
• tradeType: Transaction type: MARGIN_TRADE (cross margin), MARGIN_ISOLATED_TRADE (isolated margin)
• stop: Stop order trigger condition filter: loss | entry
• lastId: The ID of the last data set from the previous batch. Used for cursor-based pagination.
• limit: Number of results per page. Default: 20, Max: 100 (for order/fill queries).
• currentPage: Current page number for paginated queries. Default: 1.
• pageSize: Page size for paginated queries. Varies by endpoint (typical default: 50, max: 500).
• startAt / startTime: Start time filter in milliseconds.
• endAt / endTime: End time filter in milliseconds.
• currency: Currency code (e.g., BTC, USDT).
• vipLevel: VIP level. If empty, defaults to current user VIP level.
• orderNo: Order number for borrow/repay history queries.
• purchaseOrderNo: Purchase order ID for lending operations.
• redeemOrderNo: Redeem order ID for redemption queries.
• status: Order status filter. Values depend on endpoint (e.g., DONE, PENDING).
• currencyList: Comma-separated currency list for collateral ratio query.

Enums

• side: buy | sell
• type: limit | market
• tradeType: MARGIN_TRADE (cross margin) | MARGIN_ISOLATED_TRADE (isolated margin)
• stop: loss | entry
• purchase/redeem status: DONE | PENDING
• OCO order status: NEW | DONE | TRIGGERED | CANCELLED
• stop order status: NEW | TRIGGERED
• liquidity: taker | maker

Authentication

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

• API Key: Your KuCoin API key (for header KC-API-KEY)
• API Secret: Your KuCoin API secret (for signing)
• Passphrase: Your KuCoin API passphrase (for header KC-API-PASSPHRASE)

Base URL:

• Production: https://api.kucoin.com

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

Never Disclose API Key and Secret

Never disclose the location of the API key, secret, or passphrase file.

Never send the API key, secret, or passphrase to any website other than the official KuCoin API endpoint.

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: ***...s3cr3
• Passphrase: Always mask entirely: ***...

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

Listing Accounts

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

• main (Production)
• margin-keys (Production)

Transactions in Production

When performing transactions in production, always confirm with the user before proceeding by asking them to write "CONFIRM" to proceed.

---

KuCoin Accounts

main

• API Key: your_api_key
• Secret: your_api_secret
• Passphrase: your_passphrase