Listing quote
Quote snapshot for one listing
GET
/openapi/v3/listings/{ref}/quoteRefresh: 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}/quote prices from the primary listing leg (?venue= to switch); /listings/{ref}/quote prices a specific listing leg.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| ref | string | Required | Listing reference. A full_symbol such as AAPL.US or BTC-USDT-PERP.BINANCE is recommended; a stable listing_id also works |
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| venue | string | Optional | Instrument endpoint only: select a particular listing leg |
| fx | string | Optional | USD converts price fields for CNY/HKD listings. Omitted (or compatibility values native / none / mixed) keeps prices in the listing currency; market-cap and turnover fields remain USD either way |
Request Example
curl "https://openapi.sosovalue.com/openapi/v3/listings/MSTR.US/quote" \ -H "x-soso-api-key: $SOSO_API_KEY"
Response Fields
Price-like fields are all strings; ratio fields are string percentages — see Percentage Fields.
| Field | Type | Description |
|---|---|---|
| listing_id / external_id / full_symbol / symbol / venue / class / currency | — | Leg identity |
| last | String | Last price — session-dependent basis, see Notes |
| prev_close / change_pct | String | Previous close / change (percentage) |
| day_volume / day_turnover | String | Day volume / turnover (this leg only, not aggregated across venues) |
| native_day_turnover / native_currency | String | Turnover in the listing currency and that currency code. For equities/ETFs, day_turnover itself is normalized to USD |
| avg_price | String | Day VWAP = day turnover ÷ day volume (present when volume > 0) |
| vol_ratio | String | Volume ratio = day volume ÷ 5-trading-day average daily volume |
| market_cap | String | Shares outstanding × price, normalized to USD for equities/ETFs |
| float_market_cap | String | Float shares × price, normalized to USD for equities/ETFs |
| native_market_cap / native_float_market_cap | String | Listing-currency originals for market-cap fields. US rows may contain both USD and native fields with equal values |
| day_high / day_low | String | Regular-session high / low today |
| pe_ttm / pb | String | P/E (TTM) / P/B. Real-time price ÷ daily denominator — moves with the price |
| turnover_rate | String | Turnover rate |
| high_52w / low_52w / ath / atl | String | 52-week and all-time extremes (unadjusted basis) |
| is_ath | Boolean | Whether at an all-time high |
| chg_5m / chg_1h / chg_24h | String | Multi-window changes (percentages) |
| roi_1w / roi_1mo / roi_1y / roi_ytd | String | Period returns (percentages) |
| pre_price / pre_change_pct | String | Pre-market price and change (04:00–09:30 ET). Omitted if no trades in that session |
| after_price / after_change_pct | String | After-hours price and change (16:00–20:00 ET). Omitted if no trades in that session |
| pre_open / pre_close / reg_open / reg_close / after_open / after_close | String | Per-session open/close. *_close rolls while a session is in progress and freezes when it ends |
| funding_rate | String | Perps, some venues: funding rate of the current interval, as a percentage ("0.0013" = 0.0013%), rounded to 4 decimals |
| funding_rate_apr | String | Annualised funding rate, also a percentage: unrounded rate × intervals per year ("10.95" = 10.95% APR) |
| next_funding_time | Number | Next funding settlement time — a millisecond epoch number, unlike every other v3 time field (RFC3339 strings) |
| funding_interval_hours | Number | Funding interval in hours |
| funding_as_of | String RFC3339 | Snapshot time of the funding field group, independent of as_of |
| market_status | String | PRE_MARKET / TRADING / AFTER_HOURS / OVERNIGHT / CLOSED. Always TRADING for perps (7×24) |
| as_of | String RFC3339 | Snapshot time |
| funding_rate | String | Perps only: current settlement-period funding rate as a percentage ("0.0136" means 0.0136%, not 1.36%) |
| funding_rate_apr | String | Perps only: upstream annualized funding percentage; use this for cross-venue comparisons |
| next_funding_time | Number | Next settlement time as a 13-digit UNIX epoch in milliseconds |
| funding_as_of | String RFC3339 | Independent observation time of the funding snapshot |
| funding_interval_hours | Number | Funding settlement interval in hours |
Field Applicability by Class
| Field family | US equities | Perpetual futures |
|---|---|---|
| last / prev_close / change_pct / chg_* / roi_* / high_52w / low_52w / ath / atl / is_ath | Yes | Yes |
| day_volume / day_turnover / avg_price | Yes | Yes (UTC-day cumulative) |
| vol_24h / turnover_24h (rolling 24-hour volume/turnover) | Absent | Yes — prefer these for perps, see Notes |
| market_cap / float_market_cap / pe_ttm / pb / turnover_rate / vol_ratio / day_high / day_low | Yes | Absent (no share count or financial denominators) |
| pre_* / after_* / reg_* per-session prices | Yes | Absent (no session concept) |
| plus_depth_usd / minus_depth_usd / depth_as_of (±2% order-book depth, USD) | Absent | Some venues only, see Notes |
| funding_rate / funding_rate_apr / next_funding_time / funding_interval_hours / funding_as_of | Absent | Available when supplied by the venue; omitted as a group when unavailable |
Notes
- For perps use
vol_24h/turnover_24h, notday_volume/day_turnover. The latter are UTC-day cumulative and are drastically understated for small contracts in the UTC morning (i.e. Asian afternoon) — using them for volume ranking or liquidity screens gives visibly distorted results. The rolling 24-hour basis matches what exchanges display on their own sites. - Order-book depth covers only some venues. Depth is a low-frequency snapshot (~every 60 seconds), and
depth_as_ofis its own timestamp, independent ofas_of; if the upstream feed stalls past the retention window the whole field group is omitted. A perp without depth fields is normal — it does not mean an empty book. Treat the fields as optional; do not retry. - The funding field group behaves the same way as depth: it is a low-frequency snapshot with its own
funding_as_oftimestamp and is available only when supplied by the venue. A perp without funding fields is normal; do not retry.funding_as_ofcan lag behinddepth_as_of, and neither should be replaced with the quote'sas_of.funding_rate/funding_rate_aprare percentages (divide by 100 for a decimal fraction).funding_rateis rounded to 4 decimals, while APR is based on the upstream/unrounded rate, so do not derive APR from the displayed funding rate.next_funding_timeis a millisecond epoch number, the one exception to the "times are RFC3339 strings" convention. This group is the real-time snapshot only; funding-rate history is not available in this version (see Daily Metrics). - Currency contract for equities and ETFs:
market_cap,float_market_cap, andday_turnoverare always USD. Their listing-currency originals are preserved innative_*fields. By default, price fields such aslastremain in the listing currency. Passfx=USDto convert price fields too;currencythen becomesUSD.meta.fxreports the actual conversion and rate observation used. If a rate is unavailable, USD-derived fields are omitted rather than populated with a native-currency number, and a warning is returned. - The session-dependent basis of
lastfor US equities (matches the main site's lists): during the regular session = real-time; after hours and post-close = frozen at the day's regular close (after-hours trades only moveafter_*); pre-market / overnight / weekends = frozen at the previous close. - The denominator of
change_pctchanges with the session: regular / after-hours = previous trading day's close; pre-market / overnight = the close two trading days back (i.e. it shows "the previous trading day's full-day change"). Market cap androi_*follow the same primary-price basis. - Pure real-time surface — no historical fallback: no snapshot →
400404(the instrument does exist); for historical prices use Candles. Real-time channel not enabled at all →500301. Cached for 1 second.