# Python SDK

### Overview

Official Python SDK for the Infoway real-time financial data API, providing REST API and WebSocket streaming interfaces across stocks, crypto, forex, and more.

| Item    | Details                                                                             |
| ------- | ----------------------------------------------------------------------------------- |
| PyPI    | [`infoway-sdk`](https://pypi.org/project/infoway-sdk/)                              |
| Python  | 3.9+                                                                                |
| License | MIT                                                                                 |
| GitHub  | [infoway-api/infoway-sdk-python](https://github.com/infoway-api/infoway-sdk-python) |

### Installation

```bash
pip install infoway-sdk
```

### Quick Start

```python
from infoway import InfowayClient, KlineType

client = InfowayClient(api_key="YOUR_API_KEY")

# Real-time trades
trades = client.stock.get_trade("AAPL.US")

# Crypto daily K-lines
klines = client.crypto.get_kline("BTCUSDT", kline_type=KlineType.DAY, count=30)

# Market temperature
temp = client.market.get_temperature(market="HK,US")

# Industry sector ranking
plates = client.plate.get_industry("HK", limit=10)
```

### Configuration

Pass `api_key` directly or set it via environment variable:

```bash
export INFOWAY_API_KEY="YOUR_API_KEY"
```

```python
# Reads INFOWAY_API_KEY from environment automatically
client = InfowayClient()
```

#### Client Options

```python
client = InfowayClient(
    api_key="YOUR_API_KEY",
    base_url="https://data.infoway.io",  # default
    timeout=15.0,                         # request timeout in seconds
    max_retries=3,                        # retry count for failed requests
)
```

### REST API Modules

| Module     | Accessor            | Description                                           |
| ---------- | ------------------- | ----------------------------------------------------- |
| Stock      | `client.stock`      | HK, US, CN equities — trade, depth, K-line            |
| Crypto     | `client.crypto`     | Cryptocurrency — trade, depth, K-line                 |
| Japan      | `client.japan`      | Japan market — trade, depth, K-line                   |
| India      | `client.india`      | India market — trade, depth, K-line                   |
| Common     | `client.common`     | Cross-market — trade, depth, K-line                   |
| Basic      | `client.basic`      | Symbol lists, trading days, hours, adjustment factors |
| Market     | `client.market`     | Temperature, breadth, indexes, leaders, rank config   |
| Plate      | `client.plate`      | Industry/concept sectors, members, heatmap            |
| Stock Info | `client.stock_info` | Fundamentals — valuation, ratings, company, panorama  |

#### Market Data Methods (stock / crypto / japan / india / common)

| Method                                | Description              |
| ------------------------------------- | ------------------------ |
| `get_trade(codes)`                    | Get real-time trade data |
| `get_depth(codes)`                    | Get order book depth     |
| `get_kline(codes, kline_type, count)` | Get K-line (OHLCV) data  |

#### Basic Info Methods

```python
client.basic.get_symbols("US")             # Symbol list
client.basic.get_symbol_info("AAPL.US")    # Symbol details
client.basic.get_trading_days("US")        # Trading calendar
client.basic.get_trading_hours("US")       # Trading hours
client.basic.get_adjustment_factors("AAPL.US")  # Adjustment factors
```

#### Market Overview Methods

```python
client.market.get_temperature("HK,US")    # Market temperature / sentiment
client.market.get_breadth("US")            # Advance / decline stats
client.market.get_indexes()                # Major global indexes
client.market.get_leaders("US", limit=10)  # Leading industries
client.market.get_rank_config("US")        # Ranking configuration
```

#### Plate / Sector Methods

```python
client.plate.get_industry("HK", limit=200)         # Industry sector list
client.plate.get_concept("HK", limit=100)           # Concept sector list
client.plate.get_members("IN20293.HK")              # Sector constituents
client.plate.get_intro("IN20293.HK")                # Industry introduction
client.plate.get_chart("HK", limit=50)              # Sector heatmap
```

#### Stock Fundamental Methods

```python
client.stock_info.get_valuation("AAPL.US")   # Valuation data
client.stock_info.get_ratings("AAPL.US")     # Institutional ratings
client.stock_info.get_company("AAPL.US")     # Company overview
client.stock_info.get_panorama("AAPL.US")    # Stock panorama
client.stock_info.get_concepts("AAPL.US")    # Concept tags
client.stock_info.get_events("AAPL.US", limit=20)  # Corporate events
client.stock_info.get_drivers("AAPL.US")     # Key drivers analysis
```

### WebSocket Streaming

```python
import asyncio
from infoway.ws import InfowayWebSocket

async def main():
    ws = InfowayWebSocket(api_key="YOUR_API_KEY", business="stock")

    async def on_trade(msg):
        print(f"Trade: {msg}")

    ws.on_trade = on_trade
    await ws.subscribe_trade("AAPL.US,TSLA.US")
    await ws.connect()

asyncio.run(main())
```

#### WebSocket Features

* **Auto-reconnect** with exponential backoff (1s to 30s cap)
* **Heartbeat keepalive** at 30-second intervals
* **Auto-resubscribe** on reconnect — no manual re-subscription needed
* Event callbacks: `on_trade`, `on_depth`, `on_kline`, `on_error`, `on_reconnect`, `on_disconnect`

#### WebSocket Message Codes

| Code  | Name         | Description              |
| ----- | ------------ | ------------------------ |
| 10000 | SUB\_TRADE   | Subscribe to trade data  |
| 10001 | PUSH\_TRADE  | Push trade data          |
| 10002 | UNSUB\_TRADE | Unsubscribe trade data   |
| 10003 | SUB\_DEPTH   | Subscribe to depth data  |
| 10004 | PUSH\_DEPTH  | Push depth data          |
| 10005 | UNSUB\_DEPTH | Unsubscribe depth data   |
| 10006 | SUB\_KLINE   | Subscribe to K-line data |
| 10007 | PUSH\_KLINE  | Push K-line data         |
| 10008 | UNSUB\_KLINE | Unsubscribe K-line data  |
| 10010 | HEARTBEAT    | Heartbeat keepalive      |

#### K-line Types

| Enum                     | Interval   |
| ------------------------ | ---------- |
| `KlineType.MIN_1` (1)    | 1 minute   |
| `KlineType.MIN_5` (2)    | 5 minutes  |
| `KlineType.MIN_15` (3)   | 15 minutes |
| `KlineType.MIN_30` (4)   | 30 minutes |
| `KlineType.HOUR_1` (5)   | 1 hour     |
| `KlineType.HOUR_2` (6)   | 2 hours    |
| `KlineType.HOUR_4` (7)   | 4 hours    |
| `KlineType.DAY` (8)      | 1 day      |
| `KlineType.WEEK` (9)     | 1 week     |
| `KlineType.MONTH` (10)   | 1 month    |
| `KlineType.QUARTER` (11) | 1 quarter  |
| `KlineType.YEAR` (12)    | 1 year     |

### Error Handling

```python
from infoway import InfowayClient, InfowayAPIError, InfowayAuthError, InfowayTimeoutError

client = InfowayClient(api_key="YOUR_API_KEY")

try:
    trades = client.stock.get_trade("AAPL.US")
except InfowayAuthError:
    print("Invalid API key")
except InfowayTimeoutError:
    print("Request timed out")
except InfowayAPIError as e:
    print(f"API error [{e.ret}]: {e.msg}")
```

***