LiquiLens Trade Safety Gateway

LiquiLens 交易安全网关

此集成是面向 AI 交易副驾驶的只读沙盒适配器。它接受一个精确的交易安全请求和一项操作员策略，读取少量固定的公共证据端点，并签发 liquilens_evidence.trade_safety 定义的确定性 SHA-256 专用回执。

它不是订单网关。它没有经纪商凭据、经纪商预览、订单提交路由、建议路由、自动调整规模行为、托管、交易结算或真实资金操作权限。可选的 x402 路由可结算访问同一评估所需的付款；付款无法更改策略、证据、结果、回执权限或订单路径。每个响应都包含 X-Trade-Safety-Mode: sandbox、X-Trade-Safety-Authority: read-only 和 X-Trade-Safety-Execution: disabled。实时模式评估会确定性地返回 unavailable，因为证据仅供参考、回执未经租户身份验证，且经纪商预览引用为 not_applicable。

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 信封。重试时请使用退避和抖动；单独启用的付费请求还必须遵循结算日志的对账规则。

POST 预算已满时，健康检查和发现 GET 请求仍可用。此控制不会存储 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；接受的通知会返回 HTTP 202，不含 JSON-RPC 正文。
• 浏览器发起的 MCP 请求仅接受规范的 HTTPS 发行方源；非浏览器客户端可以省略 Origin，其他任何源都会返回 HTTP 403。接受的旧版 notifications/initialized POST 会返回 HTTP 202，不含正文。
• FastAPI 在 /openapi.json 发布生成的 OpenAPI，并在 /docs 提供 Swagger UI。

这里刻意没有任何形似执行操作的 MCP 工具。

由服务端管理的策略准入

协议接受由运营方编写的策略，但公共网关不允许匿名调用方重新定义安全底线。在发起任何源请求或进行 x402 验证之前，网关会根据服务端管理的约束范围审查所提供的策略：

• Seiche 和 Undertow 仍为必选项，STRESS 仍为受限状态；
• Seiche 的来源数据时效上限不得超过 8 天，Undertow 和 LiquiLens 的上限不得超过 1 天；
• 名义金额、退出成本和交易场所价差限制必须存在，且分别不得超过 100,000 USD、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 访问与 Agent 发现

当所有 TRADE_SAFETY_X402_* 设置均未配置时，x402 处于禁用状态。完整配置会添加付费路由，并发布带有 HTTP Bazaar 发现元数据的精确 x402 v2 报价。该报价通过专用报价密钥绑定规范请求正文、资源、价格、资产、收款方、ResourceInfo 和必需扩展。运行时会在评估前验证，仅在受保护响应生成后结算，并且只释放日志中记录的精确字节。

付款身份和交易来源信息保存在私有结算日志中，绝不会出现在 Trade Safety 收据或采用情况遥测中。已结算的付款不会将仅用于上下文的证据变成可执行报价，也不会让安全结果永远保持新鲜。有关配置、本地运营方命令 liquilens-trade-safety-x402-reconcile、状态恢复和激活门槛，请参阅 TRADE-SAFETY-X402.md。该命令绝不会调用 facilitator；运营方必须先独立确认状态为已结算或确定未结算，才能更改状态不确定的日志条目。

固定证据适配器

产品	固定请求	回执状态与边界
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；网关会发送规范 Trade Safety 请求哈希，以及精确的 observe/paper BTC/USD 卖出档位。Undertow 必须回显该绑定，并提供已验证的 PIT 头部/链、已部署 SHA、已批准的派生元数据权利、完整的六个交易场所覆盖范围、一致的时钟和完整的上下文摘要。
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 实体会独立进行哈希处理。来源、观测/截至时间、知识、生产方检索、网关检索、原生过期时间以及本地回执过期时钟彼此独立。

Undertow 的完整性以名单为范围，而非对整个市场的声明。 网关要求与其声明的六个 CEX 名单精确匹配，并在使用结果前交叉核对报价换算、所需深度区间、每个交易场所的基点和美元成本、最佳/最差交易场所、价差、锚定状态、证明、权利和过期时间。名单外的 CEX、DEX 和 Agent 原生交易场所按设计均未测量；添加或更改交易场所必须经过审核并更新合约，而不能默默接受。

故障关闭与网络边界

• 在任何出站调用之前，都会验证请求和策略，包括二者的交叉引用、当前有效期以及可选的机构标识。
• 在任何出站调用或付款质询／验证之前，都会根据不可变的服务安全底线审查调用方策略。
• 目标、方法、MCP 工具名称和 URL 基址均为常量。请求正文无法提供 URL。
• 重定向、环境代理、Cookie、压缩、非 JSON 正文、非 200 响应、格式错误或包含重复键的 JSON、MCP 错误以及缺少 structuredContent 均会被拒绝。
• 请求正文上限为 64 KiB；源正文上限为 1 MiB；网关响应上限为 512 KiB。每项上游操作的总超时时间为 5 秒，连接超时时间为 2 秒。
• 符合条件的独立数据源会并发获取。源错误、生产方声明的不可用状态、本机时钟过期、摘要验证失败、请求哈希不匹配、证明失败或权限不匹配，都会成为该产品的类型化 unavailable 证据部分。由于 Seiche 和 Undertow 是必需产品，回执随后会故障关闭。
• 服务不会记录请求正文、响应正文、机密信息、账户数据或源异常。捆绑的命令会禁用访问日志。
• 每个证据部分和经纪商预览引用都包含 trade_safety_request_hash(request)。Undertow 也会接收并回显该哈希；Seiche 的原生投影摘要和请求哈希则会在经过哈希封存的回执中，通过单独的本地绑定摘要进行绑定。任何最接近档位的结果都不会被提升为精确订单证据。
• 只有 observe 和 paper 模式会发送给 Undertow。Live 和 buy 请求永远不会到达其卖方 paper-context 工具；这类请求会产生类型化的不可用证据。
• 如果请求同时包含名义金额和非空数量，在经纪商标准化的经济订单摘要和参考价格契约能够证明这两个字段描述的是同一敞口之前，请求不会发送给 Undertow。

访问公共数据源并不意味着拥有真实资金交易权或再分发权。因此，所有三个适配器在适用时都会声明 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 需要专用的报价绑定密钥，但仍无需钱包私钥或经纪商凭据。采用情况遥测也默认关闭；运营方可以显式选择一个私有的仅追加 JSONL 路径，具体说明见 TRADE-SAFETY-TRACTION.md。

容器构建

请从 evidence-carrier 仓库根目录构建，以确保镜像包含完全一致的根目录 Trade Safety 实现：

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 还需要允许访问唯一配置的结算服务，并为其日志提供私有持久化卷。未设置 x402 变量时，只读容器仅运行免费路由；若设置了这些变量，但没有可写的私有日志卷，启动将失败。公共边缘还必须设置有界请求配额；应用不会信任客户端提供的 IP 标头作为速率限制键。

发布工作流会将经过证明的多架构 OCI 软件包发布到 GHCR。该注册表制品用于分发，不是托管部署或授权下单的服务；它保留相同的只读、仅哈希沙箱边界，必须由采用者自行运行。独立的网关标签发布通道只发布 OCI；它会构建 wheel 作为验证证据，但不会发布该 wheel、sdist 或 GitHub Release。

网关 0.2.2 拥有独立的发布身份，因此发布它不会移动或复用不可变的核心 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 输入／输出安全；
• 启用时采用封闭模式的遥测，不包含请求或支付身份；以及
• MCP 工具清单／调用、OpenAPI、沙箱标头、严格 JSON 和大小限制。

此目录仅包含实现制品。构建或测试它不会部署或注册公共服务。

可选安装测量

所有公开检查和 MCP 工具均可在无需账户或追踪标头的情况下使用。 集成可以选择通过生成一个随机 UUIDv4、在多次运行间保留该 UUIDv4，并将其作为 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。有关私有 stdout 配置、 群组限制和评分卡命令，请参阅 测量约定。