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

# Market Infrastructure

> Exchange metadata, real-time market status, trading hours, and market holidays for global stock markets.

The market infrastructure endpoints expose exchange-level data: which markets are available, whether they are currently open, their regular trading hours, and scheduled holidays. Use these to gate trading logic, display status indicators, or plan around market closures.

## Endpoints

| Endpoint                       | Summary               | Key use case                                        |
| ------------------------------ | --------------------- | --------------------------------------------------- |
| `GET /stocks/markets`          | Exchange metadata     | Timezone, currency, working hours for each exchange |
| `GET /stocks/markets/status`   | Current market status | Is this exchange open right now?                    |
| `GET /stocks/markets/hours`    | Trading session hours | Regular open/close times, half-days                 |
| `GET /stocks/markets/holidays` | Market holidays       | Planned closures within a date range                |
| `GET /stocks/countries`        | Available countries   | Which markets are covered by the API                |

## Exchanges

**Endpoint:** `GET /stocks/markets`

Returns metadata for all exchanges available in the API. Each exchange is identified by its MIC code (Market Identifier Code, ISO 10383) — the global standard for identifying trading venues. Pass one or more comma-separated MIC codes via the `mic` parameter to filter results.

**Key fields**

| Field                     | Type    | What it means                                             |
| ------------------------- | ------- | --------------------------------------------------------- |
| `mic`                     | string  | ISO 10383 Market Identifier Code (e.g. `XNAS` for NASDAQ) |
| `exchange`                | string  | Full legal name of the exchange                           |
| `timezone`                | string  | IANA timezone identifier (e.g. `America/New_York`)        |
| `currency_code`           | string  | ISO 4217 currency for this market                         |
| `open_time`               | string  | Regular session open time in local market time            |
| `close_time`              | string  | Regular session close time in local market time           |
| `working_days`            | array   | Days of the week the market operates                      |
| `dst`                     | boolean | Whether Daylight Saving Time is currently in effect       |
| `previous_dst_transition` | string  | Date of the most recent DST change                        |
| `next_dst_transition`     | string  | Date of the upcoming DST change                           |

**When to use**

* Building a market selector UI that shows exchange names, timezones, and currencies
* Converting market open/close times to the user's local timezone using the `timezone` field
* Determining which currency a stock is quoted in

**Example**

```bash theme={null}
# Get metadata for NYSE and NASDAQ
curl "https://api.tradewatch.io/stocks/markets?mic=XNYS,XNAS" \
  -H "api-key: YOUR_API_KEY"
```

## Market Status

**Endpoint:** `GET /stocks/markets/status`

Returns the current open/closed status for one or more exchanges. The status accounts for scheduled holidays and half-days but does **not** factor in circuit breakers, trading halts, or unscheduled closures.

**Key fields**

| Field                      | Type    | What it means                                       |
| -------------------------- | ------- | --------------------------------------------------- |
| `mic`                      | string  | Market Identifier Code                              |
| `status`                   | string  | Current status: `open` or `closed`                  |
| `is_business_day`          | boolean | Whether today is a scheduled trading day            |
| `is_early_close`           | boolean | Whether today is a half-day with an early close     |
| `holiday_name`             | string  | Name of the holiday if the market is closed for one |
| `local_time`               | string  | Current local time at the exchange                  |
| `open_time` / `close_time` | string  | Today's session times (adjusted for half-days)      |

**When to use**

* Deciding whether to display a "Market Open" badge in your UI
* Pausing data refresh loops when a market is closed
* Showing a countdown to market open

**Interpretation:** A `status: open` response means the exchange is in a scheduled trading session. It does not guarantee that all individual stocks are actively trading — securities may be halted at the exchange or regulatory level. Circuit breakers and individual trading halts are not reflected in this endpoint.

**Example**

```bash theme={null}
curl "https://api.tradewatch.io/stocks/markets/status?mic=XNAS" \
  -H "api-key: YOUR_API_KEY"
```

## Trading Hours & Holidays

**Endpoints:** `GET /stocks/markets/hours` · `GET /stocks/markets/holidays`

`/hours` returns the regular trading session times for each exchange, including half-day schedules. `/holidays` returns planned market closures within a `start`/`end` date range (YYYY-MM-DD format). Both endpoints accept comma-separated `mic` codes to filter by exchange.

**Key fields — hours**

| Field              | What it means                   |
| ------------------ | ------------------------------- |
| `open_time`        | Normal session start            |
| `close_time`       | Normal session end              |
| `early_close_time` | Close time on half-day sessions |

**Key fields — holidays**

| Field            | What it means                                     |
| ---------------- | ------------------------------------------------- |
| `date`           | Date of the holiday (YYYY-MM-DD)                  |
| `name`           | Name of the holiday                               |
| `is_early_close` | Whether the market closes early rather than fully |

**When to use**

* Rendering a market calendar for users
* Scheduling jobs that should not run during market closures
* Displaying upcoming holidays or early-close days in a trading platform

**Example**

```bash theme={null}
# NYSE holidays for a specific date range
curl "https://api.tradewatch.io/stocks/markets/holidays?mic=XNYS&start=2025-01-01&end=2025-12-31" \
  -H "api-key: YOUR_API_KEY"

# Trading hours for multiple exchanges
curl "https://api.tradewatch.io/stocks/markets/hours?mic=XNYS,XNAS,XLON" \
  -H "api-key: YOUR_API_KEY"
```