> TickerLayer documentation for AI agents and LLMs, the Markdown version of https://tickerlayer.com/docs/market-status
> REST base URL https://api.tickerlayer.com, API key in the `x-api-key` header. WebSocket wss://stream.tickerlayer.com?apiKey=YOUR_API_KEY.
> Any docs page reads as Markdown at its URL plus `.md`. Index: https://tickerlayer.com/llms.txt · Full API reference: https://tickerlayer.com/llms-full.txt

# Market Status

Check whether supported markets are open, closed, in pre-market, in post-market, or observing a holiday. Use market status to build smarter dashboards, polling schedules, alerts, and trading-hours-aware workflows.

- **Authentication:** API key (header)
- **Timestamps:** UTC ISO-8601
- **Calendars:** Indicative v1
- **Plans:** Free and paid

Responses use ISO-8601 UTC timestamps, plus local timezone fields where they help. Calendar data is **indicative**: right for integration timing, not a compliance-grade guarantee.

## Endpoints

| Endpoint | Returns |
| --- | --- |
| [`GET /markets/status`](https://tickerlayer.com/docs/market-status#markets-status-overview) | A broad snapshot for crypto, forex, regional equities, selected indices, ETFs and commodities. |
| [`GET /markets/status?market=US`](https://tickerlayer.com/docs/market-status#markets-status-detail) | One status object for a region or a resolved instrument. |
| [`GET /markets/status/bulk`](https://tickerlayer.com/docs/market-status#markets-bulk) | Several asset and symbol pairs in one round trip. |
| [`GET /markets/holidays`](https://tickerlayer.com/docs/market-status#markets-holidays) | Indicative closures and early closes by market and year. |
| [`GET /markets/sessions`](https://tickerlayer.com/docs/market-status#markets-sessions) | Session windows for one market and date. |

## Market overview (default)

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

With **no** `asset`, `symbol`, or `market`, returns **overview mode**: one JSON document with rolled-up lines and nested per-calendar objects. Adding any of those parameters switches to **detail mode** (see the next section).

### Query parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `asset` | string | Optional. Narrow routing: crypto, forex, stocks, indices, etfs, commodities, cfds. Omit with symbol/market for overview vs detail rules below. |
| `symbol` | string | Optional. Instrument code when routing depends on it (for example indices). For equities, optional; often omitted when using market=US, market=GB, etc. |
| `market` | string | Optional. CRYPTO, FOREX, COMMODITIES, GLOBAL, or a regional code: US, AR, BR, MX, GB, DE, FR, ES, IT, TR, IN, JP, CN, HK, KR, SA, AE, SE, TW, TH. With asset/symbol, selects detail mode. |
| `at` | string | Optional. ISO-8601 instant; defaults to request time. Invalid values return 400. |
| `includeSessions` | boolean | Optional. When true, includes a static session template for that calendar (detail mode). Regional equity calendars, the global calendar and commodities carry one; the continuous crypto and forex calendars have no template, so the field is absent. Default false. |
| `includeHoliday` | boolean | Optional. When true, may include holiday metadata for the local trading date (detail mode). Default true. |

### Request

```bash
curl -sS "https://api.tickerlayer.com/markets/status" \
  -H "x-api-key: YOUR_API_KEY"
```

```javascript
const res = await fetch("https://api.tickerlayer.com/markets/status", {
  headers: { "x-api-key": "YOUR_API_KEY" },
});
const data = await res.json();
```

```python
import requests

res = requests.get(
    "https://api.tickerlayer.com/markets/status",
    headers={"x-api-key": "YOUR_API_KEY"},
)
data = res.json()
```

### Response

```json
{
  "server_time": "2026-05-04T13:44:27.672Z",
  "market": "mixed",
  "early_hours": false,
  "after_hours": false,
  "currencies": {
    "crypto": "open",
    "forex": "open"
  },
  "regions": {
    "us": "open",
    "gb": "open",
    "de": "open",
    "fr": "open",
    "es": "open",
    "tr": "open",
    "in": "closed",
    "jp": "closed"
  },
  "markets": {
    "stocks": {
      "us": {
        "asset": "stocks",
        "market": "US",
        "status": "open",
        "is_open": true,
        "phase": "primary",
        "next_close": "2026-05-04T20:00:00.000Z",
        "timezone": "America/New_York"
      }
    }
  },
  "meta": {
    "calendar_version": "v1-static-2026-2027"
  }
}
```

### Notes

Optional fields such as `symbol`, `next_open`, or nested holiday rows appear only when meaningful. Overview responses include `meta.data_notice` alongside `calendar_version` in live payloads.

## Market detail

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

Pass `asset`, `symbol`, and/or `market` to retrieve a single status object. For regional equities, prefer `market=US`, `market=GB`, `market=DE`, etc. Symbols are optional for many equity queries and are most useful when resolving calendar routing (for example global listings or indices).

### Query parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `asset` | string | Optional. Narrow routing: crypto, forex, stocks, indices, etfs, commodities, cfds. Omit with symbol/market for overview vs detail rules below. |
| `symbol` | string | Optional. Instrument code when routing depends on it (for example indices). For equities, optional; often omitted when using market=US, market=GB, etc. |
| `market` | string | Optional. CRYPTO, FOREX, COMMODITIES, GLOBAL, or a regional code: US, AR, BR, MX, GB, DE, FR, ES, IT, TR, IN, JP, CN, HK, KR, SA, AE, SE, TW, TH. With asset/symbol, selects detail mode. |
| `at` | string | Optional. ISO-8601 instant; defaults to request time. Invalid values return 400. |
| `includeSessions` | boolean | Optional. When true, includes a static session template for that calendar (detail mode). Regional equity calendars, the global calendar and commodities carry one; the continuous crypto and forex calendars have no template, so the field is absent. Default false. |
| `includeHoliday` | boolean | Optional. When true, may include holiday metadata for the local trading date (detail mode). Default true. |

### Request

```bash
curl -sS "https://api.tickerlayer.com/markets/status?market=US" \
  -H "x-api-key: YOUR_API_KEY"
```

```javascript
const params = new URLSearchParams({ market: "US" });
const res = await fetch(`https://api.tickerlayer.com/markets/status?${params}`, {
  headers: { "x-api-key": "YOUR_API_KEY" },
});
const data = await res.json();
```

```python
import requests

res = requests.get(
    "https://api.tickerlayer.com/markets/status",
    params={"market": "US"},
    headers={"x-api-key": "YOUR_API_KEY"},
)
data = res.json()
```

### Response

```json
{
  "asset": "stocks",
  "market": "US",
  "status": "open",
  "is_open": true,
  "phase": "primary",
  "reason": "Primary session",
  "timestamp": "2026-05-04T13:44:27.872Z",
  "timezone": "America/New_York",
  "local_time": "2026-05-04T09:44:27.872-04:00",
  "next_close": "2026-05-04T20:00:00.000Z",
  "meta": {
    "calendar_version": "v1-static-2026-2027"
  }
}
```

### Notes

Commodities use a broad overnight metals/energy reference schedule: Sunday 18:00 through Friday 17:00 in America/New_York, with a 17:00–18:00 daily pause. UTC boundaries follow US daylight saving time. This is not a per-instrument calendar: agricultural contracts, holidays and special closures can differ. Status describes scheduled hours, not feed health. Do not use it alone to stop data consumption; check observation timestamps and your instrument requirements as well. The sessions endpoint returns windows overlapping the requested local calendar date.

Additional detail examples (same route):

- `GET /markets/status?asset=stocks&market=US`
- `GET /markets/status?asset=indices&symbol=UK100`
- `GET /markets/status?asset=etfs&symbol=CASHLIKE`
- `GET /markets/status?asset=crypto&symbol=BTCUSD`
- `GET /markets/status?asset=forex&symbol=EURUSD`

## Bulk market status

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

Evaluate many instruments at once. Each item uses `asset:symbol`, for example `crypto:BTCUSD`, `forex:EURUSD`, `stocks:US:AAPL`, `indices:UK100`, `commodities:XAUUSD`. Ideal for dashboards and watchlists.

### Query parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | string | Yes | Comma-separated asset:symbol pairs, 1-25 per request (see Bulk section). Unresolved items return a row-level error without failing the whole response; more than 25 entries returns a 400. |
| `at` | string | No | Optional. ISO-8601 instant evaluated for every resolved item. |

### Request

```bash
curl -sS "https://api.tickerlayer.com/markets/status/bulk?items=crypto:BTCUSD,forex:EURUSD,stocks:US:AAPL,indices:UK100,commodities:XAUUSD" \
  -H "x-api-key: YOUR_API_KEY"
```

```javascript
const q = new URLSearchParams({
  items: "crypto:BTCUSD,forex:EURUSD,stocks:US:AAPL,indices:UK100,commodities:XAUUSD",
});
const res = await fetch(`https://api.tickerlayer.com/markets/status/bulk?${q}`, {
  headers: { "x-api-key": "YOUR_API_KEY" },
});
const data = await res.json();
```

```python
import requests

res = requests.get(
    "https://api.tickerlayer.com/markets/status/bulk",
    params={
        "items": "crypto:BTCUSD,forex:EURUSD,stocks:US:AAPL,indices:UK100,commodities:XAUUSD",
    },
    headers={"x-api-key": "YOUR_API_KEY"},
)
data = res.json()
```

### Response

```json
{
  "data": [
    {
      "asset": "crypto",
      "market": "CRYPTO",
      "status": "open",
      "is_open": true
    },
    {
      "item": "stocks:INVALID",
      "error": { "code": "UNRESOLVED", "message": "…" }
    }
  ],
  "meta": { "calendar_version": "v1-static-2026-2027" }
}
```

### Notes

Invalid or unknown items return a row with `error`; the overall HTTP status stays `200` when the request is well-formed.

## Holiday calendar

**Endpoint:** `GET /markets/holidays`

Returns seeded holiday and early-close rows for a resolved regional calendar. Useful for UI hints and scheduling. Treat rows as **indicative**; schedules can change.

### Query parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `market` | string | Optional if asset/symbol resolves a calendar (for example market=US). |
| `asset` | string | Optional. Used with symbol to resolve the regional calendar. |
| `symbol` | string | Optional. Used with asset to resolve the calendar. |
| `year` | integer | Optional. Defaults to the current UTC year. |
| `start` | string | Optional. yyyy-mm-dd inclusive lower bound within the year. |
| `end` | string | Optional. yyyy-mm-dd inclusive upper bound within the year. |

### Request

```bash
curl -sS "https://api.tickerlayer.com/markets/holidays?market=US&year=2026" \
  -H "x-api-key: YOUR_API_KEY"
```

```javascript
const params = new URLSearchParams({ market: "US", year: "2026" });
const res = await fetch(`https://api.tickerlayer.com/markets/holidays?${params}`, {
  headers: { "x-api-key": "YOUR_API_KEY" },
});
const data = await res.json();
```

```python
import requests

res = requests.get(
    "https://api.tickerlayer.com/markets/holidays",
    params={"market": "US", "year": "2026"},
    headers={"x-api-key": "YOUR_API_KEY"},
)
data = res.json()
```

### Response

```json
{
  "market": "US",
  "year": 2026,
  "timezone": "America/New_York",
  "holidays": [
    {
      "date": "2026-01-01",
      "name": "New Year's Day",
      "schedule": "closed",
      "is_open": false,
      "observed": true,
      "memo": null
    },
    {
      "date": "2026-11-27",
      "name": "Post-holiday early close",
      "schedule": "early_close",
      "is_open": true,
      "observed": true,
      "memo": "Early close"
    }
  ],
  "meta": {
    "calendar_version": "v1-static-2026-2027",
    "completeness": "full",
    "data_notice": "Holiday calendars are indicative and may change."
  }
}
```

### Notes

`schedule` is `closed` or `early_close`. `meta.completeness` is `full` or `partial` when a regional list is not fully seeded for the requested year. Live responses also include `meta.start` and `meta.end` range strings for the filtered holiday list. Rows on this route always carry `memo`, `null` when there is no note; the holiday object nested in a status response omits it instead, so read it defensively.

## Trading sessions

**Endpoint:** `GET /markets/sessions`

Ordered session windows for a given market and local date. Where modeled, equities may include pre-market, primary, and post-market phases; simpler calendars may return a single primary window, and a market with an intraday break (TH) returns one window per trading block. Each window carries `status`: `open` for the primary block, `available` for extended hours, and `closed` for every window on a weekend or holiday, so the list still describes the shape of a normal day.

### Query parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `market` | string | Optional if asset/symbol resolves a calendar. |
| `asset` | string | Optional. Used with symbol to resolve the calendar. |
| `symbol` | string | Optional. Used with asset to resolve the calendar. |
| `date` | string | Optional. yyyy-mm-dd in that market’s context; defaults to “today” in the market timezone. |

### Request

```bash
curl -sS "https://api.tickerlayer.com/markets/sessions?market=US&date=2026-05-04" \
  -H "x-api-key: YOUR_API_KEY"
```

```javascript
const params = new URLSearchParams({ market: "US", date: "2026-05-04" });
const res = await fetch(`https://api.tickerlayer.com/markets/sessions?${params}`, {
  headers: { "x-api-key": "YOUR_API_KEY" },
});
const data = await res.json();
```

```python
import requests

res = requests.get(
    "https://api.tickerlayer.com/markets/sessions",
    params={"market": "US", "date": "2026-05-04"},
    headers={"x-api-key": "YOUR_API_KEY"},
)
data = res.json()
```

### Response

```json
{
  "market": "US",
  "date": "2026-05-04",
  "timezone": "America/New_York",
  "is_open": true,
  "holiday": null,
  "sessions": [
    {
      "phase": "pre_market",
      "status": "available",
      "start": "2026-05-04T08:00:00.000Z",
      "end": "2026-05-04T13:30:00.000Z"
    },
    {
      "phase": "primary",
      "status": "open",
      "start": "2026-05-04T13:30:00.000Z",
      "end": "2026-05-04T20:00:00.000Z"
    },
    {
      "phase": "post_market",
      "status": "available",
      "start": "2026-05-04T20:00:00.000Z",
      "end": "2026-05-05T00:00:00.000Z"
    }
  ],
  "meta": { "calendar_version": "v1-static-2026-2027" }
}
```

### Notes

The `holiday` key is always present on this route: an object when a holiday row applies to that local date, and `null` otherwise. On a day the market does not open, the windows are still returned with their scheduled times, each carrying `"status": "closed"`. A trading day on shifted hours, such as Korea's late session on 19 November 2026 (10:00 to 16:30 local), is not a holiday: its primary window carries the shifted times, and status, `next_open`, `next_close` and the status `session` block follow them.

## Field reference

| Field | Role |
| --- | --- |
| asset | Asset class for this status row. |
| symbol | Present when a symbol was supplied or resolved for routing. |
| market | Public market or calendar code (for example US, GB, CRYPTO). |
| status | High-level state (open, closed, pre_market, post_market, maintenance, unknown). |
| is_open | Whether an active trading session window applies; use together with `phase` for precision. |
| phase | Finer session context (primary, pre_market, post_market, weekend, holiday, early_close, …). |
| reason | Short human-readable explanation for the current row. |
| timestamp | Evaluation instant (UTC ISO-8601). |
| timezone | IANA timezone for local calendar logic. |
| local_time | Wall-clock instant in `timezone`. |
| next_open | UTC instant the regular (primary) session next opens. Omitted while the regular session is in progress and for 24/7 markets. |
| next_close | UTC instant the current or next regular session ends. During pre-market, post-market, weekend, holiday, and closed phases it pairs with `next_open`; extended-hours window boundaries are available via `session` and the sessions endpoint. |
| holiday | Optional holiday metadata for the local trading date (detail mode when enabled). |
| session | Optional static session template when `includeSessions=true`. |
| meta | Includes `calendar_version` and `data_notice` on status payloads. |

**status** is the simple line; **phase** is the more specific session state; **is_open** reflects an active session window for the model.

| status values |
| --- |
| - `open` - `closed` - `pre_market` - `post_market` - `maintenance` - `unknown` |

| phase values |
| --- |
| - `primary` - `pre_market` - `post_market` - `closed` - `weekend` - `holiday` - `early_close` - `maintenance` - `unknown` |

## What this API is and is not

- **Helps with:** Market-aware polling, open and closed badges on dashboards, alert scheduling, holiday display, and skipping work while markets are quiet.
- **Does not guarantee:** Venue-specific official calendars, emergency closures or halts, instrument-level commodity accuracy in v1, or that live quotes exist whenever status reads open. Status describes modeled sessions for integration timing, not a trading mandate.
- **Static schedules:** Schedules are curated for product use and never call third-party calendar services at request time. Pair them with your own disclaimers; see the [Market data disclaimer](https://tickerlayer.com/market-data-disclaimer).