# 🛡️ CHAINZ Sentinel MCP: Binance Agent OS Integration

[![Binance Agent OS](https://img.shields.io/badge/Binance-Agent%20OS-F0B90B?style=for-the-badge&logo=binance&logoColor=black)](https://binance.com)
[![Model Context Protocol](https://img.shields.io/badge/MCP-Standard%202024--11--05-blue?style=for-the-badge)](https://modelcontextprotocol.io)
[![NVIDIA NIM](https://img.shields.io/badge/NVIDIA-NIM%20GPU%20AI-76B900?style=for-the-badge&logo=nvidia&logoColor=white)](https://build.nvidia.com)
[![License](https://img.shields.io/badge/License-MIT-emerald?style=for-the-badge)](LICENSE)

> **Binance Agent OS Mini Hackathon Entry**  
> **Primary Track:** Track B — *Connect your MCPs and trade ($40,000 USDC)*  
> **Secondary Track:** Track A — *Build an AI agent with Agent OS ($20,000 USDC)*  

---

## 🌟 Executive Summary

**CHAINZ Sentinel MCP** is an institutional Model Context Protocol (MCP) server that supercharges **Binance Agent OS** with **sub-millisecond AI trade risk assessment** (powered by **NVIDIA NIM**) and cross-venue **zero-debt real-yield arbitrage**.

While traditional trading agents execute orders blindly based on raw prompt matching, CHAINZ Sentinel introduces an automated **capital preservation guard**:
1. **Pre-Trade Risk Sentinel:** Before any Binance trade executes, NVIDIA NIM evaluates market volatility and calculates exact liquidation hazard scores in $<50\text{ ms}$.
2. **Natural Language Intent Router:** Translates conversational user goals into validated spot and futures trading parameters.
3. **Real-Yield Alpha Arbitrage:** Real-time benchmarking comparing Binance Earn / Funding rates with CHAINZ Layer 1 on-chain real-yield vaults (AMM fee sharing + RWA dividends).
4. **Execution Safety Gate:** Blocks unsafe trades and automatically downsizes high-leverage orders to prevent liquidation spirals.

---

## 🏛️ System Architecture

```mermaid
flowchart TB
    subgraph Binance_Ecosystem [Binance Agent OS & Client Layer]
        User["User Prompt / Autonomous Trader"] --> AgentOS["Binance Agent OS"]
    end

    subgraph MCP_Layer [Chainz Sentinel MCP Server (JSON-RPC 2.0 stdio)]
        AgentOS <-->|"Model Context Protocol"| MCP["chainz-sentinel-mcp (Node.js)"]
        MCP --> Tool1["evaluate_trade_risk"]
        MCP --> Tool2["parse_trade_intent"]
        MCP --> Tool3["query_yield_arbitrage"]
        MCP --> Tool4["execute_hedged_trade"]
    end

    subgraph Intelligence_And_Execution [AI & Settlement Engines]
        Tool1 & Tool2 <-->|"Inference API"| NIM["NVIDIA NIM GPU Sentinel (integrate.api.nvidia.com)"]
        Tool3 <-->|"Real-Yield Oracle"| L1["CHAINZ Layer 1 Staking Vaults (Chain ID: 999402778)"]
        Tool4 <-->|"Order Routing"| BinanceAPI["Binance Spot / Futures API"]
    end
```

---

## 🛠️ Exposed MCP Tools

### 1. `evaluate_trade_risk`
* **Description:** Evaluates cryptocurrency trade risk, liquidation probability, and systemic volatility using NVIDIA NIM GPU-accelerated inference.
* **Inputs:** `symbol` (e.g. `BTCUSDT`), `side` (`BUY`/`SELL`), `amount`, `leverage` (default `1`), `currentPrice` (optional).
* **Outputs:** 
  * `risk_score` ($0 - 100$)
  * `verdict` (`APPROVED` / `CAUTION` / `REJECTED`)
  * `liquidation_buffer_pct` (Distance to liquidation)
  * `max_recommended_leverage`

### 2. `parse_trade_intent`
* **Description:** Translates conversational prompts into structured Binance trading parameters.
* **Inputs:** `prompt` (string)
* **Outputs:** `symbol`, `action`, `order_type`, `amount_usd`, `leverage`, `notes`.

### 3. `query_yield_arbitrage`
* **Description:** Benchmarks Binance Earn / Funding rates against CHAINZ zero-debt fee-sharing vaults (55% AMM fees + 30% RWA dividends + 15% bridge relayers).
* **Inputs:** `symbol` (`USDT`, `USDC`, `BTC`, `ETH`), `capitalUsd`.
* **Outputs:** Baseline yield, CHAINZ yield, Net Alpha APY spread, and recommended capital allocation.

### 4. `execute_hedged_trade`
* **Description:** Gates order execution against the pre-trade risk score, executing only when capital safety criteria are met.
* **Inputs:** `symbol`, `side`, `amountUsd`, `riskScore`, `overrideApproved`.
* **Outputs:** `status` (`FILLED` or `REJECTED`), `order_id`, `zero_debt_guard` status.

---

## 🚀 Quick Start: Connecting to Binance Agent OS

### Prerequisites
* Node.js v18+ (tested on Node v20/v24)
* No external npm package installations required! Zero internet drain.

### Step 1: Clone or Open the Directory
```bash
cd binance-agent-mcp
```

### Step 2: Test the Server Locally
Run the automated MCP test suite to simulate Binance Agent OS:
```bash
node test_mcp_client.mjs
```

Expected output:
```
======================================================================
🚀 Testing Chainz Sentinel MCP Server for Binance Agent OS
======================================================================

1. Testing 'initialize' handshake...
   ✅ Server Name: chainz-sentinel-mcp
   ✅ Protocol Version: 2024-11-05

2. Testing 'tools/list' discovery...
   ✅ Found 4 Tools: evaluate_trade_risk, parse_trade_intent, query_yield_arbitrage, execute_hedged_trade

3. Testing 'evaluate_trade_risk' (NVIDIA NIM GPU Sentinel)...
   ✅ Risk Score: 58 / 100
   ✅ Sentinel Verdict: CAUTION

4. Testing 'parse_trade_intent'...
   ✅ Derived Symbol: ETHUSDT, Action: BUY

5. Testing 'query_yield_arbitrage'...
   ✅ Binance: 7.2% APY vs CHAINZ: 18.4% APY (+11.2% Net Alpha)

6. Testing 'execute_hedged_trade'...
   ✅ Execution Status: FILLED (No liquidation hazard detected)

🎉 ALL TESTS PASSED (100% SUCCESS) — READY FOR BINANCE AGENT OS!
```

### Step 3: Add to Binance Agent OS Config
Add the server configuration into your Binance Agent OS MCP registry (`binance_agent_config.json`):

```json
{
  "mcpServers": {
    "chainz-sentinel": {
      "command": "node",
      "args": ["<PATH_TO_DIR>/index.mjs"],
      "env": {
        "NVIDIA_NIM_BASE_URL": "https://integrate.api.nvidia.com/v1",
        "NVIDIA_API_KEY": "<YOUR_NVIDIA_API_KEY>",
        "NVIDIA_DEFAULT_MODEL": "meta/llama-3.1-8b-instruct"
      }
    }
  }
}
```

---

## 🏆 Hackathon Alignment & Value Proposition

| Evaluation Criteria | How CHAINZ Sentinel Exceeds Expectations |
| :--- | :--- |
| **Technical Complexity** | Combines the **Model Context Protocol (MCP)** standard with **NVIDIA NIM sub-millisecond GPU inference** and **EVM Layer 1 smart contracts**. |
| **Real Trading Utility** | Prevents retail and algorithmic traders from catastrophic liquidation cascades through pre-trade AI safety gating. |
| **Zero External Bloat** | Fully self-contained Node.js JSON-RPC stdio engine that adheres to strict zero-dependency bandwidth guidelines. |
| **Cross-Ecosystem Synergy** | Bridges Binance's world-leading liquidity with CHAINZ asset-backed zero-debt financial architecture. |

---

## 📄 License
MIT License — Free and open-source for the Binance & Web3 AI community.