Open API

繁體中文

English
简体中文

繁體中文

English
简体中文

Appearance

身份認證 ​

所有 OpenAPI 請求都必須經過認證。本頁詳細說明支援的認證方式、環境變數配置以及 Token 刷新機制。

認證方式 ​

OpenAPI 支持兩種認證方式：

方式一：OAuth 2.0（推薦） ​

OAuth 2.0 是現代化的認證方式，使用 Bearer Token，無需 HMAC 簽名，更加安全便捷。

第一步：註冊 OAuth 客戶端

執行以下命令註冊 OAuth 客戶端，獲取 client_id：

bash
curl -X POST https://openapi.futunn.com/oauth2/register \
     -H "Content-Type: application/json" \
     -d '{
            "redirect_uris": ["http://localhost:60355/callback"],
            "token_endpoint_auth_method": "none",
            "grant_types": ["authorization_code","refresh_token"],
            "response_types": ["code"],
            "client_name": "My Futu OpenAPI"
        }'

回應示例：

json
{
  "client_id": "72d9caaf-0bd4-4000-85a7-8c7978c74544",
  "client_id_issued_at": 1773311221,
  "client_secret_expires_at": 1773314821,
  "client_name": "My Futu OpenAPI",
  "redirect_uris": ["http://localhost:60355/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "token_endpoint_auth_method": "none",
  "response_types": ["code"],
  "registration_access_token": "BVlMLEtNUUu4FoRFNItC2FfeR/rLpqLNyEuCJNNTCWE=",
  "registration_client_uri": "https://openapi.futunn.com/oauth2/register/72d9caaf-0bd4-4000-85a7-8c7978c74544"
}

保存 client_id 供後續使用。

第二步：授權並獲取 Token

SDK 提供內建 OAuth 支持。使用 OAuthBuilder 完成瀏覽器授權流程，授權後使用 Config.from_oauth() 建立配置。Token 會自動持久化，過期時自動刷新。

Token 儲存路徑： macOS/Linux 為 ~/.futu/openapi/tokens/<client_id>，Windows 為 %USERPROFILE%\.futu\openapi\tokens\<client_id>。

Python

python
from futu.openapi import Config, OAuthBuilder

oauth = OAuthBuilder("your-client-id").build(
    lambda url: print(f"請訪問此 URL 進行授權：{url}")
)
config = Config.from_oauth(oauth)

JavaScript

javascript
const { Config, OAuth } = require('@futu/openapi')

const oauth = await OAuth.build('your-client-id', (_, url) => {
  console.log('請訪問此 URL 進行授權：' + url)
})
const config = Config.fromOAuth(oauth)

OAuth 優勢

  • 更安全（無需共享密鑰）
  • 更簡單（無需計算簽名）
  • 基於 Token 的現代認證方式
  • Token 自動持久化與刷新

:::caution Token 安全 OAuth Token 應安全儲存在應用程式中（如加密檔案、安全密鑰鏈），不要儲存在環境變數中。 :::

方式二：傳統 API Key（兼容） ​

獲取 App Key、App Secret、Access Token

請登入 開發者中心，進入用戶中心。

頁面會展示應用憑證（App Key、App Secret、Access Token）。此處的 Access Token 為傳統 API Key 憑證，與 OAuth 返回的 access token 不是同一種東西。獲取後請設定為環境變數以便開發使用。

:::caution 請注意保護好您的 Access Token 資訊，任何人獲得到它，都可以通過 OpenAPI 來交易你的帳戶！ :::

環境變數 ​

傳統 API Key 憑證（僅需設定以下 3 個）：

環境變數說明
FUTU_APP_KEY從頁面上獲取到的 App Key
FUTU_APP_SECRET從頁面上獲取到的 App Secret
FUTU_ACCESS_TOKEN在開發者中心（用戶中心 → 應用憑證）獲取的 Access Token

其他環境變數：

名稱說明
FUTU_HTTP_URLHTTP 介面地址（預設：https://openapi.futunn.com）
FUTU_QUOTE_WS_URL行情 WebSocket 地址
FUTU_TRADE_WS_URL交易 WebSocket 地址
FUTU_LANGUAGE語言標識，zh-CN、zh-HK 或 en（預設：en）
FUTU_REGION覆蓋接入點，SDK 會按網路自動選擇，若判斷不正確可手動設定
FUTU_LOG_PATH日誌檔案路徑（預設：不寫日誌）

關於環境變數

環境變數非必要條件，如設定不方便，可直接在程式碼裏用參數來初始化。SDK 的 Config 可使用 Config.from_env() 從環境變數建立，或使用 Config.new(app_key, app_secret, access_token) 直接傳參。

macOS / Linux 環境下設定環境變數 ​

打開終端機，輸入下面的命令即可：

bash
export FUTU_APP_KEY="從頁面上獲取到的 App Key"
export FUTU_APP_SECRET="從頁面上獲取到的 App Secret"
export FUTU_ACCESS_TOKEN="從頁面上獲取到的 Access Token"

Windows 下設定環境變數 ​

透過 CMD 命令列設定：

bash
C:\Users\user> setx FUTU_APP_KEY "從頁面上獲取到的 App Key"
成功：指定的值已得到保存。

C:\Users\user> setx FUTU_APP_SECRET "從頁面上獲取到的 App Secret"
成功：指定的值已得到保存。

C:\Users\user> setx FUTU_ACCESS_TOKEN "從頁面上獲取到的 Access Token"
成功：指定的值已得到保存。

:::caution Windows 環境變數 Windows 環境變數限制，當上面命令執行成功以後，你需要重新啟動 Windows 或者登出後重新登入一次，才可以讀取到。 :::

登出或重新啟動後，再次打開命令列，輸入下面的命令驗證一下環境變數是否設定正確：

bash
C:\Users\user> set FUTU
FUTU_APP_KEY=xxxxxxx
FUTU_APP_SECRET=xxxxxx
FUTU_ACCESS_TOKEN=xxxxxxx

請求簽名 ​

使用傳統 API Key 時，每個 HTTP 請求使用 App Secret 作為密鑰，對規範字串 METHOD\nPATH\nTIMESTAMP\nBODY 進行 HMAC-SHA256 簽名，結果通過 X-Api-Signature 請求標頭下發：

http
POST /v1/quote/snapshot HTTP/1.1
Host: openapi.futunn.com
X-Api-Key: {appKey}
X-Api-Timestamp: 1714032000
X-Api-Signature: {hmacSha256Hex}
Authorization: Bearer {accessToken}
Content-Type: application/json

時間戳早於 60 秒的請求會被拒絕，用以抵禦重放攻擊。

刷新 Access Token ​

INFO

本節僅適用於傳統 API Key 認證方式。OAuth 2.0 的 Token 由 SDK 自動刷新。

傳統 API Key 的 Access Token 預設 90 天後過期。在過期前調用刷新介面獲取新 Token，然後將返回值更新到 FUTU_ACCESS_TOKEN。

Python

python
from datetime import datetime, timedelta
from futu.openapi import Config

config = Config.from_env()
# 指定 3 年後過期
new_token = config.refresh_access_token(
    expired_at=datetime.now() + timedelta(days=365 * 3)
)
print("新 Access Token：", new_token)

JavaScript

javascript
const { Config } = require('@futu/openapi')

const config = Config.fromEnv()
const expiredAt = new Date()
expiredAt.setFullYear(expiredAt.getFullYear() + 3)
const newToken = await config.refreshAccessToken(expiredAt)
console.log('新 Access Token：', newToken)

expired_at 參數用於指定新 Token 的過期時間（預設：從現在起 90 天後）。

吊銷憑證 ​

憑證一旦洩露，請立即在開發者中心吊銷。吊銷會在 30 秒內在所有接入點生效。

相關內容 ​