Metadata-Version: 2.4
Name: lotech-market-data
Version: 2.0.0
Requires-Dist: aioboto3>=15.5.0
Requires-Dist: boto3>=1.40.46
Requires-Dist: boto3-stubs>=1.40.46
Requires-Dist: mypy-boto3-athena>=1.40.60
Requires-Dist: polars>=1.36.1
Requires-Dist: pyarrow>=22.0.0
Requires-Dist: requests>=2.31.0
Requires-Dist: boto3-stubs[athena,s3]>=1.35.0 ; extra == 'dev'
Requires-Dist: botocore-stubs>=1.35.0 ; extra == 'dev'
Requires-Dist: librt>=0.7.7 ; extra == 'dev'
Requires-Dist: maturin[patchelf]>=1.0 ; extra == 'dev'
Requires-Dist: mypy>=1.11.0 ; extra == 'dev'
Requires-Dist: mypy-boto3-athena>=1.40.60 ; extra == 'dev'
Requires-Dist: mypy-boto3-s3>=1.40.61 ; extra == 'dev'
Requires-Dist: mypy-extensions>=1.1.0 ; extra == 'dev'
Requires-Dist: pathspec>=1.0.2 ; extra == 'dev'
Requires-Dist: pytest>=8.0.0 ; extra == 'dev'
Requires-Dist: ruff>=0.8.0 ; extra == 'dev'
Requires-Dist: twine>=6.2.0 ; extra == 'dev'
Requires-Dist: types-aioboto3[athena,s3]>=15.5.0 ; extra == 'dev'
Requires-Dist: typing-extensions>=4.15.0 ; extra == 'dev'
Requires-Dist: matplotlib>=3.0.0 ; extra == 'examples'
Requires-Dist: numpy>=1.24.0 ; extra == 'examples'
Requires-Dist: scipy>=1.10.0 ; extra == 'examples'
Provides-Extra: dev
Provides-Extra: examples
Summary: Python client for accessing LO:TECH market data
Requires-Python: >=3.11
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# lotech-market-data

Python client for accessing Lotech market data from AWS Athena.

## Installation

```bash
pip install lotech-market-data
```

For running the advanced plotting examples:

```bash
pip install lotech-market-data[examples]
```

## Usage

### Basic Example

```python
import logging
from datetime import datetime, timezone
from lotech_market_data import LotechMarketData

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

client = LotechMarketData()

# Get time range for today
query_date = datetime.now(timezone.utc).date()
start = datetime.combine(query_date, datetime.min.time()).replace(tzinfo=timezone.utc)
end = datetime.combine(query_date, datetime.max.time()).replace(tzinfo=timezone.utc)

# Fetch top of book data
df = client.load_top_of_book(
    exchange="BINANCE",
    instrument="BTC-USDT:SPOT",
    start=start,
    end=end,
)

logger.info("Total rows: %d", df.height)
```

### API Methods

The `LotechMarketData` class provides the following methods:

#### Market Data Methods

All market data methods accept the following parameters:
- `exchange`: Single exchange string or list of exchanges (e.g., `"BINANCE"` or `["BINANCE", "BYBIT"]`)
- `instrument`: Single instrument or list (e.g., `"BTC-USDT:SPOT"` or `["BTC-USDT:SPOT", "ETH-USDT:SPOT"]`)
- `start`: Start datetime (timezone-aware)
- `end`: End datetime (timezone-aware)
- `columns` (optional): List of columns to return

Available methods:
- `load_top_of_book()` - Top of book (bid/ask) data
- `load_trades()` - Trade data
- `load_funding()` - Funding rate data
- `load_reference_price()` - Reference price data
- `load_open_interest()` - Open interest data
- `load_orderbook_incremental()` - Incremental orderbook updates

#### Instrument Static

```python
# Get all instruments for an exchange (latest)
df = client.load_instr_static(exchange="BINANCE")

# Get all instruments at a specific datetime
df = client.load_instr_static(
    exchange="BINANCE",
    datetime=some_datetime
)

# Filter for specific instrument(s)
df = client.load_instr_static(
    exchange="BINANCE",
    instrument="BTC-USDT:SPOT"
)

df = client.load_instr_static(
    exchange="BINANCE",
    instrument=["BTC-USDT:SPOT", "ETH-USDT:SPOT"]
)
```

### Column Filtering

You can filter columns to reduce data transfer:

```python
df = client.load_top_of_book(
    exchange="BINANCE",
    instrument="BTC-USDT:SPOT",
    start=start,
    end=end,
    columns=["exchange", "instrument", "ingress_ts", "bid_price", "ask_price"],
)
```

### Multiple Exchanges

Query multiple exchanges:

```python
df = client.load_top_of_book(
    exchange=["BINANCE", "BYBIT"],
    instrument="BTC-USDT:SPOT",
    start=start,
    end=end,
)
```

### Multiple Instruments

Query multiple instruments:

```python
df = client.load_top_of_book(
    exchange="BINANCE",
    instrument=["BTC-USDT:SPOT", "ETH-USDT:SPOT", "SOL-USDT:SPOT"],
    start=start,
    end=end,
)
```

## Available Exchanges

Get the list of available exchanges programmatically:

```python
exchanges = LotechMarketData.get_available_exchanges()
logger.info("Available exchanges: %s", exchanges)
```

Current exchanges include:
- BINANCE
- BITFINEX
- BITGET
- BITMART
- BITMEX
- BITRUE
- BITSTAMP
- BYBIT
- COINBASEINTL
- COINBASEUS
- CRYPTOCOM
- GATEIO
- HTX
- HYPERLIQUID
- KRAKEN
- KUCOIN
- MEXC
- OKX
- POLYMARKET

## Instrument Format

Instruments follow the format: `SYMBOL:KIND[:SUBKIND]`

Examples:
- `BTC-USDT:SPOT` - Spot market
- `BTC-USDT:PERP:LINEAR` - Linear perpetual
- `BTC-USDT:PERP:INVERSE` - Inverse perpetual
- `BTC-USD:FUT:LINEAR` - Linear future
- `BTC-USD:FUT:INVERSE` - Inverse future

## Examples

### Basic Examples (`examples/basic/`)

These examples showcase fetching each data type and display all available columns:

- `top_of_book.py` - Fetch bid/ask data
- `trades.py` - Fetch trade data
- `orderbook_incremental.py` - Fetch orderbook updates and build orderbook
- `funding.py` - Fetch funding rate data
- `open_interest.py` - Fetch open interest data
- `reference_price.py` - Fetch reference price data
- `instrument_static.py` - Fetch instrument metadata
- `list_exchanges.py` - List all available exchanges

### Advanced Examples (`examples/advanced/`)

These examples demonstrate more complex use cases:

- `plot_btc_usdt_exchanges.py` - Plot BTC-USDT mid price across multiple exchanges
- `plot_trades.py` - Visualize trades with volume bars
- `analyze_instruments.py` - Analyze instrument metadata with statistics
- `animate_orderbook.py` - Create animated orderbook visualization
- `plot_polymarket_binary.py` - Compare Polymarket binary options to GBM theoretical pricing

## Example Outputs

The advanced examples generate visualizations in `examples/outputs/`:

### BTC-USDT Mid Price Across Exchanges
![BTC-USDT Exchanges](examples/outputs/btc_usdt_exchanges.png)

Comparison of BTC-USDT perpetual mid price across BINANCE, BYBIT, OKX, BITMART, and BITMEX exchanges showing price movements and spreads.

### LTC-USDT Trades Visualization
![LTC-USDT Trades](examples/outputs/ltc_usdt_trades.png)

Trades visualization for LTC-USDT perpetual contracts showing taker buy/sell trades colored by exchange, with weighted mid price overlay and 30-second volume bars.

### DOGE-USDT Orderbook Animation
![DOGE Orderbook](examples/outputs/doge_usdt_orderbook.gif)

Animated visualization of DOGE orderbook across 5 exchanges (BINANCE, BYBIT, OKX, COINBASEUS, BITSTAMP) showing cumulative order book depth, mid price movement, and cross-exchange dynamics at 10ms intervals.

