Metadata-Version: 2.4
Name: polyflux-client
Version: 0.1.0
Summary: Official Python client for Polyflux — stream real-time Polymarket trades from the mempool over WebSocket.
Project-URL: Homepage, https://polyflux.io
Project-URL: Documentation, https://polyflux.io/blog
Project-URL: Repository, https://github.com/polyflux/polyflux-python
Author: Polyflux
License: MIT
License-File: LICENSE
Keywords: market-data,mempool,polymarket,prediction-markets,real-time,sdk,trading-bot,websocket
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.10
Requires-Dist: requests>=2.28
Requires-Dist: websockets>=12.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == 'dev'
Description-Content-Type: text/markdown

# polyflux

**Official Python client for [Polyflux](https://polyflux.io) — stream real-time Polymarket trades from the mempool over WebSocket.**

See every Polymarket trade the millisecond it happens — ~3 seconds before it confirms on-chain. Build trading bots, whale alerts, and real-time signals in a few lines of Python.

> You need a Polyflux API key to stream. **[Get one at polyflux.io →](https://polyflux.io/auth)** (free trial).

## Install

```bash
pip install polyflux-client
```
Then `import polyflux` in your code.

## Quickstart

```python
import asyncio
from polyflux import Client

async def main():
    client = Client("YOUR_API_KEY")          # get one at https://polyflux.io
    async for trade in client.trades():
        print(trade.side, trade.size, trade.price, trade.wallet_address)

asyncio.run(main())
```

Each `Trade` gives you `asset_id`, `wallet_address`, `size`, `price`, `side`
(`buy`/`sell`), `timestamp`, plus helpers like `.notional` (USDC value) and
`.time` (UTC datetime). The full raw message is always on `.raw`.

The client handles connection, parsing, and **automatic reconnection** — just
`async for` over `.trades()` and let it run.

## Resolve markets

The feed identifies markets by `asset_id` (a clob token id). Use `MarketCatalog`
to turn that into a human-readable market:

```python
from polyflux import Client, MarketCatalog

catalog = MarketCatalog(market_fields=["question"])
await catalog.start()   # caches the active-market set under ./data

async for trade in client.trades():
    record = catalog.get(trade.asset_id)
    if record:
        print(record["market"]["question"], trade.size, trade.price)
```

`MarketCatalog` keeps an O(1) `asset_id → market` map with a configurable memory
footprint, refreshes in the background, and can fetch unknown ids on demand. See
[`examples/whale_alert.py`](examples/whale_alert.py) for a full bot.

## Examples

- [`examples/quickstart.py`](examples/quickstart.py) — stream trades
- [`examples/whale_alert.py`](examples/whale_alert.py) — alert on large trades, named by market
- [`examples/catalog_lookup.py`](examples/catalog_lookup.py) — market-catalog projections

```bash
POLYFLUX_API_KEY=your_key python examples/quickstart.py
```

## Links

- **Get an API key:** https://polyflux.io/auth
- **Guides:** https://polyflux.io/blog
- **Live feed / product:** https://polyflux.io

## License

MIT
