About headless-oracle
Headless Oracle provides signed market-state receipts for autonomous trading agents that need to check whether an exchange is open. Its fail-closed design treats unknown market states as closed, and receipts can be independently verified.
Key features
- 01Signed market-state receipts
- 02Market schedules for 28 exchanges
- 03Fail-closed handling of unknown states
- 04REST and offline receipt verification
- 05MCP tools for status, schedules, exchanges, and payment options
Use cases
- 01Check whether an exchange is open before trading
- 02Verify a market-state receipt independently
MCP support
The MCP server exposes tools to retrieve market status and schedules, list exchanges, and view payment options. Receipt verification is available through REST or offline tooling, not an MCP tool.
Configuration
Remote servers need no local install. Pick your client, then copy the config or install in one click.
https://headlessoracle.mmsebenzi-oracle.workers.dev/mcpclaude mcp add --transport http lembagang-headless-oracle https://headlessoracle.mmsebenzi-oracle.workers.dev/mcp{"mcpServers":{"lembagang-headless-oracle":{"type":"http","url":"https://headlessoracle.mmsebenzi-oracle.workers.dev/mcp"}}}Open in Cursor{"servers":{"lembagang-headless-oracle":{"type":"http","url":"https://headlessoracle.mmsebenzi-oracle.workers.dev/mcp"}}}Open in VS Code{"mcpServers":{"lembagang-headless-oracle":{"type":"http","url":"https://headlessoracle.mmsebenzi-oracle.workers.dev/mcp"}}}{"mcpServers":{"lembagang-headless-oracle":{"serverUrl":"https://headlessoracle.mmsebenzi-oracle.workers.dev/mcp"}}}Run commands in a terminal; paste JSON into the client’s MCP config and restart. Servers that need sign-in will prompt on first connect.
Tools
4| Parameter | Type | Required | Description |
|---|---|---|---|
| mic | enum | No | ISO 10383 Market Identifier Code. Required. Examples: XNYS=NYSE, XNAS=NASDAQ, XLON=London, XJPX=Tokyo, XCBT=CME Futures, XCOI=Coinbase (24/7), XBIN=Binance (24/7). Call list_exchanges to discover all 28 supported codes.XNYS | XNAS | XLON | XJPX | XPAR | XHKG | XSES | XASX | XBOM | XNSE | XSHG | XSHE | XKRX | XJSE | XBSP | XSWX | XMIL | XIST | XSAU | XDFM | XNZE | XHEL | XSTO | XCBT | XNYM | XCBO | XCOI | XBIN |
Details
From the project READMEHeadless 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
# Sandbox key (200 calls, 7 days, no card) - POST with an email
curl -X POST https://headlessoracle.com/v5/sandbox \
-H 'Content-Type: application/json' \
-d '{"email":"[email protected]"}'
Architecture
Single TypeScript Cloudflare Worker. Ed25519 signing via @noble/ed25519. Three KV namespaces (overrides, API keys, telemetry). Two Durable Objects (webhooks, SSE streams). Runs on Cloudflare's edge network - no origin server.
4-tier fail-closed: KV override check -> schedule engine -> UNKNOWN fallback -> unsigned critical failure.
See docs/architecture/overview.md for the full architecture.
API
Four MCP tools - get_market_status, get_market_schedule, list_exchanges,
get_payment_options. Receipt verification is REST-only (POST /v5/verify) or
offline with @headlessoracle/verify.
The REST surface is enumerated in the OpenAPI 3.1 spec, which is served live and is the list of record. Full references:
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 # the full unit/integration suite
npm run test:smoke # 11 smoke tests against live production
The passing count is published by the worker itself at
/v5/metrics/public as
tests_passing, and CI fails if that number and the suite disagree. It is not
restated here, because a number in a README is a number nothing checks.
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
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.