Metadata-Version: 2.4
Name: lse-data
Version: 0.2.0
Summary: Python SDK for London Strategic Edge real-time market data
Project-URL: Homepage, https://londonstrategicedge.com
Project-URL: Documentation, https://github.com/londonstrategicedge/lse-data
Project-URL: Repository, https://github.com/londonstrategicedge/lse-data
Project-URL: Issues, https://github.com/londonstrategicedge/lse-data/issues
Author-email: London Strategic Edge <support@londonstrategicedge.com>
License-Expression: MIT
License-File: LICENSE
Keywords: crypto,forex,market-data,options,real-time,stocks,trading,websocket
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Requires-Dist: websockets>=11.0
Provides-Extra: pandas
Requires-Dist: pandas>=1.5; extra == 'pandas'
Description-Content-Type: text/markdown

# lse-data

Python SDK for [London Strategic Edge](https://londonstrategicedge.com) real-time market data.

Stream live prices for **4,000+ instruments** including stocks, crypto, forex, indices, commodities, ETFs, and 81,000+ options contracts.

## Install

```bash
pip install lse-data
```

## Quick start

```python
from lse import LSE

client = LSE(api_key="your_api_key")

for tick in client.stream(["BTC/USD", "AAPL", "EUR/USD"]):
    print(f"{tick.symbol}: ${tick.price}")
```

Get your API key at [londonstrategicedge.com/data](https://londonstrategicedge.com/data).

## Features

- Real-time WebSocket streaming with auto-reconnect
- 4,000+ symbols: US/UK/EU/Asia stocks, crypto, forex, indices, commodities, ETFs, 81K+ options
- Symbol catalog API for discovery before subscribing
- Server-side symbol validation (invalid symbols rejected immediately)
- Sync and async interfaces
- Callback and iterator patterns
- Zero config, just an API key

## Usage

### Stream ticks (simplest)

```python
from lse import LSE

client = LSE(api_key="your_key")

for tick in client.stream(["BTC/USD", "ETH/USD", "AAPL"]):
    print(f"{tick.symbol:12s} ${tick.price:>12,.2f}")
```

### Callback style

```python
from lse import LSE

def on_tick(tick):
    print(f"{tick.symbol}: {tick.price}")

client = LSE(api_key="your_key")
client.on("tick", on_tick)
client.connect(symbols=["BTC/USD", "ETH/USD"])
```

### Async streaming

```python
import asyncio
from lse import LSE

async def main():
    client = LSE(api_key="your_key")
    async for tick in client.stream_async(["BTC/USD"]):
        print(tick)

asyncio.run(main())
```

### Save to CSV

```python
import csv, datetime
from lse import LSE

client = LSE(api_key="your_key")

with open("ticks.csv", "w", newline="") as f:
    writer = csv.writer(f)
    writer.writerow(["time", "symbol", "price", "bid", "ask"])

    for tick in client.stream(["BTC/USD", "ETH/USD"]):
        writer.writerow([
            datetime.datetime.now().isoformat(),
            tick.symbol, tick.price, tick.bid, tick.ask,
        ])
```

## Tick object

Each tick has these fields:

| Field | Type | Description |
|-------|------|-------------|
| `symbol` | `str` | Instrument symbol (e.g. `BTC/USD`, `AAPL`) |
| `price` | `float` | Latest price |
| `bid` | `float` | Bid price (if available) |
| `ask` | `float` | Ask price (if available) |
| `volume` | `float` | Volume (if available) |
| `timestamp` | `float` | Unix timestamp |
| `name` | `str` | Human-readable name (e.g. `Apple Inc.`) |

## Events

When using the callback style with `.on()`:

| Event | Callback args | Description |
|-------|---------------|-------------|
| `tick` | `Tick` | New price tick |
| `connected` | (none) | WebSocket connected |
| `authenticated` | (none) | API key accepted |
| `disconnected` | (none) | Connection lost (will auto-reconnect) |
| `error` | `str` | Error message |

## Symbol catalog

Query available instruments before subscribing. No WebSocket connection needed.

```python
from lse import LSE

client = LSE(api_key="your_key")

# Get all available symbols
all_symbols = client.catalog()
print(f"{len(all_symbols)} instruments available")

# Filter by category: stock, crypto, forex, etf, commodity, index
stocks = client.catalog(category="stock")
crypto = client.catalog(category="crypto")

# Each entry has symbol, display_name, and category
for s in crypto[:5]:
    print(f"{s['symbol']:12s} {s['display_name']:20s} {s['category']}")
```

The catalog returns every subscribable instrument. Use it to build symbol pickers, validate user input, or discover what is available.

### Available categories

| Category | Count | Examples |
|----------|-------|---------|
| stock | ~3,987 | AAPL, NVDA, TSLA, 0005.HK, 7203.T |
| forex | ~62 | EUR/USD, GBP/JPY, USD/CHF |
| crypto | ~58 | BTC/USD, ETH/USD, SOL/USD |
| etf | ~25 | SPY, QQQ, IWM, GLD |
| commodity | ~23 | XAU/USD, WTICO/USD, NATGAS/USD |
| index | ~13 | US30, NAS100, UK100 |

Options (81,000+ contracts) are available separately via the WebSocket `subscribe_options` action.

## Requirements

- Python 3.8+
- `websockets` (installed automatically)

## License

MIT
