Ed25519-signed market-state receipts for 28 exchanges. Fail-closed pre-trade gate.
Ed25519-signed market-state attestations for 28 global exchanges.
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).
# 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":"you@example.com"}'
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.
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:
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.
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.
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.
Full documentation organized by audience:
See docs/README.md for the full index.
MIT — see LICENSE
Source-derived launch command. Check the maintainer’s required arguments and credentials before running:
npx -y headless-oracle-mcpMerge this template into ~/Library/Application Support/Claude/claude_desktop_config.json. Keep existing servers. Add any arguments, credentials, and permissions required by the maintainer; this template has not been install-tested.
{
"mcpServers": {
"io-github-lembagang-headless-oracle-mcp": {
"command": "npx",
"args": [
"-y",
"headless-oracle-mcp"
]
}
}
}Restart Claude Desktop completely for changes to take effect. Confirm the server appears connected in the client’s tool list, then try a read-only example from its documentation.
Claude Desktop setup referenceheadless-oracle-mcpnpmio.github.LembaGang/headless-oracle-mcp works with any MCP-compatible client. Copy the config snippet from the Configuration section above and add it to the file shown for your client, then restart the application.
~/Library/Application Support/Claude/claude_desktop_config.jsonRestart Claude Desktop completely for changes to take effect.~/.cursor/mcp.jsonRestart Cursor for changes to take effect..vscode/mcp.jsonReload VS Code window for changes to take effect.~/.codeium/windsurf/mcp_config.jsonRestart Windsurf for changes to take effect..mcp.jsonSave at the project root, then start Claude Code in that project and review the MCP server approval prompt. Keep real credentials out of shared files.