<p align="center">
  <img src="./assets/logo.png" width="130" height="130" alt="DeFi Quant Execution MCP Logo" />
</p>

# DeFi Quant Execution MCP

[![Smithery Compatible](https://img.shields.io/badge/Smithery-Compatible-blue.svg)](https://smithery.ai)
[![Model Context Protocol](https://img.shields.io/badge/MCP-Standard%20v1.0-emerald.svg)](https://modelcontextprotocol.io)
[![Base L2 Settlement](https://img.shields.io/badge/Base%20L2-USDC%20x402-blue.svg)](https://base.org)
[![Tools](https://img.shields.io/badge/Tools-5%20Curated-purple.svg)](#included-tools)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

**Exact Uniswap v3 Q64.96 tick math, MEV sandwich risk simulation, flashloan arbitrage profit modeling, and Base blob gas estimation.**

Built specifically for Algorithmic traders, MEV searchers, Base L2 DeFi bot builders, and autonomous portfolio managers.

---

## ⚡ Quickstart

### Smithery Install
```bash
smithery skill add whambammy/defi-quant-execution-mcp
```

### Claude Desktop / Cursor (`claude_desktop_config.json`)
```json
{
  "mcpServers": {
    "defi-quant-execution-mcp": {
      "command": "npx",
      "args": ["-y", "@whambammy/defi-quant-execution-mcp"],
      "env": {
        "PAYMENT_WALLET": "0x9793E7269b3301893318dEa8338576Ba612F39B3",
        "BASE_RPC_URL": "https://mainnet.base.org"
      }
    }
  }
}
```

---

## 🛠️ Included Tools

| Tool Name | Price (USDC) | Capability |
| :--- | :---: | :--- |
| `uniswap_v3_tick_math_precise` | $0.035 | Arbitrary-precision Q64.96 fixed-point math calculator for Uniswap v3 square root price $(\sqrt{P})$, tick-to-price conversion, and exact liquidity fee compounding. |
| `mev_sandwich_risk_simulator` | $0.045 | Simulates pending swaps against Uniswap v3/v4 tick liquidity to compute exact MEV sandwich vulnerability, maximum extractable value, and safe slippage limits. |
| `compute_uniswap_v3_quote` | $0.02 | Calculates exact sqrtPriceX96 tick mathematics, price impact, and swap output amounts for concentrated liquidity pools on Base. |
| `flashloan_arbitrage_profit_calculator` | $0.045 | Calculates net arbitrage profit for multi-hop flashloans across Base L2 DEXes, factoring pool fee tiers, price impact, loan premium (0.09%), and gas burnt. |
| `base_l2_blob_gas_price_projector` | $0.035 | Evaluates EIP-4844 blob gas fee dynamics and Base L2 sequencing costs, projecting optimal block inclusion timing for transaction batch settlement. |


---

## 🔄 End-to-End Workflow

A trading agent identifies a potential arbitrage opportunity -> computes exact Q64.96 tick math across Uniswap v3 pools -> simulates MEV sandwich vulnerability -> projects Base L2 blob gas fees -> confirms net profitability before executing.

---

## 💰 The x402 Base L2 Micropayment Protocol

When an agent invokes a tool without payment, the server responds with a deterministic `HTTP 402 Payment Required` challenge containing:
- Target tool price in USDC
- Base Native USDC Contract: `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`
- Recipient payout wallet address
- Single-use cryptographic nonce

Once broadcasted on Base L2, resubmitting with `paymentSignature` unlocks deterministic execution.

---

## 📄 License
MIT License. Created by [Whambammy](https://github.com/Whambammy).