market-status.md

# market-status

Check whether a market is open and when it next opens/closes via:

- `GET /v1/markets/{market}/status` — single market status
- `GET /v1/capabilities` — all markets, accounts, order types, and live quotes

## When to consult this

User says "市场开了吗", "几点收盘", "open now?", "market status", "A股开盘
了吗", "what markets are supported". No confirmation required.

Market codes: `CN` (A-shares, SSE + SZSE), `HK` (HKEX), `US` (NYSE/NASDAQ).

## Calling

    python3 -c "
    from scripts._http import Client
    c = Client()

    # Single market status
    print(c.get('/v1/markets/CN/status'))

    # Capabilities: supported markets, order types, active quotes
    print(c.get('/v1/capabilities'))
    "

## Response shape — market status

`GET /v1/markets/CN/status`:

    {
      "market":     "CN",
      "is_open":    true,
      "next_open":  null,
      "next_close": "2026-05-21T07:00:00+00:00"
    }

| Field | Meaning |
|-------|---------|
| `is_open` | `true` if the market is in a trading session right now |
| `next_open` | ISO 8601 UTC timestamp of the next open; `null` when currently open |
| `next_close` | ISO 8601 UTC timestamp of the next close |

CN has a lunch break (11:30–13:00 local); the calendar reflects this — the
market will show `is_open=false` during the break.

When surfacing `next_open` / `next_close` to the user, convert from UTC to
the market's local timezone — CN/HK use UTC+8 year-round (no DST); US
follows ET, which the calendar already encodes via UTC offset (EDT 13:30
UTC ≡ 09:30 ET in summer, EST 14:30 UTC ≡ 09:30 ET in winter). Reporting
raw UTC forces the user to convert mentally.

## Response shape — capabilities

`GET /v1/capabilities`:

    {
      "markets":     ["CN", "HK", "US"],
      "order_types": ["MARKET", "LIMIT"],
      "tif":         ["DAY"],
      "accounts":    ["acc_default"],
      "feed": {
        "quote_count": 3,
        "quotes": [
          {
            "symbol":      "600519.SH",
            "last":        1685.00,
            "bid":         1684.50,
            "ask":         1685.50,
            "source_tier": "realtime",
            "server_ts":   "2026-05-21T09:31:00+00:00"
          }
        ]
      }
    }

`source_tier` values: `realtime` (live tick), `yesterday` (last close),
`daily` (end-of-day). A `null` bid or ask on a realtime quote indicates a
locked limit (涨停/跌停) — MARKET orders will be rejected with
`NO_ASK_LIQUIDITY` / `NO_BID_LIQUIDITY`.

## Error responses

| Code | HTTP | recovery_hint | Action |
|------|------|---------------|--------|
| `MARKET_NOT_FOUND` | 404 | fix_input | market code not CN / HK / US |
| `RULES_NOT_WIRED`  | 500 | retry | service misconfigured; run doctor.py |