# Market symbols Source: https://docs.stxapp.io/concepts/market-symbols/ Every market carries a `symbol`: a short, readable name that says which event it belongs to and which outcome it settles on. An **event** is one scheduled game, the same thing `event_id` and `event_start` refer to. ``` STXMLB-26AUG271305COLWSH-GAMEWSH ``` That is the Washington Nationals to beat the Colorado Rockies, in the MLB game starting 27 August 2026 at 13:05. The `market_id` is a UUID and tells you nothing on its own. `STX` identifies the exchange, and every segment after it is derived from the event (the competition, the start time, the two teams, and the outcome the contract settles on), all of which you already know if you track the game at all. So the symbol is predictable rather than assigned. Given a game you already follow, you can construct the symbol you expect and match it against ours, instead of calling the API to discover which `market_id` corresponds to which game. ## Anatomy A symbol has two halves, joined by a hyphen. ``` STXMLB-26AUG271305COLWSH - GAMEWSH └────── event symbol ────┘ └ market ┘ ``` The **event symbol** identifies the event, and every market on the same game shares it. The **market segment** identifies what this particular market is asking, which part of the game it settles over, and which side of it you are buying. ``` STXMLB-26SEP032210STLLAD-TOTAL8.5 full game STXMLB-26SEP032210STLLAD-R1TOTAL0.5 first inning, same game ``` To collect every market on a game, `event_id` is the field to group on: it is a UUID and needs no string handling. See [Which identifier to use](#which-identifier-to-use). Written out in full: ``` {PREFIX}{COMPETITION}-{YYMONDDHHMM}{AWAY}{HOME}-{SCOPE}{TYPE}{SELECTION} ``` | Segment | Example | What it is | | --- | --- | --- | | Prefix | `STX` | Identifies the exchange. The only segment not derived from the event. | | Competition | `MLB` | The league or competition code. | | Date and time | `26AUG271305` | `YYMONDDHHMM`, from the event's start time. | | Away | `COL` | The away team, first. | | Home | `WSH` | The home team, second. | | Scope | `R1` | The part of the game the market settles over. **Absent for a full-game market**, which is most of them. | | Type | `GAME` | What the market asks. | | Selection | `WSH` | The outcome the contract pays on. | Away always precedes home, the usual way a matchup is written. ### The date is in US Eastern `26AUG271305` is 27 August 2026, 13:05 **US Eastern**, the exchange's clock. Not UTC, not the venue's local time, and not whatever your pricing feed publishes: a LaLiga match in Spain and an MLB game in Los Angeles are both stamped Eastern. The `event_start` field on the market is the UTC timestamp for the same moment, so convert before comparing the two, or a game near midnight Eastern will look like the wrong day. ### Scope Markets covering part of a game carry a scope code at the **front of the market segment**, before the type. A symbol with no scope code covers the full game, which is most of them. ``` STXMLB-26AUG281840LADDET-R1TOTAL0.5 MLB LAD @ DET OU 0.5, 1st inning STXEPL-26AUG281500MNCCRY-R1TOTAL2.5 EPL MNC @ CRY OU 2.5, 1st half STXMLB-26AUG281840LADDET-TOTAL8.5 MLB LAD @ DET OU 8.5, full game ``` There are two codes, `F` for **first** and `R` for **range**. | Code | Window | Example | | --- | --- | --- | | `F{n}` | Periods 1 through *n*. | `F5`, the first five innings | | `R{a}T{b}` | Periods *a* through *b*, inclusive. `T` reads as *to*. | `R1T3`, innings one to three | | `R{a}` | Period *a* alone; the shorthand for `R{a}T{a}`. | `R1`, the first inning | Both count periods from 1, so `F{n}` and `R1T{n}` are the same window but the shorthand is preferred over `R{a}T{a}`. **A scope code is not a fixed duration.** The two symbols above carry the same `R1`, but it means the first inning in baseball and the first half in soccer: the first scoring period of whatever sport the competition belongs to. Read it against the competition, never on its own. The `rules` field carries the scope as a suffix (`over_under_r1` for both markets above), so if you need to know a market's scope in code, read `rules` rather than parsing it back out of the symbol. #### Telling a scope from a type The scope code is not padded to a fixed width. **A type code never begins with `F` or `R` followed by a digit**, so a market segment is scoped if and only if it opens with that pattern. The scope runs to the end of the pattern (`F{n}`, `R{a}` or `R{a}T{b}`), and the type begins immediately after. ``` TOTAL8.5 no scope, type TOTAL, line 8.5 R1TOTAL0.5 scope R1, type TOTAL, line 0.5 R1T3TOTAL0.5 scope R1T3, type TOTAL, line 0.5 F5SPREADKCPLUS9.5 scope F5, type SPREAD, selection KCPLUS9.5 ``` The `rules` field gives the scope directly. ## Market types The type segment tells you what is being asked. | Type | Market | Selection format | | --- | --- | --- | | `GAME` | Winner | The winning team, `WSH` | | `GAMEREG` | Winner in regulation | The winning team | | `GAME2W` | Winner, two-way | The winning team | | `GAME3W` | Winner, three-way | The winning team | | `DRAW` | Draw | `{AWAY}{HOME}` | | `SPREAD` | Handicap | `{HOME}PLUS{line}` or `{HOME}MINUS{line}` | | `TOTAL` | Over/under | The line, `227.5` | | `MATCH` | Tennis match winner | The player | | `CHAMP` | Championship | The team | | `WS` | World Series | The team | | `LEAGUE` | League winner | The team | | `CONF` | Conference winner | The team | | `DIV` | Division winner | The team | New market types arrive from time to time and take a code derived from the rule that created them, so treat this as the set in use today rather than a closed list. Match the types you recognize and fall through gracefully on one you do not. No type code begins with `F` or `R` followed by a digit; see [Telling a scope from a type](#telling-a-scope-from-a-type). A spread on the home team at −7.5 reads: ``` STXNBA-26APR051900CHAMIN-SPREADMINMINUS7.5 ``` ### Player props Player markets use the stat code as the type, then the player and the line: ``` {STAT}{TEAM}{INITIAL}{LASTNAME}{JERSEY}-{LINE} ``` A points line in a Memphis at Milwaukee game: ``` STXNBA-26APR051500MEMMIL-PTSMILMTURNER3-12.5 ``` Two things to know before you parse one: - **`{TEAM}` is the home team of the game, not the player's team.** Take the player's team from `participants` rather than from the symbol. - **The line is separated by a hyphen**, so a player-prop symbol has four hyphen-separated fields where other markets have three. Match the segments you need rather than splitting on every hyphen. Stat codes vary by sport: `PTS`, `REB`, `AST` and `3PT` in basketball, `PASSYDS`, `RUSHTD` and `SACK` in football, `HR`, `RBI` and `SB` in baseball. ### Futures Season markets are not tied to a single game, so the event symbol carries the competition and date without a participants segment: ``` {PREFIX}{COMPETITION}-{YYMONDDHHMM} ``` The market segment then names the team, as in a `CHAMP` or `DIV` market. ### Combination markets Combos are built from their legs rather than from a single game: ``` STXCOMBO-{EVENT_HASH}-{MARKET_HASH} ``` Each hash is derived from the symbols of the legs it combines. The same legs always produce the same symbol, in any order, so an identical combo is recognizable as one wherever you meet it. ### Custom markets Some markets do not belong to a scheduled game: a team making the playoffs, a tournament winner. They keep the same three-segment shape, but the middle segment is a label written when the market is created rather than a start time and two teams: ``` STXMLB-PLAYOFFSTOR-TOR Toronto to make the playoffs STXPGA-TOURCHAMPIONSHIP-LA Ludvig Aberg to win the Tour Championship ``` So the prefix and competition still mean what they mean, and the last segment is still the selection. Only the middle segment is free text, which means you cannot parse a date or teams out of it. Check whether it matches `{YYMONDDHHMM}` before assuming it is a scheduled game. Use `rules` and `specifier` to see what a custom market settles on, exactly as you would for a generated one. ## Which identifier to use Every market carries several identifiers, and they do different jobs. | Field | Use it for | | --- | --- | | `market_id` | **The key in your own store**, and the value you send back to us. A UUID, fixed for the life of the market. Every order, cancel and channel topic takes it. | | `event_id` | **Grouping a book by game.** A UUID every market on the game shares, and the safest thing to group on, since it needs no string handling. | | `rules` | What kind of market this is, in machine-readable form: `home_winner`, `spread`, `player_stat_line`. Scoped markets append the scope, as in `over_under_r1`. | | `specifier` | The strike: the line, the handicap, the player. | | `participants` | Team and player identity, with abbreviation, name and role given separately. | | `symbol` | Mapping to markets you already track, matching against another venue, logs, dashboards, anything a person reads. | For mapping, the pair worth leaning on is **`rules` and `specifier`**. Between them they say exactly what a market asks and at what strike, in fields meant for code, while `event_id` and `participants` supply the event and the teams. That combination is more precise than parsing a symbol, and it does not require a team-code dictionary. Symbols are rebuilt from the event they belong to, so read the current value from the API rather than treating a stored one as a key. Keep `market_id` alongside whatever you match on and you can act on a market immediately, without resolving it again. ## Finding a market `GET /api/v1/markets` returns `symbol` on every market, alongside `market_id`, `event_id` and the participants. Filter by competition and status to narrow the set: ``` GET /api/v1/markets?competitions=MLB&status=open ``` Then match on the symbol, or read `event_id` off any market and collect every market that shares it. `event_id` is the better of the two for grouping a game's book: it is a UUID, so it needs no string handling and cannot be thrown off by a change to the symbol format. Building the event symbol and matching on its prefix (matching `STXMLB-26SEP032210STLLAD-` to collect that game) does work, and picks up scoped markets along with full-game ones. The `markets` WebSocket channel carries the symbol too, so a live client can map new markets as they appear without a REST call. The order book channel accepts a symbol in place of the id, which is the one place a symbol addresses a market directly: ```json ["1", "1", "market:STXMLB-26AUG271305COLWSH-GAMEWSH", "phx_join", {}] ``` See [WebSocket channels](/websockets/) for the frame format.