鉴权

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	错误描述