Metadata-Version: 2.4
Name: predictefy
Version: 1.0.0b1
Summary: Official Python client + CLI for the Predictefy unified prediction-market API.
Project-URL: Homepage, https://predictefy.com
Author: Predictefy Inc.
License: MIT
License-File: LICENSE
Keywords: api,kalshi,polymarket,predictefy,prediction-markets,sdk
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: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == 'dev'
Description-Content-Type: text/markdown

# predictefy — Python SDK + CLI

The official Python client for **Predictefy's unified prediction-market intelligence
and execution infrastructure**. Integrate once against one normalized contract, then
change the venue client or `venue` parameter to access a different prediction-market
venue.

The Python client covers the normalized data and intelligence surface across all 17
current product venues (Polymarket, Kalshi, Smarkets, Opinion, Myriad, Gemini, SuiBets,
Hyperliquid, Limitless, Polymarket US, Rain, Baozi, PredictFun, SX Bet, Pascal, XO Market,
and PRED), plus the cross-venue router, history, market relationships, and Trader
Intelligence. Current execution and client-side signing coverage is documented separately
per SDK and venue.

Pascal, XO Market and PRED are **data-only** integrations: catalog reads and order books
on all three, plus a public trades tape on Pascal only. They serve no trading, account or
venue-history lane — trading is a later, owner-gated phase.

Thin by design: **one runtime dependency (`httpx`)**, Python 3.10+, synchronous. All venue
logic lives server-side; this SDK is a typed wrapper over the hosted REST API.

## Install

> **Release status:** the package is built, but public PyPI publication is held for
> the launch sign-off. The install command below becomes available when that
> owner-controlled release completes; repository users can install the local package.

```bash
pip install predictefy
```

## Quickstart

```python
from predictefy import Predictefy

client = Predictefy(api_key="pk_...")  # or set PREDICTEFY_API_KEY
markets = client.polymarket.fetch_markets({"limit": 5, "query": "fed"})
for m in markets:
    print(m["marketId"], m["title"])
print(f"{len(markets)} of {markets.page['total']} total")
```

The same verbs exist on every venue and are drop-in compatible with familiar exchange-style SDK verbs:

```python
client.kalshi.fetch_order_book("KXFED-26MAR-T4.00")
client.exchange("hyperliquid").fetch_trades("BTC-100K")
client.router.fetch_markets({"query": "election", "status": "active"})  # all venues
client.polymarket.fetch_categories()
client.router.fetch_tags({"category": "sports"})
client.polymarket.fetch_ohlcv({"outcomeId": "123", "resolution": "1h", "limit": 500})
```

List verbs return a `PageList` — an ordinary `list` of dicts with `.page`, `.meta`,
`.next_cursor`, and `.total_count` attached when the endpoint supplies those hints. To
walk an entire catalog, `iterate_markets` follows the cursor for you:

```python
for market in client.polymarket.iterate_markets({"status": "active"}):
    ...  # transparently pages via nextCursor until exhausted
```

## Auth

Pass `api_key`, or set the `PREDICTEFY_API_KEY` environment variable. The key is sent as
`Authorization: Bearer <key>`, is never logged, and is redacted from every error message.

```python
client = Predictefy(
    api_key="pk_...",
    base_url="https://reads-production.up.railway.app",  # the default
    retry_on_429=True,  # auto-retry a GET once on 429, honoring Retry-After
)
```

Webhook endpoint management and delivery polling use `client.webhooks`:

```python
endpoint = client.webhooks.create({
    "url": "https://hooks.example.com/predictefy",
    "events": ["execution.status.changed"],
})
page = client.webhooks.deliveries(endpoint["id"], {"after": None, "limit": 50})
client.webhooks.delete(endpoint["id"])
```

The create response is the only response containing the signing secret. Delivery pages are
oldest-to-newest; pass `nextCursor` back as `after`.

## Hosted Account Intelligence

The singular `client.account` namespace reads only the hosted public account lanes. It
never accepts venue credentials and never performs owner-authenticated venue calls:

```python
capabilities = client.account.fetch_capabilities("polymarket")
snapshot = client.account.fetch_snapshot("polymarket", "0xabc")
balances = client.account.fetch_balances("polymarket", "0xabc", limit=20)
positions = client.account.fetch_positions("polymarket", "0xabc", limit=20, cursor=None)
orders = client.account.fetch_open_orders("polymarket", "0xabc", limit=20, cursor=None)
fills = client.account.fetch_fills("polymarket", "0xabc", limit=20, cursor=None)
```

Account lists preserve `.meta` provenance/cache fields and `.next_cursor`. Balances are
not cursor-paginated and expose the exact wire `totalCount` as `.total_count`. Snapshot
resource dictionaries preserve their `totalCount` fields verbatim. Local venue-credential
and owner-authenticated account lanes are intentionally deferred.

On `429 Too Many Requests`, a GET is retried **once**, honoring the `Retry-After` header
(bounded to 30s); if it is still rate-limited, a `RateLimitError` is raised. POSTs (batch
books, execution price, checkout) are never auto-retried.

## Clusters & indicative price discrepancies

```python
clusters = client.fetch_clusters({"limit": 20})
cluster = client.fetch_cluster("cl_abc123")           # one cluster + its per-venue members
gaps = client.fetch_discrepancies(live=True)          # indicative price discrepancies
```

`fetch_discrepancies` returns **indicative price discrepancies** — the cross-venue price
gap between matched markets. These are _indicative_, not executable trades: they do not
account for live executable depth, fees, or resolution edge cases. Use them for signal, not
as a guaranteed profit.

## Errors

Every failure raises a subclass of `PredictefyError`; the server's `code` and `message` are
preserved on the exception.

| Class                      | HTTP    | Meaning                                              |
| -------------------------- | ------- | ---------------------------------------------------- |
| `ValidationError`          | 400     | Bad input / missing required param                   |
| `AuthenticationError`      | 401     | Missing / unknown / revoked key                      |
| `InsufficientCreditsError` | 402     | Balance can't cover the request (`.top_up_hint`)     |
| `ScopeError`               | 403     | Key lacks scope for this route                       |
| `NotFoundError`            | 404     | Unknown exchange/market/event/outcome/cluster        |
| `NotSupportedError`        | 400/501 | Venue/param honestly can't do that (`NOT_SUPPORTED`) |
| `RateLimitError`           | 429     | Rate-limited (raised after the retry is exhausted)   |
| `FeatureDisabledError`     | 503     | A documented route is dark on this deployment        |
| `ServerError`              | 5xx     | Transient platform failure                           |
| `NetworkError`             | —       | Transport failure / unparseable body                 |

```python
from predictefy import Predictefy, InsufficientCreditsError

try:
    client.polymarket.fetch_markets()
except InsufficientCreditsError as err:
    print(err.code, err.top_up_hint)
```

## CLI

The package installs a `predictefy` console command:

```bash
export PREDICTEFY_API_KEY=pk_...

predictefy markets polymarket --limit 10 --q fed
predictefy market kalshi KXFED-26MAR-T4.00
predictefy discrepancies --limit 20 --live
predictefy clusters --limit 20
predictefy account capabilities polymarket
predictefy account snapshot polymarket 0xabc
predictefy account balances polymarket 0xabc --limit 20
predictefy account positions polymarket 0xabc --limit 20 --cursor next-page
```

Add `--json` to any command for raw JSON. `--api-key` and `--base-url` override the
`PREDICTEFY_API_KEY` / `PREDICTEFY_BASE_URL` environment variables.

## License

MIT — see [LICENSE](./LICENSE).
