API documentation

Authentication

All API requests require a bearer token. Generate your API key in the Predicue dashboard under Settings → API Keys. Include it in every request header:

API keys are tied to your account and inherit your subscription level restrictions. Never expose your API key in client code or public repositories. Change your keys immediately if they are compromised.

You can create up to 5 API keys per account. Each key can be individually revoked from the control panel. Keys do not expire unless manually revoked.

Betting restrictions

Rate limit headers are included in each answer: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. When throttling, the API returns HTTP 429 s Retry-After title.

Markets

GET /v1/markets

Returns a page-by-page list of all active prediction markets with current prices, volumes, and probability data.

Request parameters:

• limit (int, default 20, maximum 100) — Number of results per page
• offset (int, default 0) — Page numbering offset
• category (string) — Filter by category: politics, cryptocurrency, sports, economics, technology, entertainment, science.
• sort (string) - Sort by: volume, probabilistic shift, created_in, name.
• order (string) - ascending or descending (default: descending)

GET /v1/markets/:id

Returns detailed information for a single market, including historical price data, liquidity depth, settlement criteria, and related markets. :id Parameter—Polymarket condition identifier.

Scanner

GET /v1/scanner

Returns the current edge candidates and probabilistic deviations detected by our AI models. Each signal includes:

• market_id — Polymarket condition identifier
• signal_type — probabilistic_shift, volume_jump, liquidity_anomaly, catalyst_discrepancy
• confidence — Confidence score 0–100
• reasoning — An array of reasoning steps
• historical_accuracy — Proven accuracy for similar signals
• detected_at — ISO 8601 timestamp

Request parameters: min_confidence (integer, 0–100), signal_type (thread), category (thread), limit (integer, default 10).

Briefcase

GET /v1/portfolio/analysis

Analyzes your connected portfolio for concentration risk, correlation exposure, hedging opportunities and gain and loss attribution. A connected Polymarket account is required.

The answer includes:

• total_value — Current portfolio value in US dollars
• positions — An array of all positions with P&L
• concentration — Concentration breakdown by category
• correlations — Correlation matrix between positions
• hedging_opportunities — Proposed hedges
• risk_score — Total portfolio risk (0-100)

Briefings

GET /v1/briefings

Returns the briefings you created. Each briefing includes market overviews, portfolio insights and actionable recommendations.

Request parameters: from (ISO date), to (ISO date), limit (integer, default 10).

GET /v1/briefings/:date

Returns the briefing for a specific date (format: YYYY-MM-DD). Returns 404 if no briefing exists for this date.

Alerts

GET /v1/alerts

Returns a history of alerts, including probability changes, volume jumps, and portfolio alerts.

Request parameters: type (thread), from (ISO date), to (ISO date), limit (integer, default 20).

POST /v1/alerts/config

Update your alert configuration. Accepts a JSON body with alert settings, including thresholds, delivery methods (email, push notifications, in-app), and alert types enabled.

Watchlist

GET /v1/watchlist

Returns the current watchlist with real-time price data for each monitored market.

POST /v1/watchlist

Add markets to your watchlist. Accepts a JSON body: { "market_ids": ["id1", "id2"] }.

DELETE /v1/watchlist/:id

Remove a market from your watchlist based on its state ID.

Webhooks

Pro and Elite users can configure webhooks for real-time event notifications. Webhooks are sent as POST requests to a configured URL with a JSON payload.

Supported Events:

• price_shift — Probability shift exceeds your threshold
• volume_spike — Unusual volume detected
• edge_signal — A new extreme candidate has been discovered
• portfolio_warning — Risk of concentration or correlation
• briefing_ready — A daily briefing is created

Configure endpoints in Settings → Webhooks in the dashboard. Each webhook includes a signature header (X-Predicue-Signature) to check the payload.

Error Handling

The API uses standard HTTP status codes:

All errors return a JSON body with error (string code) and message (readable description).

SDK and libraries

Official SDKs are available for:

• Python — pip install predicue-sdk
• JavaScript/TypeScript — npm install @predicue/sdk
• Go — go get github.com/predicue/predicue-go

Community maintained libraries exist for Rust, Ruby and PHP. Installation instructions and examples can be found on our GitHub organization.