> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ticktock.bet/llms.txt
> Use this file to discover all available pages before exploring further.

# Market Descriptions

> Static catalog of every CS2 market type — code, name, category, tier, translations

## What it returns

The full catalog of market types the engine can publish. Each entry has:

* `type` — internal string id (`"headshot_opening"`, `"awp_kill"`, …)
* `code` — stable integer code, used as `id` in the AMQP/XML feed and on every `<odds_change>` market element
* `name` — human-readable English label (JSON). In the **XML** form this attribute instead carries the parametrized **template** with `{placeholder}` tokens (see below) — substitute specifier values into it at render time.
* `description` — short English prose description
* `template` / `template_ru` — the parametrized name with `{placeholder}` tokens (**JSON only**; the locale-path XML puts the template directly in `name` and has no `template_ru`)
* `name_ru` — Russian display name / template (**JSON only**; the locale-path XML is single-locale — request the `ru` path to get Russian in `name`)
* `category` — display grouping (Opening Kills, Multi-Kills, Bomb, Economy, …)
* `tier` — pricing/risk tier (`featured`, `contextual`, …)
* `outcomes` — the market's declared outcomes, each `{ id, name, name_ru }`. A live `<odds_change>` outcome is unnamed (`<outcome id="1">`); match it against this list to get its display name. Every CS2 market is a single-outcome proposition (`id="1"`, "Yes"), but the form supports **multiple outcomes** — a market may declare several, each with a stable `id` and a per-locale `name` template (e.g. a football `1X2` declares `{home_team}` / `Draw` / `{away_team}`). Outcome ids are stable for the market's life (BB 3.5/3.7).
* `specifiers` — the specifier keys the market declares, each `{ name, type }` where `type` is `integer` | `variable_text` | `decimal`. This is the market instance's **stable identity** (BB 3.5) — the live `specifiers` string matches it exactly and never mutates over the instance's life. Render `{placeholder}` tokens in `name` only for keys listed here. CS2 markets carry `map` / `round`, plus `player` or `competitor` for player/team-scoped markets. (The in-game `map_name` is **not** a specifier — it is nullable and would mutate the identity; read it from the fixture/summary per-map data.)

**Codes are immutable.** Pull this once at integration time, store the mapping locally, and look up by `code` for every incoming market. No need to re-poll.

The UOF-compatible XML form (`GET descriptions/:locale/markets`, or `Accept: application/xml`) nests these as `<market_descriptions><market><outcomes>…</outcomes><specifiers>…</specifiers></market>`. It is **single-locale**: the response carries each display string once, in the path's `:locale`, with **no `name_ru` / `template_ru` siblings** — request `descriptions/en/markets` for English and `descriptions/ru/markets` for Russian. The `<market name>` and `<outcome name>` attributes are **display templates** — substitute `{placeholder}` tokens (e.g. `{round}`, `{player}` for player-scoped markets, `{competitor}` for team-scoped economy markets) from the live market's `specifiers`. Outcome names with no placeholders (CS2 "Yes") render as-is. (`description` has no Russian source today, so it stays English even under `ru`.)

```xml theme={null}
<market_descriptions>
  <market id="1001" name="First kill is a headshot — Round {round}">
    <outcomes>
      <outcome id="1" name="Yes"/>
    </outcomes>
    <specifiers>
      <specifier name="map" type="integer"/>
      <specifier name="round" type="integer"/>
    </specifiers>
  </market>
</market_descriptions>
```

## Required scope

* **Minimum:** `cs2:markets:read`

## Localization

`?lang=en` (default) or `?lang=ru`. Both locales return the same `code` and `category` — only the display strings differ. The English `name` is always present; `name_ru` is included as a separate field when a Russian translation exists.

## Example

```bash theme={null}
curl -H "X-API-Key: $TT_KEY" \
  "https://ticktock.bet/cs2/v1/markets/descriptions"
```

```json theme={null}
{
  "data": [
    {
      "type": "headshot_opening",
      "code": "1001",
      "name": "Headshot Opening Kill",
      "description": "The round's first kill is a headshot.",
      "category": "Opening Kills",
      "tier": "featured",
      "name_ru": "Хедшот на открытии",
      "outcomes": [ { "id": "1", "name": "Yes", "name_ru": "Да" } ],
      "specifiers": [
        { "name": "map", "type": "integer" },
        { "name": "round", "type": "integer" }
      ]
    },
    …
  ],
  "meta": { "count": 42, "lang": "en" }
}
```

## Where this fits

The AMQP feed also inlines `textEN` / `textRU` on every market, so light integrations can read those directly. **UOF-style clients should drive off this catalog instead:** the live `<odds_change>` market carries only `id` + `specifiers` and an unnamed `<outcome id="1">`, so you name the outcome from the catalog's `outcomes` list and render `name` placeholders only for the keys in `specifiers`. Such clients ignore `textEN` / `textRU` entirely and depend on the structured `outcomes` / `specifiers`.

Use it when you want to:

* Name live outcomes and render specifier placeholders without parsing `textEN`.
* Build a custom market browser UI grouped by `category`.
* Pre-build a name lookup keyed by `code`.
* Filter what to expose to your end-users by `tier`.


## OpenAPI

````yaml openapi/cs2-api.json GET /cs2/v1/markets/descriptions
openapi: 3.1.0
info:
  title: TickTock B2B API
  description: >-
    Unified CS2 API (``/cs2/v1/*``) plus sport-agnostic ``/v1/*`` meta
    endpoints. Tenant-authenticated via ``X-API-Key`` or ``x-access-token``
    header (REST), or ``api_key`` query parameter (WebSocket). Field visibility
    is gated by per-key scopes — see ``docs/CS2_API_REFERENCE.md`` for the
    catalog and migration.
  version: 1.0.0
servers:
  - url: https://ticktock.bet
    description: Production (same-origin proxy)
  - url: https://feed.ticktock.bet
    description: Production (B2B subdomain)
security: []
paths:
  /cs2/v1/markets/descriptions:
    get:
      tags:
        - CS2
      summary: Catalog of CS2 market types with templates and translations
      description: >-
        Static catalog of every market type the engine can publish. Each entry
        carries the stable integer ``code`` (used as ``id`` in the AMQP/XML feed
        and in odds payloads), a human-readable ``name``/``description`` in
        English, the ``category`` and ``tier``, the Russian display ``name_ru``,
        and parametrized ``template``/``template_ru`` strings. Clients
        integrating via templates render market text by substituting values from
        the messaging-feed ``specifiers`` attribute (``map``, ``round``,
        ``player``, ``competitor``) into the corresponding
        ``{map}``/``{round}``/``{player}``/``{competitor}`` placeholders.
        Team-scoped markets (eco_upset, eco_frags, force_buy_win) emit
        ``competitor=<team>``; player-scoped markets emit ``player=<name>``.
        ``map=<N>`` carries the integer map number in the BO series. The
        specifier set is the market instance's stable identity (BB 3.5) and
        never mutates; the in-game ``map_name`` is deliberately not a specifier
        (nullable) — read it from the fixture/summary per-map data. Use this
        once at integration time to build a market-name lookup; no need to
        re-poll — codes are immutable.


        Supports both JSON (default) and XML via ``Accept: application/xml`` or
        the ``.xml`` sibling URL.
      operationId: list_market_descriptions_cs2_v1_markets_descriptions_get
      parameters:
        - name: lang
          in: query
          required: false
          schema:
            type: string
            description: 'Locale: ``en`` (default) or ``ru``.'
            default: en
            title: Lang
          description: 'Locale: ``en`` (default) or ``ru``.'
        - name: accept
          in: header
          required: false
          schema:
            type: string
            default: application/json
            title: Accept
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                title: >-
                  Response List Market Descriptions Cs2 V1 Markets Descriptions
                  Get
              example:
                data:
                  - type: headshot_opening
                    code: '1001'
                    name: Headshot Opening Kill
                    description: The round's first kill is a headshot.
                    category: Opening Kills
                    tier: featured
                    name_ru: Хедшот на открытии
                meta:
                  count: 42
                  lang: en
            application/xml: {}
        '401':
          description: >-
            Missing API key. Pass either `X-API-Key: <your-key>` or
            `$x$access-token: <your-key>` on REST calls (or `?api_key=` on
            WebSocket handshakes).
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    description: Human-readable error message.
                required:
                  - detail
              example:
                detail: Missing X-API-Key or $x$access-token header
        '403':
          description: >-
            API key authenticated but lacks the scope required for this
            endpoint, or the path's sport is not in the key's `sport_allowlist`.
            Use `GET /v1/whoami` to inspect the granted scope set.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    description: Human-readable error message.
                required:
                  - detail
              example:
                detail: >-
                  Required scope 'cs2:matches:detail' is not granted to this API
                  key. Contact your account manager to extend the key's scopes.
        '422':
          description: >-
            Validation error — a query/path parameter failed validation. The
            body lists the offending fields.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
              example:
                detail:
                  - type: enum
                    loc:
                      - query
                      - time_filter
                    msg: 'Input should be one of: 3m, 6m, 1y, all'
                    input: 2w
        '429':
          description: >-
            Tenant rate limit exceeded. Default is 600 req/min per tenant;
            configurable per contract. WebSocket connections are not
            rate-limited at the request layer.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    description: Human-readable error message.
                required:
                  - detail
              example:
                detail: Rate limit exceeded (600 req/min)
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
                example: 30
      security:
        - XAPIKeyHeader: []
        - XAccessTokenHeader: []
        - UOFAccessTokenHeader: []
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    XAPIKeyHeader:
      type: apiKey
      description: Tenant API key issued during onboarding
      in: header
      name: X-API-Key
    XAccessTokenHeader:
      type: apiKey
      description: UOF-standard alias for the tenant API key
      in: header
      name: x-access-token
    UOFAccessTokenHeader:
      type: apiKey
      description: Deprecated alias for x-access-token (backward compatibility)
      in: header
      name: $x$access-token

````