Metadata-Version: 2.4
Name: parsimony-polymarket
Version: 0.0.2
Summary: Polymarket connector for the parsimony framework
Project-URL: Homepage, https://polymarket.com
Project-URL: Repository, https://github.com/ockham-sh/parsimony-connectors
Project-URL: Issues, https://github.com/ockham-sh/parsimony-connectors/issues
Author-email: "Ockham.sh" <team@ockham.sh>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: connectors,data,finance,parsimony,polymarket
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: pandas<3,>=2.3.0
Requires-Dist: parsimony~=0.0.1
Requires-Dist: pydantic<3,>=2.11.1
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=9.0.3; extra == 'dev'
Requires-Dist: respx>=0.22.0; extra == 'dev'
Requires-Dist: ruff>=0.15.10; extra == 'dev'
Description-Content-Type: text/markdown

# parsimony-polymarket

Polymarket source for parsimony: prediction-market discovery and prices via the public Gamma and CLOB HTTP APIs.

Part of the [parsimony-connectors](https://github.com/ockham-sh/parsimony-connectors) monorepo. Distributed standalone on PyPI as `parsimony-polymarket`.

## Connectors

The surface follows how a Polymarket question is actually navigated: **search → event → market → price history.**

| Name | Kind | Description |
|---|---|---|
| `polymarket_search_events` | enumerator | Natural-language search over events via Gamma `/public-search` (the only Polymarket endpoint that does server-side text search). Returns `slug` + `title` with `markets_count` and `volume`/`liquidity`/`active`/`closed` metadata. Takes `query`, `limit` (1-100), `optimized`. |
| `polymarket_event` | enumerator | The markets inside one event, by event `slug`. One row per market (`market_slug` + `market_question`, with outcome count and volume/liquidity/active/closed). |
| `polymarket_market` | enumerator | The outcomes of one market and their CLOB token ids, by market `slug`. One row per outcome (`clob_token_id` + `outcome`). |
| `polymarket_price_history` | connector | The probability time series for one outcome `token_id` via CLOB `/prices-history`. Returns a tidy `timestamp` × `probability` frame. Takes `interval` (max/1m/1w/1d/6h/1h) and `fidelity` (minutes). |

## Install

```bash
pip install parsimony-polymarket
```

Pulls in a compatible `parsimony` automatically. Verify discovery:

```bash
python -c "from parsimony import discover; print([p.name for p in discover.iter_providers()])"
```

## Configuration

No environment variables required — Polymarket's Gamma and CLOB read APIs are public. There is no API key, so this package declares no secrets and no `load(*, api_key=...)` convenience.

## Quick start

```python
from parsimony_polymarket import CONNECTORS

# 1. Search events by topic.
events = CONNECTORS["polymarket_search_events"](query="inflation", limit=5)
event_slug = events.raw.iloc[0]["slug"]

# 2. Drill into the event's markets.
markets = CONNECTORS["polymarket_event"](slug=event_slug)
market_slug = markets.raw.iloc[0]["market_slug"]

# 3. Get the market's outcomes and their CLOB token ids.
outcomes = CONNECTORS["polymarket_market"](slug=market_slug)
token_id = outcomes.raw.iloc[0]["clob_token_id"]

# 4. Pull that outcome's probability time series.
history = CONNECTORS["polymarket_price_history"](token_id=token_id, interval="1w")
print(history.raw.head())
```

For multi-plugin composition:

```python
from parsimony import discover

connectors = discover.load_all()
```

## Provider

- Homepage: <https://polymarket.com>
- Gamma API: <https://gamma-api.polymarket.com>
- CLOB API: <https://clob.polymarket.com>

## License

See [LICENSE](./LICENSE).
