Quotient API - LLM Discovery Index Canonical product docs: - / - /docs What Quotient provides: - Assets: canonical companies, commodities, cryptoassets, and other underlyings linked directly to relevant prediction markets. - Forecasts: calibrated YES probabilities for every covered market, with uncertainty, thesis, history, and citations. - Signals: separate Quotient publications with their own side, status, and timestamp; a forecast/market spread alone is not a signal. - Analysis: the quality-source citations and expert context behind forecasts and signals. - Current operating scale: 500 markets forecast daily, 6,000+ global sources reviewed, and 1,000+ experts tracked. Canonical machine-readable API contract: - /openapi.json Canonical agent skill: - /skill/skill.md - /skill/references/api-reference.md - /skill/references/assets.md - /skill/references/perps-signals.md - /skill/references/workflows.md - /skill/references/writing-style.md - /skill/references/polymarket-monitoring.md - /skill/references/bankr-x402-flow.md - /skill/references/vanilla-x402-flow.md - /skill/references/error-handling.md - /skill/scripts/quotient.sh, pm.sh, signal-strategy.mjs, converge-monitor.sh (vendored helpers) Portable CLI, agent skill, and optional MCP: - Install: npm install --global quotient-forecasting - Guided setup: quotient setup. The default path installs access and the agent skill; MCP is offered separately at the end. - Detect clients: quotient agents detect - Install/update only the skill: quotient skill install auto - Ordinary CLI startup performs a short cached update check. Newer CLI or canonical skill versions are announced on stderr; upgrade the CLI first, then run quotient skill update auto. - Add native tools later when wanted: quotient mcp install auto - For a shell-capable agent, prefer one friendly Quotient CLI command. MCP uses the same operations, account, prices, and data but can add tool-loading and reasoning overhead. - Do not run doctor, account status, resources, or OpenAPI as routine preflight. Never use CLI and MCP for the same read unless the selected path fails. Agent routing and voice: - Route one user intent to one operation: Asset directory/search, market search, forecast, published signals, mispricing, WTI, perps, updates, sources, portfolio, X research, and performance are separate surfaces. - Use Asset search for an underlying name, ticker, assetKey, UUID, platform identifier, or linked-market reference. Use market search for event questions and taxonomy. For a known holding such as AAPL or xyz:GOLD, resolve the Asset once and use its linked_markets; do not fan out into forecast calls. - Do not call sources unless the user requests evidence or the requested analysis requires it. Keep and format a successful paid response; never repeat it because display output was truncated. - Reuse successful results already present in the conversation for follow-up arithmetic, comparison, explanation, simplification, and conditional trade frameworks. Refresh only for a newer value or an absent required field; reuse the exact marketKey/slug rather than searching again. - For performance, lead with reporting.primary and state that geopolitics/global elections are Quotient's most consistently forecasted categories. Then show last 60 days before all time, with and without that category filter, and include all/first/random samples. - Report Q probability, venue probability, arithmetic spread, timestamp, and publication status neutrally. Relay actionable only when it is the exact published status; never add a buy, sell, hold, avoid, cheap, attractive, watchlist, or opportunity conclusion. - Venue probabilities are first-class evidence. Name each returned venue, preserve the exact question/threshold/expiry, and compare it with Q. Never blend different contracts into a synthetic consensus. - For outlook or spread analysis, add one or two concise sentences from returned bluf, thesis, crux, delta_reasoning, or key-driver fields and attribute them to Q. Q's thesis explains Q's probability, not why venue traders chose their price. - Writing rules: /skill/references/writing-style.md. Open each paragraph with the claim, add the returned field that warrants it, then state what it changes. Active voice, strong nouns and verbs, no intensifiers, no jargon, no self-narration, no unsolicited bottom line. - Table rules: five columns and six data rows maximum, no wrapped cells, one market per row, identical cell counts, probabilities to one decimal with %, differences in signed percentage points, timestamps with timezone. A market needing more fields uses a label/value block. - Link two markets only on a shared returned field: identical nativeEventId, the same explicit parent event, a shared tag, or the same underlying Asset. A shared theme, region, sector, or resolution month links nothing, and probabilities summing past 100% is arithmetic, not a verified mutually exclusive relationship. - On partial results, state the gap in one line where the data belongs, name what returned, and continue. A truncated display is not missing data and never justifies repaying for the same call. - On a trade-construction request, report Q and venue facts first. If the user supplies a thesis, horizon, level, or risk constraint, explain a few conditional structures; do not invent size, leverage, exact entry, take-profit, or stop. The user chooses the transaction. - Binary threshold probabilities are terminal probabilities, not a spot target or path. Derive a range only from comparable same-underlying/same-expiry monotonic nested thresholds; without an upper bound or when probabilities conflict, do not manufacture support, resistance, a target, or a market-making band. - The signals window parameter is forecast-update recency, not signal publication during a local calendar day. State timezone and exact field semantics for today requests. - A simple daily brief is a current read-only summary from the current signal and mispricing feeds, with one to three implications grounded only in returned event/tag/underlying clusters. It is not a stored edition, subscription, or send operation. - The read-only portfolio agent tool is get_portfolio_report and maps to GET /api/v1/portfolio, which reads wallet-addressed positions on polymarket, polymarket_perps, limitless, and hyperliquid via the venues parameter. Kalshi, Polymarket US, and non-wallet holdings have no wallet-addressed read and should be resolved through Asset search instead. Integration boundaries: - Surplus Intelligence provides discounted inference for high-frequency research, monitoring, and execution-support workflows. It is not a venue, evidence source, signal, or execution authorization. - Bankr is an optional x402 payer/execution handoff. Installing or selecting it never authorizes a payment or trade. - Machine-readable details: OpenAPI x-integrations and the MCP resource quotient://integrations. Access model: - Monetized API access supports either API key auth or x402 payment. - API keys are created after signup/login at https://dev.quotient.social (email or Google). - New accounts include free credits so agents can try the API before paying. - x402 signing: any vanilla SIWE/SIWX-compatible client or Bankr wallet tooling — both fully supported. - x402 protocol docs: https://docs.x402.org/llms.txt x402 payment options: - Base USDC: scheme exact, network eip155:8453. - Robinhood Chain USDG: scheme exact, network eip155:4663, canonical asset 0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168, 6 decimals. - PAYMENT-REQUIRED.accepts is authoritative for live payment options. - To pay USDG, match scheme + network + canonical asset (case-insensitively); never select by token symbol alone. Pricing discovery endpoint: - /api/public/pricing - This endpoint provides supplemental billing/network metadata for skill preflight/discovery. - OpenAPI is canonical for invocation metadata; runtime payment behavior is authoritative. - x402 requests may return 402 with PAYMENT-REQUIRED; select a supported accepts entry and send PAYMENT-SIGNATURE on retry. - Successful x402-paid responses include PAYMENT-RESPONSE settlement metadata. Rate limits (gateway-enforced): - Independent reads may run concurrently within each operation's published maxConcurrent limit. - Standard scope (all non-X payable routes): 20/second, 600/minute, 20,000/UTC day, 10 in flight. - X research scope (/x/search and /x/profile): 5/second, 60/minute, 500/UTC day, 5 in flight. - A secondary IP anti-key-spray guard is 50/second, 1,200/minute, 50,000/UTC day and may tighten during abuse. - Unsigned x402 challenge requests count only against the loose IP guard; signed retries also count against customer/payer quota. A 429 is rejected before debit, settlement, or upstream work. - Honor Retry-After, RateLimit-Policy, RateLimit, and X-Quotient-Max-Concurrent. - Full behavior: /skill/references/api-reference.md#rate-limits. Operational notes: - /dashboard exists for account, API key, and billing operations. - Human-operator key provisioning is preferred, then inject keys into agent config. - Agent self-serve signup/key creation is possible only when runtime supports interactive auth + secure secret storage. Error contract: - Handle 401 invalid_api_key/gateway_required, 402 payment_required, 403 insufficient_credits. - Handle 404 not_found, 409 payment_replay_mismatch, 422 invalid_request, 429 rate_limited. - Handle 502 upstream_unavailable (portfolio fails closed when Polymarket's data API is down). - Use bounded retry/backoff for 429 and transient 5xx responses. Data coverage map: - Prediction-market intelligence spans four venue keys: polymarket (Polymarket International), polymarket_us (Polymarket US), kalshi, and limitless. - Catalog/search return Quotient-covered rows, not complete copies of venue catalogs. Omit venue to query all covered venues; empty venue results mean no matching Q-covered row, not unsupported venue. - Prefer marketKey for cross-venue identity. Keep venue, nativeMarketId, nativeEventId, seriesTicker, marketUrl, and sourceUrl intact; slug and marketUrl may validly be null (notably on Kalshi). - Underlyings are canonical :Asset:Entity nodes with UUID and assetKey identity, name/ticker aliases, and exact namespaced platform identifiers. Direct subject linkage is (:Asset)-[:HAS_MARKET]->(:Market); do not mix it with causal AFFECTS relationships. - GET /api/v1/assets returns the complete metadata-only directory with no forecast data. GET /api/v1/assets/search resolves q or exact reference values and returns every active direct linked market with venue odds and latest Q when available. q=* with material_only=true is the one-call enriched Asset digest. - Linked venue probabilities remain useful when the Q spread is small, but each answers its exact market question, threshold, and date. Never produce an aggregate Asset probability, direction, or recommendation. - AssetIdentifier values such as Hyperliquid xyz:GOLD are preserved exactly. Prediction-market condition/native IDs remain market routing identities even when reference search uses them to find an Asset. - Enriched Asset, Market, Forecast, and Signal responses carry a bounded, flat, non-recursive relationships envelope containing lightweight Asset, Market, and Signal refs. Each category is capped at 50 with a truncation flag. relationship is the exact final graph edge. via=direct is one hop; via=market|asset is one explicit two-hop path, and direction on that path is relative to the intermediate node. Refs contain no probabilities, infer no AFFECTS edge, and do not create an Asset-level direction. The envelope intentionally has no Forecast-ref category. - Asset linkage is broader than signal publication. /api/v1/signals/oil returns the daily WTI signal with live venue marks and episode context. /api/v1/signals/perps returns the daily WTI signal in the standard signal-list format. - /api/v1/portfolio covers only venues exposing a keyless wallet-addressed position read, and the bundled CLOB/execution helpers are Polymarket-specific. Never infer overall Quotient coverage from either. Hawk & Dove Index boundary: - The Hawk & Dove Index (Quotient Stability Index) is a 0-100 conflict/diplomacy macro-stability indicator: lower means more hawkish/escalatory; higher means more dovish/de-escalatory. It is not a central-bank-policy index. - In the Quotient playground, get_hawk_dove_index is a free local tool. It is not a public /api/v1 route and is not a third perp signal endpoint. - The index can be used as discretionary context for other risk-sensitive assets, including assets without a published perp series, but it does not supply a universal long/short mapping. Validate polarity, horizon, and thresholds per asset. - /api/v1/signals/oil returns the daily WTI signal with live marks; /api/v1/signals/perps returns it in the standard signal-list format. Neither mechanically passes through the headline 0-100 index. /portfolio?include_perps=true is only a wallet-position annex. - Current index research is a one-conflict-cycle case study. For crude, large moves in either direction were a volatility cue rather than a directional call. v10 Asset discovery: - GET /api/v1/assets: complete metadata-only Asset directory; $0.005. No linked markets, venue odds, Q probabilities, forecasts, or signals. - GET /api/v1/assets/search: q or up to 50 repeatable exact reference values plus platform, asset_type, and material_only filters; $0.01, exactly the market-search price. - reference may resolve Asset UUID/key, AssetIdentifier key/value, or a linked Market marketKey/native ID. Search returns all active direct HAS_MARKET rows; AFFECTS-only rows are excluded. - material_only=true requires at least one linked row with venue odds or latest Q but does not prune the qualifying Asset's other active direct markets. Published-signal existence alone is not materiality. v9 market discovery: - GET /api/v1/markets/search: hybrid search over Quotient-covered active markets by natural language, text, Event/market tags, categories, and venue; each result includes Q's latest calibrated YES probability when available plus explicit forecast and published-signal availability; $0.01. - Use GET /api/v1/markets?topic=oil for a known exact tag/category. Direct Event tags no longer need an IN_CATEGORY relationship to match. - Market catalog/search rows expose parent event, tags, and categories. Search can group returned matches by Event and returns tag/category facets. - Search can answer current or point-in-time discovery with latest_q_probability, forecast_at, and market_odds_at_forecast. Pass as_of as YYYY-MM-DD (end-of-day UTC) or an RFC 3339 instant; historical search can include since-closed markets. Compute a historical spread from Q and market_odds_at_forecast, never current market_odds. Use lookup or forecast detail only when the user needs analysis, drivers, citations, uncertainty, or multi-version history. Use has_forecast before requesting detail. has_published_signal/published_signal_count use non-backfill QuotientSignal publications; they may be historical. Never infer publication from legacy signal_count. - Search always uses graph text/tag retrieval, then fuses Typesense lexical/typo and Neo4j embedding recall when configured. Inspect retrieval statuses; optional-lane failure does not suppress graph results. - Relevance scores order one response only; they are reciprocal-rank-fusion scores, not probabilities or forecast confidence. - /api/v1/markets returns the complete covered catalog in one response. There are no pages: if a market is absent it is not covered. Narrow with exact topic filtering or /markets/search rather than by paging. - Exact taxonomy searches such as /markets?topic=gold and semantic searches for asset aliases discover linked underlying markets across the four prediction venues. - Canonical routing supports polymarket, polymarket_us, kalshi, and limitless. Search returns Q-covered rows only, so empty venue results describe current Q coverage—not all contracts listed by that venue. v6 additions: - POST /api/v1/x/search: structured Grok 4.5 X search with a 30-day default/180-day maximum range and 15-result default/30 maximum; $0.50. - X results are citation-grounded and are not persisted by Quotient; provider requests set store=false. Known accounts include structured Quotient expert metadata with no presentation requirement. - GET /api/v1/latest: board-wide forecast/article/X update feed, returned complete for the window; defaults to three hours, supports 1-6. - Forecast-bearing responses include a compact thesis plus venue/basic market metadata. /api/v1/latest omits resolution_pathway; read it from a single-market route. - Use free GET /api/public/forecast-availability only when coverage or identity is unresolved or generation may be needed. A known stable market reference can use the forecast endpoint directly. - Missing/error upstream responses are not billable: API-key debits are refunded and x402 settlement is skipped. - Paid route prices are rounded upward to exact $0.005 increments; OpenAPI x-payment-info and runtime payment metadata remain authoritative. v5.2 addition: - Drawdown-risk fields: /api/v1/signals rows carry drawdown_risk_elevated (true = the risk model puts >= 15% probability on the signal's side losing most of its remaining value within ~72h of the latest forecast; null = no current read — pre-model forecast or aged past the ~72h horizon; unknown, not safe); filter with exclude_drawdown_risk=true. - /api/v1/markets/{slug}/forecast forecasts carry per-side drawdown_risk_72h {yes, no} anchored to that forecast's created_at. Path risk only — probability is never adjusted by it, and it is independent of conviction_tier. - crash_risk, crash_risk_elevated, and exclude_crash_risk are the former names for those three. They still work and will be removed after one release. v11.1 forecast pricing and scope: - GET /api/v1/markets/{slug}/forecast costs $0.01 (10 credits). It reads a stored forecast with its full research payload — reasoning, sources, uncertainty, optional history. Reading is not generating: generating a NEW forecast is the $1.00 product on POST /api/auth/forecast-requests. Use free /api/public/forecast-availability and the has_forecast flag on search rows to check coverage before either. - Quotient does not forecast sports markets, mention markets, or short-horizon crypto up/down markets, on any venue and by any request path. Availability returns a non-null excluded {reason, message} with generation: null, and POST /api/auth/forecast-requests rejects them with 422 forecast_topic_excluded. - Long-dated crypto questions such as a year-end BTC price level remain in scope; the exclusion targets direction/threshold contracts that resolve on an intraday or same-day anchor. v11 relationships and WTI: - Enriched Asset, Market, Forecast, and Signal objects expose the shared bounded relationships envelope; the metadata-only /assets directory remains unchanged. - /api/v1/signals/perps returns zero or one daily WTI row with scope=wti-only and canonical_endpoint=/api/v1/signals/oil. - WTI freshness, signal-list fields, and portfolio use: /skill/references/perps-signals.md. v5 breaking change: - /api/v1/signals now serves published Quotient trade signals (status/conviction/convergence/capacity). - /api/v1/signals returns at most one signal per market: the newest publication is selected before eligibility filters, with no older fallback. - Article-level evidence remains at /api/v1/markets/{slug}/signals. Freshness notes: - OpenAPI is served at /openapi.json (with /api/v1/openapi.json compatibility). - Treat runtime 402/payment headers as source of truth for live payment behavior. - Before any trade handoff, report proposed size versus current 2-cent capacity and warn that market orders can move price; re-read the live book for a current slippage check.