mcpField
H
Headless Oracle

Headless Oracle

Local
github.com/LembaGangDatabases0Updated 1w ago
Repository

About Headless Oracle

Headless Oracle reports market states for 28 global exchanges and issues Ed25519-signed receipts that agents can verify independently. Its fail-closed design treats UNKNOWN as CLOSED, for automated trading systems that need to check market availability.

Key features

  1. 01Status for 28 global exchanges
  2. 02Ed25519-signed market receipts
  3. 03Fail-closed UNKNOWN handling
  4. 04Exchange schedules and listings
  5. 05REST receipt verification

Use cases

  1. 01Check whether an exchange is open before trading
  2. 02Verify signed market status independently
  3. 03Retrieve exchange schedules for trading automation

MCP support

Exposes tools for market status, schedules, exchange listings, and payment options to MCP clients. Receipt verification is provided through REST or offline tooling.

#finance#trading#market-data#ai-agents#mcp#ed25519

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

mcp.json · Universal config
{
  "mcpServers": {
    "headless-oracle-v5": {
      "command": "npx",
      "args": [
        "-y",
        "headless-oracle-mcp"
      ]
    }
  }
}
Run commandnpx -y headless-oracle-mcp

Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.

Packages
npmheadless-oracle-mcp1.0.3

Tools

4

Saved tool list · updated 3w ago

ParameterTypeRequiredDescription
micenumNoISO 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 README

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

# 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:

See docs/README.md for the full index.

License

MIT — see LICENSE

Comments

Markdown supported

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.