Metadata-Version: 2.4
Name: ito-markets
Version: 0.1.0
Summary: Python SDK for the Ito Markets public API — prediction market data, baskets, and backtesting.
Project-URL: Homepage, https://itomarkets.com
Project-URL: Documentation, https://institutional.itomarkets.com/docs/public-api
Project-URL: Repository, https://github.com/Ito-Markets/ito-python
Project-URL: Changelog, https://github.com/Ito-Markets/ito-python/releases
Author-email: Ito Markets <dev@itomarkets.com>
License-Expression: MIT
License-File: LICENSE
Keywords: backtesting,kalshi,polymarket,prediction-markets,quant,research
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx<1.0,>=0.25
Provides-Extra: dev
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: pandas
Requires-Dist: pandas>=2.0; extra == 'pandas'
Description-Content-Type: text/markdown

# ito-markets — Python SDK for Ito Markets

Thin, typed Python wrapper for the [Ito Markets public API](https://institutional.itomarkets.com/docs/public-api). Access prediction market baskets, individual market data, historical orderbook snapshots, and run backtests — all with a single `pip install`.

## Install

```bash
pip install ito-markets
# or with pandas support:
pip install ito-markets[pandas]
```

## Quick Start

```python
from ito import ItoClient

client = ItoClient("ito_...")  # your API key from Settings

# List all baskets
baskets = client.baskets.list()
for b in baskets["data"]:
    print(f"{b['basket_id']}: ${b['stats']['current_price']:.2f}")

# Get a single market
market = client.markets.get("will-btc-reach-100k")
print(market["data"]["title"], market["data"]["last_price"])

# Price history
history = client.markets.history("will-btc-reach-100k", days=90)
for point in history["data"]["series"]:
    print(point["date"], point["close_price"])

# Bulk prices for multiple markets
prices = client.data.prices(["market-a", "market-b", "market-c"], days=30)

# Historical L2 orderbook
book = client.data.orderbook(
    venue="polymarket",
    market="will-btc-reach-100k",
    start="2026-06-01T00:00:00Z",
    end="2026-06-01T01:00:00Z",
    limit=5000,
)

# Run a backtest on a thematic basket
result = client.backtests.run(
    strategy_id="crypto_updown_roll_timing",
    dataset_id="clickhouse:ito_hot.platform_orderbook_l2",
    venues=["polymarket"],
    date_range={"start": "2026-05-01T00:00:00Z", "end": "2026-06-01T00:00:00Z"},
    basket_id="middle-east-conflict",  # only markets in this basket
    params={"roll_trigger": "liquidity_spread_score"},
)
print(f"P&L: ${result['data']['metrics']['pnl_usd']:.2f}")
```

## API Key

1. Go to [institutional.itomarkets.com](https://institutional.itomarkets.com)
2. Sign up / log in
3. Go to **Settings** -> generate an API key
4. Use the key (starts with `ito_`) in the client constructor

## Available Endpoints

### Baskets (9 endpoints)
| Method | Description |
|--------|-------------|
| `client.baskets.list()` | All baskets with current prices |
| `client.baskets.get(id)` | Single basket details |
| `client.baskets.price(id)` | Current price + underlyer snapshot |
| `client.baskets.history(id)` | Price time series |
| `client.baskets.chart(id)` | OHLC chart data |
| `client.baskets.metrics(id)` | Returns, volatility |
| `client.baskets.underlyers(id)` | Component markets |
| `client.baskets.overrides()` | Manual overrides |
| `client.baskets.volume_daily()` | Daily traded volume |

### Markets (3 endpoints)
| Method | Description |
|--------|-------------|
| `client.markets.search()` | Filtered listing by volume |
| `client.markets.get(id)` | Single market detail |
| `client.markets.history(id)` | Daily price series |

### Research Data (2 endpoints)
| Method | Description |
|--------|-------------|
| `client.data.orderbook(venue, market)` | Historical L2 snapshots |
| `client.data.prices(market_ids)` | Bulk daily close prices |

### Backtesting (9 endpoints)
| Method | Description |
|--------|-------------|
| `client.backtests.strategies()` | Available strategies |
| `client.backtests.create_strategy(...)` | Create custom strategy |
| `client.backtests.custom_strategies()` | List custom strategies |
| `client.backtests.datasets()` | Available datasets |
| `client.backtests.execution_models()` | Fill models |
| `client.backtests.validate(...)` | Dry-run validation |
| `client.backtests.plan(...)` | Multi-window experiment |
| `client.backtests.submit(...)` | Submit for execution |
| `client.backtests.run(...)` | Submit + poll to completion |

## Features

- **Typed**: Full type hints for IDE autocompletion
- **Retries**: Automatic retry with exponential backoff on 429/5xx
- **Errors**: Typed exceptions (`ItoAuthError`, `ItoRateLimitError`, etc.)
- **Context manager**: `with ItoClient(...) as client:` for clean resource management
- **Lightweight**: Only dependency is `httpx`

## Development

```bash
git clone https://github.com/Ito-Markets/ito-python.git
cd ito-python
pip install -e ".[dev]"
pytest
```

## License

MIT
