> ## 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"
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.