Instrument catalog
Instrument catalog and filters (cursor pagination)
GET
/openapi/v3/instrumentsRefresh: Minute / daily
This endpoint uses v3 at https://openapi.sosovalue.com/openapi/v3. Do not append it to /openapi/v1; see version-specific conventions.
Browse tradable instruments with pagination. This is a catalog/discovery endpoint — no {ref}, no resolved in the response.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| type | string | Optional | equity, etf / fund, or perp. Comma-separated non-derivative values are accepted, for example equity,etf; derivative types cannot be combined with other types. Default: all. Values come from the product-types vocabulary |
| underlying | string | Optional | Filter by underlying asset class, e.g. type=perp&underlying=crypto for coin-margined perps only, underlying=equity for equity perps only. Default: all |
| has | string | Optional | Only value: perp — return only rows with linked contracts. E.g. type=equity&has=perp = stocks that have perpetual futures |
| delisted | string | Optional | exclude (default) / include (rows carry is_delisted=true) / only |
| expand | string | Optional | Comma-combinable: quote, profile, derivatives — see below |
| fx | string | Optional | With expand=quote, USD also converts CNY/HKD price fields. Market-cap and turnover fields are already USD; see the quote currency contract |
| lang | string | Optional | Display language for supported names/profile labels (en default, zh for Simplified Chinese; missing translations fall back to English) |
| cursor | string | Optional | Cursor pagination (see Pagination) |
| limit | integer | Optional | Default 500, max 2000 |
expand Values
| Value | Effect |
|---|---|
| quote | Attach a real-time quote snapshot to each row (structure: Unified Quote Snapshot). Response cache drops to 10 seconds; rows without a snapshot omit the field |
| profile | Attach classification and profile fields. Equity rows can include sector, industry, industries[], gics_industry, logo_url, valuation fields, and ipo_date; fund rows additionally include a fund profile block |
| derivatives | Attach derivatives[] to each row: the perp legs linked to this instrument (with full_symbol, ready for direct follow-up calls) |
Request Example
curl "https://openapi.sosovalue.com/openapi/v3/instruments?type=equity&expand=quote,profile&limit=50" \ -H "x-soso-api-key: $SOSO_API_KEY"
# Stock list with quotes and sectors — one call renders a screen GET /openapi/v3/instruments?type=equity&expand=quote,profile&limit=50
Response Fields
| Field | Type | Description |
|---|---|---|
| instrument_id | Number | Stable id |
| instrument_type | String | Internal structural class such as equity_share, fund, or derivative; use the public product-type vocabulary for filters |
| symbol / name | String | Symbol / name |
| is_delisted | Boolean | Whether delisted |
| venue | String | Primary listing venue (for perps, the contract's exchange) |
| underlying_type / underlying_symbol | String | Perps only: underlying asset class and symbol (distinguishes coin-based from equity-based contracts) |
| primary_full_symbol | String | Unambiguous next-hop ref — recommended for follow-up calls |
| external_id | String | The primary listing leg's alternate stable id (string) |
| target_code | String | region.ticker form, e.g. US.AAPL |
| sector / industry / gics_industry | String | Classification (populated with expand=profile). industry is the primary display label |
| industries | Array of String | All industry labels assigned to the instrument, ordered for display. A stock may belong to multiple custom industries; use this array for membership tests |
| pe_ttm / pb / ps_ttm / forward_pe / dividend_yield / beta | String | Latest available valuation/profile values when expand=profile; omitted individually when unavailable |
| ipo_date | String YYYY-MM-DD | Issuer profile date, when available. Treat it as display metadata rather than a guaranteed listing-history boundary |
| fund | Object | ETF/fund profile when expand=profile: available fields include issuer, category, inception date, tracked index, AUM, expense ratio, yield, holdings count, description, and website URLs |
| logo_url | String | Instrument icon |
| href | String | Relative path to the detail endpoint |
Notes
- Delisting ≠ erased history: detail, candles and corporate actions via a direct ref are unaffected by the
delistedparameter. type=equity&has=perp&expand=derivativesis the bridge between equities and perps: it returns "stocks with contracts, plus their contracts" in one call.- The equity catalog includes US, Hong Kong, Shanghai, and Shenzhen listings. Prefer
primary_full_symbolfor follow-up calls: examples includeAAPL.US,00700.HK,688825.SH, and300308.SZ.