# Sports markets

Sports markets on HermesTrade are built around scheduled game fixtures. This guide explains how to find sports markets, interpret game data, manage timing risk, and place orders safely before match start.

{% hint style="warning" %}
**Auto-cancellation at game start:** All outstanding limit orders on a sports market are automatically canceled when the game starts. If the game kicks off earlier than its scheduled time — which is common in some sports — your orders may be canceled with no warning. Read the [Critical timing risk](#critical-timing-risk) section before placing any order on a sports market.
{% endhint %}

***

## What makes sports markets different

Standard markets on HermesTrade resolve based on a reported real-world outcome. Sports markets add a structured data layer on top:

* Each market is linked to a `PredictGameFixture` — a structured record of the game with home team, away team, venue, scheduled start, and live score fields.
* The market's order book **closes automatically when the game starts** (`gameStatus` transitions from `pre-game` to `live`).
* Resolution is driven by the final score reported through the game data feed, following the same adjudication process as standard markets (see Core Concepts: Market resolution).
* Live score data is available via `GET /games/{id}/scores` during the game.

***

## Finding sports markets

### 1. List available sport types

```
GET /config/sport-types
```

Returns the full list of sports supported by HermesTrade. Use the `sport_type` value from this response as a filter in subsequent calls.

### 2. Browse games

```
GET /games
```

Query parameters:

| Parameter            | Description                                         |
| -------------------- | --------------------------------------------------- |
| `sport_type`         | Filter by sport (values from `/config/sport-types`) |
| `status`             | `pre-game`, `live`, or `finished`                   |
| `date`               | Filter by scheduled game date                       |
| `keyword`            | Text search across team names and other fields      |
| `page` / `page_size` | Pagination                                          |

Each result is a `PredictGameFixture`:

| Field                     | Description                                     |
| ------------------------- | ----------------------------------------------- |
| `id`                      | Game ID                                         |
| `sportType`               | Sport identifier                                |
| `homeTeam` / `awayTeam`   | Team objects with name and metadata             |
| `scheduledAt`             | Scheduled kickoff (ISO 8601 datetime)           |
| `gameStatus`              | `pre-game`, `live`, or `finished`               |
| `homeScore` / `awayScore` | Current scores (non-zero once the game is live) |
| `venue`                   | Venue name                                      |
| `primaryEventId`          | Links to the HermesTrade event and its markets  |

### 3. Navigate to the market

Use `primaryEventId` (or `linkedEventIds`) to fetch the event and its associated markets via the Gamma API:

```
GET /events/{id}
```

Markets within the event each have `clobTokenIds` — the YES and NO outcome token IDs you use when placing CLOB orders.

***

## Critical timing risk

{% hint style="warning" %}
**This section describes a safety-critical behavior. Read it fully before trading sports markets.**

**Outstanding limit orders are canceled the moment `gameStatus` changes from `pre-game` to `live`.** This happens automatically, server-side, and cannot be reversed. You will not receive advance notice of the cancellation.

**Early starts are common.** Many sports (football, basketball, etc.) regularly start a few minutes before the official scheduled time. Do not assume your GTD expiration will protect you if you set it at the exact `scheduledAt` time — the game may go live before that timestamp.
{% endhint %}

### What happens when a game starts early

1. Your resting GTC or GTD order is on the book.
2. The game starts (e.g., 3 minutes before `scheduledAt`).
3. The platform detects the `gameStatus` transition and cancels all open orders on that market.
4. Your capital is returned to your available balance. No fill occurs.

This behavior protects traders from holding positions in an actively-playing game whose final outcome is no longer speculative. However, if you were counting on your order to execute, you may miss the trade entirely.

### Recommended practices

**For manual traders:**

* Cancel all open orders on sports markets at least **15 minutes before the scheduled start time**.
* Do not leave resting GTC orders overnight on markets with morning start times.

**For automated strategies:**

* Poll `GET /games/{id}` at least every 60 seconds in the pre-game window.
* When `gameStatus` changes from `pre-game` to anything else, immediately call `DELETE /cancel-market-orders` for that market.
* Alternatively, use `GTD` orders with an `expiration` set to **15 minutes before `scheduledAt`** as a safety net. Example: if `scheduledAt` is `1700000000`, set `expiration` to `1699999100`.

***

## Game score sync

Once a game is live, use the scores endpoint to understand data freshness:

```
GET /games/{id}/scores
```

Response is a `GameScoresResponse`:

| Field           | Description                                     |
| --------------- | ----------------------------------------------- |
| `fixtureId`     | Game ID                                         |
| `consistency`   | Data quality indicator for the score feed       |
| `lastFetchedAt` | When the platform last requested score data     |
| `lastUpdatedAt` | When the score data itself last changed         |
| `latestStatus`  | Current game status reported by the data source |

Use `lastFetchedAt` and `lastUpdatedAt` to gauge data staleness. If `lastUpdatedAt` is significantly older than `lastFetchedAt`, the score feed may be delayed. Factor this into any near-final-score trading decisions.

***

## Sports market resolution

Sports markets resolve based on the final score reported by the game data feed. The resolution process follows the same adjudication flow as standard markets:

1. The game finishes (`gameStatus` = `finished`).
2. The platform proposes a resolution outcome based on the final score.
3. The adjudication liveness period begins (visible in the market's `adjudication` object).
4. If unchallenged within the liveness window, the market settles at the proposed outcome.
5. Winning YES or NO shares redeem at $1.00 each.

For full details on disputes and adjudication phases, see Core Concepts: Market resolution.

***

## Worked example: placing a GTD order before kickoff

This example walks through finding an upcoming football match, reading its market, and placing a limit order with a GTD expiration that protects against the auto-cancel risk.

{% stepper %}
{% step %}

### Find the game

```
GET /games?sport_type=football&status=pre-game&date=2024-11-15
```

Locate the fixture you want. Note the `id` and `scheduledAt` fields:

```
id:           "game_abc123"
scheduledAt:  "2024-11-15T15:00:00Z"   →  Unix: 1731679200
gameStatus:   "pre-game"
homeTeam:     "Team A"
awayTeam:     "Team B"
```

{% endstep %}

{% step %}

### Find the market

```
GET /events/{primaryEventId}
```

Identify the YES/NO market for the outcome you want (e.g., "Team A wins"). Note the `clobTokenIds`:

```
clobTokenIds: ["112233...YES_tokenId", "445566...NO_tokenId"]
```

{% endstep %}

{% step %}

### Read the order book

```
GET /book?token_id=112233...YES_tokenId
```

Check the current best bid, best ask, and spread. Decide on your limit price.
{% endstep %}

{% step %}

### Calculate a safe GTD expiration

Set your expiration to 15 minutes before `scheduledAt`:

```
expiration = 1731679200 - (15 × 60) = 1731678300
```

If the game starts early, the auto-cancel will fire before your GTD expiry. If the game starts on time, your GTD expiry fires first and removes your order cleanly. Either way, you will not be holding a resting order when the game goes live.
{% endstep %}

{% step %}

### Place the GTD order

Construct, sign (EIP-712), and POST the order:

```
POST /order
{
  "tokenID":    "112233...YES_tokenId",
  "side":       "BUY",
  "orderType":  "GTD",
  "expiration": "1731678300",
  ...
}
```

See [Authentication](/reference/authentication.md) for the full signing and submission flow.
{% endstep %}

{% step %}

### Monitor until expiry or fill

Poll `GET /order/{orderID}` to track status. Once `gameStatus` changes to `live` (or your GTD fires), verify the order status is `CANCELED` or `MATCHED` — not `LIVE`.
{% endstep %}
{% endstepper %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.hermestrade.xyz/guides/sports-markets.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.