Loading data, please wait a moment. We are fetching the latest content from the server and validating, organizing, and rendering it to ensure the information you see is accurate, complete, and up to date. Loading speed may be affected by your network, device performance, or the current amount of data, so a brief wait is normal. To avoid extra delays caused by duplicate requests, please don't refresh frequently or repeatedly click buttons, and don't close the page or switch to an offline network. The page will update automatically once the data is ready. If it takes noticeably longer, check your network connection and try refreshing or coming back later. If the issue persists, please let us know so we can investigate. Thanks for your patience and understanding.
Candles with adjustment and interval, priced from the primary listing (date cursor)
GET/openapi/v3/instruments/{ref}/candles
Refresh: Minute / daily
This endpoint uses v3 at https://openapi.sosovalue.com/openapi/v3. Do not append it to /openapi/v1; see version-specific conventions.
/instruments/{ref}/candles returns the instrument's default series — the consolidated series where one exists, otherwise the default venue's series (recommended); /listings/{ref}/candles returns the series of one specific listing (venue) and takes no venue parameter. For an instrument traded on a single venue the two are equivalent; where the same asset trades on multiple venues — e.g. a perp listed on several exchanges — the two can return different series, so use the listings form when you need a particular exchange.
Path Parameters
Parameter
Type
Required
Description
ref
string
Required
Instrument reference. A full_symbol such as AAPL.US or BTC-USDT-PERP.BINANCE is recommended; a stable id, symbol or FIGI also works
See Pagination. Daily: closed interval; intraday: half-open interval
order
string
Optional
asc / desc. Default: desc
limit
integer
Optional
Default 500, max 2000; silently truncated above the cap
price_type
string
Optional
Daily: trade / official_close / composite / mark / index / oracle; intraday has no official_close (passing it → 400003). Default: official_close for equity daily, trade for perps and intraday
adjust
string
Optional
unadjusted (default) / back (back-adjusted — 前复权) / forward (forward-adjusted — 后复权), see Adjustments. Computed at read time. Meaningful for equities only — no effect for perps
adjust_scope
string
Optional
Only applies when adjust is not unadjusted: split_dividend (default) includes share-count actions and cash dividends, producing a total-return series; split includes share-count actions only and preserves ex-dividend gaps
venue
string
Optional
/instruments/* only; echoed as meta.resolution=venue. Not needed for perps (the venue is fixed by the ref)
session
string
Optional
Equity intraday only. regular filters to the venue's regular session; extended (default) includes supported extended sessions. Ignored for 7×24 instruments
currency
string
Optional
Pricing-currency filter, e.g. USD
fx
string
Optional
USD converts CNY/HKD equity OHLC values to USD at the daily offshore FX rate. Conversion happens after adjustment and before weekly/monthly aggregation; volume is unchanged. Unsupported instruments remain in native currency and return a warning
Parameter Applicability by Class
Parameter
Equities / ETFs
Perpetual futures
interval / from / to / order / limit
Yes
Yes
price_type
Yes — daily defaults to official_close
Yes — always trade (no official close)
adjust / adjust_scope
Yes
No effect (no corporate actions)
session
Yes — intraday only, using the listing's venue calendar
Ignored (7×24)
fx=USD
CNY/HKD listings; harmless warning for other currencies
The exchange-local session date — the authoritative key for "which trading day does this bar belong to". Present on both daily and intraday bars
bar_start_at
String RFC3339
The unified time axis. Intraday = the bar's true UTC start; daily = a UTC-midnight anchor for trade_date
open / high / low / close
String
OHLC as decimal strings
volume
String
Volume
provisional
Boolean
Only present when true — see below
Notes
Never derive the trading day from bar_start_at yourself. A US after-hours bar (ET 20:00 = next-day UTC 00:00) has a UTC date one day later than its trade_date. For daily joins and earnings alignment, always use trade_date.
A daily bar's bar_start_at is a date anchor, not the opening time — don't display it as "the day's open time".
Weekly / Monthly Bars and Adjustments
1w / 1mo are aggregated server-side from daily bars: bucket boundaries follow the exchange-local calendar (weeks start on ISO Monday, months are calendar months), and each bar is anchored to the bucket's first trading day. The currently unfinished week / month is returned as a partial in-progress bucket.
adjust=back (back-adjustment — 前复权): the latest bar keeps its as-traded price and earlier bars are rescaled. adjust=forward (forward-adjustment — 后复权): the earliest bars keep their as-traded prices and later bars are rescaled. Note the naming: English back/forward refers to which direction the rescaling propagates, so back corresponds to Chinese 前复权 and forward to 后复权 — they are intentionally "reversed" relative to the literal Chinese terms.
OHLC is multiplied by the price factor; volume is inversely scaled by the split-only share factor (dividends don't change share count).
The default adjust_scope=split_dividend is a total-return adjustment. If you need the common charting convention that adjusts splits/rights issues but leaves cash-dividend gaps visible, request adjust_scope=split explicitly.
If a factor cannot be computed for an event, that event is treated as 1 and reported in warnings — never silently mis-scaled. To adjust yourself or audit the methodology, use the Adjustment Factors endpoint.
Provisional Data (must read)
Same-day candles are preliminary until end-of-day finalization completes. Each such bar is marked provisional: true, and meta.provisional_through gives the latest timestamp of the provisional portion.
Case
Behavior
What you should do
Today's intraday bars
Marked provisional: true per bar
Do not persist as final values; re-fetch after reconciliation
Today's / yesterday's daily bar
Before the official daily bar is produced, one is synthesized from today's intraday bars, marked the same way
Same as above
No today-bar before the open
When the regular session hasn't opened, or regular-session volume is 0, no same-day bar is synthesized
This is expected behavior, not missing data — do not retry
Real-time data temporarily unavailable
The response contains finalized data only, plus a warnings entry
Data is usable but excludes today; read warnings to tell
Notes
Once finalized, the provisional flag disappears automatically. Persisting provisional bars as final values is the most common integration mistake — they will change tomorrow.
History Depth Limits for Perps
For perps and crypto-class instruments, intraday history is guaranteed complete for the most recent 30 days only. Requests reaching further back usually still return data, but for the older portion:
granularity or field completeness may differ from the recent portion;
the series may contain honest gaps, reported in warnings — do not read a gap as "no trading during that period".
Notes
Daily bars are not subject to this limit — daily history is complete.
Use daily bars for long-horizon perp analysis; use intraday bars for intraday scenarios within the last 30 days.
Whenever your request window extends past 30 days, read warnings to tell whether the returned series is complete.