Headless Oracle

Headless Oracle

面向 28 个全球交易所的 Ed25519 签名市场状态证明。

功能

自主交易 Agent 需要在执行交易前确认交易所是否开市。Headless Oracle 会提供经过加密签名的凭证来回答这个问题，任何 Agent 都可以独立验证，无需信任运营方。UNKNOWN 状态始终视为 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":"[email protected]"}'

架构

单个 TypeScript Cloudflare Worker。使用 @noble/ed25519 进行 Ed25519 签名。三个 KV 命名空间（覆盖项、API 密钥、遥测）。两个 Durable Objects（webhook、SSE 流）。运行于 Cloudflare 边缘网络，无源站服务器。

四层故障关闭机制：KV 覆盖项检查 -> 日程引擎 -> UNKNOWN 回退 -> 未签名的严重故障。

完整架构请参阅 docs/architecture/overview.md。

API

四个 MCP 工具 - get_market_status、get_market_schedule、list_exchanges、 get_payment_options。凭证验证仅支持 REST（POST /v5/verify）或使用 @headlessoracle/verify 离线验证。

REST 接口以 OpenAPI 3.1 规范为准，该规范在线提供，并作为权威记录。完整参考文档：

• REST API 参考
• MCP 参考
• OpenAPI 3.1 规范

交易所

23 个传统市场（XNYS、XNAS、XLON、XJPX、XPAR、XHKG、XSES、XASX、XBOM、XNSE、XSHG、XSHE、XKRX、XJSE、XBSP、XSWX、XMIL、XIST、XSAU、XDFM、XNZE、XHEL、XSTO），以及 5 个扩展市场（XCBT、XNYM、XCBO、XCOI、XBIN）。根据 IANA 时区名称自动处理夏令时。涵盖 2026-2027 年的午休、半日市和节假日。

测试

npm test              # the full unit/integration suite
npm run test:smoke    # 11 smoke tests against live production

通过测试的数量由 Worker 自行在 /v5/metrics/public 上发布为 tests_passing；如果该数字与测试套件结果不一致，CI 就会失败。此处不重复列出， 因为 README 中的数字没有任何检查机制。

安全

每个响应都带有 Ed25519 签名。凭证有效期为 60 秒。采用故障关闭架构（UNKNOWN = CLOSED）。所有响应均带有安全标头（HSTS、CSP、X-Content-Type-Options、X-Frame-Options）。

负责任披露政策请参阅 SECURITY.md。

文档

按受众分类的完整文档：

• 工程师：架构、API 参考、ADR
• 运维：部署、监控、SLA
• 法律：服务条款、隐私政策、IP 所有权
• 业务：定价、竞争分析

完整索引请参阅 docs/README.md。

许可证

MIT — 详见 LICENSE