What can you do with headless oracle?

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:

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

Install

Add headless oracle to your client. Pick the one you use.

claude mcp add --transport http headless-oracle https://headlessoracle.mmsebenzi-oracle.workers.dev/mcp

codex mcp add headless-oracle --url https://headlessoracle.mmsebenzi-oracle.workers.dev/mcp

{
  "mcpServers": {
    "headless-oracle": {
      "url": "https://headlessoracle.mmsebenzi-oracle.workers.dev/mcp"
    }
  }
}

Add to `~/.cursor/mcp.json`, or `.cursor/mcp.json` for a single project.

{
  "servers": {
    "headless-oracle": {
      "type": "http",
      "url": "https://headlessoracle.mmsebenzi-oracle.workers.dev/mcp"
    }
  }
}

Add to `.vscode/mcp.json` in your workspace.

{
  "mcpServers": {
    "headless-oracle": {
      "url": "https://headlessoracle.mmsebenzi-oracle.workers.dev/mcp"
    }
  }
}

Add to `claude_desktop_config.json`, then restart Claude Desktop.

{
  "mcpServers": {
    "headless-oracle": {
      "serverUrl": "https://headlessoracle.mmsebenzi-oracle.workers.dev/mcp"
    }
  }
}

Add to `~/.codeium/windsurf/mcp_config.json`.

Score

39 / 100

Incomplete

Documentation17/25
Maintenance19/25
Trust13/20
Capability0/15
Install experience12/15

Documents what it does and how to connect
Has a resolvable package or endpoint
Exposes at least one tool, prompt or resource
README has substantive content
Includes a code example
Documents its configuration
Mentions credentials or security posture
Last commit 14 days ago
Has a release history
Repository is not archived
Licensed MIT
Namespace verified in the official MCP registry
Claimed by its owner
Published under an organisation
0 tool(s) documented
Provides prompt templates
Provides resources
6 documented install method(s)
Published to a package registry
Offers a hosted endpoint — no local install

Read the full rubric →

Version history

Versions	Published
1.0.0	Mar 24, 2026
5.0.0Latest	Feb 23, 2026