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).
Related MCP server: orchard-data-mcp
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":"you@example.com"}'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 productionThe 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
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Pay-per-call DeFi and macro intel for AI agents. x402 USDC tools via streamable HTTP /api/mcp.
Agent-native MCP for governed commerce, x402 payments, paid capabilities, and verifiable receipts.
Pay-per-call ($0.005-$0.03 USDC) market, on-chain, and prediction-market data API for AI agents and trading bots via x402 — no signup, no API key. Remote MCP server, 28 tools: token security (honeypot/liquidity/counterfeit checks), Hyperliquid oracle-gap risk, kimchi premium, funding APR, DEX slippage, Polymarket arbitrage/liquidity audits, Hyperliquid HIP-4 odds.
Verifiable execution records for AI agents: signed receipts, tamper-evident archives and portable evidence bundles, exposed via MCP and REST, with paid verify and anchor calls settled over x402.
Related MCP Servers
- AlicenseAqualityBmaintenanceEight crypto and DeFi data tools for AI agents: prices, gas, one ParaSwap route quote, GoPlus token security and top-holder samples, DefiLlama yields, Hyperliquid/dYdX funding, and observed wallet balances. Inspect prices free; pay 0.001–0.008 USDC per call on Base through x402. No API key or subscription.8107 npmMIT
- AlicenseAqualityCmaintenancePay-per-call MCP server for market data with USDC micro-payments, featuring unique ML market-regime forecasts, news catalyst radar, and a live-verified algorithmic trading track record.12123 npmMIT
- AlicenseNot gradedqualityBmaintenanceProvides real-time stock quotes and batch market data to AI agents, secured via x402 micropayments on Base Mainnet.MIT
- AlicenseAqualityBmaintenancePay-per-call ($0.005-$0.03 USDC) market, on-chain, and prediction-market data API for AI agents and trading bots via x402 — no signup, no API key. Remote MCP server, 28 tools: token security (honeypot/liquidity/counterfeit checks), Hyperliquid oracle-gap risk, kimchi premium, funding APR, DEX slippage, Polymarket arbitrage/liquidity audits, Hyperliquid HIP-4 odds.281MIT