# Omni Execution MCP

A production-grade, 100% non-custodial Model Context Protocol (MCP) server providing deterministic execution payloads, official quote aggregations, and transparent integrator fee attribution across 6 major DeFi and CeFi protocols.

Built strictly with Python 3.10+ standard library (zero external pip dependencies required).

---

## Non-Custodial Architecture

`omni-execution-mcp` is designed from first principles with **zero custody** and **zero private key access**:

1. **No Key Storage or Handling**: The MCP server never accepts, requires, or stores private keys or seed phrases.
2. **Deterministic Payload Construction**: All actions returned by this server are unsigned transaction payloads (EIP-712 typed data, L1 actions, or official quote URLs).
3. **Client-Side Signature**: The client application, desktop agent, or connected wallet (e.g., MetaMask, Rabby, Phantom, Ledger) signs and broadcasts the transaction directly.
4. **Transparent Fee Attribution**: Integrator builder codes, referral accounts, and partner basis points are transparently included in the generated payloads and disclosed in response metadata.

---

## The 6 Monetization Fee Rails

| Rail # | Protocol | Asset / Venue | Attribution Mechanism | Default Fee | Protocol Cap | Required Environment Variable(s) |
|---|---|---|---|---|---|---|
| **1** | **Hyperliquid** | L1 Perps & Spot DEX | Builder Code (`builder: {b, f}`) + `approveBuilderFee` | 3 bps (`0.03%`) | 10 bps (`0.10%`) perps / 100 bps (`1.00%`) spot | `HYPERLIQUID_BUILDER_ADDRESS`, `HYPERLIQUID_BUILDER_TENTHS_BPS` |
| **2** | **Jupiter v6** | Solana DEX Aggregation | `platformFeeBps` query param + `feeAccount` in `/v6/swap` | 5 bps (`0.05%`) | 100 bps (`1.00%`) | `JUPITER_REFERRAL_ACCOUNT`, `JUPITER_FEE_BPS` |
| **3** | **LI.FI** | Cross-Chain Bridges | FeeForwarder (`integrator` + `fee` decimal param) | 5 bps (`0.05%`) | 100 bps (`1.00%`) | `LIFI_INTEGRATOR_ID`, `LIFI_FEE_BPS` |
| **4** | **CoW Protocol** | MEV-Protected Batch Auctions | Canonical `appData` JSON (`metadata.partnerFee`) | 5 bps (`0.05%`) | 100 bps (`1.00%`) | `COW_PARTNER_FEE_RECIPIENT`, `COW_PARTNER_FEE_BPS` |
| **5** | **Polymarket** | Prediction Market CLOB | Builder Program HMAC-SHA256 headers | Volume Rebate | N/A | `POLY_BUILDER_API_KEY`, `POLY_BUILDER_SECRET`, `POLY_BUILDER_PASSPHRASE` |
| **6** | **0x Swap API v2** | EVM DEX Aggregation | AllowanceHolder `swapFeeBps` & `swapFeeRecipient` | 5 bps (`0.05%`) | 100 bps (`1.00%`) | `ZEROX_FEE_RECIPIENT`, `ZEROX_FEE_BPS` |

---

## Available MCP Tools

The server exposes 7 standard tools implementing strict JSON Schema contracts:

1. `omni_fee_status`: Inspect configured fee basis points, protocol caps, and active rail status.
2. `hyperliquid_build_order`: Generate unsigned Hyperliquid L1 order payloads and `approveBuilderFee` actions.
3. `jupiter_solana_quote`: Generate Jupiter v6 quote URLs with referral fee parameters and unsigned swap payload templates.
4. `lifi_crosschain_quote`: Generate LI.FI `/v1/quote` cross-chain bridge parameters with integrator FeeForwarder decimal string.
5. `cow_mev_safe_order`: Generate unsigned CoW Protocol order payloads and canonical `appData` JSON with MEV-safe partner fees.
6. `polymarket_builder_order`: Generate unsigned Polymarket CLOB order previews with HMAC-SHA256 Builder Program attribution headers.
7. `zerox_evm_quote`: Generate 0x Swap API v2 `/swap/allowance-holder/quote` parameters with affiliate swap fees.

---

## Quickstart & Setup

### 1. Local Run (Zero pip dependencies)

```bash
# Clone and enter directory
cd omni-execution-mcp

# Copy environment variable template
cp .env.example .env

# Run stdio MCP server directly
python3 -m omni_execution_mcp.server
```

### 2. Configuration in Claude Desktop / Code

Add the following entry to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "omni-execution-mcp": {
      "command": "python3",
      "args": [
        "-m",
        "omni_execution_mcp.server"
      ],
      "cwd": "/path/to/omni-execution-mcp",
      "env": {
        "HYPERLIQUID_BUILDER_ADDRESS": "0xc8dc4ecb93c4c665Fad07E1261F5f7D60e3C6E0F",
        "HYPERLIQUID_BUILDER_TENTHS_BPS": "30",
        "JUPITER_REFERRAL_ACCOUNT": "49sNhYNVSFxBuMPh5S2EC6Wkyay7mBWEPVv7pcyHJDxu",
        "JUPITER_FEE_BPS": "5",
        "LIFI_INTEGRATOR_ID": "omni-execution-mcp",
        "LIFI_FEE_BPS": "5",
        "COW_PARTNER_FEE_RECIPIENT": "0xc8dc4ecb93c4c665Fad07E1261F5f7D60e3C6E0F",
        "COW_PARTNER_FEE_BPS": "5",
        "ZEROX_FEE_RECIPIENT": "0xc8dc4ecb93c4c665Fad07E1261F5f7D60e3C6E0F",
        "ZEROX_FEE_BPS": "5"
      }
    }
  }
}
```

### 3. Configuration in Cursor

In Cursor Settings -> Features -> MCP -> Add New MCP Server:
- **Name**: `omni-execution`
- **Type**: `command`
- **Command**: `python3 -m omni_execution_mcp.server`

### 4. Configuration in Hermes / Smithery

The repository includes `smithery.yaml` and `mcp.json` ready for automatic discovery on Smithery, Glama, and mcp.so registries.

---

## Testing

Run the full unit test suite with standard library `unittest`:

```bash
python3 -m unittest discover -s tests -v
```