--- name: Predictefy description: Use when building trading bots, research agents, or programmatic integrations against prediction markets. Reach for this skill to fetch normalized market, event, order-book, or historical data across many venues at once, to compare prices between venues, to look up wallet-level trader intelligence, or to place non-custodial orders with client-side signing. metadata: version: '1.0' --- # Predictefy Skill ## Product summary Predictefy is unified prediction-market infrastructure: one normalized API and SDK across **16 served product venues** plus a `router` pseudo-venue that answers for all served venues at once. You integrate once and change the venue parameter to reach a different market. Base URL: `https://data.predictefy.com`. Every record carries honest-data fields (`asOf`, `provenance`, `capabilities`), and per-venue support is **capability-qualified** — read the `has` verb for a venue's map rather than assuming a verb works everywhere. Execution is **non-custodial and isolated**: Predictefy never holds keys and exposes no generic signing endpoint. Orders are built server-side, signed **in your process**, and relayed back. ## When to use Use this skill when: - Fetching markets, events, series, order books, trades, or OHLCV history from one venue or across all served venues - Comparing prices for the same real-world outcome across venues - Looking up wallet-level trader intelligence — leaderboards, holders, smart-money signals - Placing, cancelling, or monitoring orders with client-side signing - Wiring an LLM agent to live prediction-market data over MCP Do not use this skill for: custodial trading, hosted key storage, or a venue Predictefy does not serve. Check venue coverage first. ## Release status — read before writing install instructions **As of 2026-08-11 all packages are published, on beta version lines:** | Package | Registry | Version | | ----------------- | -------- | -------------- | | `@predictefy/sdk` | npm | `1.0.0-beta.5` | | `@predictefy/mcp` | npm | `1.0.0-beta.5` | | `@predictefy/cli` | npm | `1.0.0-beta.5` | | `predictefy` | PyPI | `1.0.0b3` | Because these are beta lines the versions move; pin an exact one rather than tracking `latest`. This block is time-sensitive — verify before relying on it: ```bash npm view @predictefy/sdk version pip index versions predictefy ``` **The REST API needs none of these packages** — the HTTP examples below work with only an API key. ## Authentication Every route requires an API key. Anonymous requests answer `401 UNAUTHORIZED`. ```http Authorization: Bearer pk_live_… ``` Keys are created at **`https://portal.predictefy.com/keys`** (Privy sign-in → dashboard → API keys). The raw key is shown **once**; only a hash and display prefix are stored. Send it in the header — never in a query string. ## Quick reference ### REST — the path that works today Routes are `/{base}/api/{exchange}/{verb}`, where `{verb}` is the **camelCase name exactly as written in the verb tables below**, and `{exchange}` is a venue slug or `router`. Reads are `GET`. ```bash curl -s "https://data.predictefy.com/api/router/fetchMarkets?query=fed&sort=volume&limit=2" \ -H "Authorization: Bearer $PREDICTEFY_API_KEY" ``` Every success is enveloped — `data` plus `meta` and, on list verbs, `page`: ```json { "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": "venue-rest" }, "capabilities": { "read": true, "trade": false, "depth": true, "history": false } } ], "meta": { "asOf": "…", "provenance": { "source": "venue-rest" } }, "page": { "limit": 2, "offset": 0, "total": 1519, "hasMore": true, "nextCursor": "…" } } ``` `outcomeId` is what order-book and candle verbs key on — a binary market has one per side, so select the outcome before calling `fetchOrderBook` or `fetchOHLCV`. **Common query parameters** (`fetchMarkets` / `fetchEvents`): | Parameter | Values | | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------- | | `limit`, `offset`, `page`, `cursor` | Pagination. Follow `page.nextCursor` rather than incrementing offset. | | `sort` | `volume`, `liquidity`, `newest` — use this for "top" requests rather than assuming result order | | `status` | `active`, `inactive`, `closed`, `resolved`, `all` | | `query`, `searchIn` | Text search; `searchIn` is `title`, `description`, or `both` | | `category`, `marketId`, `slug`, `eventId`, `outcomeId` | Filters | **Venue slugs:** `polymarket`, `kalshi`, `opinion`, `myriad`, `gemini`, `hyperliquid`, `limitless`, `polymarket_us`, `rain`, `predictfun`, `sxbet`, `pascal`, `xo`, `pred`, `predictstreet`, `novig` — plus `router` for the all-served-venues union. `pascal`, `xo` and `pred` are **not** data-only: each has a hosted order lane. `pascal` builds, submits and cancels. `xo` builds, submits and cancels on the venue's current order contract, rebuilt 2026-08-18 after the previous builder was disarmed for signing a retired order struct; nothing has been submitted to XO yet, so the first live submit is the confirmation checkpoint. `pred`'s hosted lane is **fully dark** — including build, which answers `404 VENUE_NOT_SUPPORTED` because the empty `PRED_EXCHANGE_ADDRESSES` allowlist unregisters the whole lane — while the venue's platform-key model stays unresolved; the client-side signing helpers documented for it remain valid, and no PRED cancel lane exists at all. `sxbet` is also not data-only, but its lane is **client-side only**: `client.accounts.sxbet` places and cancels orders directly at the venue from your process, with no hosted lane. Read `/api/{exchange}/has` for a venue's live capability map rather than inferring it from this list. ### SDK initialization ```ts import Predictefy from '@predictefy/sdk'; const client = new Predictefy({ apiKey: process.env.PREDICTEFY_API_KEY }); const markets = await client.polymarket.fetchMarkets({ limit: 5, query: 'fed' }); const everywhere = await client.router.fetchMarkets({ limit: 5, query: 'fed' }); ``` ```python from predictefy import Predictefy client = Predictefy(api_key=os.environ["PREDICTEFY_API_KEY"]) markets = client.polymarket.fetch_markets(limit=5, query="fed") ``` Python mirrors the TypeScript verbs in snake_case (`fetch_markets`, `fetch_order_book`, …). ### Core verbs REST routes are `/api/{exchange}/`, where `{exchange}` is a venue or `router`. | Verb | Purpose | | ------------------------------------ | --------------------------------------------------------------- | | `fetchMarkets` / `fetchMarket` | Catalog listing / single market by id or slug | | `fetchEvents` / `fetchEvent` | Event-shaped groupings | | `fetchSeries` | Recurring series (empty on venues without the concept) | | `fetchCategories` / `fetchTags` | Canonical taxonomy with served counts | | `fetchOrderBook` / `fetchOrderBooks` | Live or archived depth; batch form takes a body | | `fetchTrades` | Recent public trades tape, where the venue exposes one | | `fetchOHLCV` | Historical candles at 1m / 1h / 1d | | `has` | The venue's capability map — check this before assuming support | Cross-venue verbs are `router`-only: `fetchMarketMatches`, `fetchMatchedMarkets`, `compareMarketPrices`, `fetchMatchedMarketClusters`, `fetchMatchedEventClusters`, `fetchRelatedMarkets`, `fetchEventMatches`, `fetchHedges`, `fetchArbitrage`. Trader intelligence lives under `/v1/traders/…` rather than `/api/{exchange}/…`: `/v1/traders/{venue}/leaderboard`, `/v1/traders/leaderboard` (cross-venue, `by=score` only), `/v1/traders/{venue}/wallets/{address}`, and `/v1/traders/{venue}/markets/{marketId}/holders`. The full operation inventory — all 57, with parameters and response schemas — is at `https://docs.predictefy.com/api/`, generated from the OpenAPI contract. Treat that as authoritative over this summary. ### Price-gap wording — this matters Cross-venue price gaps are **indicative price discrepancies**: observed mid-price gaps, not executable opportunities. `fetchMatchedMarkets`, `compareMarketPrices`, and `fetchHedges` return indicative output and must be described that way. Only `fetchArbitrage` (`GET /api/router/fetchArbitrage?contracts=100&limit=500&executableOnly=true`, paged via `cursor`, with optional `venues` and `minEdge` filters) and `qualifyDiscrepancy` (`GET /v1/discrepancies/{clusterId}/qualification`) perform a live executable assessment — against live asks, open markets, depth, fees/gas, and resolution equivalence. `fetchArbitrage` response `meta` includes `{ asOf, seq, source }` (`'published'` or `'computed-fallback'`). Never present indicative output as arbitrage. **Both fail closed, and that is not the same as "no opportunity".** A row is labelled executable only when every gate passes; when a gate cannot be evaluated the row stays **indicative and carries the reason it was not upgraded**. Read that reason before reporting — "we could not verify" and "we verified there is no edge" are different answers, and only the second one justifies telling a user there is nothing there. ### Execution Client-side signing, in three steps, on a separate isolated service (`execBaseUrl`, no implicit default — you must set it): 1. `buildOrder` — server returns an unsigned, venue-shaped order 2. **you sign locally** — the key never leaves your process 3. `submitOrder` — relays the signed payload `createOrder` composes all three with your signer callback. No endpoint both builds and submits, and no hosted signing endpoint exists. **`submitOrder` and `createOrder` move real money and have no dry-run default** — unlike the MCP `exec_submit` tool, which previews unless passed `confirm: true`. Confirm venue, side, size, and price with the human before calling either, and check `has` for the venue's `trade` capability first. Order parameters and signing payloads are venue-shaped: read the operation pages under `https://docs.predictefy.com/api/` rather than guessing field names or price units. ### Funding Execution assumes the venue is already funded. Predictefy holds no funds and no keys: every funding route returns provider-native data or an unsigned artifact, and the caller signs. - `GET /v1/funding/{venue}/requirements` — what that venue needs before it can trade. - `POST /v1/funding/{venue}/steps` — unsigned transactions (Polymarket wrap/approve; Hyperliquid reports readiness only and returns no transfer step). - `GET /v1/funding/transfer-plan` — the ordered caller-signed legs for moving collateral from one venue to another. It plans only: it moves nothing, stores nothing, and submits nothing. - `GET /v1/bridge/quote` — a routed quote (no route → 422 `BRIDGE_NO_ROUTE` (not retryable) for both providers; do not retry, change the source chain/token/amount). The destination is **either** `toVenue` **or** an explicit `toChain` + `toToken` pair, never both. The explicit form is not restricted to Predictefy venues: any LI.FI-supported chain and token works, including a chain's native gas token via the zero-address sentinel `0x0000000000000000000000000000000000000000`. Cross-VM destinations such as Solana additionally require `toAddress` — without it LI.FI defaults the recipient to the EVM `fromAddress` and rejects the quote. - `POST /v1/bridge/session` — the Glide-backed venues, Hyperliquid and SX Bet. Gas is a two-chain problem: the approval and order that follow a bridge need native gas on both the source and destination chains. Quote native gas to the destination chain first, then bridge the collateral. **There is no withdrawal and no bridge-out route.** Each venue is a custody island: funds leave only by that venue's own rails, and no balance moves between venues through Predictefy. This is the no-escrow posture rather than a gap, and unified funding is roadmap — never tell a user Predictefy can withdraw or transfer their funds. Hyperliquid's withdrawal reaches **Arbitrum only**, because its `withdraw3` action is the venue's Arbitrum bridge; the SDK's `buildWithdrawRequest` is build-only and the caller posts it to the venue. Any other chain is two legs — withdraw to Arbitrum, then bridge onward with `GET /v1/bridge/quote`. `GET /v1/funding/transfer-plan` returns those legs pre-composed for the pairs it supports, but it only plans: every leg is caller-signed, Predictefy submits none of them, and no balance moves through the API. ### MCP server `@predictefy/mcp` runs over stdio. Its ungated data, intelligence, and platform surface has **33 tools**; two are honestly annotated, account-scoped writes (`manage_webhook` and `create_billing_session`). Ten execution and collateral tools register by default and are removed only when `MCP_ENABLE_TRADE=false`. ```jsonc { "mcpServers": { "predictefy": { "command": "npx", "args": ["-y", "@predictefy/mcp"], "env": { "PREDICTEFY_API_KEY": "pk_live_your_key_here" }, }, }, } ``` The execution and collateral set is `exec_venues`, `exec_quote`, `exec_prepare`, `exec_submit`, `exec_cancel`, `exec_modify`, `exec_refresh`, `exec_orders`, `prepare_funding`, and `get_funding_artifacts`. `MCP_EXEC_BASE_URL` defaults to the canonical isolated execution origin. `exec_submit` is dry-run unless passed `confirm: true`. Guardrails: 100-row list cap, 5000-candle cap, ~50KB response budget (sets `"truncated": true`), 15s timeout. ### Credit costs Requests are endpoint-weighted. Bulk operations cost base × ceil(items / 100). | Action | Credits | | --------------------------------------------------------------------- | -------------------------------: | | Metadata, search, price snapshot | 1 | | Trades or candles | 2 | | Order-book snapshot, history, cross-match lookup, order submit/cancel | 5 | | Enterprise SQL | 10 | | Cross-venue comparison, price-gap query, smart-money analytics | 10 | | Executable arbitrage query | 15 | | Fresh AI-assisted cross-match | 25 | | WebSocket streaming | 2 per connection-minute, prepaid | ### Error handling Every error returns the same envelope — nothing else: ```json { "success": false, "error": { "code": "UNAUTHORIZED", "message": "…", "retryable": false } } ``` | Code | Status | What to do | | ---------------------------------------------- | ------- | -------------------------------------------- | | `VALIDATION_ERROR` | 400 | Fix the request; do not retry unchanged | | `NOT_SUPPORTED` | 400/501 | The venue genuinely lacks this — check `has` | | `UNAUTHORIZED` | 401 | Missing or invalid key | | `INSUFFICIENT_CREDITS` | 402 | Top up; retrying will not help | | `PLAN_REQUIRED` | 403 | Feature gated to a higher plan | | `RATE_LIMITED` | 429 | Back off, honour `retryAfterMs` | | `TRADERS_UNSUPPORTED` | — | Venue exposes no trader identity | | `CATALOG_UNAVAILABLE` / `PLATFORM_UNAVAILABLE` | 503 | Transient; retry with backoff | Treat `retryable` as authoritative rather than inferring from the status code. ## Common mistakes | Mistake | Correct approach | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | Calling a verb on every venue and expecting uniform support | Read `has` first — coverage is capability-qualified | | Describing price gaps as arbitrage | They are **indicative price discrepancies** unless from `fetchArbitrage` / `qualifyDiscrepancy` | | Looking for a hosted signing endpoint | None exists — sign locally between `buildOrder` and `submitOrder` | | Assuming `exec_*` MCP tools are absent unless armed | They register by default; `MCP_ENABLE_TRADE=false` is what removes them | | Retrying a 402 | Credits are exhausted; retrying cannot succeed | | Using cross-venue verbs on a single venue | They are `router`-only | | Putting the API key in a query string | Header only | ## Further reference - Full documentation index: `https://docs.predictefy.com/llms.txt` - Complete corpus: `https://docs.predictefy.com/llms-full.txt` - Generated API reference: `https://docs.predictefy.com/api/`