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

# OHLCV candles for one coin

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

## Request

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

Historical OHLCV candles for indicator/momentum strategies (RSI,
moving averages, breakouts), keyed by UCID like the rest of the agent
surface — call /api/agent/resolve first. `range` picks both the
lookback and the per-candle resolution: 1H = 60×1-minute,
1D = 288×5-minute, 1W = 672×15-minute, 1M = 720×1-hour,
3M = 540×4-hour, 1Y = up to 366 daily candles. Candles are oldest→newest with `t` in unix
SECONDS. o/h/l/c are converted to `fiat` (default USD) at the nearest
stored rate; `v` stays USD regardless of fiat. These are sampled
composite-price bars, not venue trade candles, and `v` is a rolling
24h volume observation rather than per-candle volume (see the field
description). Pure market data, cached ~60s server-side. Requires
scope `read`.

## Path parameters

- `coinId` string, required

## Query parameters

- `range` '1H' | '1D' | '1W' | '1M' | '3M' | '1Y'
- `fiat` string

## Response `200`

OK

- object
  - `coin` object
    - `ucid` string
    - `slug` string
    - `symbol` string
    - `name` string
  - `range` '1H' | '1D' | '1W' | '1M' | '3M' | '1Y'
  - `fiat` string
  - `rateToUsd` number: Latest fiat-per-USD rate applied (1 for USD).
  - `candles` object[]: Oldest → newest.
    - `t` integer: Candle timestamp, unix SECONDS (UTC).
    - `o` number
    - `h` number
    - `l` number
    - `c` number
    - `v` number: Mean rolling 24-HOUR quote volume observed at this bar, in USD regardless of `fiat`. This is NOT the volume traded during the candle. Every bar in a range carries its own ~24h figure, so summing `v` across bars adds the same window repeatedly, and differencing consecutive bars is not a volume delta. Read a single bar's `v` as a rolling daily quote-volume observation, not order-book depth or executable liquidity. Do not sum it as interval turnover. Missing venue contributions can change this observation without representing a change in activity at the missing venues.
    - `vm` integer, nullable: Number of expected venues whose volume contribution was missing because that venue fetch failed at this observation. 0 means no known missing venue, a positive value means partial coverage, and null means coverage is unknown.
  - `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`: Unknown coinId — body `{ "error": "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)