Headless Oracle

Ed25519-signed market-state attestations for 28 global exchanges.

What It Does

Autonomous trading agents need to know if an exchange is open before executing trades. Headless Oracle answers that question with a cryptographically signed receipt that any agent can verify independently — no trust in the operator required. UNKNOWN states are always treated as CLOSED (fail-closed).

Quick Start

# MCP (Claude Desktop, Cursor, any MCP client)
npx headless-oracle-mcp

# REST API — demo receipt (no auth required)
curl https://headlessoracle.com/v5/demo?mic=XNYS

# Instant sandbox key (200 calls, 7 days, no signup)
curl https://headlessoracle.com/v5/sandbox

Architecture

Single TypeScript Cloudflare Worker (~14,000 lines). Ed25519 signing via @noble/ed25519. Three KV namespaces (overrides, API keys, telemetry). Two Durable Objects (webhooks, SSE streams). Deployed to 300+ edge locations globally.

4-tier fail-closed: KV override check -> schedule engine -> UNKNOWN fallback -> unsigned critical failure.

See docs/architecture/overview.md for the full architecture.

API

5 MCP tools and 25+ REST endpoints. Full references:

• REST API Reference
• MCP Reference
• OpenAPI 3.1 Spec

Exchanges

23 traditional markets (XNYS, XNAS, XLON, XJPX, XPAR, XHKG, XSES, XASX, XBOM, XNSE, XSHG, XSHE, XKRX, XJSE, XBSP, XSWX, XMIL, XIST, XSAU, XDFM, XNZE, XHEL, XSTO) plus 5 extended (XCBT, XNYM, XCBO, XCOI, XBIN). DST handled automatically via IANA timezone names. Lunch breaks, half-days, and holidays for 2026-2027.

Testing

npm test              # 725+ unit/integration tests
npm run test:smoke    # 11 live production smoke tests

Security

Ed25519 signatures on every response. 60-second receipt TTL. Fail-closed architecture (UNKNOWN = CLOSED). Security headers on all responses (HSTS, CSP, X-Content-Type-Options, X-Frame-Options).

See SECURITY.md for the responsible disclosure policy.

Documentation

Full documentation organized by audience:

• Engineers: Architecture, API Reference, ADRs
• Operations: Deployment, Monitoring, SLA
• Legal: Terms of Service, Privacy Policy, IP Ownership
• Business: Pricing, Competitive Analysis

See docs/README.md for the full index.

License

MIT — see LICENSE