# LongPort Python SDK API Reference

## QuoteContext Methods (Watchlist & Quotes)

```python
from longport import openapi
cfg = openapi.Config.from_env()
ctx = openapi.QuoteContext(config=cfg)
```

### Watchlist Management

| Method | Description | Returns |
|--------|-------------|---------|
| `ctx.watchlist()` | Get all watchlist groups with securities | `list[WatchlistGroup]` |
| `ctx.create_watchlist_group(name, securities)` | Create new watchlist group | - |
| `ctx.update_watchlist_group(name, securities)` | Update existing group | - |
| `ctx.delete_watchlist_group(name)` | Delete a watchlist group | - |

### Watchlist Response Structure

```python
resp = ctx.watchlist()
for group in resp:
    print(f'Group: {group.name}')
    print(f'  Securities: {len(group.securities)}')
    for sec in group.securities:
        # sec has: symbol, market, name, watched_price, watched_at
        print(f'  - {sec.symbol}: {sec.name} @ {sec.watched_price}')
```

**WatchlistSecurity fields:**
- `symbol` — e.g. "O.US", "823.HK"
- `market` — "US", "HK", "CN"
- `name` — display name
- `watched_price` — `Some(float)` or `None`
- `watched_at` — ISO timestamp string

**Special groups:**
- `all` — contains all securities across groups (auto-generated)
- `us` / `hk` — market-based auto-groups
- User-created groups (e.g. "收息", "月派", "月拼", "季派")

### Quote Methods

| Method | Description |
|--------|-------------|
| `ctx.quote(symbols)` | Get real-time quotes for symbols |
| `ctx.realtime_quote(symbols)` | Real-time quote subscription |
| `ctx.candlesticks(symbol, period, count)` | Get K-line data |
| `ctx.history_candlesticks_by_offset(...)` | Historical K-lines |
| `ctx.depth(symbol)` | Order book depth |
| `ctx.trades(symbol)` | Recent trades |
| `ctx.static_info(symbols)` | Static security info |
| `ctx.capital_flow(symbol)` | Capital flow data |
| `ctx.capital_distribution(symbol)` | Capital distribution |

### Quote Response

```python
resp = ctx.quote(['O.US', 'STAG.US', 'AGNC.US'])
for q in resp:
    print(f'{q.symbol}: ${q.last_done:.2f}, vol={q.volume}')
```

**Quote fields:** `symbol`, `last_done`, `prev_close`, `volume`, `turnover`, `high`, `low`, `open`

## TradeContext Methods

```python
trade_ctx = openapi.TradeContext(config=cfg)
```

| Method | Description |
|--------|-------------|
| `trade_ctx.stock_positions()` | Get holdings |
| `trade_ctx.account_balance()` | Get account balance |
| `trade_ctx.today_orders()` | Today's orders |
| `trade_ctx.history_orders(...)` | Historical orders |
| `trade_ctx.place_order(...)` | Place new order |
| `trade_ctx.cancel_order(order_id)` | Cancel order |

### Positions Response

```python
positions = trade_ctx.stock_positions()
for ch in positions.channels:
    for pos in ch.positions:
        print(f'{pos.symbol}: {pos.quantity} @ {pos.cost_price}')
```

## Symbol Format

| Market | Format | Example |
|--------|--------|---------|
| US | `{TICKER}.US` | `O.US`, `AAPL.US` |
| HK | `{CODE}.HK` | `823.HK`, `9988.HK` |
| CN | `{CODE}.SZ` or `{CODE}.SH` | `000001.SZ` |

## Market Access Notes

- LV1 Real-time Quotes: CN, HK, US
- Nasdaq Basic: US stocks
- USOption: requires separate purchase
- Some markets may show access warnings on connect (normal)