Quick start
Get a key, make your first request and read the response in five minutes. You only need an API key — no client-id or secret.
Coding with AI? Give your Agent a prompt to quickly learn the SoSoValue API.
- v1 Base URL
- https://openapi.sosovalue.com/openapi/v1
- v3 Base URL · stocks & funds
- https://openapi.sosovalue.com/openapi/v3
- Auth header
- x-soso-api-key
- Format
- JSON · UTF-8 · v1 timestamps in UTC ms
- 1
Get an API key
Log in to the console with your SoSoValue account and click "Create key" on the API Keys page. Every account gets 10,000 calls a month and 100 calls a minute, shared by all of its keys — free, no card required. You can keep up to 5 active keys. The full key is available only in the creation dialog; save it before closing. If lost, revoke it and create a new one. Existing keys remain valid and do not need replacing. Store your key in an environment variable:
export SOSO_API_KEY=YOUR_API_KEY
- 2
Make the first request
Fetch the last 5 trading days of US spot BTC ETF flows with cURL or the soso command-line tool:
curl "https://openapi.sosovalue.com/openapi/v1/etfs/summary-history?symbol=BTC&country_code=US&limit=5" \ -H "x-soso-api-key: $SOSO_API_KEY"
CLI v0.2.0 (preview): Download and install. Available for macOS, Linux and Windows; source code is not public yet.
- 3
Read the response
Every v1 endpoint shares the same envelope:
code0 means success,datais an array, a paginated object{list, page, page_size, total}, a single object ornull. Amounts default to USD, dates areyyyy-MM-ddand timestamps are UTC milliseconds. v1 response headers carry this minute's rate-limit information. v3 market-data endpoints use their own envelope (code,status,data,meta,pagination,warnings).{ "code": 0, "message": "success", "data": [ { "date": "2024-04-12", "total_net_inflow": -55066297.0000000000000000, "total_value_traded": 4706120449.0000000000000000, "total_net_assets": 56216535367.0000000000000000, "cum_net_inflow": 13534833596.0950000000000000 } ] }HTTP/1.1 200 OK Content-Type: application/json X-RateLimit-Limit-Minute: 100 X-RateLimit-Remaining-Minute: 17 X-RateLimit-Reset-Minute: 1793250060 X-RateLimit-Limit-Month: 10000 X-RateLimit-Remaining-Month: 3580 X-RateLimit-Reset-Month: 1796083200
- 4
Handle errors
On failure the HTTP status and the six-digit
codein the body tell you why;detailscarries the field, constraint and a suggested fix. The most common ones:HTTP code Meaning and what to do 401 400101 Key missing or invalid. Check the key in the console; do not retry. 401 400102 Key expired; apply again or contact us. 403 400301 Key revoked/disabled, or no access to this module or history depth. 429 402901 Rate limit or monthly quota exceeded. v1 returns details.retry_after (seconds) — wait and retry; v3 returns no extra fields — back off exponentially. 400 400001 / 400002 / 400003 Bad format, missing parameter or out of range; details names the field and constraint. 404 400401 / 400402 Resource not found, or wrong path. The full list is on the error codes page. When emailing [email protected], include the request time, endpoint and response body so we can locate the call.
CLI sign-in with soso auth
After installing the CLI, use soso auth to save your API key locally, then run soso status to verify authentication and view rate-limit headers:
soso auth --key $SOSO_API_KEY soso status
The key is stored in ~/.config/soso/config.json with file permissions 600. You can also pass --api-key for a single command or set SOSO_API_KEY. Priority: --api-key > SOSO_API_KEY > the saved configuration. This authenticates CLI requests with your API key; it does not replace signing in to the web console.