---
title: "One TradFi reference with venue constituents and history"
method: GET
path: "/api/market/references/{ticker}"
tags: ["public-market-data"]
---

# One TradFi reference with venue constituents and history

`GET /api/market/references/{ticker}`

## Request

- Base URL: `https://api.coinrithm.com`
- URL: `https://api.coinrithm.com/api/market/references/{ticker}`
- Auth: none required

Keyless detail for one catalog ticker: the latest validated
consensus with each contributing venue's index price, derived
change and range, the optional `live` overlay, and recorded
15-minute history over `window` (24 hours or 7 days, oldest
first). Same methodology and caveats as the catalog. A ticker
outside the catalog returns 404.

## Path parameters

- `ticker` string, required

## Query parameters

- `window` '24h' | '7d'

## Response `200`

Latest snapshot with venues, live overlay and history

- PublicTradfiReferenceDetail
  - `version` integer, required
  - `generatedAt` string, date-time, required
  - `methodology` PublicTradfiReferenceMethodology, required
    - `basis` string, required
    - `aggregation` string, required
    - `minimumVenueCount` integer, required
    - `maxVenueSpreadPct` number, required
    - `collectionIntervalSeconds` integer, required
    - `freshnessThresholdSeconds` integer, required
    - `retentionDays` integer, required
    - `liveMaxAgeSeconds` integer, required: A `live` value older than this is not served.
  - `instrument` PublicTradfiReferenceInstrument, required
    - `ticker` string, required
    - `name` string, required
    - `assetClass` string, required: Currently equity, etf, metal, commodity or fx.
    - `unit` PublicTradfiReferenceUnit, required: The index denomination is deliberately not inferred; `status` is `unverified`.
      - `status` string, required
      - `currency` string, nullable, required
      - `per` string, nullable, required
    - `venueQuoteAsset` string, required: Contract quote asset (`USDT`).
    - `issuer` string, nullable, required: Fund issuer, set for leveraged or inverse ETFs.
    - `leverage` PublicTradfiReferenceLeverage, required
      - `factor` number, required: Daily target multiple of the underlying's return; negative means inverse.
      - `underlying` string, required
    - `homeListing` PublicTradfiReferenceHomeListing, required: Home-market listing of an instrument quoted outside the US.
      - `exchange` string, required: `KRX` or `HKEX`.
      - `currency` string, required: `KRW` or `HKD`.
      - `code` string, required: Home-market code without the exchange suffix.
  - `availability` string, required: `available` or `unavailable`.
  - `freshness` PublicTradfiReferenceFreshness, required
    - `status` 'fresh' | 'stale' | 'unavailable', required: Freshness of an upstream dataset CoinRithm re-reads on a schedule. `stale` data is still served inside its documented maximum age; `unavailable` means no usable copy, never zero or empty truth.
    - `basis` string, required: `collection`: CoinRithm's batch collection time, not a venue quote time.
    - `asOf` string, date-time, nullable, required
    - `ageSeconds` integer, nullable, required
    - `staleAt` string, date-time, nullable, required
  - `latest` PublicTradfiReferenceSnapshot, required
    - `bucketStart` string, date-time, required
    - `fetchedAt` string, date-time, required
    - `consensusPrice` number, required
    - `minPrice` number, required
    - `maxPrice` number, required
    - `venueSpreadPct` number, required
    - `venueCount` integer, required
    - `venues` PublicTradfiReferenceVenueQuote[], required
      - `venue` string, required: `binance`, `bybit` or `gate`.
      - `symbol` string, required
      - `label` string, required: The venue's own instrument label.
      - `assetClass` string, required
      - `indexPrice` number, required
      - `sourceObservedAt` string, date-time, nullable, required: Venue observation time; currently always null (not recorded).
  - `change24h` PublicTradfiReferenceChange, required: Change against a validated recorded snapshot at the comparison time (within 30 minutes); never interpolated.
    - `pct` number, required
    - `referencePrice` number, required
    - `referenceBucketStart` string, date-time, required
  - `change7d` PublicTradfiReferenceChange, required: Change against a validated recorded snapshot at the comparison time (within 30 minutes); never interpolated.
    - `pct` number, required
    - `referencePrice` number, required
    - `referenceBucketStart` string, date-time, required
  - `range24h` PublicTradfiReferenceRange, required: Low and high of validated recorded medians in the 24 hours ending at `latest`.
    - `low` number, required
    - `high` number, required
    - `observations` integer, required
  - `live` PublicTradfiReferenceLive, required: Near-real-time consensus with the same method as `latest`, republished about every 10 seconds. Null when the overlay is off or unavailable, fails validation, or is older than `liveMaxAgeSeconds`; `latest` and every derived field are unaffected by it.
    - `price` number, required
    - `minPrice` number, required
    - `maxPrice` number, required
    - `venueSpreadPct` number, required
    - `venueCount` integer, required
    - `venues` PublicTradfiReferenceLiveVenue[], required
      - `venue` string, required
      - `indexPrice` number, required
    - `sourceAt` string, date-time, required: Oldest venue read inside this consensus, the honest age of the price.
    - `ageSeconds` integer, required
    - `change24hPct` number, nullable, required: Live price against the same reference as `change24h`.
  - `history` PublicTradfiReferenceSnapshot[], required: Recorded 15-minute snapshots in the window, oldest first.
    - `bucketStart` string, date-time, required
    - `fetchedAt` string, date-time, required
    - `consensusPrice` number, required
    - `minPrice` number, required
    - `maxPrice` number, required
    - `venueSpreadPct` number, required
    - `venueCount` integer, required
    - `venues` PublicTradfiReferenceVenueQuote[], required
      - `venue` string, required: `binance`, `bybit` or `gate`.
      - `symbol` string, required
      - `label` string, required: The venue's own instrument label.
      - `assetClass` string, required
      - `indexPrice` number, required
      - `sourceObservedAt` string, date-time, nullable, required: Venue observation time; currently always null (not recorded).
  - `historyWindow` PublicTradfiReferenceHistoryWindow, required
    - `window` string, required: `24h` or `7d`.
    - `from` string, date-time, required
    - `to` string, date-time, required
    - `intervalSeconds` integer, required
  - `fundamentals` PublicTradfiReferenceFundamentals: Company-reported SEC XBRL data. Each value is null when SEC data cannot give it without guessing. Market cap, dividend yield and P/E use the CoinRithm reference price (USDT perp index median, treated as USD), not an exchange quote.
    - `marketCapUsd` number, nullable, required: sharesOutstanding x referencePrice.
    - `marketCapBasis` 'shares x reference price', required
    - `referencePrice` number, nullable, required: The live consensus when present, else the latest stored consensus.
    - `sharesOutstanding` number, nullable, required
    - `sharesAsOf` string, date, nullable, required
    - `sharesSource` 'dei_cover' | 'balance_sheet', nullable, required: `dei_cover`: filing cover page; `balance_sheet`: all classes at quarter end.
    - `dividendPerShareTtm` number, nullable, required: Dividends declared per share over the trailing twelve months, USD.
    - `dividendTtmBasis` 'quarters' | 'annual', required
    - `dividendTtmPeriodEnd` string, date, nullable, required
    - `dividendYieldPct` number, nullable, required: dividendPerShareTtm / referencePrice x 100.
    - `lastDividendPerShare` number, nullable, required: Declared in the latest reported quarter.
    - `lastDividendPeriodEnd` string, date, nullable, required
    - `revenueTtmUsd` number, nullable, required
    - `netIncomeTtmUsd` number, nullable, required
    - `epsDilutedTtm` number, nullable, required
    - `peRatio` number, nullable, required: referencePrice / epsDilutedTtm; null when EPS <= 0.
    - `ttmBasis` 'quarters' | 'annual', required
    - `ttmPeriodEnd` string, date, nullable, required: End of the twelve months behind revenue, net income and EPS.
    - `sector` string, nullable, required: SEC SIC industry description, e.g. Electronic Computers.
    - `fiscalYearEnd` string, nullable, required: MM-DD, e.g. 09-26.
    - `latestFiling` object, nullable, required
      - `form` string, required
      - `date` string, date, required
    - `fetchedAt` string, date-time, required: When the aggregator last read SEC.
    - `source` object, required
      - `name` 'SEC EDGAR', required
      - `publisher` string, required
      - `url` string, required: EDGAR filing list of the issuer.
      - `dataUrl` string, required: The XBRL companyfacts JSON the values were derived from.
      - `note` string, required
  - `week52` PublicTradfiReferenceWeek52
    - `high` number, required
    - `low` number, required
    - `asOf` string, date, required: Latest UTC day included.
    - `days` integer, required: Days with data in the window (not 365 while history is short).
  - `corporateEvents` PublicTradfiReferenceCorporateEvents
    - `lastEarnings` object, nullable, required: Latest Item 2.02 earnings release 8-K, or null.
      - `date` string, date, required: US Eastern date of EDGAR acceptance.
      - `timing` 'before_open' | 'after_close' | 'during_market', nullable, required: Acceptance time against the 09:30-16:00 ET session; null when unknown.
      - `url` string, required: The SEC filing.
    - `nextEarningsEstimate` object, nullable, required: An ESTIMATE, never an announced date: the last release plus the median gap, only with at least 3 consecutive releases 80-100 days apart and while the date is not past. Otherwise null.
      - `date` string, date, required
      - `basis` 'quarterly_cadence', required
      - `fromReleases` integer, required: Releases the cadence was measured from.
    - `dividends` PublicTradfiReferenceDividendEvent[], required: Up to 4 dividend declarations found in 8-K text, newest first. Issuers that announce dividends only by press release (e.g. KO, MSFT, JPM) have an empty list.
      - `declaredDate` string, date, nullable, required: Announcement date stated in the filing, else the SEC filing date.
      - `dividendPerShare` number, required: USD per common share.
      - `recordDate` string, date, nullable, required
      - `exDate` string, date, nullable, required
      - `exDateDerived` boolean, required: true when `exDate` is the record date under T+1 settlement (not stated by the company).
      - `payableDate` string, date, nullable, required
      - `url` string, required: The SEC document the dates were read from.
    - `upcomingDividend` PublicTradfiReferenceDividendEvent, required
      - `declaredDate` string, date, nullable, required: Announcement date stated in the filing, else the SEC filing date.
      - `dividendPerShare` number, required: USD per common share.
      - `recordDate` string, date, nullable, required
      - `exDate` string, date, nullable, required
      - `exDateDerived` boolean, required: true when `exDate` is the record date under T+1 settlement (not stated by the company).
      - `payableDate` string, date, nullable, required
      - `url` string, required: The SEC document the dates were read from.
    - `source` object, required
      - `name` 'SEC EDGAR', required
      - `url` string, required: The issuer's 8-K filing list.

## Other responses

- `400`: Invalid ticker, window or query parameter
- `404`: Reference instrument not found
- `429`: Public request rate limit exceeded; honor `Retry-After`.
- `500`: Reference data temporarily unavailable

---

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