Docs · Orakll

Read Orakll from any agent or pipeline.

One token, three transports — hosted MCP, Markdown mirror, REST.

Quickstart

1Sign up and start a free trial (pricing).
2Mint a PAT at /account/tokens. Shown once.
3Paste it into the transport below that fits your stack.

Auth · personal access tokens

Every call carries Authorization: Bearer ppc_pat_…. User-scoped, premium-gated at issue and at validation, revocable, hashed at rest.

·ppc_pat_ + 43 base64url chars (51 total).
·Downgrade kills outstanding tokens — tier is checked on every call.
·Mint one PAT per agent or script, so you can revoke just the leaky one.

Hosted MCP (recommended)

Streamable HTTP. Paste into ~/.claude/mcp.json, Cursor, ChatGPT, or OpenAI Agents — all accept URL + headers.

{
  "mcpServers": {
    "orakll": {
      "url": "https://orakll.com/api/mcp",
      "headers": { "Authorization": "Bearer ppc_pat_…" }
    }
  }
}

Sanity check: https://orakll.com/api/mcp returns a small JSON banner in the browser.

Seventeen read-only tools in three families — the newsroom, live markets & charts, and the labelled resolution corpus. Each takes a premium PAT; the markets and resolution tools populate structuredContent so your agent gets typed data to trade on, not just prose.

Newsroom

search_articles({query, limit?})Full-text search across the wire.
list_recent_articles({category?, limit?})Newest, optionally by desk.
get_article({slug})One article — body, conditionId, market URL.
list_categories()The 9 desks.

Markets & charts

screen_markets({category?, limit?})Live markets ranked by 24h volume.
list_movers({category?, limit?})Biggest 24h movers right now.
get_market({slug})Odds, volume, liquidity, resolution, dates.
get_market_chart({slug, include_series?})7-day hourly series + computed summary.
analyze_market({slug})Chart + book + tape + VWAP in one read.
get_order_book({slug, depth?})Depth ladder, mid, spread, pressure.
get_top_holders({slug, limit?})Top YES/NO holders (whale read).
market_calibration({category?})Do N¢ markets resolve YES ~N%? Reliability curves + Brier.
market_term_structure({slugs})Compare 2–8 related markets across expiries — curve + hazard.
explain_metrics()The metric glossary — what each reading means and how it's computed.
coverage_for_market({slug})Orakll's articles on a market.

Resolution corpus

Ground truth plus causality for every meaningful market that resolved — the labelled data layer no other Polymarket tool offers. Backtest a thesis against what actually moved the market.

list_resolutions({category?, q?, outcome?, since?, until?, min_volume?, sort?, limit?})Query resolved markets — filter by desk, keyword (question + cause), outcome, resolution-date window, and min volume; sort by recent / volume / biggest move. Each labelled with its decisive cause + outcome.
explain_resolution({conditionId})Why it resolved — sourced causal events + per-market reliability read.

Markets & charts

Beyond the newsroom, the MCP exposes the same live Polymarket intelligence the premium dashboard runs on — screen markets, pull a chart, or get a full microstructure read — all behind your premium PAT. Get a market slug from screen_markets, list_movers, or an article’s market link, then pass it to the other tools.

·category filters accept the 9 desks: politics, crypto, economics, science, sports, finance, weather, mentions, other.
·Prices are in cents (¢ = implied probability); moves are in percentage points (pp). The trade tape is YES-normalized.
·Every reading is also returned as structuredContent — parse that instead of the text when you can.

analyze_market — example

analyze_market({ slug: "us-x-iran-permanent-peace-deal-by-may-31-2026-…" })

# Analysis · US x Iran permanent peace deal by May 31, 2026?
Now: 12¢

CHART  net -7pp/7d · range 62pp · vol 18.3pp/day · falling
BOOK   mid 12¢ · spread 1¢ · pressure 0.88 (buyers) · depth $6.6M bid / $3.2M ask
TAPE   100 prints · imbalance -0.87 (sellers) · largest $28k · VWAP 11¢
VERDICT  falling · book leans buyers · tape leans sellers

structuredContent carries the same as typed fields: market, chart (open/close/high/low ¢, netChangePp, rangePp, realizedVolPpPerDay, trend), book (midCents, spreadCents, pressure, lean, depth), and tape (takerImbalance, largestFillUsd, vwapCents, lean).

get_market_chart returns the 7-day hourly series (set include_series: false for the summary only). A typical agent flow: screen_markets → analyze_market → coverage_for_marketto pair the price action with Orakll’s reporting.

Markdown mirror

Every slug has a .md twin. Anonymous gets the preview (frontmatter access: preview); a premium PAT gets the full body (access: full).

# Preview — no token
curl https://orakll.com/article/<slug>.md

# Full body — premium PAT
curl -H "Authorization: Bearer ppc_pat_…" \
  https://orakll.com/article/<slug>.md

Responses set Vary: Authorization; premium adds Cache-Control: private, no-store.

REST API

Plain JSON. Same PAT, same envelope as the wrapper.

GET https://orakll.com/api/v1/feed?limit=20
GET https://orakll.com/api/v1/feed/category/<slug>?limit=20
GET https://orakll.com/api/v1/articles/<slug>
GET https://orakll.com/api/v1/articles/<slug>/related?limit=6
GET https://orakll.com/api/v1/articles/search?q=<query>
GET https://orakll.com/api/v1/markets/articles?ids=<conditionId>[,…]

Success: { "data": … }. Failure: { "error": "<code>", "message": "<human>" }. Cursor pagination via next_cursor.

Error envelope

Stable codes to branch on:

`unauthenticated`	No credential on a gated route.
`invalid_token`	PAT malformed, revoked, or unknown.
`premium_required`	Valid PAT, but tier is free.
`invalid_credentials`	Email / password mismatch.
`email_not_verified`	Confirm your email first.
`email_taken`	Account already exists.
`weak_password`	Under the minimum length.
`bad_request`	Malformed query or body.
`not_found`	No such article / slug.
`rate_limited`	Over the IP cap — see Retry-After.
`upstream_unavailable`	A backend is temporarily down.

Rate limits

120 req/min/IP. Over the cap returns 429 rate_limited with retry_after_seconds and a Retry-After header. Per-PAT limits on the roadmap.

Docs · Orakll

Read Orakll from any agent or pipeline.

One token, three transports — hosted MCP, Markdown mirror, REST.

Quickstart

1Sign up and start a free trial (pricing).
2Mint a PAT at /account/tokens. Shown once.
3Paste it into the transport below that fits your stack.

Auth · personal access tokens

Every call carries Authorization: Bearer ppc_pat_…. User-scoped, premium-gated at issue and at validation, revocable, hashed at rest.

·ppc_pat_ + 43 base64url chars (51 total).
·Downgrade kills outstanding tokens — tier is checked on every call.
·Mint one PAT per agent or script, so you can revoke just the leaky one.

Hosted MCP (recommended)

Streamable HTTP. Paste into ~/.claude/mcp.json, Cursor, ChatGPT, or OpenAI Agents — all accept URL + headers.

{
  "mcpServers": {
    "orakll": {
      "url": "https://orakll.com/api/mcp",
      "headers": { "Authorization": "Bearer ppc_pat_…" }
    }
  }
}

Sanity check: https://orakll.com/api/mcp returns a small JSON banner in the browser.

Newsroom

search_articles({query, limit?})Full-text search across the wire.
list_recent_articles({category?, limit?})Newest, optionally by desk.
get_article({slug})One article — body, conditionId, market URL.
list_categories()The 9 desks.

Markets & charts

screen_markets({category?, limit?})Live markets ranked by 24h volume.
list_movers({category?, limit?})Biggest 24h movers right now.
get_market({slug})Odds, volume, liquidity, resolution, dates.
get_market_chart({slug, include_series?})7-day hourly series + computed summary.
analyze_market({slug})Chart + book + tape + VWAP in one read.
get_order_book({slug, depth?})Depth ladder, mid, spread, pressure.
get_top_holders({slug, limit?})Top YES/NO holders (whale read).
market_calibration({category?})Do N¢ markets resolve YES ~N%? Reliability curves + Brier.
market_term_structure({slugs})Compare 2–8 related markets across expiries — curve + hazard.
explain_metrics()The metric glossary — what each reading means and how it's computed.
coverage_for_market({slug})Orakll's articles on a market.

Resolution corpus

Ground truth plus causality for every meaningful market that resolved — the labelled data layer no other Polymarket tool offers. Backtest a thesis against what actually moved the market.

list_resolutions({category?, q?, outcome?, since?, until?, min_volume?, sort?, limit?})Query resolved markets — filter by desk, keyword (question + cause), outcome, resolution-date window, and min volume; sort by recent / volume / biggest move. Each labelled with its decisive cause + outcome.
explain_resolution({conditionId})Why it resolved — sourced causal events + per-market reliability read.

Markets & charts

·category filters accept the 9 desks: politics, crypto, economics, science, sports, finance, weather, mentions, other.
·Prices are in cents (¢ = implied probability); moves are in percentage points (pp). The trade tape is YES-normalized.
·Every reading is also returned as structuredContent — parse that instead of the text when you can.

analyze_market — example

analyze_market({ slug: "us-x-iran-permanent-peace-deal-by-may-31-2026-…" })

# Analysis · US x Iran permanent peace deal by May 31, 2026?
Now: 12¢

CHART  net -7pp/7d · range 62pp · vol 18.3pp/day · falling
BOOK   mid 12¢ · spread 1¢ · pressure 0.88 (buyers) · depth $6.6M bid / $3.2M ask
TAPE   100 prints · imbalance -0.87 (sellers) · largest $28k · VWAP 11¢
VERDICT  falling · book leans buyers · tape leans sellers

Markdown mirror

Every slug has a .md twin. Anonymous gets the preview (frontmatter access: preview); a premium PAT gets the full body (access: full).

# Preview — no token
curl https://orakll.com/article/<slug>.md

# Full body — premium PAT
curl -H "Authorization: Bearer ppc_pat_…" \
  https://orakll.com/article/<slug>.md

Responses set Vary: Authorization; premium adds Cache-Control: private, no-store.

REST API

Plain JSON. Same PAT, same envelope as the wrapper.

GET https://orakll.com/api/v1/feed?limit=20
GET https://orakll.com/api/v1/feed/category/<slug>?limit=20
GET https://orakll.com/api/v1/articles/<slug>
GET https://orakll.com/api/v1/articles/<slug>/related?limit=6
GET https://orakll.com/api/v1/articles/search?q=<query>
GET https://orakll.com/api/v1/markets/articles?ids=<conditionId>[,…]

Success: { "data": … }. Failure: { "error": "<code>", "message": "<human>" }. Cursor pagination via next_cursor.

Error envelope

Stable codes to branch on:

`unauthenticated`	No credential on a gated route.
`invalid_token`	PAT malformed, revoked, or unknown.
`premium_required`	Valid PAT, but tier is free.
`invalid_credentials`	Email / password mismatch.
`email_not_verified`	Confirm your email first.
`email_taken`	Account already exists.
`weak_password`	Under the minimum length.
`bad_request`	Malformed query or body.
`not_found`	No such article / slug.
`rate_limited`	Over the IP cap — see Retry-After.
`upstream_unavailable`	A backend is temporarily down.

Rate limits

120 req/min/IP. Over the cap returns 429 rate_limited with retry_after_seconds and a Retry-After header. Per-PAT limits on the roadmap.

§Quickstart

§Auth · personal access tokens

§Hosted MCP (recommended)

§Markets & charts

§Markdown mirror

§REST API

§Error envelope

§Rate limits

§Quickstart

§Auth · personal access tokens

§Hosted MCP (recommended)

§Markets & charts

§Markdown mirror

§REST API

§Error envelope

§Rate limits

Quickstart

Auth · personal access tokens

Hosted MCP (recommended)

Markets & charts

Markdown mirror

REST API

Error envelope

Rate limits

Quickstart

Auth · personal access tokens

Hosted MCP (recommended)

Markets & charts

Markdown mirror

REST API

Error envelope

Rate limits