{
  "markdown": "# Arsenal Decision Engine 🛡️\n**The Risk-Validation Layer for Autonomous AI Agents (DeFAI)**\n\n[![Arsenal-Quant-Project MCP server](https://glama.ai/mcp/servers/Faouzi122/Arsenal-Quant-Project/badges/card.svg)](https://glama.ai/mcp/servers/Faouzi122/Arsenal-Quant-Project)\n[![smithery badge](https://smithery.ai/badge/khelifa-faouzi16/arsenal-decision-engine)](https://smithery.ai/servers/khelifa-faouzi16/arsenal-decision-engine)\n\n> **Method and raw results are published** — [backtest script](./decision_engine/07_Backtest_Engine/run_empirical_backtest.py) · [result data](./decision_engine/07_Backtest_Engine/data/) (180 days of Binance ETH/USDC daily closes):\n> 🔬 **Breakeven Corridor** is a deterministic algebraic boundary (where IL = accumulated yield). Any position whose price ratio stays within `[lower_be, upper_be]` has R_net > 0 by mathematical definition — not a probabilistic model.\n> 📐 This engine **measures**; it does not forecast. No predictive-accuracy figure is claimed — read the published result files and judge the method for yourself.\n\n---\n\n## Mission\n\n**Transform DeFi uncertainty into deterministic, actionable risk metrics for autonomous agents.**\nWe do not run stateful trading bots or generate speculative prediction signals; we provide a stateless risk middleware layer that agents query before deploying or maintaining standard constant-product / full-range LP positions.\n\nBuilt for agents. **100 free calls per IP per day — no wallet, no sign-up, custom parameters included.** An L402 payment path is implemented in the gateway but is **not operational in production**: today, the engine is free to use.\n\n---\n\n## What This Engine Does\n\nBefore an autonomous agent deploys capital or adjusts a standard constant-product / full-range LP position (such as Uniswap V2 or full-range V3), it submits the pool parameters (APY, price ratio, days held) to our API. The engine computes the exact mathematical risk, the net return ($R_{net}$), and the dynamic **Breakeven Corridor** bounds.\n\n- **No LLMs. No hallucinations. Pure algebraic calculation.**\n- **Complexity:** $\\mathcal{O}(1)$ time and memory.\n- **Latency:** $< 15\\text{ms}$ local execution.\n\n### Two ways to call it\n\n**1. MCP JSON-RPC — the endpoint advertised on the MCP registry**\n```\nPOST https://api.arsenal-quant.com/mcp\n```\n```json\n{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/call\",\n \"params\":{\"name\":\"evaluate_pool\",\n           \"arguments\":{\"apy\":0.20,\"price_ratio\":0.85,\"days_held\":30}}}\n```\nStandard MCP handshake: `initialize` → `tools/list` → `tools/call`. Available over\nstreamable HTTP and stdio.\n\n**2. REST convenience route — no MCP client required**\n```\nGET https://api.arsenal-quant.com/mcp/evaluate?apy=0.20&price_ratio=0.85&days_held=30\n```\nBoth routes run the same calculation and the same quota. Note that\n`/mcp/evaluate` is **GET-only**: a `POST` to that path returns `405 Allow: GET`,\nbecause JSON-RPC belongs on `/mcp`.\n\n### Engine Response (JSON Contract)\n```json\n{\n  \"impermanent_loss_pct\": 0.3292,\n  \"accumulated_yield_pct\": 1.6438,\n  \"r_net_pct\": 1.3146,\n  \"il_to_yield_ratio\": 0.2,\n  \"risk_level\": \"LOW\",\n  \"breakeven_corridor\": {\n    \"lower_ratio\": 0.6941,\n    \"upper_ratio\": 1.4407,\n    \"interpretation\": \"Position remains profitable if price ratio stays within [0.6941, 1.4407]\"\n  },\n  \"inputs\": {\n    \"apy\": 0.2,\n    \"price_ratio\": 0.85,\n    \"days_held\": 30\n  },\n  \"source\": \"Arsenal Decision Engine v2.0\",\n  \"oracle_signature\": \"<HMAC-SHA256 hex — illustrative placeholder, yours will differ>\",\n  \"layer\": \"FREE\"\n}\n```\n`layer` reports how the call was served: `FREE` while inside the free quota,\n`PREMIUM` once an L402 payment has been verified. The call shown above is\nserved as `FREE`.\n\n---\n\n## Access and Pricing\n\n- **Free tier — `evaluate_pool`:** **100 calls per IP per day, custom parameters\n  included.** No Lightning wallet is needed. **This is the only tier currently in\n  service.**\n- **Beyond the free quota:** the gateway implements the L402 challenge and returns\n  `402` with a `WWW-Authenticate` header. **The payment rail is not operational in\n  production** — invoices issued today are not settleable, and no payment is expected\n  or accepted. Treat the paid tier as announced, not available.\n- **`GET /mcp/audit/latest`:** 3 free calls per IP per hour; beyond that the route\n  returns `402`. That response documents the protocol; it is not a live payment path.\n\n---\n\n## Python Integration Example\n\n```python\nimport urllib.request\nimport urllib.error\nimport json\nimport re\nimport os\n\nAPI_URL = \"https://api.arsenal-quant.com/mcp/evaluate?apy=0.20&price_ratio=0.85&days_held=30\"\nLNBITS_URL = \"https://demo.lnbits.com\"\n\n# LNbits requires a wallet key with send permission to pay an invoice.\n# Use a DEDICATED wallet funded with a small working balance, and never the key\n# of a wallet holding significant funds. Keep it in the environment, never in code.\nLNBITS_PAYMENT_KEY = os.getenv(\"LNBITS_PAYMENT_KEY\")\n\ndef query_risk_oracle():\n    req = urllib.request.Request(API_URL, method=\"GET\")\n    req.add_header(\"x-agent-id\", \"autonomous-lp-bot\")\n\n    try:\n        with urllib.request.urlopen(req) as resp:\n            return json.loads(resp.read().decode('utf-8'))\n    except urllib.error.HTTPError as e:\n        if e.code == 402:\n            auth_header = e.headers.get(\"WWW-Authenticate\")\n            macaroon = re.search(r'token=\"([^\"]+)\"', auth_header).group(1)\n            invoice = re.search(r'invoice=\"([^\"]+)\"', auth_header).group(1)\n\n            pay_req = urllib.request.Request(\n                f\"{LNBITS_URL}/api/v1/payments\",\n                data=json.dumps({\"out\": True, \"bolt11\": invoice}).encode(),\n                headers={\"X-Api-Key\": LNBITS_PAYMENT_KEY, \"Content-Type\": \"application/json\"}\n            )\n            with urllib.request.urlopen(pay_req) as pay_resp:\n                preimage = json.loads(pay_resp.read().decode())[\"preimage\"]\n\n            retry_req = urllib.request.Request(API_URL, method=\"GET\")\n            retry_req.add_header(\"Authorization\", f\"L402 {macaroon}:{preimage}\")\n            retry_req.add_header(\"x-agent-id\", \"autonomous-lp-bot\")\n\n            with urllib.request.urlopen(retry_req) as final_resp:\n                return json.loads(final_resp.read().decode('utf-8'))\n        else:\n            raise\n\nif __name__ == \"__main__\":\n    evaluation = query_risk_oracle()\n    print(f\"Risk Level     : {evaluation['risk_level']}\")\n    print(f\"R_net          : {evaluation['r_net_pct']:+.4f}%\")\n    print(f\"Breakeven      : [{evaluation['breakeven_corridor']['lower_ratio']}, {evaluation['breakeven_corridor']['upper_ratio']}]\")\n```\n\n---\n\n## Developer Integration\n- Integration cookbook & MCP guides: [`COOKBOOK.md`](./decision_engine/08_SDK_Wrappers/COOKBOOK.md)\n- MCP auto-discovery card: `https://api.arsenal-quant.com/.well-known/mcp/server-card.json`\n\n## Why per-call pricing is the intended model\n\nThis engine does not prevent losses, and it makes no claim about how much money it\nsaves you. What it does is compute — deterministically, in $\\mathcal{O}(1)$ — whether\na position sits above or below its breakeven boundary. Each response carries an HMAC\ntag over the result, which lets the engine detect tampering with its own output; it is\na symmetric provenance marker, **not a proof a third party can verify independently**.\n\nThe intended model is per-call pricing, so the cost can be budgeted like any other\ninput. **That model is not yet in service: today every call is free.**\n",
  "bytes": 7453,
  "sha": "14ea24de41eb648d3c3d570574680c06663a5456e1a6c151eba731aee3db1281",
  "repo_slug": "faouzi122/arsenal-quant-project",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_faouzi122_arsenal_decision_eng_21704c66/readme"
}