---
title: "Compact factual market context for one coin"
method: GET
path: "/api/agent/market/{coinId}"
tags: ["reads"]
---

# Compact factual market context for one coin

`GET /api/agent/market/{coinId}`

## Request

- Base URL: `https://api.coinrithm.com`
- URL: `https://api.coinrithm.com/api/agent/market/{coinId}`
- Auth: HTTP bearer

Price + 1h/24h/7d change + market cap, per-coin sentiment, the global
Fear & Greed value, and up to 3 directly-related OPEN prediction markets
(leading outcome + probability). Optional context includes source price
timing, perpetual funding, open interest, positioning, captured
liquidations, observed order-book depth, macro derivative proxies and
DeFi. Each block has its own coverage and time basis; response `asOf`
does not make every input fresh. All from CoinRithm's stored data; no
generated thesis. Requires scope `read`.

## Path parameters

- `coinId` string, required

## Response `200`

OK

- object
  - `coin` object
    - `coinId` string
    - `symbol` string
    - `name` string
    - `marketCapRank` integer, nullable
    - `categories` string[]: CoinGecko sector tags (canonical English names).
  - `price` object, nullable
    - `usd` number
    - `change1h` number, nullable
    - `change24h` number, nullable
    - `change7d` number, nullable
    - `marketCapUsd` number, nullable
    - `asOf` string, date-time, nullable: LivePrice row write time (an observation, not a trade); null without a price row.
  - `priceTiming` SpotPriceTiming: Source-vs-row timing of the spot price (optional: absent on older API versions). Informational only: `freshness`, `eligible` and the write path's mark guard still measure the row WRITE time and are unchanged. `sourceObservedAt` is a venue snapshot/ticker time, NOT a last-trade time and NOT a per-fill receipt.
    - `rowWrittenAt` string, date-time, nullable, required: When CoinRithm wrote the price row; the same instant as freshness.asOf. null when there is no row.
    - `sourceObservedAt` string, date-time, nullable, required: The OLDEST venue snapshot time among the winning price cluster's members that carry one. null when no member carries one.
    - `sourceAgeSeconds` number, nullable, required: max(0, now - sourceObservedAt), the same clamp as freshness.ageSeconds.
    - `writeLagSeconds` number, nullable, required: rowWrittenAt - sourceObservedAt in seconds, SIGNED. Negative means the venue's clock ran ahead of CoinRithm's (the writer admits up to 5 minutes); it is never clamped.
    - `coverage` 'recorded' | 'not_recorded' | 'no_row', required: recorded: at least one cluster member carried a source time. It may be PARTIAL: members without a stamp (e.g. Kraken, Gate.io) are not represented. not_recorded: the row has no source time (unknown, never fresh). no_row: there is no price row.
    - `basis` 'venue_snapshot_time', required
  - `funding` MarketFundingContext: One venue-attributed perpetual funding reference for this coin, not a cross-venue average. The market field is optional on older APIs and null without a usable reference. Display staleness does not determine futures entry eligibility; quote/open re-check their own reference rule.
    - `venue` string, required
    - `symbol` string, required
    - `ratePct` number, required: Signed percent per funding interval (0.0056 means 0.0056%, not a fraction); rounded to six decimals.
    - `intervalHours` integer, required: Funding interval in hours; defaults to 8 when the stored interval is absent or zero.
    - `annualizedPct` number, required: Simple, non-compounded annualized percent; rounded to two decimals.
    - `nextFundingTime` string, date-time, required
    - `asOf` string, date-time, required: CoinRithm collection time, not a provider observation timestamp.
    - `ageSeconds` integer, required: Rounded collection age, clamped at zero.
    - `stale` boolean, required: True when collection age exceeds 1800 seconds (30 minutes).
  - `derivatives` MarketDerivativesContext: Optional on older APIs. Members are additive and may be absent on older APIs; each can independently be null when unavailable or unusable.
    - `fundingByVenue` MarketFundingByVenueContext: Independent venue collection clocks; available only with usable additional context within the bounded two-hour read. Does not change the top-level funding reference or futures entry gate. Not simultaneous prices or an arbitrage/return forecast.
      - `rates` MarketFundingVenueRate[], required
        - `role` 'settlement_reference' | 'context_only', required
        - `venue` string, required
        - `symbol` string, required
        - `source` 'paper_futures_reference' | 'hyperliquid_predicted_fundings', required
        - `rateFraction` number, required: Raw fraction per intervalHours, including valid zero/negative values; not percent.
        - `intervalHours` integer, nullable, required: Null when unknown. Hyperliquid HlPerp context is hourly.
        - `hourlyEquivalentFraction` number, nullable, required: rateFraction / intervalHours; simple normalization, not realized performance, APR or forecast return. Null when interval unknown.
        - `nextFundingTime` string, date-time, nullable, required: Null for missing/rolled/unusable provider boundaries; never advanced synthetically.
        - `fetchedAt` string, date-time, required: CoinRithm collection time, not provider observation time.
        - `sourceAt` unknown, required
        - `ageSeconds` integer, required: Floor of collection age, clamped at zero.
        - `stale` boolean, required: Collection age exceeds 1800 seconds.
        - `freshnessBasis` 'collection_time', required
      - `sameTime` false, required
      - `note` string, required
    - `openInterest` MarketOpenInterestContext: Single-side perpetual open interest in USD from covered Bybit/OKX contracts, not total-market open interest. Reads up to 25 hours of 15-minute buckets. Only venues in the newest bucket or one bucket behind contribute to the total; this relative inclusion rule can include stale data. Null when no usable reading exists. A finite zero is valid.
      - `totalUsd` number, required: Sum of included single-side USD readings, rounded to whole USD.
      - `change1hPct` number, nullable, required: Percent change over matching venue and contract buckets exactly one hour apart; null without a positive comparable base.
      - `change1hVenues` string[], required: Contributing venues for change1hPct; empty when the change is null.
      - `change24hPct` number, nullable, required: Percent change over matching venue and contract buckets exactly 24 hours apart; null without a positive comparable base.
      - `change24hVenues` string[], required: Contributing venues for change24hPct; empty when the change is null.
      - `venues` MarketOpenInterestVenue[], required: Included venues, descending by open interest; each retains its own provider timestamp.
        - `venue` string, required
        - `symbol` string, required: Resolved perpetual contract identifier.
        - `openInterestUsd` number, required: Single-side USD open interest, rounded to whole USD.
        - `asOf` string, date-time, required: This venue's provider timestamp.
      - `asOf` string, date-time, required: Newest provider timestamp among included venues; does not date every venue.
      - `ageSeconds` integer, required: Rounded age of asOf, clamped at zero.
      - `stale` boolean, required: True when ageSeconds exceeds 2700 (45 minutes).
    - `positioning` MarketPositioningContext: Binance positioning for covered top coins by open interest. Each metric is the newest usable value on the newest bucket's venue and contract, within a 75-minute bucket lookback. Metrics retain independent provider period timestamps; times more than 60 seconds ahead are rejected. Null when no metric is usable, not evidence of balanced positioning.
      - `venue` string, required
      - `symbol` string, required
      - `longShortAccountRatio` MarketPositioningMetric, required
        - `value` number, required: Unit is defined by the containing metric (ratio or percent).
        - `asOf` string, date-time, required: Provider period timestamp for this metric.
        - `stale` boolean, required: True when the provider period timestamp is more than 2700 seconds (45 minutes) old.
      - `longAccountPct` MarketPositioningMetric, required
        - `value` number, required: Unit is defined by the containing metric (ratio or percent).
        - `asOf` string, date-time, required: Provider period timestamp for this metric.
        - `stale` boolean, required: True when the provider period timestamp is more than 2700 seconds (45 minutes) old.
      - `topTraderPositionRatio` MarketPositioningMetric, required
        - `value` number, required: Unit is defined by the containing metric (ratio or percent).
        - `asOf` string, date-time, required: Provider period timestamp for this metric.
        - `stale` boolean, required: True when the provider period timestamp is more than 2700 seconds (45 minutes) old.
      - `takerBuySellRatio` MarketPositioningMetric, required
        - `value` number, required: Unit is defined by the containing metric (ratio or percent).
        - `asOf` string, date-time, required: Provider period timestamp for this metric.
        - `stale` boolean, required: True when the provider period timestamp is more than 2700 seconds (45 minutes) old.
    - `liquidations` MarketLiquidationContext: OKX USDT-margined swaps only, using the coin's resolved OKX contract. Sums cover events pushed while CoinRithm capture ran. Null without a resolved contract or usable capture-coverage rows. Uncovered spans are unknown, never evidence of no liquidations. Windows end at response time.
      - `venue` 'okx', required
      - `instId` string, required
      - `note` string, required: Source and capture-completeness limitations.
      - `last1h` MarketLiquidationWindow, required
        - `longLiquidatedUsdt` number, required: Captured liquidated-long notional in USDT, rounded to whole USDT.
        - `shortLiquidatedUsdt` number, required: Captured liquidated-short notional in USDT, rounded to whole USDT.
        - `events` integer, required
        - `capturedPct` number, required: Conservative lower bound of capture uptime within this window, floored to 0.1 percent. Not exchange completeness or a missing-event estimate.
      - `last24h` MarketLiquidationWindow, required
        - `longLiquidatedUsdt` number, required: Captured liquidated-long notional in USDT, rounded to whole USDT.
        - `shortLiquidatedUsdt` number, required: Captured liquidated-short notional in USDT, rounded to whole USDT.
        - `events` integer, required
        - `capturedPct` number, required: Conservative lower bound of capture uptime within this window, floored to 0.1 percent. Not exchange completeness or a missing-event estimate.
      - `lastEventAt` string, date-time, nullable, required: Latest usable captured event in the 24-hour read window; null without one. Not a capture heartbeat.
    - `depth` MarketDepthContext: Hyperliquid's observed book only: at most 20 full-precision levels per side, not total-market liquidity or an executable fill estimate. Latest stored bucket within 30 minutes for reviewed coins. Null without a usable snapshot; each side can independently be null when invalid. Provider times more than 60 seconds ahead are rejected.
      - `venue` string, required
      - `mid` number, required: Mid-price in USD of the observed book.
      - `bid` MarketDepthSide, required
        - `usd` number, required: Resting USD in returned levels, rounded to whole USD.
        - `reachPct` number, required: Farthest returned level's distance from mid in percent; rounded to four decimals.
        - `levels` integer, required
        - `complete` boolean, required: True only for a side returned whole with fewer than 20 levels. False means liquidity beyond reachPct is unknown, not zero.
      - `ask` MarketDepthSide, required
        - `usd` number, required: Resting USD in returned levels, rounded to whole USD.
        - `reachPct` number, required: Farthest returned level's distance from mid in percent; rounded to four decimals.
        - `levels` integer, required
        - `complete` boolean, required: True only for a side returned whole with fewer than 20 levels. False means liquidity beyond reachPct is unknown, not zero.
      - `asOf` string, date-time, required: Provider book timestamp.
      - `ageSeconds` integer, required: Rounded provider age, clamped at zero.
      - `stale` boolean, required: True when ageSeconds exceeds 900 (15 minutes).
      - `note` string, required: One-venue visible-book and completeness limitations.
  - `macro` MarketMacroContext: Optional on older APIs; null without usable quotes. Curated Hyperliquid xyz perpetuals tracking indices, commodities, FX and rates around the clock are derivative proxies, not underlying exchange quotes. Each quote has its own time; the block is market-wide, not coin-specific.
    - `note` string, required: Source and derivative-proxy limitations.
    - `quotes` MarketMacroQuote[], required
      - `symbol` string, required: Provider perpetual identifier.
      - `label` string, required
      - `kind` string, required: Currently index, commodity, fx or rates; not a closed enumeration.
      - `price` number, required: Provider derivative price in the quoted instrument's units; not a spot-market price.
      - `change24hPct` number, nullable, required: Percent change from the stored previous-day price, rounded to two decimals; null without a valid positive base.
      - `asOf` string, date-time, required: Provider time of the latest traded minute; times more than 60 seconds ahead are rejected.
      - `ageSeconds` integer, required: Rounded provider age, clamped at zero.
      - `stale` boolean, required: True when ageSeconds exceeds 3600 (one hour).
  - `defi` MarketDefiContext: Optional on older APIs; null when neither chain TVL nor market-wide stablecoin supply is usable. Each member can independently be null.
    - `chainTvl` MarketChainTvlContext, required: Value locked on the chain associated with this asset by DefiLlama, matched using two identifiers. The association does not prove this is the chain's native/gas token. TVL is not the coin's market value. Current TVL has no provider observation time; publication/fetch times are provenance, not substitutes for it. Null without a usable mapping and value. Times more than 60 seconds ahead are treated as unknown.
      - `chain` string, required
      - `tvlUsd` number, required: Current associated-chain TVL, rounded to whole USD.
      - `publishedAt` string, date-time, nullable, required: Response HTTP Last-Modified time; not an observation time.
      - `fetchedAt` string, date-time, nullable, required: CoinRithm collection time.
      - `sourceObservedAt` unknown, required
      - `stale` boolean, required: True when publication or fetch time is unknown, publication exceeds 6 hours, or fetch exceeds 3 hours.
      - `dayAt` string, date-time, nullable, required: Provider daily point used for changes; null when invalid, older than 2 days, or its value is unavailable.
      - `change1dPct` number, nullable, required: Percent change between provider daily points, not current TVL versus yesterday. Null without a usable daily point and positive comparison base.
      - `change7dPct` number, nullable, required: Percent change between provider daily points seven days apart; null without a usable daily point and positive comparison base.
      - `note` string, required: Chain-association and daily-comparison limitations.
    - `stablecoinSupply` MarketStablecoinContext, required: Total stablecoin supply across all pegs in USD, market-wide, from DefiLlama daily points. Null without a usable value and provider day. Unknown or more-than-60-seconds-future collection/publication times become null; an invalid/future provider day makes the block null.
      - `totalUsd` number, required: Total supply across all pegs, rounded to whole USD.
      - `dayAt` string, date-time, required: Provider daily point; may be stale.
      - `change1dPct` number, nullable, required: Percent change versus the previous daily point; null without a valid positive base. May be retained on a stale block.
      - `change7dPct` number, nullable, required: Percent change versus the daily point seven days earlier; null without a valid positive base. May be retained on a stale block.
      - `stale` boolean, required: True when the provider day exceeds 2 days, or collection time is unknown or exceeds 3 hours.
      - `publishedAt` string, date-time, nullable, required: Response HTTP Last-Modified time, not the provider daily point.
      - `fetchedAt` string, date-time, nullable, required: CoinRithm collection time.
      - `note` string, required: Market-wide, all-pegs USD supply basis.
  - `sentiment` object
    - `bullishVotes` integer
    - `bearishVotes` integer
    - `totalVotes` integer
    - `bullishPct` integer, nullable
    - `dayUtc` string, date-time, nullable: UTC day of this vote cohort; may be older than the response or price.
    - `updatedAt` string, date-time, nullable: Last write to this vote cohort; not the price clock.
  - `fearGreed` object, nullable
    - `value` integer
    - `label` string
    - `fetchedAt` string, date-time, nullable: Last successful collection time. The provider observation timestamp is not retained.
  - `futuresEntryEligibility` object: What the server entry gate's perpetual-reference rule says about a NEW futures open on this coin right now (backend-v2 #106). Informational: quote/open re-check at execution, and eligibility can change in between. Adds to and closes of an existing position are never refused for it. `reference_unavailable` states that CoinRithm holds no supported perpetual reference for the coin, not that no perpetual exists anywhere. Absent on older API versions.
    - `status` 'eligible' | 'reference_stale' | 'reference_unavailable', required
    - `referenceRequired` boolean, required: Whether the gate currently requires a reference for NEW opens.
    - `venue` string, nullable
    - `symbol` string, nullable
    - `referenceFetchedAt` string, date-time, nullable
    - `maxReferenceAgeHours` number, required
    - `evaluatedAt` string, date-time, required
  - `relatedMarkets` object[]
    - `source` string
    - `title` string
    - `outcome` string, nullable
    - `probability` number, nullable: Leading-outcome probability as a 0..1 FRACTION — unlike the PM quote/discovery endpoints, which use 0..100. Multiply by 100 before comparing.
    - `slug` string
    - `volume24h` number
    - `liquidity` number
    - `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
  - `similarCoins` object[]: Peer coins by shared CoinGecko category (then market-cap neighbours), each with a live price. Call /api/agent/market on one to drill in.
    - `coinId` string
    - `slug` string
    - `symbol` string
    - `name` string
    - `marketCapRank` integer, nullable
    - `sharedCategoryCount` integer
  - `asOf` string, date-time
  - `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.

## 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`: Coin 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)