跳轉到內容

快速開始

前言

Longbridge OpenAPI SDK 基於 Rust 底層提供標準實現,目前我們已經發布了 Python, Node.js, Rust, C++/C, Java 等多種編程語言 SDK,其他語言的支持後面會陸續推出。

API Host

  • HTTP API - https://openapi.longportapp.com
  • WebSocket Quote - wss://openapi-quote.longportapp.com
  • Webssocket Trade - wss://openapi-trade.longportapp.com
💡Tip

中國大陸地區訪問,建議採用 openapi.longportapp.cn, openapi-quote.longportapp.cn, openapi-trade.longportapp.cn 以提升訪問速度。

如果您使用我們的 SDK,可以通過設置環境變量 LONGPORT_REGION=cn 來使用位於中國大陸的接入點,目前我們只有 hkcn 兩個地區可選。

時間格式

所有 API 傳回有關時間的字段,我們都採用 Unix Timestamp 時區為 UTC。

環境需求

安裝 SDK

下面我們以獲取資產為例,演示一下如何使用 SDK。

配置

開通開發中帳戶

  1. 下載 Longbridge,並完成開戶
  2. Longbridge OpenAPI 官網取得認證資訊

認證方式

LongPort OpenAPI 支援兩種認證方式:

方式一:OAuth 2.0(推薦) ⭐

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

第一步:註冊 OAuth 客戶端

造訪 Longbridge OpenAPI 網站,登入後進入「個人中心」,註冊 OAuth 客戶端獲取 client_id

bash
curl -X POST https://openapi.longportapp.com/v1/oauth2/client/register \
  -H “Content-Type: application/json” \
  -d '{
    “name”: “我的應用程式”,
    “redirect_uris”: [“http://localhost:60355/callback”],
    “grant_types”: [“authorization_code”, “refresh_token”]
  }'

回應範例:

json
{
  “client_id”: “your-client-id-here”,
  “client_secret”: null,
  “name”: “我的應用程式”,
  “redirect_uris”: [“http://localhost:60355/callback”]
}

儲存 client_id 供後續使用。

第二步:授權並取得 Token

使用各語言的標準 OAuth 2.0 函式庫進行授權,取得 access token 後,使用 Config.from_oauth() 建立設定。

💡OAuth 優勢
  • ✅ 更安全(無需共享金鑰)
  • ✅ 更簡單(無需計算簽名)
  • ✅ 基於 Token 的現代認證方式
  • ✅ 更適合現代應用程式
⚠️Token 安全

OAuth Token 應安全儲存在應用程式中(如加密檔案、安全金鑰鏈),不要儲存在環境變數中

方式二:傳統 API Key(相容)

取得 App Key, App Secret, Access Token 等資訊

造訪 Longbridge OpenAPI 網站,登入後,進入「個人中心」。

在頁面上會給出「應用憑證」憑證訊息,我們拿到以後設定環境變量,方便後面開發使用方便。

環境變量

⚠️Caution

請注意保護好您的 Access Token 訊息,任何人獲得到它,都可以透過 OpenAPI 來交易你的帳戶!

環境變量說明值範圍
LONGPORT_APP_KEY從頁面上取得到的 App Key
LONGPORT_APP_SECRET從頁面取得到的 App Secret
LONGPORT_ACCESS_TOKEN從頁面上取得到的 Access Token
LONGPORT_REGIONAPI 伺服器存取點,請根據您所在地區設置,以獲得更好的連線速度hk, cn
LONGPORT_ENABLE_OVERNIGHT是否開啟夜盤行情,設定 true 開啟,false 關閉true, false

建議您設定好這幾個環境變量,我們後面各章節文件中的範例程式碼都會使用這幾個環境變量。

💡關於環境變量

環境變量非必要條件,如設定不方便或遇到問題難以解決,可不用環境變量,而是直接在程式碼裡用參數來初始化。

Longbridge OpenAPI SDK 的 Config 都可以直接傳入 app_key, app_secret, access_token 等參數來初始化,注意看後面的例子註釋內 Init config without ENV 的部分。

macOS / Linux 環境下設定環境變量

打開終端,輸入下面的命令即可:

bash
export LONGPORT_APP_KEY="從頁面上取得到的 App Key"
export LONGPORT_APP_SECRET="從頁面取得到的 App Secret"
export LONGPORT_ACCESS_TOKEN="從頁面取得到的 Access Token"

Windows 下設定環境變量

Windows 要稍微複雜一些,有以下兩種方式可以設定環境變量:

  1. 透過圖形介面設定:在桌面上找到“我的電腦”,右鍵點擊,選擇“屬性”,在彈出的視窗中點擊“高級系統設定”。

    • 在彈出的視窗中點選「環境變量」。

    • 在彈出的視窗中點擊“新建”,然後輸入環境變量名稱,例如 LONGPORT_APP_KEYValue 分別填寫從頁面上取得到的 App Key,App Secret,Access Token,Region。

  2. CMD 命令列設定:按下Win + R 快捷鍵,輸入cmd 命令啟動命令列(建議使用[Windows Terminal](https://apps.microsoft.com/store/detail /windows-terminal/9N0DX20HK701) 獲得更好的開發體驗)。

    在命令列裡面輸入下面的命令設定環境變量:

    bash
    C:\Users\jason> setx LONGPORT_APP_KEY "從頁面上取得到的 App Key"
    成功:指定的值已儲存。
    
    C:\Users\jason> setx LONGPORT_APP_SECRET "從頁面取得到的 App Secret"
    成功:指定的值已儲存。
    
    C:\Users\jason> setx LONGPORT_ACCESS_TOKEN "從頁面取得到的 Access Token"
    成功:指定的值已儲存。
    ⚠️Windows 環境變量

    Windows 環境變量限制,當上面指令執行成功以後,你需要重新啟動 Windows 或登出後重新登入一次,才可以讀取。

    登出或重新啟動後,再次開啟命令列,輸入下面的命令以驗證環境變量是否設定正確:

    bash
    C:\Users\jason> set LONGPORT
    LONGPORT_APP_KEY=xxxxxxx
    LONGPORT_APP_SECRET=xxxxxx
    LONGPORT_ACCESS_TOKEN=xxxxxxx

    如果你能正確列印你剛才設定的值,那麼環境變量就是對了。

場景示範

獲取資產總覽

運行後會輸出如下:

[
  AccountBalance {
    total_cash: 503898884.81,
    max_finance_amount: 0.00,
    remaining_finance_amount: 501403229.49,
    risk_level: Some(1),
    margin_call: 0,
    currency: "HKD",
    cash_infos: [
      CashInfo {
        withdraw_cash: 501214985.15,
        available_cash: 501214985.15,
        frozen_cash: 584438.25,
        settling_cash: -3897793.90,
        currency: "HKD",
      },
      CashInfo {
        withdraw_cash: -25546.89,
        available_cash: -25546.89,
        frozen_cash: 295768.57,
        settling_cash: 2326.60,
        currency: "USD",
      }
    ]
  }
]

訂閱實時行情

訂閱行情數據請檢查 開發者中心 - “行情權限”是否正確

  • 港股 - BMP 基礎報價,無實時行情推送,無法用 WebSocket 訂閱
  • 美股 - LV1 納斯達克最優報價 (只限 OpenAPI)

運行前訪問 開發者中心,檢查確保賬戶有正確的行情權限。

ℹ️Info

如沒有開通行情權限,可以通過“Longbridge”手機客戶端,並進入“我的 - 我的行情 - 行情商城”購買開通行情權限。

https://longbridge.com/download

當你有正確的行情權限,看起來可能會是這樣:

運行後會輸出如下:

700.HK PushQuote {
    last_done: 367.000,
    open: 362.000,
    high: 369.400,
    low: 356.000,
    timestamp: "2022-06-06T08:10:00Z",
    volume: 22377421,
    turnover: 8081883405.000,
    trade_status: Normal,
    trade_session: Normal
  }
AAPL.US PushQuote {
  last_done: 147.350,
  open: 150.700,
  high: 151.000,
  low: 146.190,
  timestamp: "2022-06-06T11:57:36Z",
  volume: 3724407,
  turnover: 550606662.815,
  trade_status: Normal,
  trade_session: Pre
}
NFLX.US PushQuote {
  last_done: 201.250,
  open: 205.990,
  high: 205.990,
  low: 200.110,
  timestamp: "2022-06-06T11:57:26Z",
  volume: 137821,
  turnover: 27888085.590,
  trade_status: Normal,
  trade_session: Pre
}

委託下單

下面我們做一次 委託下單 動作,我們假設要以 50 HKD 買入 700.HK 的數量為 100

NOTE: 為了防止測試買入成功,這裡演示給了一個較低的價格,避免成交。OpenAPI 操作均等同與線上交易,請謹慎操作,開發調試注意參數細節。

運行後會輸出如下:

SubmitOrderResponse { order_id: "718437534753550336" }

獲取當日訂單

運行後會輸出如下:

Order {
  order_id: "718437534753550336",
  status: NotReported,
  stock_name: "腾讯控股 1",
  quantity: 200,
  executed_quantity: None,
  price: Some(50.000),
  executed_price: None,
  submitted_at: 2022-06-06T12:14:16Z,
  side: Buy,
  symbol: "700.HK",
  order_type: LO,
  last_done: None,
  trigger_price: Some(0.000),
  msg: "",
  tag: Normal,
  time_in_force: Day,
  expire_date: Some(NaiveDate(Date { year: 2022, ordinal: 158 })),
  updated_at: Some(2022-06-06T12:14:16Z),
  trigger_at: None,
  trailing_amount: None,
  trailing_percent: None,
  limit_offset: None,
  trigger_status: None,
  currency: "HKD",
  outside_rth: nonce
}

上面例子已經完整演示瞭如何使用 SDK 訪問 OpenAPI 的接口,更多其他接口請詳細閱讀 Longbridge OpenAPI 文檔,根據不同的接口使用。

更多例子

我們在 Longbridge OpenAPI Python SDK 的 GitHub 倉庫中提供了上面幾個例子的完整代碼,當然後期我們也會持續往裡面補充或更新。

https://github.com/longportapp/openapi/tree/master/examples

SDK API 文檔

SDK 的詳細 API 文檔請訪問:

https://longportapp.github.io/openapi/

回饋及溝通

如果您在使用 SDK 的過程中遇到任何問題,歡迎透過以下方式返回或與我們討論,我們會盡力協助您解決問題。

GitHub Issues

在 GitHub 上,也有很多歷史的討論和問題可以參考,你也可以試著搜尋一下,或許也能找到問題的解決方案。

訪問網址:https://github.com/longportapp/openapi/issues