headless-oracle

Returns the next open and close UTC timestamps for a stock exchange. WHEN TO USE: call this to plan trade execution windows, schedule market-dependent tasks, check session times, or determine how long until a market opens. RETURNS: { mic: string, name: string, timezone: string (IANA), queried_at: ISO8601, current_status: "OPEN"|"CLOSED"|"UNKNOWN", next_open: ISO8601|null, next_close: ISO8601|null, lunch_break: { start: "HH:MM", end: "HH:MM" }|null, data_coverage_years: string[] }. FAILURE BEHAVIOUR: NOT cryptographically signed. Does not reflect real-time halts, circuit breakers, or KV overrides. For authoritative signed status use get_market_status instead. LATENCY: sub-100ms p95 (pure schedule computation, no signing). Includes lunch break windows for Tokyo (XJPX: 11:30–12:30 JST), Hong Kong (XHKG: 12:00–13:00 HKT), Shanghai (XSHG: 11:30–13:00 CST), Shenzhen (XSHE: 11:30–13:00 CST).

Returns a cryptographically signed Ed25519 receipt stating whether a stock exchange is OPEN, CLOSED, HALTED, or UNKNOWN. WHEN TO USE: call this before executing any trade, payment, or market-dependent workflow on a specific exchange. RETURNS: { receipt_id: string, mic: string, status: "OPEN"|"CLOSED"|"HALTED"|"UNKNOWN", issued_at: ISO8601, expires_at: ISO8601, issuer: string, source: "SCHEDULE"|"OVERRIDE"|"REALTIME"|"SYSTEM", schema_version: "v5.0", receipt_mode: "live"|"demo", public_key_id: string, signature: string (hex Ed25519) }. FAILURE BEHAVIOUR: UNKNOWN and HALTED MUST be treated as CLOSED — halt all execution immediately. Do not act on a receipt where expires_at is in the past (TTL = 60s). LATENCY: sub-200ms p95 from Cloudflare edge. Covers 28 global exchanges. Equities: XNYS (NYSE), XNAS (NASDAQ), XLON (London), XJPX (Tokyo), XPAR (Paris), XHKG (Hong Kong), XSES (Singapore), XASX (Sydney), XBOM (Mumbai BSE), XNSE (Mumbai NSE), XSHG (Shanghai), XSHE (Shenzhen), XKRX (Seoul), XJSE (Johannesburg), XBSP (São Paulo), XSWX (Zurich), XMIL (Milan), XIST (Istanbul), XSAU (Riyadh), XDFM (Dubai), XNZE (Auckland), XHEL (Helsinki), XSTO (Stockholm). Derivatives: XCBT (CME Futures, overnight), XNYM (NYMEX, overnight), XCBO (Cboe Options). Crypto 24/7: XCOI (Coinbase), XBIN (Binance).

Returns all 28 exchanges supported by Headless Oracle with their MIC codes, names, IANA timezones, and mic_type (iso | convention). WHEN TO USE: call this once at agent startup to discover supported markets before calling get_market_status or get_market_schedule. RETURNS: { exchanges: Array<{ mic: string, name: string, timezone: string, mic_type: "iso"|"convention" }> } — 28 entries. FAILURE BEHAVIOUR: pure static data, no signing, no failure modes. Always returns 200. LATENCY: sub-50ms p95.

Verifies the Ed25519 cryptographic signature on a Headless Oracle signed receipt. WHEN TO USE: call this when you receive a receipt from another agent or upstream system and must confirm it was genuinely issued by Headless Oracle and has not been tampered with or expired. RETURNS: { valid: boolean, expired: boolean, reason: "signature_valid"|"MISSING_FIELDS"|"EXPIRED"|"INVALID_SIGNATURE"|"ORACLE_NOT_CONFIGURED"|"MALFORMED_RECEIPT"|"VERIFY_ERROR", mic: string|null, status: string|null, expires_at: string|null }. FAILURE BEHAVIOUR: valid=false MUST be treated as an untrusted receipt — do not act on any data from it. A receipt can be valid=true but expired=true (past TTL) — re-fetch if expired. LATENCY: sub-50ms p95 (in-worker Ed25519 verification, no network calls).