Quick Start

MEVScan exposes Ethereum MEV analysis as MCP tools and a real-time SSE push stream. Your API Key authenticates both.

1. Get your API Key

Sign in with Google on the login page. Your API Key is shown on the Dashboard.

2. Connect an AI tool

Paste the config below into your preferred AI coding tool. See Install in AI Tools for all supported clients.

claude mcp add mevscan https://eigenphi.com/sse \
          --transport sse \
          --header "Authorization: Bearer <YOUR_API_KEY>"

3. Ask a question

What MEV arbitrage happened in the last 100 blocks?

4. Subscribe to the push stream (optional)

Receive new MEV events in real-time via SSE. See SSE Push Stream for details.

✓ You're billed only for events you actually receive. Points are deducted per event delivery.

Supported Chains

MEVScan currently provides data for Ethereum mainnet only.

Current Coverage

Chain	Network	Status
Ethereum	Mainnet (chain ID 1)	✓ Supported

chain_id Parameter

Some API interfaces expose a chain_id parameter. This parameter is currently not supported — all queries return Ethereum mainnet data regardless of the value supplied. Passing any chain_id other than 1 will not filter or change the result set.

Multi-chain support (e.g. BSC, Arbitrum) is on the roadmap. Follow our Substack for announcements.

Authentication

All API requests (MCP and HTTP) use Bearer Token authentication.

Bearer Token

Include your API Key in every request header:

Authorization: Bearer <YOUR_API_KEY>

Your API Key is available on the Dashboard. Keep it secret — it grants full access to your account.

Error responses

Status	Meaning
`401`	Missing or invalid Authorization header
`403`	Token revoked or subscription not authorized

query_mev_ids

Search MEV events by block range, timestamp, address, or type. Returns a list of transaction hashes (mev_id).

ONLY Ethereum mainnet MEV data is served.

Parameters

Parameter	Type	Default	Description
`from_block`	integer	0	Start block number inclusive (0 = no lower bound)
`to_block`	integer	0	End block number inclusive (0 = no upper bound)
`from_timestamp`	integer	0	Unix timestamp (seconds), start of time range (0 = no limit)
`to_timestamp`	integer	0	Unix timestamp (seconds), end of time range (0 = no limit)
`mev_type`	string	""	`ARBITRAGE` / `SANDWICH` / `LIQUIDATION` / `JIT` / `""` (all)
`address`	string	""	Filter by searcher or contract address (empty = all)
`limit`	integer	20	Max results (1–1000)
`chain_id`	integer	1	NOT SUPPORTED NOW, will support when we serve multi-chain data

Billing

Charged 1 point per returned mev_id. A query returning 0 results costs 0 points.

Scenario	Cost
Query returns 20 results	20 points
Query returns 0 results	0 points
Query returns 1000 results (max limit)	1000 points

✓ Charge is applied after results are fetched, based on the actual count returned.

Example prompts

"Show me the latest 10 arbitrage MEV events"

"What MEV transactions did address 0x<ADDRESS> do in the last 100 blocks?"

"List all sandwich attacks between block 21800000 and 21800100"

"Find liquidation events from the past 24 hours, up to 50 results"

Response

{
  "ok": true,
  "data": {
    "mev_ids": [
      { "mev_id": "0xc48bf502ca59ee29cd404c627acaf771ba44543677e097d25cadec2fc8dd9ec4" },
      { "mev_id": "0x19b52f7029cf61d2d1c1fd83fb4d5fe2438e57a1ba51d7140ca96fe3890892c9" }
    ],
    "total": 35,
    "truncated": true,
    "query": { "from_block": 0, "to_block": 0, "mev_type": "ARBITRAGE", "limit": 2 }
  },
  "error": null,
  "meta": { "request_id": "...", "latency_ms": 3, "data_freshness": "2026-05-07T11:20:35+00:00" }
}

Response fields

Field	Description
`mev_ids`	Array of `{mev_id}` objects (transaction hashes)
`total`	Total matching results before truncation
`truncated`	`true` if results were cut at the requested limit
`meta.data_freshness`	ISO 8601 timestamp of the most recent ingested block

Error codes

code	Description
`INVALID_INPUT`	Invalid parameter value (e.g. unrecognized mev_type)
`INSUFFICIENT_BALANCE`	Not enough points to cover the result count
`UPSTREAM_ERROR`	Data source returned an error

curl example

curl -s -X POST "https://eigenphi.com/messages/?session_id=SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "query_mev_ids",
      "arguments": {
        "mev_type": "ARBITRAGE",
        "limit": 5
      }
    }
  }'

✓ MCP tools use JSON-RPC over SSE. You must first open a GET /sse connection to obtain a session_id. See the Install in AI Tools page for connection details.

get_mev_detail

Fetch full details for a specific MEV event by its transaction hash: transaction relationships, token transfers, DeFi actions, and PNL.

ONLY Ethereum mainnet MEV data is served.

Parameters

Parameter	Type	Description
`tx_hash` required	string	Transaction hash of the MEV event — use `mev_id` from `query_mev_ids`
`chain_id`	integer	NOT SUPPORTED NOW, will support when we serve multi-chain data

Rate limit

Maximum 1 call per second per user. Calls exceeding this rate return RATE_LIMITED immediately with no charge.

Billing

Charged after the query completes:

Scenario	Cost
MEV event found	2 points
MEV event not found (404)	2 points
Rate limited	0 points

Example prompt

"Get the full detail of MEV transaction 0xc48bf502ca59ee29cd404c627acaf771ba44543677e097d25cadec2fc8dd9ec4"

Response

{
  "ok": true,
  "data": {
    "id": "0xc48bf502...",
    "type": "ARBITRAGE",
    "blockNumber": 21800050,
    "blockTimestamp": 1746700000,
    "mevTxRelation": {
      "primary": ["0xc48bf502..."]
    },
    "pnl": {
      "tokenBalance": [{ "token": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", "amount": "1500000000000000" }],
      "tokenPrice": { "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2": 3200.5 },
      "summary": { "revenueUsd": 4.8, "costUsd": 1.2, "profitUsd": 3.6 }
    }
  },
  "error": null,
  "meta": { "request_id": "...", "latency_ms": 45, "data_freshness": "2026-05-07T11:20:35+00:00" }
}

data.mevTxRelation roles

Role	MEV type	Description
`primary`	arbitrage, liquidation	Main profit-taking transaction
`frontrun`	sandwich	Attacker's opening transaction
`victim`	sandwich	User's transaction being sandwiched
`backrun`	sandwich	Attacker's closing transaction
`mint` / `burn`	jit	JIT liquidity provision transactions

Error codes

code	Description
`NOT_FOUND`	No MEV event found for this tx_hash (2 points charged, fee is upfront)
`RATE_LIMITED`	Called more than once per second (0 points charged)
`INSUFFICIENT_BALANCE`	Not enough points (2 required)
`UPSTREAM_ERROR`	Data source returned an error

curl example

curl -s -X POST "https://eigenphi.com/messages/?session_id=SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "get_mev_detail",
      "arguments": {
        "tx_hash": "0xc48bf502ca59ee29cd404c627acaf771ba44543677e097d25cadec2fc8dd9ec4"
      }
    }
  }'

get_leaderboard

Get top MEV events ranked by profit, revenue, or cost. Aggregates and ranks all MEV events in the requested time window — saving you the cost of querying and sorting individually.

ONLY Ethereum mainnet MEV data is served.

Parameters

Parameter	Type	Default	Description
`time_range`	string	"1d"	`"1d"` = last 24 hours · `"7d"` = last 7 days
`mev_type`	string	""	`"arbitrage"` / `"sandwich"` / `"jit"` / `"liquidation"` / `""` (all)
`bot`	string	""	Filter by bot address (`to_address`), e.g. `"0x1f2f..."`. Empty = all.
`sort`	string	"profit"	Ranking field, descending: `"profit"` / `"revenue"` / `"cost"`
`limit`	integer	20	Max items to return (1–100)
`chain_id`	integer	1	NOT SUPPORTED NOW, will support when we serve multi-chain data

Billing

The leaderboard aggregates large amounts of data on your behalf. Cost scales with the time window and the total number of MEV events in that window.

Formula

base    = int(900 × √days)
overage = max(0, (total_mev_events − days × 10000) ÷ 100)
cost    = min(cap, max(5, base + overage))

where: cap = int(1500 × √days)

base: fixed charge per day of data, scaled by √days to reward longer queries
overage: +1 point per 100 MEV events exceeding the free tier (days × 10,000 events)
cap: hard maximum, ensuring cost never exceeds 1500 × √days regardless of data volume

Typical costs

time_range	Base cost	Hard cap	Overage trigger
`"1d"`	900 points	1,500 points	> 10,000 events in window
`"7d"`	2,381 points	3,969 points	> 70,000 events in window
`"30d"`	4,929 points	8,216 points	> 300,000 events in window

✓ Charge is deducted after data is fetched, based on the total event count in the time window (not the limit parameter). If you have insufficient balance at that point, the call is rejected.

Example prompts

"Show me the top 10 most profitable MEV events in the last 24 hours"

"Which arbitrage bots made the most revenue in the last 7 days?"

"Get the top sandwich attacks by cost over the past day"

Response

{
  "ok": true,
  "data": {
    "items": [
      {
        "mev_id": "0xc48bf502...",
        "from_address": "0xabc...",
        "to_address": "0xdef...",
        "mev_type": "arbitrage",
        "revenue_usd": 12500.0,
        "cost_usd": 320.5,
        "profit_usd": 12179.5
      }
    ],
    "total": 48320,
    "truncated": true,
    "query": {
      "time_range": "1d",
      "mev_type": "",
      "bot": "",
      "sort": "profit",
      "limit": 20
    }
  },
  "error": null,
  "meta": { "request_id": "...", "latency_ms": 120 }
}

Response fields

Field	Description
`items[].mev_id`	Transaction hash — pass to `get_mev_detail` for full details
`items[].from_address`	Searcher/sender address
`items[].to_address`	Bot/contract address
`items[].mev_type`	Event type: `arbitrage` / `sandwich` / `jit` / `liquidation`
`items[].revenue_usd`	Gross revenue in USD
`items[].cost_usd`	Gas + input cost in USD
`items[].profit_usd`	Net profit in USD
`total`	Total MEV events in the time window (used to calculate billing)
`truncated`	`true` if results were cut at the requested `limit`

Error codes

code	Description
`INVALID_INPUT`	Invalid `time_range`, `mev_type`, or `sort` value
`INSUFFICIENT_BALANCE`	Not enough points after data was fetched
`UPSTREAM_ERROR`	Data source returned an error

curl example

curl -s -X POST "https://eigenphi.com/messages/?session_id=SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "get_leaderboard",
      "arguments": {
        "time_range": "1d",
        "sort": "profit",
        "limit": 10
      }
    }
  }'

Install in AI Tools

Replace <YOUR_API_KEY> with your key from the Dashboard.

Claude Code

Cursor

VS Code

Gemini CLI

OpenAI Codex

JetBrains

Others

One-command install

claude mcp add mevscan \
  --transport sse \
  --header "Authorization: Bearer <YOUR_API_KEY>" \
  https://eigenphi.com/sse

Or edit `~/.claude/settings.json`

{
  "mcpServers": {
    "mevscan": {
      "type": "sse",
      "url": "https://eigenphi.com/sse",
      "headers": { "Authorization": "Bearer <YOUR_API_KEY>" }
    }
  }
}

✓ Restart Claude Code after editing settings.json. Run /mcp to verify.

Edit `~/.cursor/mcp.json`

{
  "mcpServers": {
    "mevscan": {
      "type": "sse",
      "url": "https://eigenphi.com/sse",
      "headers": { "Authorization": "Bearer <YOUR_API_KEY>" }
    }
  }
}

✓ Check Settings → MCP for a green dot confirming connection.

Create `.vscode/mcp.json` in workspace root

{
  "servers": {
    "mevscan": {
      "type": "sse",
      "url": "https://eigenphi.com/sse",
      "headers": { "Authorization": "Bearer <YOUR_API_KEY>" }
    }
  }
}

⚠️ VS Code uses servers as the top-level key, not mcpServers.

Edit `~/.gemini/settings.json`

{
  "mcpServers": {
    "mevscan": {
      "httpUrl": "https://eigenphi.com/sse",
      "headers": { "Authorization": "Bearer <YOUR_API_KEY>" }
    }
  }
}

✓ Run gemini and type /tools to verify MEVScan is loaded.

Edit `~/.codex/config.toml`

[[mcp_servers]]
name    = "mevscan"
type    = "sse"
url     = "https://eigenphi.com/sse"

[mcp_servers.headers]
Authorization = "Bearer <YOUR_API_KEY>"

Settings → Tools → AI Assistant → MCP Servers → "+"

Name:   mevscan
Type:   SSE
URL:    https://eigenphi.com/sse
Header: Authorization: Bearer <YOUR_API_KEY>

Or edit `~/.idea/mcp.json`

{
  "servers": {
    "mevscan": {
      "type": "sse",
      "url": "https://eigenphi.com/sse",
      "headers": { "Authorization": "Bearer <YOUR_API_KEY>" }
    }
  }
}

Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mevscan": {
      "type": "sse",
      "url": "https://eigenphi.com/sse",
      "headers": { "Authorization": "Bearer <YOUR_API_KEY>" }
    }
  }
}

Windsurf

{
  "mcpServers": {
    "mevscan": {
      "type": "sse",
      "url": "https://eigenphi.com/sse",
      "headers": { "Authorization": "Bearer <YOUR_API_KEY>" }
    }
  }
}

Generic (any MCP client)

{
  "name":      "mevscan",
  "transport": "sse",
  "url":       "https://eigenphi.com/sse",
  "headers":   { "Authorization": "Bearer <YOUR_API_KEY>" }
}

SSE Push Stream — Overview

Receive new MEV events in real-time without polling. Uses standard Server-Sent Events (SSE), supported natively in all browsers and HTTP clients.

ONLY Ethereum mainnet MEV data is served.

How it works

Create a subscription → costs 10 points upfront
Connect to /stream/events with your API key
Receive events as JSON; points deducted per event
Cancel the subscription when done

Key facts

Subscriptions expire after 1 hour (TTL configurable)
Missed events are replayed on reconnect (up to 10-minute buffer)
Billed per delivered event: cost = f(tx_count) points
All active subscribers receive the same event stream

✓ Use the ?last_event_id=<seq> query param on reconnect to replay missed events automatically.

Create a Subscription

POST/stream/subscribe

Creates a new subscription. Each subscription costs 10 points upfront and is valid for 1 hour. Only one active subscription per account is allowed.

Request headers

Header	Required	Value
`Authorization`	yes	`Bearer <YOUR_API_KEY>`

Request body

No body required.

Example

curl -s -X POST https://eigenphi.com/stream/subscribe \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "subscription_id": "sub_a1b2c3d4",
  "expires_at": "2026-04-27T11:00:00Z",
  "contract_version": "v1_fixed_rate"
}

Response fields

Field	Description
`subscription_id`	Unique ID for this subscription
`sse_url`	SSE stream path, append to the base URL to connect, e.g. `GET /stream/events/{id}`
`expires_at`	Subscription auto-expires at this time (UTC ISO 8601)
`contract_version`	Billing contract version, e.g. `v1_fixed_rate`

Status codes

Code	Meaning
`201`	Subscription created
`401`	Missing or invalid API Key
`402`	Insufficient points (requires 10)
`409`	Already have an active subscription

Connect SSE Stream

GET/stream/events

Opens a persistent SSE connection. The server identifies your subscription via your Bearer token. Events are pushed as they arrive.

Request headers

Header	Required	Description
`Authorization`	yes	`Bearer <YOUR_API_KEY>`

Query parameters

Parameter	Required	Description
`last_event_id`	no	Sequence number (`seq`) from previous connection; server replays missed events from this point

Browser example

// EventSource doesn't support custom headers; use fetch() for Bearer auth
const resp = await fetch('https://eigenphi.com/stream/events', {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});
const reader = resp.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  console.log(decoder.decode(value));
}

// Reconnect with last_event_id to replay missed events:
// fetch('https://eigenphi.com/stream/events?last_event_id=42', ...)

curl example

curl -N \
  -H "Authorization: Bearer YOUR_API_KEY" \
  https://eigenphi.com/stream/events

# Reconnect with replay:
curl -N \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://eigenphi.com/stream/events?last_event_id=42"

Event format

id:42
data:{
  "subscription_id": "sub_a1b2c3d4",
  "event_id": "arb-0x1a2b3c-19800000",
  "mev_type": "arbitrage",
  "tx_count": 1,
  "points_charged": 1,
  "seq": 42,
  "data": { ... }
}

Field	Description
`seq`	Global monotonic sequence number. Pass as `?last_event_id=<seq>` on reconnect.
`points_charged`	Points deducted from your balance for this event
`data`	Full MEV event payload (transfers, actions, PNL)

Heartbeat

The server sends : ping comments every 25 seconds to keep the connection alive. No action required.

Close events

When the server closes the stream, it sends a final event:close message:

event:close
data:{"reason": "subscription_expired"}   // or "insufficient_balance"

Status codes

Code	Meaning
`200`	SSE stream opened
`401`	Missing or invalid API Key
`403`	No active subscription

Cancel a Subscription

DELETE/stream/subscription

Cancels the current user's active subscription and terminates any connected SSE stream.

Request headers

Header	Required	Value
`Authorization`	yes	`Bearer <YOUR_API_KEY>`

Example

curl -s -X DELETE https://eigenphi.com/stream/subscription \
  -H "Authorization: Bearer YOUR_API_KEY"

Status codes

Code	Meaning
`200`	Cancelled successfully — `{"status": "cancelled"}`
`401`	Missing or invalid API Key
`404`	No active subscription found

Event Format

Each pushed event contains a full MEV report.

Top-level fields

Field	Type	Description
`event_id`	string	Global unique ID, e.g. `arb-0x1a2b-19800000`
`mev_type`	string	`arbitrage` / `sandwich` / `liquidation` / `jit`
`tx_count`	integer	Number of transactions in this MEV event
`points_charged`	integer	Points deducted for this delivery
`seq`	integer	Monotonic sequence; use as `?last_event_id=<seq>` on reconnect
`data`	object	Full MEV report (see below)

data.mevTxRelation

Transactions grouped by role:

Role	MEV type	Description
`primary`	arbitrage, liquidation	Main profit-taking transaction
`frontrun`	sandwich	Attacker's opening transaction
`victim`	sandwich	User's transaction being sandwiched
`backrun`	sandwich	Attacker's closing transaction
`mint` / `burn`	jit	JIT liquidity provision transactions

data.pnl

Field	Description
`tokenBalance`	Net token balance changes: `[{token, amount}]`
`tokenPrice`	USD price snapshot at block time: `{tokenAddress: price}`
`summary.revenueUsd`	Gross revenue in USD
`summary.costUsd`	Gas + input cost in USD
`summary.profitUsd`	Net profit in USD

MEVScan Marketplace

An open collection of demo apps and community-built tools that showcase what you can build with the MEVScan API.

github.com/eigenphi/MEVScan-marketplace ↗ Open

About

MEVScan Marketplace is an open-source repository of applications built on top of the MEVScan API — EigenPhi's professional MEV intelligence platform. It tracks MEV activity including arbitrage, sandwich attacks, liquidations, and JIT liquidity events across Ethereum and EVM-compatible chains.

All apps are released under the MIT License. Developers who contribute via pull requests earn MEVScan points redeemable for platform perks.

Featured Applications

📡

MEV Live Stream

Python · SSE · Browser UI

Real-time MEV event viewer powered by the MEVScan SSE push service. Displays the 500 most recent Arbitrage, Sandwich, Liquidation, and JIT events with pause/resume, address filter, and auto-reconnect.

Python 3.10+ local proxy
Single-page browser dashboard
Auto-reconnect with exponential backoff

⭐ View on GitHub

🤖

MEV Report

Python · MCP · LLM · Browser UI

AI-powered MEV analysis generator. Enter a tx hash, choose an LLM (Claude / GPT / Gemini / DeepSeek / Qwen), and get a structured report with token flow and Mermaid transaction diagrams, streamed live in the browser.

Multi-provider LLM support
Streamed Markdown + Mermaid diagram
Raw MEV JSON syntax-highlighted viewer

⭐ View on GitHub

🏆

MEV Leaderboard New

Python · MCP · Browser UI

A browser-based leaderboard that calls the get_leaderboard MCP tool to rank top MEV bots by profit, revenue, or cost. Supports filtering by time window (1d / 7d), MEV type, and bot address.

Python 3.10+ local proxy (MCP over SSE)
Filter by timeframe, MEV type, bot address
Displays rank, addresses, type, and USD P&L
Etherscan links for each wallet address

⭐ View on GitHub

Requirements

Python 3.10+
A MEVScan API key from your Dashboard
Environment variables: MEVSCAN_URL and MEVSCAN_TOKEN

Contribute & Earn Points

Have an idea for a useful MEV tool? Submit a pull request and earn MEVScan points redeemable for API access.

🐛

Bug Fix

Fix a verified bug in an existing demo

10000 ~ 20000 points

✨

New Feature

Add a meaningful feature to an existing demo

10000 ~ 20000 points

🚀

New Demo

Submit a complete, runnable application

10000 ~ 100000 points

Points are awarded after the PR is reviewed and merged. Open a PR at github.com/eigenphi/MEVScan-marketplace — include a short description and a screenshot or screen recording.

Points & Pricing

MEVScan uses a points system. Points are consumed by MCP tool calls and SSE stream events.

Summary

Operation	Cost	Timing
`query_mev_ids`	1 pt per returned mev_id	Charged after query, based on actual result count
`get_mev_detail`	2 pts per call	Charged upfront — regardless of whether the event is found
`get_leaderboard`	5 – 8,216 pts (dynamic)	Charged after data is fetched, based on time window and event count
Create SSE subscription	10 pts flat	Charged at subscription creation
SSE event delivery	1 pt per pushed event	Charged per delivery, in real time

MCP Tools

query_mev_ids

Charged 1 point per returned mev_id after the query completes. A query returning 0 results costs 0 points.

Scenario	Cost
Returns 0 results	0 points
Returns 50 results	50 points
Returns 1,000 results (max limit)	1,000 points

get_mev_detail

Charged a flat 2 points per call, upfront — before the lookup is executed. The charge applies whether or not the requested event exists.

Scenario	Cost
Event found	2 points
Event not found (`NOT_FOUND`)	2 points

get_leaderboard

Cost scales with the requested time window and the total number of MEV events in that window. The charge is deducted after data is fetched.

days    = int(time_range)           # e.g. "7d" → 7
base    = int(900 × √days)
overage = max(0, (total_events − days × 10,000) // 100)
cap     = int(1500 × √days)
cost    = min(cap, max(5, base + overage))

base: scales with the square root of the number of days
overage: +1 point per 100 MEV events beyond the free tier (days × 10,000 events)
cap: hard maximum — cost never exceeds 1500 × √days

time_range	Base cost	Hard cap	Overage trigger
`"1d"`	900 pts	1,500 pts	> 10,000 events in window
`"7d"`	2,381 pts	3,969 pts	> 70,000 events in window
`"30d"`	4,929 pts	8,216 pts	> 300,000 events in window

Overage is based on the total event count in the time window, not the limit parameter.

SSE Push Stream

Subscription fee (upfront)

Creating a subscription via POST /stream/subscribe deducts 10 points immediately. The subscription is valid for 1 hour. If it expires or you disconnect, the unused portion is not refunded.

Per-event delivery fee

Each MEV event pushed to your SSE connection deducts 1 point, regardless of MEV type:

points_charged = 1 # flat rate per pushed event

Reconnecting with Last-Event-ID replays missed events — replayed events use idempotent deduction and are not double-charged.

Insufficient balance

When a tool call or stream delivery cannot be charged due to insufficient balance:

MCP tools — return INSUFFICIENT_BALANCE error, no data is returned
SSE stream — server sends a close event and terminates the connection

event:close
data:{"reason": "insufficient_balance"}

Top up your balance and create a new subscription to resume streaming.

Service Status API

Public endpoint — no authentication required. Returns real-time health and waterline data for the MEVScan stack.

GET /status

curl https://eigenphi.com/status

Response fields

Field	Type	Description
`status`	string	`"ok"` — always present when the service is reachable
`service_health`	string	`"UP"` / `"DOWN"` — this MCP API service
`mevscan_health`	string	`"UP"` / `"DOWN"` / `"UNKNOWN"` — MEVScan engine system
`mevscan_data_health`	string	`"UP"` / `"DOWN"` / `"UNKNOWN"` — MEVScan data system
`latest_block_number`	integer \| null	Most recently ingested block number — MEVScan Waterline

Example response

{"status":"ok","service_health":"UP","mevscan_health":"UP","mevscan_data_health":"UP","latest_block_number":25043738}

Status indicators

Indicator	Field	Values
MEVScan MCP Service Health	`service_health`	`"UP"` service alive · `"DOWN"` degraded
MEVScan Engine Health	`mevscan_health`	`"UP"` running · `"DOWN"` unreachable · `"UNKNOWN"` not configured
MEVScan Data Health	`mevscan_data_health`	`"UP"` running · `"DOWN"` unreachable · `"UNKNOWN"` not configured
MEVScan Waterline	`latest_block_number`	integer block number; `null` if no events ingested yet

Data Quality API

A set of MCP tools for community-driven MEV data quality calibration — spot errors, submit reports, and earn Points when your reports are confirmed.

✅ Available

The Data Quality API is now live. All four tools (report_mev_quality, get_my_quality_stats, get_quality_report_status, admin_review_quality_report) are fully functional. Authenticate with a valid API Key to start submitting reports and earning Points.

How It Works

Any user with a valid API Key can submit quality reports against MEV transactions. The system weights each report by the reporter's Credibility Score and aggregates a confidence score. Once the threshold is reached, the issue is auto-confirmed and Points are settled the next day.

Issue types: FALSE_POSITIVE, FALSE_NEGATIVE, PNL_ERROR, TYPE_ERROR
Daily report limit: 20 for normal users, 5 for restricted users
Points settle at UTC 00:05 the following day, distributed from the daily Points pool weighted by credibility

MCPreport_mev_quality

Submit a MEV data quality report.

Parameters

Parameter	Type	Required	Description
`tx_hash`	string	Required	Transaction hash being reported (`0x` + 64 hex chars)
`issue_type`	string	Required	`FALSE_POSITIVE` / `FALSE_NEGATIVE` / `PNL_ERROR` / `TYPE_ERROR`
`evidence_tx_hash`	string	Conditional	Required when `issue_type` is `FALSE_NEGATIVE` — the real transaction as evidence
`description`	string	Optional	Additional notes, max 500 characters

Success Response

{
  "ok": true,
  "data": {
    "report_id": 42,
    "status": "pending",
    "current_score": 1.8,
    "threshold": 3.0,
    "message": "Report submitted. Thank you for your contribution."
  }
}

Error Codes

code	Description
`UNAUTHORIZED`	API Key is invalid or missing
`INVALID_ISSUE_TYPE`	issue_type is not a valid enum value
`VALIDATION_ERROR`	tx_hash format is invalid, or evidence_tx_hash is missing for FALSE_NEGATIVE
`DUPLICATE_REPORT`	You have already submitted a report for this transaction
`DAILY_LIMIT_EXCEEDED`	Daily report limit reached; resets at UTC 00:00

MCPget_my_quality_stats

Query quality report statistics and credibility info for the current user. No parameters required.

Success Response

{
  "ok": true,
  "data": {
    "credibility_score": 1.2,
    "trust_level": "normal",
    "total_reports": 15,
    "confirmed_reports": 10,
    "rejected_reports": 1,
    "total_points_earned": 320,
    "daily_remaining": 17,
    "recent_reports": [
      {
        "report_id": 42,
        "tx_hash": "0xabc...",
        "issue_type": "FALSE_POSITIVE",
        "status": "confirmed",
        "created_at": 1746700000
      }
    ]
  }
}

The credibility_score starts at 0.5. Each confirmed report adds +0.1; each rejected report subtracts 0.3. Range: 0.1–2.0. When trust_level is "restricted", the daily report limit drops to 5.

MCPget_quality_report_status

Query the status of a single report. Provide either report_id or tx_hash.

Parameters

Parameter	Type	Required	Description
`report_id`	integer	One of	Report ID returned by `report_mev_quality`
`tx_hash`	string	One of	Transaction hash that was reported

Success Response

{
  "ok": true,
  "data": {
    "report_id": 42,
    "tx_hash": "0xabc...",
    "issue_type": "FALSE_POSITIVE",
    "status": "confirmed",
    "evidence_tx_hash": null,
    "description": "This is not an arbitrage transaction",
    "created_at": 1746700000
  }
}

Status lifecycle: pending → confirmed (auto or admin) / rejected (admin) → rewarded (Points settled).

Quick Start

1. Get your API Key

2. Connect an AI tool

3. Ask a question

4. Subscribe to the push stream (optional)

Supported Chains

Current Coverage

chain_id Parameter

Authentication

Bearer Token

Error responses

query_mev_ids

Parameters

Billing

Example prompts

Response

Response fields

Error codes

curl example

get_mev_detail

Parameters

Rate limit

Billing

Example prompt

Response

data.mevTxRelation roles

Error codes

curl example

get_leaderboard

Parameters

Billing

Formula

Typical costs

Example prompts

Response

Response fields

Error codes

curl example

Install in AI Tools

One-command install

Or edit ~/.claude/settings.json

Edit ~/.cursor/mcp.json

Create .vscode/mcp.json in workspace root

Edit ~/.gemini/settings.json

Edit ~/.codex/config.toml

Settings → Tools → AI Assistant → MCP Servers → "+"

Or edit ~/.idea/mcp.json

Claude Desktop

Windsurf

Generic (any MCP client)

SSE Push Stream — Overview

How it works

Key facts

Create a Subscription

Request headers

Request body

Example

Response fields

Status codes

Connect SSE Stream

Request headers

Query parameters

Browser example

curl example

Event format

Heartbeat

Close events

Status codes

Cancel a Subscription

Request headers

Example

Status codes

Event Format

Top-level fields

data.mevTxRelation

data.pnl

MEVScan Marketplace

About

Featured Applications

Requirements

Or edit `~/.claude/settings.json`

Edit `~/.cursor/mcp.json`

Create `.vscode/mcp.json` in workspace root

Edit `~/.gemini/settings.json`

Edit `~/.codex/config.toml`

Or edit `~/.idea/mcp.json`