headless-oracle

Headless Oracle

28 のグローバル取引所に対応した、Ed25519 署名付きの市場状態証明です。

機能

自律型取引エージェントは、取引を実行する前に取引所が営業中かどうかを確認する必要があります。Headless Oracle は、あらゆるエージェントが独立して検証できる暗号署名付きの証明を返すことで、その疑問に答えます。運営者を信頼する必要はありません。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 署名に対応しています。3 つの KV 名前空間（オーバーライド、API キー、テレメトリー）と、2 つの Durable Objects（ウェブフック、SSE ストリーム）を使用します。Cloudflare のエッジネットワークで稼働し、オリジンサーバーはありません。

4 段階のフェイルクローズ：KV オーバーライドの確認 → スケジュールエンジン → UNKNOWN へのフォールバック → 署名のない重大な障害。

アーキテクチャの全容については、docs/architecture/overview.md をご覧ください。

API

4 つの MCP ツール — get_market_status、get_market_schedule、list_exchanges、 get_payment_options。証明の検証は REST のみ（POST /v5/verify）、または @headlessoracle/verify を使用したオフラインで行います。

REST API の仕様は 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

テスト合格数はワーカー自体が /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
• 法務向け：利用規約、プライバシーポリシー、知的財産の所有権
• ビジネス向け：料金、競合分析

全項目の一覧については、docs/README.md をご覧ください。

ライセンス

MIT — LICENSE をご覧ください。