鑑權

Web API 支持兩種 OAuth 2.0 鑑權方式：客戶端憑證（Client Credentials） 和 授權碼（Authorization Code）。

環境信息

平台	支持券商	域名
Moomoo	SG, MFI, CA	webapi.moomoo.com

應用參數

以下參數由 Futu 分配，用於 OAuth 2.0 認證流程：

參數	說明
client_id	應用唯一標識
client_secret	應用密鑰
scope	權限範圍，多個值以空格分隔

scope 取值

取值	含義
acc_read	只讀權限
trade_1007	Moomoo US 交易權限
trade_1019	Moomoo CA 交易權限

請求規範

所有業務接口請求頭必須攜帶 AccessToken：

Authorization: Bearer <AccessToken>

方式一：客戶端憑證（Client Credentials）

適用於服務端對服務端的場景，不涉及用戶授權。

請求

POST /api/v1.0/oauth/svr/token HTTP/1.1
Host: webapi.moomoo.com
Authorization: Basic base64({client_id}:{client_secret})
Content-Type: application/x-www-form-urlencoded

grant_type=client_credential

參數	位置	必填	說明
grant_type	Body	是	固定值 client_credential
Authorization	Header	是	Basic base64({client_id}:{client_secret})

示例

使用 client_id: testcli_1002，secret: XRYORwFK06lkA6Dz：

POST /api/v1.0/oauth/svr/token HTTP/1.1
Host: webapi.moomoo.com
Authorization: Basic dGVzdGNsaV8xMDAyOlhSWU9Sd0ZLMDZsa0E2RHo=
Content-Type: application/x-www-form-urlencoded

grant_type=client_credential

響應

{
  "access_token": "eyJhbGc.eyJvYWEiOiIwMDA0NCIsImlzcQ.gElDA_9M0_eDr6Jw...",
  "expires_in": 7200,
  "token_type": "Bearer"
}

字段	類型	說明
access_token	string	訪問令牌
expires_in	int	令牌有效期（秒）
token_type	string	固定值 Bearer

方式二：授權碼（Authorization Code）

適用於需要用戶授權的場景，標準 OAuth 2.0 授權碼流程。

步驟 1：發起授權請求

將用戶重定向到授權鏈接：

GET https://passport.fututrade.com/authorize?response_type=code&client_id={client_id}&scope={scope}&redirect_uri={redirect_uri}&state={state}

參數	說明
client_id	應用標識
scope	權限範圍
redirect_uri	回調地址
state	狀態參數，授權服務器將原值回傳，用於防 CSRF

步驟 2：獲取授權碼

用戶授權成功後，授權服務器重定向至 redirect_uri，附帶以下參數：

參數	說明
code	授權碼，短時效有效
state	與請求中發送的值一致

步驟 3：用授權碼換取 Access Token

POST /api/v1.0/oauth/svr/token HTTP/1.1
Host: webapi.moomoo.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&client_id={client_id}&client_secret={client_secret}&code={code}&redirect_uri={redirect_uri}

參數	說明
grant_type	固定值 authorization_code
client_id	應用標識
client_secret	應用密鑰
code	上一步獲取的授權碼
redirect_uri	與授權請求中的 redirect_uri 一致

Token 響應

{
  "access_token": "xxxx",
  "refresh_token": "xxxx",
  "token_type": "bearer",
  "expires_in": 7200,
  "refresh_token_expires_in": 649670
}

字段	類型	說明
access_token	string	訪問令牌，用於調用業務接口
refresh_token	string	刷新令牌，用於獲取新的 access_token
token_type	string	固定值 bearer
expires_in	int	access_token 有效期（秒）
refresh_token_expires_in	int	refresh_token 有效期（秒）

步驟 4：刷新 Access Token

當 access_token 過期後，使用 refresh_token 獲取新令牌：

POST /api/v1.0/oauth/svr/token HTTP/1.1
Host: webapi.moomoo.com
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token={refresh_token}&client_secret={client_secret}

參數	說明
grant_type	固定值 refresh_token
refresh_token	刷新令牌
client_secret	應用密鑰

響應格式與步驟 3 一致。

錯誤響應

鑑權失敗時返回：

{
  "s": "error",
  "errcode": -1200,
  "errmsg": "Error message."
}

字段	類型	說明
s	string	狀態，error 表示失敗
errcode	int	錯誤碼
errmsg	string	錯誤描述