Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

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.

pip install predictefy

Quickstart

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:

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:

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.

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:

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:

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

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
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:

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.

Metadata

Release files for predictefy 1.0.0b1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for predictefy 1.0.0b1
File Size Uploaded Provenance Actions
predictefy-1.0.0b1.tar.gz 76.1 kB Without provenance Details for predictefy-1.0.0b1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for predictefy 1.0.0b1
File Interpreter ABI Platform Actions
predictefy-1.0.0b1-py3-none-any.whl Python 3 none any Details for predictefy-1.0.0b1-py3-none-any.whl

Total release size: 99.6 kB

Release files / predictefy-1.0.0b1.tar.gz

Download URL predictefy-1.0.0b1.tar.gz
Size 76.1 kB
Tags Source
SHA-256 checksum
How to use checksums
aefea2a48380be0c5cec54ce8b77bdcac6c9d9f4ef75736628ea97c84bce934f
BLAKE2b-256 checksum
How to use checksums
e315362513df0d70ee1ca3da137887d5d72b65a81b4ca08f954a03be961df2be
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.9.6

Release files / predictefy-1.0.0b1-py3-none-any.whl

Download URL predictefy-1.0.0b1-py3-none-any.whl
Size 23.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
39f02428394c273329393682ef9962ee288a8895a78ee05d77303728ace276f0
BLAKE2b-256 checksum
How to use checksums
e651ff18dc2503ca43db63f7f48f969d26f32dc9baed24f906c809ed4c27089b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.9.6

Security for predictefy 1.0.0b1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page