Auth, quota and conventions
Shared authentication and account limits, followed by version-specific base URLs, responses, pagination and data conventions.
Choose the correct API version
| Item | v1 · first ten modules | v3 · stocks and funds market data |
|---|---|---|
| Base URL | https://openapi.sosovalue.com/openapi/v1 | https://openapi.sosovalue.com/openapi/v3 |
| Authentication | x-soso-api-key | x-soso-api-key |
| Coverage | Currencies, crypto ETF flows, indices, news, fundraising, macro and more | US, HK and A-share equities, ETFs / funds and perpetuals |
| Success response | code / message / data | code / status / data; resolved / meta / pagination / warnings when applicable |
| Pagination | Endpoint-specific page / page_size, time windows or date ranges | Catalog cursor; candles / actions use from / to; some lists have has_more only |
| Time | Date strings or UTC milliseconds; check each field | Usually RFC3339 / dates; from / to also accept Unix seconds; next_funding_time is milliseconds |
| Numbers and currency | Many amounts are numbers; some endpoints return strings | Quote / candle prices and quantities are generally strings; fundamentals may be numbers; use meta.currency and field definitions |
| Rate-limit signal | X-RateLimit--Minute / X-RateLimit--Month; HTTP 429 | X-RateLimit--Minute / X-RateLimit--Month; HTTP 429 |
/crypto-stocks is the v1 crypto-stocks module; /instruments is v3 market data.For v3, HTTP 200 with warnings remains a successful response; preserve warnings when interpreting data. Quote 404 / 400404 means no current snapshot, not a missing instrument; use candles for history.
Authentication
Send your API key in the x-soso-api-key request header. It is the only auth method — no client-id, secret or signature.
GET /openapi/v1/etfs/summary-history?symbol=BTC&country_code=US HTTP/1.1 Host: openapi.sosovalue.com x-soso-api-key: YOUR_API_KEY
Using the command-line tool? See CLI sign-in with soso auth for local key configuration and verification.
An account can have up to 5 active keys. One key per project or environment makes it easy to read usage per key and delete keys individually; deleted keys free up a slot.
Rate limits and quota
Limits apply to your account, shared by all of its API keys: 100 requests per minute and 10,000 requests per month. Creating more keys does not add capacity. The monthly quota follows the UTC calendar month and resets at 00:00 UTC on the 1st. Exceeding either limit returns HTTP 429 with code 402901.
v1 and v3 responses include minute and monthly quota headers. Use these headers to control request frequency:
X-RateLimit-Limit-Minute: 100 # max requests in the current minute window X-RateLimit-Remaining-Minute: 17 # requests left in this window X-RateLimit-Reset-Minute: 1793250060 # Unix seconds when this window resets X-RateLimit-Limit-Month: 10000 # monthly quota X-RateLimit-Remaining-Month: 3580 # requests left this month X-RateLimit-Reset-Month: 1796083200 # Unix seconds when the quota resets
On v1, a 429 body includes details with limit, window and retry_after (seconds) — wait and retry. v3 returns no extra fields; use exponential backoff and lower your polling rate. When the monthly quota is used up, retrying is pointless until the next month.
Error codes
Success is HTTP 200 with code 0. On failure the HTTP status gives the category and code is a six-digit number; message is human-readable. v1 errors carry details (field, value, constraint, suggestion); v3 errors carry error and, for ambiguous refs, candidates.
HTTP/1.1 429 Too Many Requests
{
"code": 402901,
"message": "Rate limit exceeded",
"details": { "limit": 100, "window": "60s", "retry_after": 45 }
}| HTTP | code | Reason | What to do |
|---|---|---|---|
| 400 | 400001 | Bad parameter format (v3: invalid ref syntax) | Check details.constraint, fix and retry |
| 400 | 400002 | Missing required parameter | Add the field named in details.field (v3: error.param) |
| 400 | 400003 | Invalid parameter value (not in the enum, or from > to) | Use a value from the allowed list |
| 401 | 400101 | Key missing or invalid | Check the x-soso-api-key header; do not retry |
| 401 | 400102 | Key expired | Apply again or contact us |
| 403 | 400301 | Key revoked/disabled, or no access to this endpoint | Check the key status and endpoint permissions in the console |
| 404 | 400401 | Resource not found (wrong ID, ticker or chart name) | Call the list endpoint for valid IDs first |
| 404 | 400402 | Path not found | Check the /openapi/v1 or /openapi/v3 prefix |
| 404 | 400404 | v3: no real-time snapshot right now (the instrument still exists) | Common outside trading hours; use candles for history |
| 409 | 400901 | v3: ambiguous ref, candidates returned | Use a full_symbol such as BTC-USDT-PERP.BINANCE, or follow candidates[].href |
| 429 | 402901 | Rate limit or monthly quota exceeded | v1: wait details.retry_after; v3: exponential backoff |
| 500 | 500001 | Internal error | Do not retry; email us the request URL and time |
| 503 / 504 | 500301 | Service or upstream unavailable | Back off 1s → 2s → 4s, max 3 retries |
Pagination and queries
v1 endpoints use one of two query modes; each endpoint's doc says which. Some list endpoints (projects, crypto stocks, BTC treasuries, currencies) take no parameters and return the full list as a plain array.
Mode 1: page numbers
page starts at 1 and page_size defaults to 20. The maximum depends on the endpoint: 50 for /news/search, 100 for /news/pick. data is {list, page, page_size, total}.
GET /news?language=zh&page=2&page_size=50
→ { "code": 0, "message": "success", "data": { "list": [...], "page": 2, "page_size": 50, "total": 1842 } }Mode 2: time window
start_time and end_time are UTC millisecond timestamps combined with limit; results are ascending by time. To continue, use the last row's timestamp + 1 as the next start_time. Used by currency, index and crypto-stock klines (interval=1d is required).
GET /currencies/1673723677362319866/klines?interval=1d&start_time=1790899200000&end_time=1793577600000&limit=100
→ { "code": 0, "message": "success", "data": [ { "timestamp": 1790899200000, "open": ..., "close": ... }, ... ] }Date-range endpoints are different: ETF history, ETF summary history, BTC purchase history and macro event history take start_date / end_date as yyyy-MM-dd and return newest first. Analysis-chart data is also newest first.
For v1, the following window limits apply to every key: klines cover the last 3 months, ETF history the last month, news time filters the last 7 days. Where a limit has a maximum, most endpoints silently clamp larger values instead of returning an error.
v3 market data
v3 paginates in three ways: the instrument catalog returns pagination.next_cursor — pass it back as ?cursor=; candles and corporate actions return a date cursor — pass it as from (order=asc) or to (order=desc); daily metrics, financials and similar endpoints have no cursor, only data.has_more, so slice your own from / to windows.
Data dictionary and conventions
| Convention | Rule | Example |
|---|---|---|
| Field names | snake_case everywhere | "total_net_assets" |
| Amounts | v1 amounts are usually USD; v3 uses the currency in meta or field definitions. Usually numbers, but some endpoints return strings (market overview, macro rates, v3 prices, fundraising amounts such as "15,000,000 USD") | "total_net_inflow": -55066297.0 |
| Ratios | Varies by endpoint: index and currency snapshots use decimal fractions; market overview and every v3 *_pct field use percentages. Check each field table | "change_pct_24h": -0.0016 |
| Dates | v1: yyyy-MM-dd | "date": "2024-04-12" |
| Timestamps | v1: UTC milliseconds (a few fields are strings, e.g. analysis-chart timestamp, currency ath_date); v3: usually RFC3339; quote next_funding_time is milliseconds | "release_time": 1677151845000 |
| Missing values | May be null, an empty string (macro releases not yet published) or an omitted key (index snapshot, market overview, chart rows, v3) — guard every access | "actual": "" |
| Identifiers | currency_id from /currencies; symbol + country_code or ticker for ETFs; v3 uses a full_symbol ref such as MSTR.US or BTC-USDT-PERP.BINANCE | "currency_id": "1673723677362319866" |
Every endpoint has its own page under All endpoints with parameters and response fields; the machine-readable OpenAPI spec is in the legacy GitBook docs.