Crate longbridge

Source

Expand description

§Longbridge OpenAPI SDK for Rust

longbridge provides an easy-to-use interface for invoking Longbridge OpenAPI.

§Context Types

Context	Description
`QuoteContext`	Real-time quotes, candlesticks, options, warrants, watchlists, push subscriptions
`TradeContext`	Orders, positions, account balance, executions, cash flow
`AssetContext`	Account statement download
`ContentContext`	News, community topics
`FundamentalContext`	Financial reports, analyst ratings, dividends, valuation, company overview, shareholders
`MarketContext`	Market status, broker holdings, A/H premium, trade statistics, anomaly alerts, index constituents
`CalendarContext`	Financial calendar (earnings, dividends, splits, IPOs, macro data, market closures)
`PortfolioContext`	Exchange rates, portfolio P&L analysis
`AlertContext`	Price alert management (add/enable/disable/delete)
`DCAContext`	Dollar-cost averaging plan management
`SharelistContext`	Community sharelist management

§Documentation

SDK docs: https://longbridge.github.io/openapi/rust/longbridge/index.html
crates.io: https://crates.io/crates/longbridge
Longbridge OpenAPI: https://open.longbridge.com/en/

§Examples

Runnable examples live in examples/rust/:

examples/rust/account_asset/src/main.rs
examples/rust/http_client/src/main.rs
examples/rust/subscribe_quote/src/main.rs
examples/rust/subscribe_candlesticks/src/main.rs
examples/rust/submit_order/src/main.rs
examples/rust/today_orders/src/main.rs

§Quickstart

Add dependencies to Cargo.toml

[dependencies]
longbridge = "4.0.0"

§Authentication

Longbridge OpenAPI supports two authentication methods:

§1. OAuth 2.0 (Recommended)

OAuth 2.0 uses Bearer tokens without requiring HMAC signatures. The token is persisted automatically at ~/.longbridge/openapi/tokens/<client_id> (%USERPROFILE%\.longbridge\openapi\tokens\<client_id> on Windows) and refreshed transparently on every request.

Step 1: Register an OAuth Client

Register an OAuth client to obtain your client_id:

bash / macOS / Linux

curl -X POST https://openapi.longbridge.com/oauth2/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "My Application",
    "redirect_uris": ["http://localhost:60355/callback"],
    "grant_types": ["authorization_code", "refresh_token"]
  }'

PowerShell (Windows)

Invoke-RestMethod -Method Post -Uri https://openapi.longbridge.com/oauth2/register `
  -ContentType "application/json" `
  -Body '{
    "client_name": "My Application",
    "redirect_uris": ["http://localhost:60355/callback"],
    "grant_types": ["authorization_code", "refresh_token"]
  }'

Response:

{
  "client_id": "your-client-id-here",
  "client_secret": null,
  "client_name": "My Application",
  "redirect_uris": ["http://localhost:60355/callback"]
}

Step 2: Build an OAuth handle and create Config

use std::sync::Arc;
use longbridge::{Config, oauth::OAuthBuilder};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Loads an existing token from ~/.longbridge/openapi/tokens/<client_id>.
    // If none exists or it is expired, opens the browser authorization flow.
    // Token refresh is handled automatically on every subsequent request.
    let oauth = OAuthBuilder::new("your-client-id")
        // .callback_port(8080)  // optional, default 60355
        .build(|url| println!("Open this URL to authorize: {url}"))
        .await?;

    let config = Arc::new(Config::from_oauth(oauth));

    // Use config to create contexts...
    Ok(())
}

Benefits:

No shared secret required
No per-request signature calculation
Token lifecycle (load, refresh, persist) managed automatically

§2. Legacy API Key (Environment Variables)

For backward compatibility you can use the traditional API key method.

Setting environment variables (macOS/Linux)

export LONGBRIDGE_APP_KEY="App Key get from user center"
export LONGBRIDGE_APP_SECRET="App Secret get from user center"
export LONGBRIDGE_ACCESS_TOKEN="Access Token get from user center"

Setting environment variables (Windows)

setx LONGBRIDGE_APP_KEY "App Key get from user center"
setx LONGBRIDGE_APP_SECRET "App Secret get from user center"
setx LONGBRIDGE_ACCESS_TOKEN "Access Token get from user center"

§Other environment variables

Name	Description
LONGBRIDGE_LANGUAGE	Language identifier, `zh-CN`, `zh-HK` or `en` (Default: `en`)
LONGBRIDGE_HTTP_URL	HTTP endpoint url (Default: `https://openapi.longbridge.com`)
LONGBRIDGE_QUOTE_WS_URL	Quote websocket endpoint url (Default: `wss://openapi-quote.longbridge.com/v2`)
LONGBRIDGE_TRADE_WS_URL	Trade websocket endpoint url (Default: `wss://openapi-trade.longbridge.com/v2`)
LONGBRIDGE_ENABLE_OVERNIGHT	Enable overnight quote, `true` or `false` (Default: `false`)
LONGBRIDGE_PUSH_CANDLESTICK_MODE	`realtime` or `confirmed` (Default: `realtime`)
LONGBRIDGE_PRINT_QUOTE_PACKAGES	Print quote packages when connected, `true` or `false` (Default: `true`)
LONGBRIDGE_LOG_PATH	Set the path of the log files (Default: `no logs`)
LONGBRIDGE_PAPERTRADING	Enable paper trading mode, `true` or `false` (Default: `false`). See Paper Trading.

§Paper Trading

If your account is a paper trading (simulation) account and you want to place orders, you must explicitly enable paper trading mode. When enabled, all API calls target the paper trading environment and the server validates the token — if the token belongs to a real-money account the server returns an error.

By default this option is off: the server imposes no restrictions and accepts requests from both paper trading and real-money accounts.

Via environment variable (applies automatically to all constructor methods):

export LONGBRIDGE_PAPERTRADING=true   # macOS / Linux

$env:LONGBRIDGE_PAPERTRADING = "true"   # Windows PowerShell

Programmatically:

use std::sync::Arc;
use longbridge::Config;

let config = Arc::new(
    Config::from_apikey("app-key", "app-secret", "access-token")
        .enable_papertrading()
);

§Quote API (Get basic information of securities)

Using OAuth 2.0 (Recommended):

use std::sync::Arc;
use longbridge::{Config, QuoteContext, oauth::OAuthBuilder};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let oauth = OAuthBuilder::new("your-client-id")
        .build(|url| println!("Open this URL to authorize: {url}"))
        .await?;
    let config = Arc::new(Config::from_oauth(oauth));

    // Create a context for quote APIs
    let (ctx, _) = QuoteContext::new(config);

    // Get basic information of securities
    let resp = ctx
        .quote(["700.HK", "AAPL.US", "TSLA.US", "NFLX.US"])
        .await?;
    println!("{:?}", resp);

    Ok(())
}

Using legacy API key (environment variables):

use std::sync::Arc;
use longbridge::{Config, QuoteContext};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Load configuration from environment variables
    let config = Arc::new(Config::from_apikey_env()?);

    // Create a context for quote APIs
    let (ctx, _) = QuoteContext::new(config.clone());

    // Get basic information of securities
    let resp = ctx
        .quote(["700.HK", "AAPL.US", "TSLA.US", "NFLX.US"])
        .await?;
    println!("{:?}", resp);

    Ok(())
}

use std::sync::Arc;
use longbridge::{quote::SubFlags, Config, QuoteContext};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Load configuration from environment variables
    let config = Arc::new(Config::from_apikey_env()?);

    // Create a context for quote APIs
    let (ctx, mut receiver) = QuoteContext::new(config);

    // Subscribe
    ctx.subscribe(["700.HK"], SubFlags::QUOTE).await?;

    // Receive push events
    while let Some(event) = receiver.recv().await {
        println!("{:?}", event);
    }

    Ok(())
}

§Trade API (Submit order)

use std::sync::Arc;
use longbridge::{
    decimal,
    trade::{OrderSide, OrderType, SubmitOrderOptions, TimeInForceType},
    Config, TradeContext,
};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Load configuration from environment variables
    let config = Arc::new(Config::from_apikey_env()?);

    // Create a context for trade APIs
    let (ctx, _) = TradeContext::new(config);

    // Submit order
    let opts = SubmitOrderOptions::new(
        "700.HK",
        OrderType::LO,
        OrderSide::Buy,
        decimal!(500),
        TimeInForceType::Day,
    )
    .submitted_price(decimal!(50i32))
    .remark("Hello from Rust SDK".to_string());

    let resp = ctx.submit_order(opts).await?;
    println!("{:?}", resp);

    Ok(())
}

§Troubleshooting

Windows setx requires a new terminal; use set for the current cmd.exe session.
If you don’t see push events, keep the process alive (receiver loop / sleep).
For debugging, set LONGBRIDGE_LOG_PATH to enable SDK logs.

§Crate features

To avoid compiling unused dependencies, longbridge gates certain features, all of which are disabled by default:

Feature	Description
blocking	Provides the `blocking` client API.

§License

Licensed under either of

Apache License, Version 2.0,(LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT) at your option.

Re-exports§

pub use agent::AgentContext;
pub use alert::AlertContext;
pub use asset::AssetContext;
pub use calendar::CalendarContext;
pub use content::ContentContext;
pub use dca::DCAContext;
pub use fundamental::FundamentalContext;
pub use fundamental::types::USCompanyDividends;
pub use fundamental::types::USCompanyOverview;
pub use fundamental::types::USDividendItem;
pub use fundamental::types::USETFDividendInfo;
pub use fundamental::types::USETFFile;
pub use fundamental::types::USETFFilesResponse;
pub use fundamental::types::USFinancialStatement;
pub use fundamental::types::USRankTag;
pub use fundamental::types::USValuationMetric;
pub use fundamental::types::USValuationOverview;
pub use market::MarketContext;
pub use portfolio::PortfolioContext;
pub use quote::QuoteContext;
pub use quote::USCryptoOverview;
pub use screener::ScreenerContext;
pub use sharelist::SharelistContext;
pub use trade::GetUSHistoryOrders;
pub use trade::GetUSRealizedPLOptions;
pub use trade::QueryUSOrdersOptions;
pub use trade::QueryUSOrdersResponse;
pub use trade::TradeContext;
pub use trade::USAssetOverview;
pub use trade::USCashEntry;
pub use trade::USCryptoEntry;
pub use trade::USOrderDetailResponse;
pub use trade::USOrderHistory;
pub use trade::USRealizedPL;
pub use trade::USRealizedPLEntry;
pub use trade::USRealizedPLMetric;
pub use longbridge_oauth as oauth;
pub use longbridge_httpcli as httpclient;
pub use longbridge_wscli as wsclient;

Modules§

agent: AI Agent conversation types and context
alert: Price alert types and context
asset: Asset related types
calendar: Financial calendar types and context
content: Content related types
counter: Symbol ↔ counter_id conversion utilities.
dca: DCA (dollar-cost averaging) types and context
fundamental: Fundamental data types and context
market: Market data types and context
portfolio: Portfolio analytics types and context
quote: Quote related types
runtime: Global tokio runtime shared across all contexts and language bindings.
screener: Stock screener — strategies, search, and indicators
sharelist: Community sharelist types and context
trade: Trade related types

Macros§

decimal: A macro to construct decimal.

Structs§

Config: Configuration options for Longbridge SDK
Decimal: Decimal represents a 128 bit representation of a fixed-precision decimal number. The finite set of values of type Decimal are of the form m / 10^e, where m is an integer such that -2⁹⁶ < m < 2⁹⁶, and e is an integer between 0 and 28 inclusive.

Enums§

DcRegion: Data center region used for API gateway routing.
Error: Longbridge OpenAPI SDK error type
Language: Language identifier
Market: Market
PushCandlestickMode: Push mode for candlestick
SimpleError: Simple error type
SimpleErrorKind: Simple error kind

Constants§

DC_REGION_HEADER: HTTP and WebSocket header that selects the data center serving a request.

Type Aliases§

Result: Longbridge OpenAPI SDK result type