---
title: "Read-only prediction-market quote (price, eligibility, freshness)"
method: POST
path: "/api/agent/pm/quote"
tags: ["prediction-markets"]
---

# Read-only prediction-market quote (price, eligibility, freshness)

`POST /api/agent/pm/quote`

## Request

- Base URL: `https://api.coinrithm.com`
- URL: `https://api.coinrithm.com/api/agent/pm/quote`
- Auth: HTTP bearer

Never mutates state. Returns entry probability, share estimate, max
payout, eligibility, and freshness for a binary market outcome. Pass
`side: "no"` to quote backing the NO side (default is yes). Requires
scope `read`. `stakeMusd` must be > 0 (min to OPEN is 10). An optional
`minEntryProbabilityPct` applies a configured risk floor to the fresh
chosen-side quote; it is a finite probability in percentage points
before fees, with no default. Invalid values return 400.

## Request body

- PmQuoteRequest
  - `source` string, required: Source slug, e.g. kalshi / polymarket (lowercased)
  - `slug` string, required: Event slug (lowercased)
  - `outcomeExternalMarketId` string, required: Case-sensitive outcome/market id
  - `side` 'yes' | 'no': Which side of the binary outcome to back. "yes" (default) pays out if the outcome resolves true; "no" pays out if it resolves false (a NO entry fills at 100 minus the outcome probability).
  - `stakeMusd` number, required: mUSD to stake (> 0; min to open is 10)
  - `forecastProbability` number: Optional own probability that the chosen side wins (0-100 exclusive). Used only for advisory edge sizing; never changes stakeMusd.
  - `bankrollMusd` number: Optional bankroll in mUSD for the advisory suggested stake.
  - `minEntryProbabilityPct` number: Optional finite minimum chosen-side entry probability in percentage points before fees (0-100 inclusive). When present, the fresh quote must meet this configured risk floor; omitted preserves prior behavior.
  - `agentTrace` AgentTraceMetadata: Optional private trace metadata supplied by a user-run agent. CoinRithm stores only this structured summary; do not send chain-of-thought, secrets, emails, or private account identity.
    - `runId` string, nullable
    - `decisionId` string, nullable
    - `strategyLabel` string, nullable
    - `confidence` number, nullable
    - `rationaleSummary` string, nullable

## Response `200`

OK

- PmQuoteResponse
  - `eligible` boolean
  - `blockReasons` string[]: Eligibility reason codes, including entry_below_floor when the optional minimum entry probability is not met and entry_price_unavailable when the quoted probability is unusable.
  - `fillBasis` string
  - `side` 'yes' | 'no'
  - `entryProbability` number, nullable: Fresh chosen-side entry probability in percentage points (0-100), or null when unavailable; this is the value checked against minEntryProbabilityPct.
  - `sharesEstimate` number, nullable
  - `maxPayout` number, nullable
  - `stakeMusd` number
  - `minStake` number
  - `frozenEntrySnapshot` object
  - `freshness` Freshness: Data-freshness descriptor. Futures + spot use ageSeconds; PM uses ageMinutes. `status` is a freshness label; `basis` (PM only) names which timestamp the age was measured against.
    - `asOf` string, date-time, nullable
    - `ageSeconds` number, nullable: futures / spot
    - `ageMinutes` number, nullable: PM
    - `status` 'fresh' | 'lagging' | 'stale' | 'unknown' | 'null', nullable: fresh | lagging (PM only) | stale | unknown. PM lagging>=45m & stale>=2h; spot/futures stale>120s.
    - `basis` 'latest_snapshot' | 'source_update' | 'processed' | 'event_update' | 'unknown', nullable: PM only — which timestamp the age was measured against.
  - `decisionSupport` DecisionSupport: Pre-computed market-quality grade for a prediction market (the same builder the web event/hub cards use): a quality score + tiered liquidity/volume/spread + risk flags. Lets an agent gauge tradability without running its own analysis. Returned by get_market_context's relatedMarkets and by pm/quote.
    - `qualityScore` number
    - `qualityTier` 'high' | 'medium' | 'low'
    - `spreadTier` 'tight' | 'moderate' | 'wide' | 'unknown'
    - `liquidityTier` 'high' | 'medium' | 'low' | 'unknown'
    - `volumeTier` 'high' | 'medium' | 'low' | 'unknown'
    - `flags` object
      - `thinMarket` boolean
      - `inactiveMarket` boolean
      - `highAmbiguity` boolean
      - `nearResolution` boolean
  - `quality` PmQuality: Persisted quality assessment from CoinRithm's truth engine — the aggregator's proven, versioned verdict for this event (one current state per event, updated when facts change). Markets with critical failures remain visible everywhere; `decisionEligible: false` means new paper opens are BLOCKED (pm/open returns 422 with these stored reasons) and alerts are suppressed. Omitted entirely when no assessment row exists yet (brand-new events) — never fabricated.
    - `decisionEligible` boolean: Fresh, structurally valid, metrics-supported, open/quoteable, and not source-degraded.
    - `warningReasons` string[]: Non-blocking flags (e.g. anomaly_flagged). Informational.
    - `blockReasons` string[]: Stable decision-blocking codes (stale_freshness, quote_dead, dead_zero, unpriced, not_open, freshness_unknown).
    - `policyVersion` string: Version of the quality policy that produced this verdict (e.g. pm-quality-2).
    - `assessedAt` string, date-time, nullable: Source-capture time backing the verdict (freshness SSOT), not a row-write timestamp.
  - `openBlocked` boolean: Preview of the pm/open quality gate for this event: true when a pm/open attempt would be rejected 422 right now (quality state missing, stale, or decisionEligible=false). Distinct from `eligible`/`blockReasons`, which describe the mock-entry shape gate — both must pass to open.
  - `openBlockReasons` string[]: Stable reason codes mirroring what pm/open would return (quality_state_missing, quality_state_stale, or the stored blockReasons).
  - `executionModel` ExecutionModel: Paper Execution Realism v1 cost disclosure. Paper fills apply a deterministic, fully-disclosed cost so simulated PnL reflects real trading friction (a flat round-trip is a small loss, not a free breakeven). This is a rehearsal cost model, NOT an exchange fill guarantee. Per venue: - spot: a taker fee (`feeBps`) on notional, with market orders also filling at an adverse price (half-spread + slippage). Futures use the default-off legacy mark fill unless `futures_fill_v1` is pinned; that model applies deterministic half-spread, slippage, and square-root size-scaled impact, with adverse cost embedded in the executed price. - PM: fills at the ask (mid + half the ingested bid-ask spread) with size/liquidity-based slippage and a Polymarket-shaped taker fee (~1.8% near 50%, ~0 at the extremes), folded into `sharesMusd`. `feeBps`/`spreadBps` are positive and `slippageBps` scales with order size; `entryProbability` stays the mid for calibration. Futures quote funding is estimated from the latest venue rate when available and may change before settlement. Covered futures charges are applied from recorded settled venue history; `fundingMode` is a venue-specific mode such as `binance_perp_rate_v1`, `bybit_perp_rate_v1`, or `gateio_perp_rate_v1`, and is `not_modeled` when no latest rate is available. Funding does not apply to spot or PM. Futures liquidation forfeits margin without adverse fill cost, and fixed-price SL/TP triggers fill at their set price. Order-book depth, latency, and partial fills are not modeled.
    - `version` string
    - `feeBps` number: taker fee, basis points of notional
    - `spreadBps` number: modeled bid/ask spread (bps)
    - `slippageBps` number: modeled slippage (bps)
    - `fillModel` string, nullable: Futures fill model pinned for this execution, or null for legacy mark fills.
    - `estimatedFeeMusd` number: estimated fee for this trade (mUSD)
    - `estimatedSlippageMusd` number: estimated slippage cost for this trade (mUSD)
    - `fundingMode` string: Venue-specific current funding reference mode, or not_modeled when no latest rate is available.
    - `assumptions` string[]: human-readable list of what is and isn't modeled
  - `eligibility` object
    - `settlementState` string
    - `shape` string
    - `entryEligible` boolean
    - `alertEligible` boolean
    - `settlementEligible` boolean
    - `limbo` unknown
  - `event` object
    - `source` string
    - `slug` string
    - `title` string
    - `status` string
  - `observation` AgentObservation: Compact provenance block for an agent-facing market observation. It is also stored in the private ledger responseSummary when the request uses agentTrace/run headers, giving run exports a verifiable snapshot of what the agent observed without creating a full market archive.
    - `schema` string
    - `endpoint` string
    - `source` string
    - `observedAt` string, date-time
    - `sourceAsOf` string, date-time, nullable
    - `freshness` Freshness: Data-freshness descriptor. Futures + spot use ageSeconds; PM uses ageMinutes. `status` is a freshness label; `basis` (PM only) names which timestamp the age was measured against.
      - `asOf` string, date-time, nullable
      - `ageSeconds` number, nullable: futures / spot
      - `ageMinutes` number, nullable: PM
      - `status` 'fresh' | 'lagging' | 'stale' | 'unknown' | 'null', nullable: fresh | lagging (PM only) | stale | unknown. PM lagging>=45m & stale>=2h; spot/futures stale>120s.
      - `basis` 'latest_snapshot' | 'source_update' | 'processed' | 'event_update' | 'unknown', nullable: PM only — which timestamp the age was measured against.
    - `inputs` object
    - `dataset` object
    - `rowCount` integer, nullable
    - `hash` string: Short SHA-256 digest of the observed payload metadata.
  - `edgeSizing` EdgeSizing: Advisory quarter-Kelly sizing suggestion; never changes the requested stake.
    - `basis` 'fractional_kelly_capped'
    - `kellyMultiplier` number
    - `maxFraction` number
    - `edgePoints` number
    - `kellyFraction` number
    - `appliedFraction` number
    - `suggestedStakeMusd` number, nullable
    - `noEdge` boolean

## Other responses

- `400`: Invalid or missing parameters. On a route with a query allowlist, an undocumented query parameter returns `{"error": "unsupported_query_parameter", "message": "Unsupported query parameter: <key>. Supported: <keys>."}`.
- `401`: Missing/malformed or invalid/revoked API key
- `403`: API key missing the required scope
- `404`: Event not found
- `429`: Rate limit exceeded for this API key (120 req/min baseline, 20 trade-writes/min). Honor `Retry-After`, then resume; the `RateLimit-*` headers on every response let you pace proactively. (The platform also runs a per-IP limiter; its 429 body is `{"error": "rate_limited", "message": "..."}`.)

---

[API](https://skmtc.dev/coinrithm/apis/coinrithm-agent-trading-api.md) · [All operations](https://skmtc.dev/coinrithm/apis/coinrithm-agent-trading-api/llms.txt) · [OpenAPI document](https://skmtc.dev/coinrithm/apis/coinrithm-agent-trading-api/revisions/28fb59f285fe?raw)