# valorem-mev-mcp

**Model Context Protocol (MCP) server for Valorem MEV Intelligence.**

Gives any MCP-compatible LLM agent (Claude Desktop, ChatGPT, Cursor, etc.) direct access to real-time MEV and DeFi data via Valorem's x402-paid API endpoints. Payments are made in USDC on Base mainnet.

---

## Tools

| Tool | Endpoint | Cost | Description |
|---|---|---|---|
| `catalog` | `GET /catalog` | Free | Full service catalog with all endpoints and prices |
| `liquidation_watchlist` | `GET /liquidations/watchlist` | $0.50 | Aave V3 near-liquidation positions — health factors, collateral, debt |
| `decoded_hints` | `GET /hints/decoded` | $0.10 | Last 50 decoded MEV-Share hints — swap direction, pool, token pair |
| `builder_stats` | `GET /builders/stats` | $0.25 | Per-builder acceptance rates for Flashbots, Titan, Beaver, BuilderNet, Quasar |
| `agent_intelligence` | `GET /agents/intelligence` | $1.00 | Agent wallet tracking — active wallets, x402 spend patterns, top providers |
| `pool_spreads` | `GET /pools/spreads` | $0.05 | L2 arb opportunities across 125+ Base + Arbitrum pools |
| `token_safety` | `GET /tokens/safety?token=` | $0.02 | Token tax/rebase/reflect classification by contract address |
| `rpc_health` | `GET /rpc/health` | $0.01 | RPC provider health — latency, error rates, uptime |
| `rpc_proxy` | `POST /rpc/proxy` | $0.001 | Premium Reth L1 RPC proxy (~6 ms latency) — any JSON-RPC method |

---

## Payment Modes

### Free Mode (default)

No private key required. When an API call returns `HTTP 402`, the server surfaces the payment requirements to the agent as a formatted message. The agent or user can then pay externally and retry.

```bash
npx valorem-mev-mcp
```

### Paid Mode (auto-pay)

Set the `PRIVATE_KEY` environment variable to an EVM private key with USDC on Base mainnet. The server uses `@x402/fetch` + `@x402/evm` to automatically sign and submit payments, then retries the request transparently.

```bash
PRIVATE_KEY=0xYourPrivateKeyHere npx valorem-mev-mcp
```

> **Security**: Never commit your private key. Use a dedicated spending wallet with only the USDC you intend to spend. The key never leaves your machine.

---

## Installation

### Global install

```bash
npm install -g valorem-mev-mcp
valorem-mev-mcp
```

### npx (no install)

```bash
npx valorem-mev-mcp
```

### Local development

```bash
git clone https://github.com/advalorem/valorem-mev-mcp
cd valorem-mev-mcp
npm install
node src/index.js
```

---

## Connecting to Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

### Free mode

```json
{
  "mcpServers": {
    "valorem-mev": {
      "command": "npx",
      "args": ["valorem-mev-mcp"]
    }
  }
}
```

### Paid mode

```json
{
  "mcpServers": {
    "valorem-mev": {
      "command": "npx",
      "args": ["valorem-mev-mcp"],
      "env": {
        "PRIVATE_KEY": "0xYourPrivateKeyHere"
      }
    }
  }
}
```

Restart Claude Desktop after editing. The tools will appear in the tool selector.

---

## Connecting to ChatGPT (Actions / Plugins)

ChatGPT plugins and Actions use an HTTP-based transport. To bridge this MCP server to HTTP, use [`mcp-proxy`](https://github.com/sparfenyuk/mcp-proxy) or the [OpenAI MCP adapter](https://platform.openai.com/docs/mcp):

```bash
# Install the bridge
npm install -g @modelcontextprotocol/proxy

# Run valorem-mev-mcp behind an HTTP proxy on port 3000
mcp-proxy --port 3000 -- npx valorem-mev-mcp
```

Then point your ChatGPT Action or plugin manifest at `http://localhost:3000`.

---

## Connecting to Cursor / Windsurf / Other Clients

Most IDE-based MCP clients accept a command + args configuration identical to Claude Desktop. Add this to your client's MCP server list:

```json
{
  "command": "npx",
  "args": ["valorem-mev-mcp"],
  "env": {
    "PRIVATE_KEY": "0xOptionalForAutoPay"
  }
}
```

---

## Tool Usage Examples

### Get service catalog (free)

```
Use the catalog tool to show me what MEV data is available.
```

### Check near-liquidation positions

```
Call liquidation_watchlist and tell me which Aave V3 positions are closest to liquidation.
```

### Classify a token

```
Use token_safety to check if 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 is a tax token.
```

### Proxy an eth_call

```
Use rpc_proxy to call eth_blockNumber with params [].
```

---

## Architecture

```
Claude / ChatGPT / Cursor
        │
        │  MCP stdio transport (JSON-RPC 2.0)
        ▼
valorem-mev-mcp  (this server)
        │
        │  HTTPS + optional x402 payment header
        ▼
https://18-220-76-66.nip.io/engine-api/x402
        │
        ▼
Valorem MEV Intelligence API (Base mainnet USDC payments)
```

### x402 Payment Flow

```
1. Server calls API endpoint (no payment header)
2. API returns HTTP 402 with X-PAYMENT-REQUIRED header
3a. FREE mode: 402 details returned to agent as text
3b. PAID mode: @x402/fetch parses requirements, signs USDC EIP-712 permit
                with viem private key account, retries with X-PAYMENT header
4. API verifies payment, returns 200 with data
```

---

## Environment Variables

| Variable | Required | Description |
|---|---|---|
| `PRIVATE_KEY` | No | EVM private key (hex, `0x`-prefixed or raw) for auto-payment in paid mode |

---

## Requirements

- Node.js ≥ 18
- npm ≥ 8

---

## License

MIT — see [LICENSE](LICENSE)

---

## Links

- **Valorem**: https://advalorem.io
- **x402 Protocol**: https://x402.org
- **MCP Specification**: https://modelcontextprotocol.io
- **@modelcontextprotocol/sdk**: https://www.npmjs.com/package/@modelcontextprotocol/sdk