---
title: "Dated spot reference price for one coin (Binance stream or stored consensus)"
method: GET
path: "/api/agent/spot/reference/{coinId}"
tags: ["spot"]
---

# Dated spot reference price for one coin (Binance stream or stored consensus)

`GET /api/agent/spot/reference/{coinId}`

## Request

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

Reference data only. Returns the Binance spot 24h-ticker last price
(USDT) for the coin's single verified Binance/USDT mapping when a
recent stream snapshot exists, plus the stored REST consensus price
(USD) as an individually dated fallback. Both values keep their own
units; `preferredSource` is not a USDT/USD conversion, an executable
price or a paper-fill promise. Spot quotes, orders and market context
never read this endpoint, so their prices are unchanged by it.

The stream observation is refused (with `stream.reason`) unless the
snapshot is connected, at most 10 s old, its universe metadata at
most 10 min old, and the coin's identity and source policy match.
`fallback.status` is `fresh` when the stored row was written at most
120 s ago. Requires scope `read`. Any query parameter returns 400.
Responses carry `Cache-Control: no-store`.

## Path parameters

- `coinId` string, required

## Response `200`

OK

- SpotReferenceResponse
  - `version` 1, required
  - `policyVersion` string, required
  - `coin` object, required
    - `coinId` string, required
    - `symbol` string, required
    - `name` string, required
  - `evaluatedAt` string, date-time, required: Server time at which ages and expiries were checked (after all I/O).
  - `referenceOnly` true, required
  - `preferredSource` 'binance_stream' | 'rest_consensus' | 'null', nullable, required: `binance_stream` when `stream.observation` is present, else `rest_consensus` when a stored price exists, else null. A preference between two values in different units, not a conversion or an executable price.
  - `stream` SpotReferenceStream, required
    - `status` 'available' | 'unavailable', required
    - `reason` string, nullable, required: null when available. Otherwise one code: `inactive_coin`, `mapping_unavailable`, `mapping_ambiguous`, `mapping_suppressed`, `policy_denied`, `clock_regression`, `disabled`, `redis_unavailable`, `missing`, `invalid_snapshot`, `disconnected`, `expired_snapshot`, `expired_metadata`, `symbol_not_captured`, `identity_mismatch`, `expired_observation`. Treat unknown codes as unavailable.
    - `observation` SpotReferenceObservation, required
      - `venue` 'binance', required
      - `market` 'spot', required
      - `basis` '24h_ticker_last', required: Last price of Binance's rolling 24h ticker, not a last-trade receipt.
      - `pair` string, required
      - `base` string, required
      - `quoteCurrency` 'USDT', required
      - `price` number, required: Price in USDT (not USD).
      - `quoteVolume24h` number, required: 24h quote volume in USDT.
      - `eventAt` string, date-time, required: Venue event time of the ticker.
      - `statisticsCloseAt` string, date-time, required: Close of the venue's 24h statistics window.
      - `receivedAt` string, date-time, required: When CoinRithm received the ticker.
      - `lastTradeAt` unknown, required
      - `localPriceChangedAt` string, date-time, required: When CoinRithm last saw this price change.
      - `capturedAt` string, date-time, required: When the snapshot holding this ticker was written.
      - `expiresAt` string, date-time, required: Earliest instant at which any input passes its age limit (10 s per stamp, 10 min for universe metadata).
      - `universeVerifiedAt` string, date-time, required
      - `universeRevision` string, required: Provenance of the collector's pair cohort.
      - `connectionGeneration` integer, required
  - `fallback` SpotReferenceFallback, required
    - `basis` 'stored_rest_consensus', required
    - `currency` 'USD', required
    - `status` 'fresh' | 'stale' | 'unavailable', required: fresh = stored row written at most 120 s before evaluatedAt; unavailable = no positive stored price.
    - `priceUsd` number, nullable, required
    - `priceTiming` SpotPriceTiming, required: 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
    - `expiresAt` string, date-time, nullable, required: Row write time + 120 s; null when there is no row.
  - `verification` object, required
    - `identityCheckedAt` string, date-time, required: Database statement time of the coin/mapping/policy read.
    - `mappingUpdatedAt` string, date-time, nullable, required
    - `policyUpdatedAt` string, date-time, nullable, required
    - `policyMode` string, nullable, required: Enabled per-coin source policy mode (`allow` / `deny`), null when none.

## Other responses

- `400`: Invalid coin id, or a query parameter was supplied.
- `401`: Missing/malformed or invalid/revoked API key
- `403`: API key missing the required scope
- `404`: No coin with this UCID.
- `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": "..."}`.)
- `503`: Database read failed; no fallback is guessed.

---

[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)