Arsenal Decision Engine

Arsenal Decision Engine 🛡️

自主 AI Agent 的风险验证层（DeFAI）

方法和原始结果已发布 — 回测脚本 · 结果数据（180 天的 Binance ETH/USDC 日收盘价）： 🔬 盈亏平衡区间是一个确定性的代数边界（即 IL = 累计收益的位置）。任何价格比保持在 [lower_be, upper_be] 内的头寸，按数学定义均有 R_net > 0——这不是概率模型。 📐 此引擎负责测量，而非预测。我们不宣称任何预测准确率——请阅读已发布的结果文件，自行判断此方法。

---

使命

将 DeFi 的不确定性转化为供自主 Agent 使用的确定性、可执行风险指标。 我们不运行有状态交易机器人，也不生成推测性预测信号；我们提供无状态风险中间件层，供 Agent 在部署或维护标准恒定乘积／全区间 LP 头寸之前调用。

专为 Agent 打造。每个 IP 每天免费调用 100 次——无需钱包、无需注册，也包含自定义参数。 网关中已实现 L402 付款路径，但尚未在生产环境中启用：目前，此引擎可免费使用。

---

此引擎的功能

自主 Agent 在投入资金或调整标准恒定乘积／全区间 LP 头寸（例如 Uniswap V2 或全区间 V3）之前，会将池参数（APY、价格比、持有天数）提交到我们的 API。引擎会计算精确的数学风险、净收益（$R_{net}$）以及动态盈亏平衡区间边界。

• 无需大模型。没有幻觉。纯代数计算。
• **复杂度：**时间和内存均为 $\mathcal{O}(1)$。
• **延迟：**本地执行时间 $< 15\text{ms}$。

两种调用方式

1. MCP JSON-RPC — MCP 注册表中公布的端点

POST https://api.arsenal-quant.com/mcp

{"jsonrpc":"2.0","id":1,"method":"tools/call",
 "params":{"name":"evaluate_pool",
           "arguments":{"apy":0.20,"price_ratio":0.85,"days_held":30}}}

标准 MCP 握手：initialize → tools/list → tools/call。支持通过可流式 HTTP 和 stdio 调用。

2. REST 便捷路由 — 无需 MCP 客户端

GET https://api.arsenal-quant.com/mcp/evaluate?apy=0.20&price_ratio=0.85&days_held=30

两种路由使用相同的计算逻辑和配额。请注意，/mcp/evaluate 仅支持 GET：向该路径发送 POST 会返回 405 Allow: GET，因为 JSON-RPC 应使用 /mcp。

引擎响应（JSON 契约）

{
  "impermanent_loss_pct": 0.3292,
  "accumulated_yield_pct": 1.6438,
  "r_net_pct": 1.3146,
  "il_to_yield_ratio": 0.2,
  "risk_level": "LOW",
  "breakeven_corridor": {
    "lower_ratio": 0.6941,
    "upper_ratio": 1.4407,
    "interpretation": "Position remains profitable if price ratio stays within [0.6941, 1.4407]"
  },
  "inputs": {
    "apy": 0.2,
    "price_ratio": 0.85,
    "days_held": 30
  },
  "source": "Arsenal Decision Engine v2.0",
  "oracle_signature": "<HMAC-SHA256 hex — illustrative placeholder, yours will differ>",
  "layer": "FREE"
}

layer 表示调用的服务方式：在免费配额内为 FREE，验证 L402 付款后为 PREMIUM。上方示例中的调用由 FREE 提供服务。

---

访问和定价

• 免费层级 — evaluate_pool： 每个 IP 每天调用 100 次，包含自定义参数。 无需 Lightning 钱包。这是目前唯一提供的层级。
• **超出免费配额：**网关会执行 L402 挑战，并返回带有 WWW-Authenticate 标头的 402。付款渠道尚未在生产环境中启用——目前开具的发票无法结算，也不期待或接受任何付款。付费层级目前仅已公布，尚不可用。
• **GET /mcp/audit/latest：**每个 IP 每小时可免费调用 3 次；超出后，该路由会返回 402。此响应用于说明协议，并非实际付款渠道。

---

Python 集成示例

import urllib.request
import urllib.error
import json
import re
import os

API_URL = "https://api.arsenal-quant.com/mcp/evaluate?apy=0.20&price_ratio=0.85&days_held=30"
LNBITS_URL = "https://demo.lnbits.com"

# LNbits requires a wallet key with send permission to pay an invoice.
# Use a DEDICATED wallet funded with a small working balance, and never the key
# of a wallet holding significant funds. Keep it in the environment, never in code.
LNBITS_PAYMENT_KEY = os.getenv("LNBITS_PAYMENT_KEY")

def query_risk_oracle():
    req = urllib.request.Request(API_URL, method="GET")
    req.add_header("x-agent-id", "autonomous-lp-bot")

    try:
        with urllib.request.urlopen(req) as resp:
            return json.loads(resp.read().decode('utf-8'))
    except urllib.error.HTTPError as e:
        if e.code == 402:
            auth_header = e.headers.get("WWW-Authenticate")
            macaroon = re.search(r'token="([^"]+)"', auth_header).group(1)
            invoice = re.search(r'invoice="([^"]+)"', auth_header).group(1)

            pay_req = urllib.request.Request(
                f"{LNBITS_URL}/api/v1/payments",
                data=json.dumps({"out": True, "bolt11": invoice}).encode(),
                headers={"X-Api-Key": LNBITS_PAYMENT_KEY, "Content-Type": "application/json"}
            )
            with urllib.request.urlopen(pay_req) as pay_resp:
                preimage = json.loads(pay_resp.read().decode())["preimage"]

            retry_req = urllib.request.Request(API_URL, method="GET")
            retry_req.add_header("Authorization", f"L402 {macaroon}:{preimage}")
            retry_req.add_header("x-agent-id", "autonomous-lp-bot")

            with urllib.request.urlopen(retry_req) as final_resp:
                return json.loads(final_resp.read().decode('utf-8'))
        else:
            raise

if __name__ == "__main__":
    evaluation = query_risk_oracle()
    print(f"Risk Level     : {evaluation['risk_level']}")
    print(f"R_net          : {evaluation['r_net_pct']:+.4f}%")
    print(f"Breakeven      : [{evaluation['breakeven_corridor']['lower_ratio']}, {evaluation['breakeven_corridor']['upper_ratio']}]")

---

开发者集成

• 集成指南和 MCP 文档：COOKBOOK.md
• MCP 自动发现卡片：https://api.arsenal-quant.com/.well-known/mcp/server-card.json

为什么按调用计费是预期模式

此引擎无法防止亏损，也不承诺能为你节省多少钱。它的功能是以确定性的方式，在 $\mathcal{O}(1)$ 时间内计算某个头寸处于盈亏平衡边界之上还是之下。每个响应都带有对结果进行 HMAC 标记的标签，让引擎能够检测自身输出是否遭到篡改；这是一种对称的来源标记，并非第三方可独立验证的证明。

预期模式是按调用计费，因此费用可以像其他输入一样纳入预算。该模式目前尚未启用：现在所有调用均免费。