LiquiLens Trade Safety Gateway

LiquiLens Trade Safety Gateway

この統合機能は、AI トレーディングコパイロット向けの読み取り専用サンドボックスアダプターです。Trade Safety Request を厳密に 1 件、オペレーターポリシーを 1 件受け取り、固定された少数の公開エビデンスエンドポイントを読み取り、liquilens_evidence.trade_safety で定義された、SHA-256 のみを用いる決定的なレシートを発行します。

注文ゲートウェイではありません。 ブローカー認証情報、ブローカーによるプレビュー、注文送信ルート、推奨ルート、自動リサイズ動作、カストディ、取引決済、実資金を扱う権限はありません。オプションの x402 ルートでは、同じ評価へのアクセス料金を決済できます。決済によってポリシー、エビデンス、結果、レシートの権限、注文経路が変わることはありません。すべてのレスポンスには、X-Trade-Safety-Mode: sandbox、X-Trade-Safety-Authority: read-only、X-Trade-Safety-Execution: disabled が含まれます。ライブモードの評価は、エビデンスがコンテキスト専用であり、レシートがテナント認証されておらず、ブローカープレビュー参照が not_applicable であるため、決定的に unavailable を返します。

HTTP および MCP のインターフェース

• GET /healthz は、ソースの状態を調査したり隠したりすることなく、プロセスの健全性を報告します。
• GET /v1/capabilities は、静的な制限、ソース、権限を説明します。

匿名の POST リクエストは、各ゲートウェイワーカー内で共通の予算を使用します。処理中のリクエストは 16 件、新規リクエストは毎秒 20 件、バーストは 40 件で、ボディのアップロードと処理を含む合計タイムアウトは 20 秒です。レート上限に達した場合は HTTP 429 を返し、処理容量が埋まっている場合、またはタイムアウトした場合は HTTP 503 を返します。これらのレスポンスには、Retry-After: 1、Cache-Control: no-store、通常の読み取り専用ヘッダーが含まれます。MCP エラーでは JSON-RPC エンベロープが維持されます。バックオフとジッターを用いて再試行してください。別途有効化されている場合、有料リクエストも決済ジャーナルの照合ルールに従う必要があります。

ヘルスチェックおよびディスカバリーの GET リクエストは、POST の予算が上限に達していても引き続き利用できます。この制御では、IP アドレスやインストールの識別情報は保存されず、転送、インストール、モニタリングのヘッダーを変更しても回避できません。この制限はワーカーごとに適用され、フリート全体のクォータでも、エッジネットワーク保護の代替でもありません。オペレーターは、TRADE_SAFETY_MAX_IN_FLIGHT（1～64）、TRADE_SAFETY_REQUESTS_PER_SECOND（1～100）、TRADE_SAFETY_REQUEST_BURST（1～200）を使って、上限の範囲内で予算を増減できます。無効な値を指定すると起動に失敗します。有効な設定は、ケイパビリティレスポンスの limits.admission に公開されます。

• POST /v1/check は、{"request": {...}, "policy": {...}} のみを受け付けます。
• POST /v1/x402/check は、完全な x402 設定がある場合にのみ登録されます。それ以外の場合と同一の評価への有料アクセスをチャレンジして決済します。
• POST /mcp は、initialize、ping、tools/list、tools/call をサポートします。
• MCP が公開するのは、assess_trade_safety と trade_safety_capabilities のみです。
• MCP は、初期化ベースの 2025-11-25 とステートレスの 2026-07-28 をネゴシエートします。後者では server/discover メタデータが公開され、一致する MCP-Protocol-Version、Mcp-Method、および該当する Mcp-Name ヘッダーが必要です。無効なバージョンやヘッダーとボディの不一致には HTTP 400 を返します。
• レガシー初期化の後、以降のすべてのレガシー POST には MCP-Protocol-Version: 2025-11-25 が必要です。受け付けられた通知には、JSON-RPC ボディを伴わず HTTP 202 を返します。
• ブラウザーからの MCP リクエストでは、正規の HTTPS 発行元オリジンのみを受け付けます。ブラウザー以外のクライアントは Origin を省略できますが、それ以外のオリジンには HTTP 403 を返します。受け付けられたレガシー notifications/initialized POST には、ボディなしで HTTP 202 を返します。
• FastAPI は、生成された OpenAPI を /openapi.json に、Swagger UI を /docs に公開します。

意図的に、実行を行う形の MCP ツールは用意されていません。

サーバー管理ポリシーによる受け入れ判定

プロトコルではオペレーターが作成したポリシーを受け付けますが、パブリックゲートウェイでは、匿名の呼び出し元が安全性の最低基準を変更することはできません。ソースへのリクエストや x402 の検証を行う前に、指定されたポリシーをサーバー管理の適用範囲に照らして受け入れ判定します。

• Seiche と Undertow は引き続き必須であり、STRESS は引き続き保留対象のレジームです。
• ソースの経過時間の上限は、Seiche では 8 日、Undertow と LiquiLens では 1 日を超えることはできません。
• 想定元本、退出コスト、取引所スプレッドの上限は必須で、それぞれ USD 100,000、50 bps、20 bps を超えることはできません。
• エビデンスが不足している場合は引き続きフェイルクローズとなり、ライブでは引き続き執行可能な見積もりとブローカープレビューが必要です。また、自動リサイズは禁止されたままです。
• オペレーターは任意の上限を厳しくするか、正規のポリシーハッシュと完全一致するもののみを受け入れるよう設定できます。

認識される TRADE_SAFETY_POLICY_* 設定は、trade_safety_gateway.policy_guard に記載されています。不明な設定、不正な形式の設定、または上限を緩和する設定がある場合、起動に失敗します。GET /v1/capabilities では、現在有効な非機密の適用範囲を公開します。

設定	形式と、上限を厳しくする場合の意味
TRADE_SAFETY_POLICY_REQUIRED_PRODUCTS	seiche,undertow,liquilens の一意なカンマ区切り部分集合。Seiche と Undertow を含める必要があります
TRADE_SAFETY_POLICY_HOLD_REGIMES	CALM,EROSION,STRAIN,STRESS の一意なカンマ区切り部分集合。STRESS を含める必要があります
TRADE_SAFETY_POLICY_MAX_SEICHE_AGE_SECONDS	691200 以下の正の整数
TRADE_SAFETY_POLICY_MAX_UNDERTOW_AGE_SECONDS	86400 以下の正の整数
TRADE_SAFETY_POLICY_MAX_LIQUILENS_AGE_SECONDS	86400 以下の正の整数
TRADE_SAFETY_POLICY_MAX_NOTIONAL_USD	100000 以下の正の有限数
TRADE_SAFETY_POLICY_MAX_EXIT_COST_BPS	50 以下の正の有限数
TRADE_SAFETY_POLICY_MAX_VENUE_SPREAD_BPS	20 以下の正の有限数
TRADE_SAFETY_POLICY_SHA256_ALLOWLIST	正規ポリシーの SHA-256 値（小文字）の一意なカンマ区切りリスト

x402 アクセスとエージェントの検出

すべての TRADE_SAFETY_X402_* 設定が未指定の場合、x402 は無効になります。設定がすべて揃うと、有料ルートが追加され、HTTP Bazaar の検出メタデータを含む、正確な x402 v2 オファーが公開されます。このオファーでは、正規化されたリクエスト本文、リソース、価格、アセット、支払先、ResourceInfo、および必須の拡張機能が、専用の見積もりキーに紐付けられます。ランタイムは評価前に検証を行い、保護されたレスポンスが生成された後にのみ決済を確定し、ジャーナルに記録された正確なバイト列のみを解放します。

支払いの識別情報と取引の来歴は、非公開の決済ジャーナルに保持され、Trade Safety のレシートや採用テレメトリには含まれません。決済が完了しても、コンテキストのみのエビデンスが執行可能な見積もりに変わるわけではなく、安全性の判定がいつまでも最新の状態になるわけでもありません。設定、ローカルの liquilens-trade-safety-x402-reconcile オペレーターコマンド、状態の復旧、アクティベーションゲートについては、 TRADE-SAFETY-X402.md を参照してください。このコマンドがファシリテーターを呼び出すことはありません。オペレーターは、不確かなジャーナルエントリを変更する前に、決済済みまたは確実に未決済である状態を独立して確認する必要があります。

固定エビデンスアダプター

製品	固定リクエスト	レシートの状態と境界
Seiche	GET https://api.seiche.info/api/trade-safety/risk-context、スキーマ seiche.risk-context.v1	context_only。ネイティブのキャッシュのみの投影、保守的なエビデンス時刻、権利の状態、陳腐化の件数、証明境界、投影ダイジェストが検証され、保持されます。Seiche は上流で注文にバインドされないため、レシートでは、その正確な投影ダイジェストを正規の Trade Safety リクエストハッシュに明示的にバインドします。
Undertow	POST https://api.seiche.info/undertow/mcp、ツール trade_safety_exit_context	context_only。ゲートウェイは、正確な observe/paper BTC/USD sell rung とともに、正規の Trade Safety リクエストハッシュを送信します。Undertow はそのバインドをエコーし、検証済みの PIT ヘッド／チェーン、デプロイ済み SHA、承認済みの派生メタデータ権利、6 つの全取引所の網羅、整合性のある時刻、および損なわれていないコンテキストダイジェストを提供する必要があります。
LiquiLens	GET https://api.liquilens.in/api/failure-radar/institution/{quoted_slug}	検証済みの request.order.instrument.identifiers.liquilens_institution_slug がある場合にのみ呼び出されます。最新期間の終了日と、過去のエビデンスの状態／適格性のみが投影されます。それ以外は not_applicable です。

Undertow の JSON-RPC テキストコンテンツは無視されます。ゲートウェイは structuredContent のみを使用します。Seiche は固定の REST 表現から取得します。 どちらのネイティブオブジェクトもキーを厳密に検証し、キーなしの正規 ダイジェストを再計算したうえで、ダイジェスト検証後にフィールド間の整合性を チェックします。圧縮されていない正確な HTTP エンティティのハッシュは独立して計算されます。ソース、 観測／as-of、知識、プロデューサーによる取得、ゲートウェイによる取得、ネイティブの有効期限、 ローカルレシートの有効期限の各時刻は、それぞれ別個に保持されます。

Undertow の網羅性は、ロスターの範囲に限られ、市場全体を対象とするものではありません。 ゲートウェイは、宣言された 6 つの CEX ロスターとの完全な集合一致を必須とし、 結果を使用する前に、クオート通貨の換算、必要な深度帯、取引所ごとのベーシスポイントおよびドル建てコスト、 最良／最悪の取引所、スプレッド、ペッグ、証明、権利、有効期限を相互に照合します。 ロスター外の CEX、DEX、エージェントネイティブの取引所は、設計上、引き続き未計測です。取引所の追加や変更には、 黙って受け入れるのではなく、レビュー済みの契約更新が必要です。

fail-closed とネットワーク境界

• 送信リクエストとポリシー（相互参照、現在の有効期間、任意の機関スラッグを含む）は、外部への呼び出しの前に検証されます。
• 呼び出し元のポリシーは、外部への呼び出しや決済チャレンジ／検証の前に、変更不可能なサーバーの安全性基準に照らして許可されます。
• 接続先、メソッド、MCP ツール名、URL のベースは定数です。リクエスト本文から URL を指定することはできません。
• リダイレクト、環境プロキシ、Cookie、圧縮、JSON 以外の本文、200 以外のレスポンス、不正な JSON／重複キーを含む JSON、MCP エラー、structuredContent の欠落は拒否されます。
• リクエスト本文の上限は 64 KiB、ソース本文の上限は 1 MiB、ゲートウェイレスポンスの上限は 512 KiB です。上流への各操作には合計タイムアウトとして 5 秒、接続タイムアウトとして 2 秒が設定されています。
• 独立した利用可能なソースは並行して取得されます。ソースエラー、プロデューサーが宣言した利用不可状態、古いネイティブクロック、ダイジェストの失敗、リクエストハッシュの不一致、証明の失敗、権利の不一致は、そのプロダクトの型付き unavailable エビデンスセクションになります。Seiche と Undertow は必須プロダクトであるため、その場合レシートは fail-closed になります。
• このサービスはリクエスト本文、レスポンス本文、シークレット、アカウントデータ、ソース例外をログに記録しません。同梱のコマンドではアクセスログが無効になっています。
• すべてのエビデンスセクションとブローカープレビューの参照には、trade_safety_request_hash(request) が含まれます。Undertow にはこの値も渡され、エコーバックされます。Seiche のネイティブ投影ダイジェストとリクエストハッシュは、ハッシュで封印されたレシート内の個別のローカルバインディングダイジェストを受け取ります。最も近いラングの結果が、完全一致する注文のエビデンスとして扱われることはありません。
• Undertow に送信されるモードは observe と paper のみです。live と buy のリクエストは、Undertow の売り側のペーパーコンテキストツールには到達せず、代わりに型付きの利用不可エビデンスが生成されます。
• notional と null ではない quantity の両方を含むリクエストは、ブローカーベースで正規化された経済注文ダイジェストと参照価格契約によって、両方のフィールドが同じエクスポージャーを表すと証明できるまで、Undertow に到達しません。

公開ソースへのアクセスは、実資金の使用権や再配布権を意味するものではありません。そのため、該当する場合、3 つすべてのアダプターは metadata_only、context_only、real_money_eligible: false、executable_quote: false を宣言します。

ローカル開発

このディレクトリから、リポジトリのプロトコルパッケージとゲートウェイを同じ環境にインストールします。

python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e ../.. -e '.[test]'
pytest
liquilens-trade-safety-gateway

サーバーは 0.0.0.0:8080 でリッスンします。無料のサンドボックスモードでは、API キーもブローカーシークレットも不要です。x402 を有効にするには専用の見積もりバインディングシークレットが必要ですが、ウォレットの秘密鍵やブローカーの認証情報は引き続き不要です。導入テレメトリーもデフォルトで無効です。オペレーターは、 TRADE-SAFETY-TRACTION.md の説明に従って、プライベートな追記専用 JSONL パスを明示的に選択できます。

コンテナのビルド

イメージにルートの Trade Safety 実装が正確に含まれるよう、evidence-carrier リポジトリのルートからビルドしてください。

docker build -f integrations/trade-safety-gateway/Dockerfile \
  --build-arg SOURCE_REVISION="$(git rev-parse HEAD)" \
  --build-arg CREATED="$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  --build-arg ISSUER_ENDPOINT=https://your-sandbox.example/v1/check \
  -t liquilens-trade-safety-gateway:0.2.2 .
docker run --read-only --tmpfs /tmp:rw,noexec,nosuid,size=16m \
  --cap-drop ALL --security-opt no-new-privileges \
  -p 8080:8080 liquilens-trade-safety-gateway:0.2.2

Dockerfile はマルチプラットフォームのダイジェストでベースイメージを固定し、コミット済みのゲートウェイロックファイルからインストールし、数値で指定した非 root ユーザーを使用して、ヘルスチェックと機能情報を通じてソースとビルドの識別情報を公開します。本番環境へのデプロイでは、api.seiche.info:443 と api.liquilens.in:443 のみを許可する送信トラフィックポリシーも適用してください。アプリケーションの許可リストは、ネットワークポリシーの代わりにはなりません。x402 を有効にするには、設定済みの 1 つのファシリテーターへの送信トラフィックと、ジャーナル用の非公開の永続ボリュームも必要です。x402 の変数が設定されていない場合、読み取り専用コンテナでは無料ルートのみが実行されます。変数が設定されていても、書き込み可能な非公開ジャーナルボリュームがない場合は、起動に失敗します。公開エッジでは、上限付きのリクエストクォータも適用する必要があります。このアプリケーションは、クライアントが指定した IP ヘッダーをレート制限キーとして信頼しません。

リリースワークフローは、アテステーション付きのマルチアーキテクチャ OCI パッケージを GHCR に公開します。このレジストリアーティファクトは配布用であり、ホスト型デプロイメントでも注文を承認するサービスでもありません。読み取り専用のハッシュのみを扱うサンドボックス境界は維持され、運用は採用者が担う必要があります。独立したゲートウェイタグ用レーンは OCI のみを公開します。検証用の証拠として wheel をビルドしますが、その wheel、sdist、GitHub Release は公開しません。

ゲートウェイ 0.2.2 は独立したリリース ID を持つため、公開しても不変のコア v0.19.0 タグは移動も再利用もされません。リリースコミットが origin/main に反映された後、許可リストに登録されたリリース担当者は、注釈付きの署名済みタグ trade-safety-gateway-v0.2.2 を作成してプッシュできます。ワークフローは、軽量タグまたは未署名タグ、未署名の対象コミット、origin/main 外の対象、ゲートウェイとタグのバージョン不一致、または 0.19.0 以外のコア VERSION を拒否します。また、公開前に、既存のゲートウェイバージョン、ソースコミット、署名済みタグオブジェクトの OCI タグも拒否します。ゲートウェイ専用レーンは、可変の latest や core-* のエイリアスを出力しません。マルチアーキテクチャイメージには、最大限のビルド来歴、SBOM、個別の GitHub 来歴アテステーション、および OCI メタデータ内の署名済み Git タグオブジェクトが保持されます。一方、コアの v* リリースが更新できるのは core-*、core-sha-*、latest のみです。ゲートウェイが所有するセマンティックバージョン、ソースコミット、署名済みタグオブジェクトのエイリアスは移動できません。

対象を絞ったテスト

テストではバイト単位で正確な上流の応答を偽装し、以下を検証します。

• 未対応サイズや無効なサイズの場合に Undertow が呼び出されないこと。
• ソースエラー、プロデューサー利用不可の結果、古い時計、ダイジェスト不一致によってフェイルクローズすること。
• 不完全な Undertow 会場マップや、変換、深度、コスト、権利、PIT、デプロイ済み SHA、権限フィールドの不整合によってフェイルクローズすること。
• 正確な応答ハッシュ、ネイティブダイジェストの保持、および両方の製品における厳密な注文順のリクエストハッシュ紐付け。
• ペーパーレシートがオペレーターポリシーのもとで合格し、制限されること。
• ライブレシートは決して合格せず、適用対象外のブローカープレビューを伴うこと。
• 条件付きの最小限の LiquiLens 投影。
• ネットワーク処理と決済処理の前に、サーバー所有のポリシー判定が行われること。
• x402 チャレンジ、オファーと本文の厳密な紐付け、検証、決済、永続的なリプレイ／照合、終端失敗の転送、Cookie を使用しない HTTP、保持期間に上限のあるトゥームストーン、古い応答の拒否、送金方法の正確な表示、設定のローテーション、ローカルオペレーター CLI の入出力安全性。
• オプトイン方式のクローズドスキーマテレメトリに、リクエストや決済の ID が含まれないこと。
• MCP のツール一覧／呼び出し、OpenAPI、サンドボックスヘッダー、厳密な JSON、サイズ制限。

このディレクトリは実装アーティファクトのみです。これをビルドまたはテストしても、公開サービスはデプロイも登録もされません。

任意のインストール測定

すべての公開チェックと MCP ツールは、アカウントやトラッキングヘッダーなしで動作します。 インテグレーションでは、ランダムな UUIDv4 を 1 つ生成して実行間で保持し、X-Liquilens-Client-Id として送信することで、再インストールを測定できます。アカウント、メールアドレス、ウォレット、機関の ID は絶対に送信しないでください。 ゲートウェイに記録されるのはキー付きハッシュのみです。インストールが実在の人物であることを確認するものではありません。

import os
import uuid
from pathlib import Path

identity_path = Path(".liquilens-installation-id")
try:
    descriptor = os.open(identity_path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
except FileExistsError:
    pass
else:
    with os.fdopen(descriptor, "w") as handle:
        handle.write(str(uuid.uuid4()))
headers = {"X-Liquilens-Client-Id": identity_path.read_text().strip()}
# Add these optional headers to your existing REST or MCP HTTP client.

オペレーターのスモークテストでは、X-Liquilens-Traffic-Class: synthetic も送信する必要があります。非公開の標準出力設定、コホートの上限、スコアカードのコマンドについては、測定仕様を参照してください。