Metadata-Version: 2.4
Name: moomoo-data
Version: 0.2.0
Summary: Moomoo OpenD data provider for HKSE/KLSE markets with capital flow analysis
Project-URL: Homepage, https://github.com/hwase0ng/moomoo-data
Project-URL: Documentation, https://github.com/hwase0ng/moomoo-data#readme
Project-URL: Repository, https://github.com/hwase0ng/moomoo-data
Project-URL: Changelog, https://github.com/hwase0ng/moomoo-data/blob/main/CHANGELOG.md
Author-email: hwaseong <hwaseong.tan@gmail.com>
License: MIT
License-File: LICENSE
Keywords: HKSE,KLSE,capital flow,finance,moomoo,stock,trading
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.10
Requires-Dist: moomoo-api>=1.0.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: all
Requires-Dist: aiosqlite>=0.19.0; extra == 'all'
Requires-Dist: redis>=4.5.0; extra == 'all'
Provides-Extra: cache
Requires-Dist: aiosqlite>=0.19.0; extra == 'cache'
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: mypy>=1.5.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: ruff>=0.2.0; extra == 'dev'
Provides-Extra: redis
Requires-Dist: redis>=4.5.0; extra == 'redis'
Description-Content-Type: text/markdown

# moomoo-data

[![PyPI version](https://img.shields.io/pypi/v/moomoo-data.svg)](https://pypi.org/project/moomoo-data/)
[![Python versions](https://img.shields.io/pypi/pyversions/moomoo-data.svg)](https://pypi.org/project/moomoo-data/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Moomoo OpenD data provider for HKSE/KLSE markets with capital flow analysis**

A comprehensive Python library for accessing Moomoo OpenD API data, featuring:

- 📈 **Real-time quotes** for HKSE and KLSE stocks
- 📊 **K-line data** (daily, weekly, monthly, intraday)
- 💰 **Capital flow analysis** (super/big/mid/small order tracking)
- 🎯 **Chip distribution analysis** (triangular distribution model)

- 💾 **Built-in caching** (memory + SQLite)
- ⚡ **Rate limiting** with configurable limits

## Installation

```bash
pip install moomoo-data
```

### Optional dependencies

```bash
# Full installation with all features
pip install moomoo-data[all]

# SQLite caching (recommended for production)
pip install moomoo-data[cache]
```

## Requirements

- Python 3.10+
- Moomoo OpenD gateway running locally (default: `127.0.0.1:11111`)
- `moomoo-api` package (`pip install moomoo-api`)

## Quick Start

```python
from moomoo_data import get_stock_quote, get_daily_kline, get_capital_flow

# Get real-time quote
quote = get_stock_quote("0700.HK")
print(f"Price: {quote['最新价']}, Change: {quote['涨跌幅']}%")

# Get daily K-line
kline = get_daily_kline("0700.HK", count=100)
print(f"Retrieved {len(kline)} days of data")

# Get capital flow
flow = get_capital_flow("0700.HK")
print(f"Net inflow: {flow['net_inflow']}")
```

## Configuration

Configure via environment variables or `.env` file:

```bash
# Moomoo OpenD connection
MOOMOO_HOST=127.0.0.1
MOOMOO_PORT=11111
MOOMOO_ENABLED=true

# Cache settings
MOOMOO_CACHE_PATH=~/.cache/moomoo-data/cache.db
MOOMOO_CACHE_ENABLED=true

# Rate limits (requests per 30 seconds)
MOOMOO_RATE_LIMIT_QUOTE=30
MOOMOO_RATE_LIMIT_KLINE=20
```

## API Reference

### Core Functions

| Function | Description | Returns |
|----------|-------------|---------|
| `get_stock_quote(ticker)` | Real-time stock quote | Dict with OHLCV + changes |
| `get_daily_kline(ticker, count)` | Daily K-line data | pandas DataFrame |
| `get_history_kline(ticker, start, end)` | Historical K-line | pandas DataFrame |
| `get_capital_flow(ticker)` | Capital flow by order size | Dict with inflow/outflow |
| `get_capital_distribution(ticker)` | Current capital distribution | Dict with super/big/mid/small |
| `analyze_chip_distribution(ticker)` | Chip distribution analysis | Dict with avg_cost, concentration |

### Ticker Formats

Supported formats:
- **FinGenius**: `0700.HK`, `7088.KL`
- **Moomoo**: `HK.00700`, `MY.07088`

The library automatically converts between formats.

## Markets Supported

| Market | Ticker Suffix | Example |
|--------|---------------|---------|
| HKSE | `.HK` | `0700.HK` (Tencent) |
| KLSE | `.KL` | `7088.KL` (Yinson) |
| A-Share | 6-digit code | `600519` (Kweichow Moutai) |

## Chip Analysis

The library includes a professional-grade chip distribution analyzer using:

- **Triangular distribution**: Spreads turnover across price range
- **L-Curve decay**: Models psychological selling behavior
- **Dynamic bin sizing**: Market-aware granularity
- **NumPy vectorization**: 100x faster than loops

```python
from moomoo_data import analyze_chip_distribution

result = analyze_chip_distribution("0700.HK")
print(f"Average cost: {result['avg_cost']}")
print(f"Concentration (90%): {result['concentration_90']}%")
print(f"Profit ratio: {result['profit_ratio']}%")
```



## Examples

See the `examples/` directory for:

- `01_basic_quote.py` - Real-time quotes
- `02_kline_analysis.py` - K-line data retrieval
- `03_capital_flow.py` - Capital flow analysis
- `04_chip_distribution.py` - Chip distribution visualization


## Documentation

Full API documentation: [GitHub](https://github.com/hwase0ng/moomoo-data)

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for version history.
