Skip to content
PredictefyPredictefy Docs
SupportDashboard

OverviewIntroduction

Quickstart

Copy page

Set up with AI

Section titled “Set up with AI”

Open your project in a coding agent that can read URLs, edit files, and run commands. Copy this prompt and paste it into your agent — the skill it points at carries the setup steps:

Set up Predictefy in this project using this skill: https://docs.predictefy.com/.well-known/agent-skills/predictefy/skill.md

The agent will prepare your integration and verify it with a small authenticated market request. If you do not have an API key yet, it will guide you to create one and enter it locally. Sign-in, key creation, and any required client reload are guided steps. The verification request uses API credits.

For chat-client configuration and reusable skill installation, see AI agents. To set up manually, follow the steps below.

API origins

Section titled “API origins”

Use these canonical production origins directly:

SurfaceOrigin
REST readshttps://data.predictefy.com
REST executionhttps://exec.predictefy.com
WebSocket streamingwss://stream.predictefy.com

REST examples below use the reads origin. Execution operations in the REST API reference declare the isolated execution origin themselves. WebSocket clients append /v1/stream; see the WebSocket API reference.

Terminal window
export PREDICTEFY_API_URL="https://data.predictefy.com"

Every request is authenticated and metered against your credit balance. Anonymous requests receive 401 UNAUTHORIZED (only the health endpoints and docs are open).

1. Get an API key

Section titled “1. Get an API key”

Keys are created in the Predictefy developer dashboard. Sign-up is free during the private beta: every new account starts on the Free plan with 25,000 credits, topped up to 25,000 at the start of each UTC month; unused allowance does not carry over. The top-up is applied within a minute of 00:00 UTC. Trading with your own funds ships on every plan, Free included. Feature access follows your plan from the first request: a Free key gets Free’s caps and 403 PLAN_REQUIRED on the features Free does not include. Every plan meters all usage in credits, so upgrade when you need more volume. See Pricing, credits & billing.

Portal sign-in uses Privy with email or wallet; wallet-only accounts are asked to link an email during onboarding. The portal shares its sign-in with the Predictefy terminal: being signed in on one means being signed in on the other, and an X- or wallet-only terminal sign-in is asked to add an email or to switch to the email account you use here. If that email already signs in to a Predictefy account, choose I already sign in with an email on that screen: the fresh wallet-only sign-in is removed (it holds no account, credits, or keys), you sign in with the email, and you link the wallet again from Settings → Sign-in methods. Accounts are never merged automatically.

  1. Sign up (or sign in) via Privy, with your email address or wallet.
  2. Open API keys and choose Create API key. Signing in never creates a key automatically.
  3. Copy the raw pk_live_… value when it appears. Only a hash authenticates it; the console keeps an encrypted copy so API keys can show the full key again later (eye icon), and Regenerate on a key swaps it for a fresh one with the same name.

Treat the key like a password: send it only in the Authorization header, never in URLs (query strings leak into request logs).

2. First request

Section titled “2. First request”

List the three highest-volume active Polymarket markets:

Terminal window
curl -s "$PREDICTEFY_API_URL/api/polymarket/fetchMarkets?limit=3&sort=volume" \
  -H "Authorization: Bearer pk_live_YOUR_KEY"

Successful responses are always enveloped as { success, data, … }:

{
  "success": true,
  "data": [
    {
      "marketId": "…",
      "title": "…",
      "outcomes": [{ "outcomeId": "…", "label": "Yes", "price": 0.62 }],
      "volume24h": 123456.78,
      "liquidity": 98765.43,
      "url": "https://…",
      "asOf": "2026-07-03T09:15:00.000Z",
      "provenance": { "source": "overlay" },
      "capabilities": { "read": true, "trade": false, "depth": true, "history": false }
    }
  ],
  "meta": { "asOf": "2026-07-03T09:15:00.000Z", "provenance": { "source": "overlay" } },
  "page": { "limit": 3, "offset": 0, "total": 1519, "hasMore": true, "nextCursor": "…" }
}

Three honest-data fields ride on every record:

  • asOf — when the data was snapshotted (never pretend-fresh).
  • provenance.source — where it came from. The full enum is venue-rest, predictefy-live, fixture, overlay, archive, predictefy-store, glide, and lifi; live catalog reads currently report overlay on both the market record and response meta.
  • capabilities — what this venue actually supports (read / trade / depth / history). trade is false on these reads records; public execution availability is documented separately for each supported venue. The history flag is conservative — it flips on per venue as coverage is proven, while the fetchOHLCV endpoint is already live.

Swap the exchange segment for any of the 16 served venues, or use router to search across all of them at once:

Terminal window
curl -s "$PREDICTEFY_API_URL/api/router/fetchMarkets?query=election&status=active" \
  -H "Authorization: Bearer pk_live_YOUR_KEY"

3. Pagination

Section titled “3. Pagination”

List verbs accept limit (max 100 — fetchArbitrage is the exception, at max 500), offset, page, and cursor pagination. Prefer cursors: the response’s nextCursor freezes the catalog snapshot from page one, so a long walk never skips or double-counts rows that move while you page.

Offsets above 10,000 are rejected. Snapshot/offset cursors are signed; if a cursor fails validation, restart the walk from page one.

Terminal window
# Page 1
curl -s ".../api/kalshi/fetchMarkets?limit=100" -H "Authorization: Bearer pk_live_…"
# Page 2 — pass the previous response's nextCursor
curl -s ".../api/kalshi/fetchMarkets?limit=100&cursor=CURSOR_FROM_PAGE_1" \
  -H "Authorization: Bearer pk_live_…"

Cursors expire after 60 seconds by default; tune that with snapshotTTL (milliseconds, 0 = the cursor chain never expires). The final page omits nextCursor.

page.total can be null. The data page is the product and the total is only metadata, so a count that overruns its own short budget is abandoned and your page is still served — rather than failing the whole request over a number. null means “not counted”, never “zero matches”, and meta.totalUnavailable says so explicitly. Drive your loop with hasMore / nextCursor, not with total: hasMore is decided by fetching one row past your limit, so it stays correct whether or not the total was computed.

4. The error envelope

Section titled “4. The error envelope”

Every error — 4xx or 5xx — uses one shape:

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "…",
    "retryable": false,
    "requestId": "…"
  }
}

code, message, retryable, and requestId are always present — treat anything else as optional.

The most common codes:

HTTPcodeMeaningRetry?
400VALIDATION_ERRORBad or missing parameters.no
400NOT_SUPPORTEDAccepted-but-unsupported capability (honest gap).no
401UNAUTHORIZEDMissing, unknown, or revoked API key.no
402INSUFFICIENT_CREDITSBalance below the endpoint weight — see credits & plans.after balance update
403PLAN_REQUIREDThe account does not include this route or history window.after access update
404EXCHANGE_NOT_AVAILABLE, MARKET_NOT_FOUND, EVENT_NOT_FOUND, OUTCOME_NOT_FOUNDUnknown or dark venue, or unknown record.no
429RATE_LIMITEDPer-key or per-plan request-rate window exceeded.yes (back off)
501NOT_SUPPORTEDVenue has no public feed for this verb (e.g. trades tape).no
503EXCHANGE_NOT_AVAILABLEA served venue’s own upstream failed.yes (backoff)
503CATALOG_UNAVAILABLE, PLATFORM_UNAVAILABLE, HISTORY_UNAVAILABLE, BILLING_UNAVAILABLETemporary outage — fail-closed, never silently wrong.yes (backoff)

EXCHANGE_NOT_AVAILABLE is the one code that carries two statuses: 404 for a venue this deployment does not serve (dark, unknown, or sandbox), and 503 when a served venue’s own upstream fails. Branch on the status, not on the code alone.

API_KEY_LIMIT applies to creating a key in the developer dashboard when the plan’s key cap is reached; reads and execution operations do not emit it.

The full code enum per endpoint is in the API reference.

Next steps

Section titled “Next steps”