> For the complete documentation index, see [llms.txt](https://sodex.com/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sodex.com/documentation/for-developers/developers/data-api/common-definitions.md).

# Common Definitions

The conventions on this page apply across the Market Data API unless an endpoint states otherwise.

## Resource identifiers

| Name           | Description                                                                          |
| -------------- | ------------------------------------------------------------------------------------ |
| `currency_id`  | String identifier for a digital asset. Retrieve valid values from `GET /currencies`. |
| `ticker`       | Symbol used by ETF and BTC treasury resources.                                       |
| `index_ticker` | Symbol identifying a SoSoValue index.                                                |
| `stock_ticker` | Symbol identifying a crypto-related public company.                                  |
| `project_id`   | Identifier for a fundraising project.                                                |
| `chart_name`   | Identifier used to request an analysis chart.                                        |

Resolve identifiers from the relevant list endpoint instead of hardcoding values that may change.

## Pagination

List endpoints marked as paginated use these common parameters:

| Parameter   | Type    | Required | Default | Description                                                                     |
| ----------- | ------- | -------- | ------- | ------------------------------------------------------------------------------- |
| `page`      | integer | No       | `1`     | Page number, starting from 1                                                    |
| `page_size` | integer | No       | `20`    | Items per page; the general maximum is 100 unless the endpoint states otherwise |

A paginated result is returned in the response `data` object:

```json
{
  "list": [],
  "page": 1,
  "page_size": 20,
  "total": 0
}
```

## Time windows

Time-series endpoints use these common parameters:

| Parameter    | Type    | Required | Description                                                       |
| ------------ | ------- | -------- | ----------------------------------------------------------------- |
| `start_time` | long    | No       | Start of the requested window as a Unix timestamp in milliseconds |
| `end_time`   | long    | No       | End of the requested window as a Unix timestamp in milliseconds   |
| `limit`      | integer | No       | Maximum number of records; endpoint-specific limits apply         |

Results are returned in ascending chronological order. When a window contains more records than `limit`, continue from the last returned timestamp plus one millisecond. When no time window is supplied, time-series endpoints return the most recent records up to `limit`.

## Data conventions

| Convention      | Definition                                              |
| --------------- | ------------------------------------------------------- |
| Timestamps      | UTC Unix timestamps in milliseconds                     |
| Monetary values | Denominated in USD unless the endpoint states otherwise |
| Field names     | `snake_case`                                            |
| Kline interval  | Currently `1d`                                          |

Endpoint-specific availability windows and maximum values are documented with each operation.

## Response envelope

Successful responses use a common envelope:

```json
{
  "code": 0,
  "message": "success",
  "data": {}
}
```

Depending on the operation, `data` can contain a single object, a list, a paginated object, or `null`.

## Resolve currency identifiers

```bash
curl -sS https://openapi.sosovalue.com/openapi/v1/currencies \
  -H "x-soso-api-key: $SOSO_API_KEY" \
  -H 'Accept: application/json'
```

Set `SOSO_API_KEY` to your approved key and use identifiers returned by this list in subsequent queries.