跳转到内容

快速开始

前言

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
  • WebSocket Trade - wss://openapi-trade.longportapp.com
ℹ️Info

中国大陆地区访问,建议采用 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 获得更好的开发体验)。

    在命令行里面输入下面的命令设置环境变量:

    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