經紀商 Fast API 服務

1. 簡介

KuCoin 已推出 Fast API 服務，讓經紀商用戶可透過 KuCoin OAuth 2.0 登入，無縫連接至經紀商網站或應用程式。透過一鍵授權流程，用戶可安全地將其 KuCoin 帳戶連接至第三方應用程式，無需手動建立或綁定 API 密鑰（版本 3）或密碼短語。亦無需手動建立 API 密鑰或設定密碼短語。

授權完成後，系統會自動產生 API 密鑰，並連接至經紀商平台，預設權限包括：

現貨交易

合約交易

KuCoin Earn 存取權限

支援的使用場景

向 KuCoin 用戶付款：產生充值地址，讓資金可無縫轉入 KuCoin 用戶帳戶。適用於空投聚合器及套利解決方案。

使用 KuCoin 付款：讓用戶可在第三方應用程式及 DeFi 生態中使用其 KuCoin 帳戶付款。適用於支付應用程式、DeFi 跨鏈橋及 Web3 閘道。

交易整合：將 KuCoin 交易功能整合至您的平台，以高效執行交易。適用於交易機械人及投資組合追蹤工具。

會計及審計：匯出交易及交易記錄資料，以用於會計、審計及財務報告。

2. 整合前準備

如要使用 KuCoin Fast API 服務，經紀商合作夥伴需要準備以下三項內容，並透過此表格提交。

經紀商用於請求 KuCoin Fast API 服務的完整 IP 清單。這是經紀商服務器向 KuCoin Fast API 服務服務器發出請求時使用的 IP。

經紀商用於交易的完整 IP 清單。

KuCoin OAuth 登入後的重新導向 URL。

經紀商提供上述資料後，KuCoin 將向經紀商發送其唯一的 client_id

3. Fast API 服務

經紀商用戶可使用 KuCoin OAuth 登入授權經紀商獲取其 API 密鑰。FastAPI 2.0 中的每次權限建立操作均必須完成身分驗證及授權。

用戶現在可在授權期間，根據實際需要自訂 API 權限，包括：

唯讀權限

現貨交易權限

槓桿交易權限

合約交易權限

Earn 權限

靈活劃轉權限

提現權限

統一賬戶權限

這可讓用戶更清楚掌握並控制帳戶授權，同時協助經紀商支援更多元化的業務場景。

4. OpenAPI Demo

4.1 OAuth Demo [舊版本]

OAuth Demo 為較舊版本，現有經紀商合作夥伴仍可使用。不過，如您方便切換，我們建議改用新版本，因為新版本提供最新功能及改進。

URI：
https://www.kucoin.com/_oauth/resource/ucenter/outer/api-key/add
method：POST
content-type：application/json
header:

"Authorization":"bearer {token}"

parameter:

 no parameter needed

{
	"success": true,
	"code": "200",
	"msg": "success",
	"retry": false,
	"data": {
    	"apiName": "",
    	"apiKey": "",
    	"secret": "",
    	"passphrase": "",
    	"brokerId": "",
    	"authGroup": API_COMMON,API_FUTURES,API_SPOT,API_EARN,API_TRANSFER,API_MARGIN,
    	"ipWhiteList": ""
	}
}

錯誤：

apiName 重複

用戶的 apiKey 數量已達上限

4.2 OAuth New Demo [建議使用]

如果您是 KuCoin 的新經紀商合作夥伴，我們建議直接使用新的 demo 環境，因為這是我們的最新版本，並提供最新功能及基礎設施。
請注意，如果您在 KuCoin 本地站營運經紀商服務，則必須使用此版本。

URI：https://www\.kucoin\.com/\_oauth/resource/cyber\-truck\-vault/v2/outer/api\-key/add
method：POST
content-type：application/json
header:
"Authorization":"bearer {token}"

{
"authGroupMap": {
"API_COMMON": true,
"API_SPOT": true,
"API_MARGIN": true,
"API_FUTURES": true,
"API_EARN": true,
"API_TRANSFER": true,
"API_WITHDRAW_OAUTH": false
},
"isAddressbookOnly": false
}

{
"success": true,
"code": "200",
"msg": "success",
"retry": false,
"data": {
"apiName": "",
"apiKey": "",
"secret": "",
"passphrase": "",
"brokerId": "",
"authGroup": API_COMMON,API_FUTURES,API_SPOT,API_EARN,API_TRANSFER,API_MARGIN,
"ipWhiteList": ""
}
}

錯誤：

apiName 重複

用戶的 apiKey 數量已達上限

5. 授權碼模式

KuCoin 僅提供授權碼模式。透過授權，經紀商提供 client_secret 以獲取授權碼。access Token 及 refresh Token 可根據授權碼獲取。經紀商會保存密鑰，並與 KuCoin OAuth2.0 服務器互動。

6. Token 的使用

6.1 Token 的分別

經紀商透過授權碼調用 Token 交換端點後，將會獲得兩種類型的 Token。

access Token：用於經紀商調用 KuCoin OpenAPI 端點。

refresh Token：用於在上一個 access Token 過期時獲取新的 access Token。

6.2 如何使用 Token

經紀商完成授權並獲取 Token 後，即可透過 access Token 調用 KuCoin OpenAPI 端點。發出請求時，經紀商需要在請求標頭中攜帶以下資料：

Header 參數	是否必填	描述
Authorization	是	在此欄位填入 bearer 格式的 access Token。

6.3 Token 有效期

access Token：1 小時內有效

refresh Token：3 天內有效

如果 access Token 過期，將無法再存取該端點。如果 refresh Token 仍在有效期內，經紀商需要調用 refresh Token 端點，以獲取一組新的 access Token 及 refresh Token。新的 access Token 可繼續使用。透過 refresh Token 獲取新的 access Token 後，舊的 access Token 無論是否已過期均不可再使用。

7. OAuth Controller API 設計

7.1 OAuth 登入頁面及權限編輯

URI:

http://www\.kucoin\.com/oauth?response\_type=code\&client\_id=XXXX\&redirect\_uri=XXX\&scope=OAUTH\_CREATE\_API\&state=123

Method: GET

Params：

Response Type	請使用 authorization_code 模式
Client_id	經紀商的唯一身分識別
Redirect_url	經紀商網站
Scope	access_token 的範圍
State	經紀商可在此處自行決定所需內容，但此欄位為必填。<br><br><br><br>您可以在此處填入您系統中的用戶 ID。

Response:

    "success": true, 
    "code": "668*********c711", 
    "msg": "success.", 
    "retry": false, 
    "data": null
   "state": XXX

💡

提示：請不要對 redirect URL 進行編碼。

用戶可使用其註冊電郵地址或電話號碼登入 KuCoin 帳戶，並授予約定權限，以授權經紀商存取相應功能。

如果經紀商需要用戶授予提現權限，經紀商應在授權流程中自行引導用戶選擇並授權提現權限。

7.2 請求 Token

URI: https://www\.kucoin\.com/\_oauth/access\-Token?grant\_type=authorization\_code\&code=xxxxxxxxxx\&redirect\_uri=https://www\.xxxxxxxxxxxxx\.com\&client\_id=xxxxxxxxx

Method: GET

Params:

Header 參數	是否必填	描述
Grant_type	必填	grant_type=authorization_code
Code	必填
Redirect_url	必填
Client_id	必填	經紀商的唯一身分識別

Response:

    "access_token":"",  	//access token received from user authorization
    "token_type":"bearer"     //token type, extension point to facilitate the addition of more secure tokens in the future
    "expires_in":3600,  	//token expiration time, in seconds
    "refresh_token":,   	//token used to obtain a new access token after the access token expires
    "scope": ["", ""]   	//scope of permissions for the access token
}

提示：請不要對 redirect URL 進行編碼。

7.3 刷新 Token

URI：https://www\.kucoin\.com/\_oauth/refresh\-Token

Method: POST

Params:

Header 參數	是否必填	描述
Grant_type	必填	authorization_code
Refresh_token	必填	用於刷新驗證的 Token
Scope	必填

Response:

    "access_token":"",  	//token used to access resources
    "token_type":"bearer",  //token type, an extension point to facilitate the addition of more secure tokens in the future, such as MAC (Message Authentication Code). Bearer indicates a token that does not contain any information
    "expires_in":3600,  	//token expiration time, in seconds
    "refresh_token":,   	//token used to obtain a new access token after the access token expires
    "scope": [""OAUTH_CREATE_API""]  //scope of permissions for the access token
}

8. 提現使用場景

8.1. 安全設定及經紀商頁面重新導向

**步驟 1：安全驗證檢查 **
如果用戶的帳戶安全級別不足（例如未啟用 2FA），KuCoin 會向經紀商返回安全設定連結，讓用戶完成所需驗證步驟。API 錯誤回應將返回類似以下的訊息：
「您需要綁定更多驗證因素，才可繼續此操作。請前往以下連結：https://xxx\.kucoin\.xxx/account/security/g2fa」

步驟 2：新增重新導向參數（可選）
向用戶展示安全設定連結時，經紀商可附加以下參數，以支援安全設定完成後自動重新導向：

client_id：經紀商／供應商 ID

redirect_uri：完成後將用戶重新導向返回的 URL（請注意 URL 編碼）

URL 產生後的 Demo 連結：
construction:https://www\.kucoin\.com/account/security/g2fa?client\_id=demo\_client\_id\&redirect\_uri=https%3a%2f%2fwww\.kucoin\.com

步驟 3：用戶完成安全設定

用戶點擊連結後，將被重新導向至 KuCoin 網頁以完成所需安全驗證設定。設定完成後，用戶將自動重新導向返回經紀商指定頁面。

8.2. 提現端點

請注意，OAuth 服務的提現功能是經紀商部分下的獨立提現端點。

URI：https://api\.kucoin\.com/api/v2/broker/withdrawal

Method: POST

Headers:

Header 參數	是否必填	描述
KC-API-KEY	是	您的 API 密鑰，以字串形式提供。
KC-API-SIGN	是	為請求產生的 Base64 編碼簽名。
KC-API-TIMESTAMP	是	請求時間戳，單位為毫秒。
KC-API-PASSPHRASE	是	建立 API 密鑰時指定的密碼短語。
KC-API-KEY-VERSION	是	API 密鑰版本。可在 API 管理頁面查看此值。
Content-Type	是	所有請求及回應均使用 application/json 內容類型。

Params:

Header 參數	是否必填	描述
address	必填	提現地址
amount	必填	提現金額。必須為正數，且為指定金額精度的倍數。
withdrawType	必填	提現類型：ADDRESS（提現地址）、UID、MAIL（電郵）、PHONE（手機號碼）。注意：如果透過 uid/mail/phone 提現，將受頻率限制：10 秒內 3 次、24 小時內 50 次（按首次請求時間滾動計算）。
chain	可選	幣種的 chainId。對於支援多條鏈的幣種，建議指定 chain 參數，而非使用預設鏈；您可透過 GET /api/v3/currencies/{currency} 接口的回應查詢 chainId。
memo	可選	地址備註（memo/tag）。如無需備註，請將此欄位留空。提現至外部平台或錢包時，請向接收地址確認是否需要 memo/tag。未能提供正確 memo/tag 可能導致接收平台無法入賬您的資金。
isInner	可選	是否為站內提現。預設值：False
remark	可選	備註
feeDeductType	可選	提現手續費扣除類型。如未指定 feeDeductType 參數，當主賬戶餘額足以支援提現時，系統會優先從主賬戶扣除交易手續費。但如果主賬戶餘額不足以支援提現，系統會從提現金額中扣除手續費。例如：假設您要從 KuCoin 平台提現 1 BTC（交易手續費：0.0001 BTC），如果主賬戶餘額不足，系統會從您的提現金額中扣除交易手續費。在此情況下，您將收到 0.9999 BTC。

response fields:

Header 參數	是否必填	描述
withdrawalId	可選	提現 ID，即提現的唯一 ID
transactionId	可選	交易 ID，即驗證交易的唯一 ID
allFactors	可選	驗證交易期間需要驗證的所有 2FA 因素
sentFactors	可選	發送至用戶端的 2FA 因素，僅包括需要發送的因素

獲取 2FA 驗證因素Response：

    "code": "200000",
    "data": {
        "transactionId": "sample transactionId",
        "allFactors": [
            ["GAV", "EMV"]
        ],
        "sentFactors": [
            ["EMV"]
        ]
    }
}
withdraw success response：
{
    "code": "200000",
    "data": {
        "withdrawalId": "sample withdrawalId"
    }
}

提現成功Response：

    "code": "200000",
    "data": {
        "withdrawalId": "sample withdrawalId"
    }
}

9. 費用結構

交易及提現費用：適用標準交易及提現費用。請在此處參閱費率表：KuCoin VIP 費率表

OAuth 服務費：對於透過 Fast API OAuth 服務發起的充值及提現交易，KuCoin 將根據交易量收取 OAuth 服務費。

充值	提現
每筆交易 0 USDT	提現金額的 10%，最低費用：每次提現等值 1 USDT，最高費用：每次提現等值 30 USDT

感謝您的時間與關注。

KuCoin 經紀商團隊

Telegram: @KuCoin_Broker

經紀商 Fast API 服務

1. 簡介#

2. 整合前準備#

3. Fast API 服務#

4. OpenAPI Demo#

4.1 OAuth Demo [舊版本]#

4.2 OAuth New Demo [建議使用]#

5. 授權碼模式#

6. Token 的使用#

6.1 Token 的分別#

6.2 如何使用 Token#

6.3 Token 有效期#

7. OAuth Controller API 設計#

7.1 OAuth 登入頁面及權限編輯#

7.2 請求 Token#

7.3 刷新 Token#

8. 提現使用場景#

8.1. 安全設定及經紀商頁面重新導向#

8.2. 提現端點#

9. 費用結構#

1. 簡介

2. 整合前準備

3. Fast API 服務

4. OpenAPI Demo

4.1 OAuth Demo [舊版本]

4.2 OAuth New Demo [建議使用]

5. 授權碼模式

6. Token 的使用

6.1 Token 的分別

6.2 如何使用 Token

6.3 Token 有效期

7. OAuth Controller API 設計

7.1 OAuth 登入頁面及權限編輯

7.2 請求 Token

7.3 刷新 Token

8. 提現使用場景

8.1. 安全設定及經紀商頁面重新導向

8.2. 提現端點

9. 費用結構