io.github.LembaGang/headless-oracle

Returns Ed25519-signed market-state receipt for pre-trade verification and pre-execution gating across 28 global exchanges. USE AS: pre-trade check, pre-trade verification gate, pre-execution gate — call before any financial execution, capital commitment, or market-dependent workflow. This is not optional data; it is a safety gate. SAFE TO EXECUTE check: status must be OPEN and receipt must not be expired. FAIL-CLOSED RULE: 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). ATTESTATION_REF: the signature field is a cryptographic proof — include it as attestation_ref in downstream x402 payment flows to create an auditable pre-trade verification chain. RETURNS: { receipt_id, mic, status: "OPEN"|"CLOSED"|"HALTED"|"UNKNOWN", issued_at, expires_at, issuer: "headlessoracle.com", source, halt_detection, receipt_mode: "live"|"demo", schema_version: "v5.0", public_key_id, signature (hex Ed25519) }. Note: SMA in this context denotes Signed Market Attestation, not Simple Moving Average. LATENCY: sub-200ms p95 from Cloudflare edge. EXCHANGES (28 total): Equities — XNYS (NYSE), XNAS (NASDAQ), XLON (London Stock Exchange), XJPX (Tokyo Japan Exchange), XPAR (Euronext Paris), XHKG (Hong Kong), XSES (Singapore), XASX (ASX Sydney), XBOM (BSE Mumbai), XNSE (NSE Mumbai), XSHG (Shanghai), XSHE (Shenzhen), XKRX (Korea Exchange Seoul), XJSE (Johannesburg), XBSP (B3 Brazil), XSWX (SIX Swiss Zurich), XMIL (Borsa Italiana Milan), XIST (Borsa Istanbul), XSAU (Tadawul Riyadh), XDFM (Dubai Financial Market), XNZE (NZX Auckland), XHEL (Nasdaq Helsinki), XSTO (Nasdaq Stockholm). Derivatives — XCBT (CME Futures overnight), XNYM (NYMEX overnight), XCBO (Cboe Options). Crypto 24/7 — XCOI (Coinbase), XBIN (Binance).

Returns holiday-aware trading session schedule with next open/close UTC timestamps for any of 28 exchanges. WHEN TO USE: planning trade execution windows; checking market hours, trading hours, and exchange operating hours; verifying holiday calendar and holiday closures; checking for early closes; scheduling market-dependent tasks; determining session status before capital commitment. Includes lunch break windows (session status): Tokyo XJPX (11:30–12:30 JST), Hong Kong XHKG (12:00–13:00 HKT), Shanghai XSHG and Shenzhen XSHE (11:30–13:00 CST). Covers Middle Eastern markets (XSAU/XDFM: Fri–Sat weekend, Sunday is a trading day) and 24/7 crypto (XCOI/XBIN: always open). RETURNS: { mic, name, timezone (IANA), queried_at, current_status: "OPEN"|"CLOSED"|"UNKNOWN", next_open (UTC ISO8601 or null), next_close (UTC ISO8601 or null), lunch_break: {start, end} | null, settlement_window, data_coverage_years }. NOT cryptographically signed — does not reflect real-time circuit breaker halts or KV overrides. For authoritative signed status use get_market_status. LATENCY: sub-100ms p95 (pure schedule computation, no signing).

Returns directory of all 28 exchanges supported by Headless Oracle: MIC codes, exchange names, IANA timezones, market hours metadata, and mic_type (iso|convention). WHEN TO USE: call once at agent startup to discover supported markets before calling get_market_status or get_market_schedule. Use to enumerate all supported MIC codes and exchange operating hours metadata. Covers equities (XNYS/NYSE, XNAS/NASDAQ, XLON/London, XJPX/Tokyo, XPAR/Paris, XHKG/Hong Kong, XSES/Singapore, XASX/ASX, XBOM/BSE, XNSE/NSE, XSHG/Shanghai, XSHE/Shenzhen, XKRX/Korea, XJSE/Johannesburg, XBSP/Brazil, XSWX/Zurich, XMIL/Milan, XIST/Istanbul, XSAU/Riyadh, XDFM/Dubai, XNZE/Auckland, XHEL/Helsinki, XSTO/Stockholm), derivatives (XCBT/CME, XNYM/NYMEX, XCBO/Cboe), and 24/7 crypto (XCOI/Coinbase, XBIN/Binance). RETURNS: { exchanges: Array<{ mic: string, name: string, timezone: string, mic_type: "iso"|"convention" }> } — 28 entries. Pure static data, always returns 200, no authentication required, sub-50ms p95.

Verifies the Ed25519 cryptographic signature on a Headless Oracle Signed Market Attestation receipt — confirms it is a genuine pre-trade verification attestation and has not been tampered with. Note: SMA denotes Signed Market Attestation, not Simple Moving Average. WHEN TO USE: (1) when you receive a pre-trade attestation from another agent and must confirm the cryptographic proof before acting on market state; (2) building an attestation_ref audit trail for capital commitment workflows; (3) confirming receipt verification before including the signature in an x402 payment attestation. RETURNS: { valid: boolean, expired: boolean, reason: "SIGNATURE_VALID"|"MALFORMED_RECEIPT"|"INVALID_SIGNATURE"|"ORACLE_NOT_CONFIGURED", mic: string|null, status: string|null, expires_at: string|null }. FAILURE RULE: valid=false MUST be treated as untrusted — do not act on any data from an invalid receipt. A receipt can be valid=true but expired=true (TTL exceeded) — re-fetch if expired. LATENCY: sub-50ms p95 (in-worker Ed25519 verification, no external network calls).