longport 4.3.3

A Python library for Longport Open API

Longport OpenAPI SDK for Python

longport provides an easy-to-use interface for invoking Longport 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://longportapp.github.io/openapi/python/index.html
• Longport OpenAPI: https://open.longportapp.com/en/

Examples

Runnable examples live in examples/python/, grouped as follows.

Synchronous API (same as the snippets in this README):

• examples/python/account_asset.py
• examples/python/history_candlesticks.py
• examples/python/http_client.py
• examples/python/subscribe_candlesticks.py
• examples/python/subscribe_quote.py
• examples/python/submit_order.py
• examples/python/today_orders.py

Asynchronous API (AsyncQuoteContext, AsyncTradeContext, HttpClient.request_async):

• examples/python/account_asset_async.py
• examples/python/history_candlesticks_async.py
• examples/python/http_client_async.py
• examples/python/subscribe_candlesticks_async.py
• examples/python/subscribe_quote_async.py
• examples/python/submit_order_async.py
• examples/python/today_orders_async.py

References

• Config

  The configuration of the SDK.

• QuoteContext

  The Quote API part of the SDK, e.g.: get basic information of securities, subscribe quotes...

• TradeContext

  The Trade API part of the SDK, e.g.: submit order, get order status...

Quickstart

Install Longport OpenAPI SDK

pip install longport

Authentication

Longport OpenAPI supports two authentication methods:

1. OAuth 2.0 (Recommended)

OAuth 2.0 is the modern authentication method that uses Bearer tokens without requiring HMAC signatures.

Step 1: Register OAuth Client

First, register an OAuth client to get your client_id:

bash / macOS / Linux

curl -X POST https://openapi.longportapp.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.longportapp.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"]
}

Save the client_id for use in your application.

Step 2: Build an OAuth client and create Config

OAuthBuilder loads a cached token from ~/.longport/openapi/tokens/<client_id> (%USERPROFILE%\.longport\openapi\tokens\<client_id> on Windows) if one exists and is still valid, or starts the browser authorization flow automatically. The token is persisted to the same path after a successful authorization or refresh.

from longport.openapi import OAuthBuilder, Config

oauth = OAuthBuilder("your-client-id").build(
    lambda url: print(f"Open this URL to authorize: {url}")
)
config = Config.from_oauth(oauth)

For async code use build_async:

import asyncio
from longport.openapi import OAuthBuilder, Config

async def main():
    oauth = await OAuthBuilder("your-client-id").build_async(
        lambda url: print(f"Open this URL to authorize: {url}")
    )
    config = Config.from_oauth(oauth)

asyncio.run(main())

2. Legacy API Key (Environment Variables)

Setting environment variables (macOS/Linux)

export LONGPORT_APP_KEY="App Key get from user center"
export LONGPORT_APP_SECRET="App Secret get from user center"
export LONGPORT_ACCESS_TOKEN="Access Token get from user center"

Setting environment variables (Windows)

setx LONGPORT_APP_KEY "App Key get from user center"
setx LONGPORT_APP_SECRET "App Secret get from user center"
setx LONGPORT_ACCESS_TOKEN "Access Token get from user center"

Other environment variables

Name	Description
LONGPORT_LANGUAGE	Language identifier, zh-CN, zh-HK or en (Default: en)
LONGPORT_HTTP_URL	HTTP endpoint url (Default: https://openapi.longportapp.com)
LONGPORT_QUOTE_WS_URL	Quote websocket endpoint url (Default: wss://openapi-quote.longportapp.com/v2)
LONGPORT_TRADE_WS_URL	Trade websocket endpoint url (Default: wss://openapi-trade.longportapp.com/v2)
LONGPORT_ENABLE_OVERNIGHT	Enable overnight quote, true or false (Default: false)
LONGPORT_PUSH_CANDLESTICK_MODE	realtime or confirmed (Default: realtime)
LONGPORT_PRINT_QUOTE_PACKAGES	Print quote packages when connected, true or false (Default: true)
LONGPORT_LOG_PATH	Set the path of the log files (Default: no logs)

Then create a config from the environment:

from longport.openapi import Config

config = Config.from_apikey_env()

Quote API (Get basic information of securities)

from longport.openapi import Config, QuoteContext, OAuthBuilder

oauth = OAuthBuilder("your-client-id").build(
    lambda url: print(f"Open this URL to authorize: {url}")
)
config = Config.from_oauth(oauth)

# Create a context for quote APIs
ctx = QuoteContext(config)

# Get basic information of securities
resp = ctx.quote(["700.HK", "AAPL.US", "TSLA.US", "NFLX.US"])
print(resp)

Quote API (Subscribe quotes)

from time import sleep
from longport.openapi import Config, QuoteContext, SubType, PushQuote, OAuthBuilder

oauth = OAuthBuilder("your-client-id").build(
    lambda url: print(f"Open this URL to authorize: {url}")
)
config = Config.from_oauth(oauth)

# A callback to receive quote data
def on_quote(symbol: str, event: PushQuote):
    print(symbol, event)

# Create a context for quote APIs
ctx = QuoteContext(config)
ctx.set_on_quote(on_quote)

# Subscribe
ctx.subscribe(["700.HK"], [SubType.Quote])

# Receive push for 30 seconds
sleep(30)

Trade API (Submit order)

from decimal import Decimal
from longport.openapi import TradeContext, Config, OrderType, OrderSide, TimeInForceType, OAuthBuilder

oauth = OAuthBuilder("your-client-id").build(
    lambda url: print(f"Open this URL to authorize: {url}")
)
config = Config.from_oauth(oauth)

# Create a context for trade APIs
ctx = TradeContext(config)

# Submit order
resp = ctx.submit_order(
    "700.HK", OrderType.LO, OrderSide.Buy,
    Decimal("500"), TimeInForceType.Day,
    submitted_price=Decimal("50"),
    remark="Hello from Python SDK",
)
print(resp)

Asynchronous API

The SDK provides async contexts and an async HTTP client for use with Python's asyncio. All I/O methods return awaitables; callbacks (e.g. for push events) are set the same way as in the sync API. Async quote/trade contexts support async callbacks: if a set_on_quote, set_on_candlestick, or set_on_order_changed callback is an async function (returns a coroutine), it is scheduled on the event loop. When using async callbacks, pass the loop so the SDK can schedule them: AsyncQuoteContext.create(config, loop_=asyncio.get_running_loop()).

• Async quote: create with ctx = AsyncQuoteContext.create(config) (synchronous, no await), then e.g. await ctx.quote(["700.HK"]), await ctx.subscribe(...).
• Async trade: create with ctx = AsyncTradeContext.create(config) (synchronous, no await), then e.g. await ctx.today_orders(), await ctx.submit_order(...).
• Async HTTP: resp = await http_cli.request_async("get", "/v1/trade/execution/today").

Example (async quote):

import asyncio
from longport.openapi import Config, AsyncQuoteContext, SubType, PushQuote, OAuthBuilder

def on_quote(symbol: str, event: PushQuote):
    print(symbol, event)

async def main():
    oauth = await OAuthBuilder("your-client-id").build_async(
        lambda url: print(f"Open this URL to authorize: {url}")
    )
    config = Config.from_oauth(oauth)
    ctx = AsyncQuoteContext.create(config, loop_=asyncio.get_running_loop())
    ctx.set_on_quote(on_quote)
    await ctx.subscribe(["700.HK", "AAPL.US"], [SubType.Quote])
    quotes = await ctx.quote(["700.HK"])
    print(quotes)
    await asyncio.sleep(10)

asyncio.run(main())

See the *_async.py examples in examples/python/ for full async flows.

Troubleshooting

• Windows setx requires a new terminal; use set for the current cmd.exe session.
• If the program exits, you won't receive push events; keep the process alive (e.g. sleep(...)).
• For debugging, set LONGPORT_LOG_PATH to enable SDK logs.

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.