{ "markdown": "# arb-dex-mcp\n\n**Live cross-DEX crypto prices for your AI agent** — per-venue pool price, pool liquidity\nand the gross cross-venue spread on 6 EVM chains, read straight from on-chain pool state.\n\n[![npm](https://img.shields.io/npm/v/arb-dex-mcp)](https://www.npmjs.com/package/arb-dex-mcp)\n[![npm downloads](https://img.shields.io/npm/dw/arb-dex-mcp)](https://www.npmjs.com/package/arb-dex-mcp)\n[![provenance](https://img.shields.io/badge/npm-provenance-brightgreen)](https://www.npmjs.com/package/arb-dex-mcp#provenance)\n[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-io.github.donnywin85%2Farb--dex--mcp-blue)](https://registry.modelcontextprotocol.io/v0/servers?search=arb-dex)\n[![Indexed on TensorBlock MCP Index](https://mcp-index.tensorblock.co/v1/servers/github-donnywin85-arb-dex-mcp-7dd9a70c/badge.svg)](https://www.tensorblock.co/mcp/servers/github-donnywin85-arb-dex-mcp-7dd9a70c)\n[![Listed on mcpservers.org](https://mcpservers.org/badge.svg)](https://mcpservers.org/servers/donnywin85/arb-dex-mcp)\n[![license](https://img.shields.io/npm/l/arb-dex-mcp)](LICENSE)\n\nChains: **BSC · Polygon · Arbitrum · Base · Avalanche · Optimism**.\nVenues: PancakeSwap (v2 + v3), Uniswap v3, SushiSwap, QuickSwap, Biswap, ApeSwap, BaseSwap,\nTrader Joe, Pangolin — every v2-style pool **and every v3 fee tier separately**, because a\n$12k 1% pool and a $19M 0.01% pool are not the same quote.\n\nNothing is modelled, estimated or backfilled. Every payload states its own block number and\ncarries its own scope note, so an agent that quotes a figure also has the caveats attached to it.\n\n**Works with no API key** against a free hourly public snapshot. [Docs](https://donnywin85.github.io/arb-dex-mcp/) · [npm](https://www.npmjs.com/package/arb-dex-mcp)\n\n---\n\n## Quickstart\n\nNothing to clone or build. Your MCP client fetches the package. Requires Node 18+.\n\n### Claude Desktop\n\n`claude_desktop_config.json` — macOS `~/Library/Application Support/Claude/`,\nWindows `%APPDATA%\\Claude\\`:\n\n```json\n{\n \"mcpServers\": {\n \"arb-dex\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"arb-dex-mcp\"],\n \"env\": {\n \"RAPIDAPI_KEY\": \"your-rapidapi-key-here\"\n }\n }\n }\n}\n```\n\nRestart Claude Desktop; the six tools appear under the connectors icon.\n**Drop the `env` block entirely to run keyless** — the server still starts and the\nfree-snapshot tools still answer.\n\n### Claude Code\n\n```bash\nclaude mcp add arb-dex --env RAPIDAPI_KEY=your-rapidapi-key-here -- npx -y arb-dex-mcp\n```\n\nKeyless:\n\n```bash\nclaude mcp add arb-dex -- npx -y arb-dex-mcp\n```\n\nThen `/mcp` to confirm it connected.\n\n### Cursor\n\n`~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per project):\n\n```json\n{\n \"mcpServers\": {\n \"arb-dex\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"arb-dex-mcp\"],\n \"env\": {\n \"RAPIDAPI_KEY\": \"your-rapidapi-key-here\"\n }\n }\n }\n}\n```\n\nCursor → Settings → MCP shows the server and its tools once the file is saved.\n\n### Any other MCP client\n\nSame three facts: command `npx`, args `[\"-y\", \"arb-dex-mcp\"]`, transport **stdio**,\noptional env `RAPIDAPI_KEY`.\n\n---\n\n## Try it\n\nReal prompts, and the real shape that comes back. Payloads below were measured live on\n**2026-08-15**; they are trimmed for width but nothing is invented.\n\n### 1. \"What is WBNB/USDT trading at on every BSC venue right now?\"\n\n`get_prices` reads every pool holding the pair — v2 pairs and each v3 fee tier separately —\nat one stated block:\n\n```json\n{\n \"pair\": \"WBNB/USDT\",\n \"network\": \"bsc\",\n \"chainId\": 56,\n \"blockNumber\": 116151268,\n \"pricesByVenue\": [\n { \"venue\": \"pancake\", \"surface\": \"v2\", \"feeBps\": 25, \"price\": 611.7347, \"tvlUsd\": 56834814.36 },\n { \"venue\": \"biswap\", \"surface\": \"v2\", \"feeBps\": 10, \"price\": 610.8278, \"tvlUsd\": 415733.94 },\n { \"venue\": \"apeswap\", \"surface\": \"v2\", \"feeBps\": 20, \"price\": 611.1244, \"tvlUsd\": 3659.06 },\n { \"venue\": \"pancakeV3:1\", \"surface\": \"v3\", \"feeBps\": 1, \"price\": 610.5684, \"tvlUsd\": 18596810.32 },\n { \"venue\": \"pancakeV3:5\", \"surface\": \"v3\", \"feeBps\": 5, \"price\": 610.6531, \"tvlUsd\": 4941099.44 },\n { \"venue\": \"pancakeV3:25\", \"surface\": \"v3\", \"feeBps\": 25, \"price\": 610.6304, \"tvlUsd\": 52534.35 },\n { \"venue\": \"pancakeV3:100\", \"surface\": \"v3\", \"feeBps\": 100, \"price\": 609.1025, \"tvlUsd\": 12206.21 }\n ],\n \"bestBuy\": { \"venue\": \"pancakeV3:100\", \"price\": 609.1025 },\n \"bestSell\": { \"venue\": \"pancake\", \"price\": 611.7347 },\n \"midSpreadBps\": 43.22,\n \"crossDex\": {\n \"grossSpreadBps\": 0,\n \"grossUsd\": 0,\n \"optimalInput\": { \"amount\": 0, \"token\": \"WBNB\", \"usd\": 0 },\n \"buyVenue\": \"-\",\n \"sellVenue\": \"-\"\n },\n \"liquidity\": { \"venues\": 7, \"totalTvlUsd\": 80856857.67 },\n \"source\": \"rpc\"\n}\n```\n\n**Read the two spread numbers against each other.** The raw mid spread is **43 bps** — and the\ngross capturable spread is **0**. The 609.10 quote lives in a $12k pool; the size that would\nactually clear it moves the price past the gap before you get there. A tool that reported only\nthe 43 bps would be handing an agent a number it cannot trade. This one reports both, and\n`optimalInput` is where the honesty lands.\n\n### 2. \"Show me the cross-DEX spreads on Base — are any actually capturable?\"\n\n`get_spreads` sweeps a whole chain and ranks by **gross USD at the optimal size**, not by\nheadline basis points:\n\n```json\n{\n \"network\": \"base\",\n \"chainId\": 8453,\n \"scannedPairs\": 11,\n \"opportunities\": [],\n \"found\": 0,\n \"filters\": { \"minSpreadBps\": 10, \"minVenueTvlUsd\": 1000, \"minGrossUsd\": 0.01, \"limit\": 5 },\n \"ranking\": \"gross USD at the optimal trade size, NOT raw spread — a large spread with a tiny optimal size is not an opportunity\",\n \"scope\": \"GROSS cross-venue spread from live pool state, BEFORE gas, MEV and any slippage beyond the optimal size. Not a profit estimate and not trade advice. Venues below the liquidity floor are excluded because a spread against a dust pool is an artefact, not an opportunity.\",\n \"elapsedMs\": 2847\n}\n```\n\n**`found: 0` is a real answer and it is the common one.** Eleven pairs scanned, nothing cleared\nthe floor. Venues under $1,000 TVL are dropped outright. When rows *do* come back, each carries\n`capturable`, `warning` and `shallowestSideTvlUsd` so a big basis-point number cannot mislead on\nits own. This tool will tell your agent there is nothing there — which is the whole point of\nasking it.\n\n### 3. \"How much history does arb-dex actually have, and for which chains?\"\n\n`get_history_summary` sizes the archive *before* you query it:\n\n```json\n{\n \"rows\": 133,\n \"rowsWithPairDetail\": 103,\n \"rowsByEra\": { \"digest-totals-only\": 30, \"top-list-pairs\": 5, \"full-sweep\": 98 },\n \"pairsTracked\": 107,\n \"firstAt\": \"2026-08-10T17:35:09.355Z\",\n \"lastAt\": \"2026-08-15T20:54:34.417Z\",\n \"spanHours\": 123.32,\n \"chainsSeen\": [\"arbitrum\", \"avalanche\", \"base\", \"bsc\", \"optimism\", \"polygon\"],\n \"pairs\": [\n { \"chain\": \"polygon\", \"pair\": \"WBTC/USDC\", \"observations\": 103, \"qualifiedObservations\": 39 },\n { \"chain\": \"bsc\", \"pair\": \"BTCB/USDT\", \"observations\": 99, \"qualifiedObservations\": 15 },\n { \"chain\": \"arbitrum\", \"pair\": \"ARB/USDC\", \"observations\": 98, \"qualifiedObservations\": 0 }\n ]\n}\n```\n\nCoverage is only what was measured. A gap stays a gap — `rowsByEra` says how much detail each\nera of rows carries, and `ARB/USDC` having 98 observations but **0 qualified** is the archive\ntelling you that pair has never once cleared the spread floor.\n\n---\n\n## Tools\n\n| Tool | What it answers | Access |\n|---|---|---|\n| `get_chains` | Which chains are covered, their chain IDs, tokens and DEX venues | Any key · keyless returns the chain list only, and says so |\n| `get_pairs` | What is priceable on one chain: token universe, venues, pair syntax | Any key · keyless returns the measured subset, labelled as such |\n| `get_prices` | One pair's price at **every** venue holding a pool for it, plus reserves, TVL, fee tier and the cross-DEX spread | Any key |\n| `get_spreads` | A whole chain's cross-venue dislocations, ranked by gross USD at the optimal size | Any key for `live: true` · keyless serves the free hourly snapshot |\n| `get_history_summary` | What the measurement archive covers: rows, pairs tracked, chains seen, span, retention | Any key (free tier included) |\n| `get_history` | One pair's per-venue price/liquidity series and gross cross-venue spread over 24h / 7d / 30d | **PRO plan** — see [Plans](#plans) |\n\nThe two history tools read the service's own measurement archive, so they answer the question\nthe live tools cannot: whether a dislocation *persisted* or was a single sample. Sampling is\nroughly hourly, and gaps are never interpolated or backfilled. Call `get_history_summary` first\nto see what span exists before asking for a window.\n\n## What it will not do\n\n- **Spreads are gross** — before gas, MEV and slippage beyond the optimal size. Not a profit\n estimate and not trade advice.\n- **It never fabricates a row.** Without a key, `get_chains`, `get_pairs` and `get_spreads`\n answer from the free public surface and each carries a `limitation` field naming exactly what\n a key would add. `get_prices`, `get_history_summary` and `get_history` return an explicit\n key-required error with the signup link rather than a thinner answer dressed up as a full one.\n- **It does not execute trades**, hold funds, or touch a wallet. It is read-only market data.\n- **This package ships no credentials of any kind.** The key is yours and stays in your config.\n\n## Get a key\n\nThe paid tools call the API through RapidAPI using **your own** key.\n\n1. Subscribe — there is a free tier: \n2. Copy your `X-RapidAPI-Key` from the RapidAPI dashboard.\n3. Put it in `RAPIDAPI_KEY` in the config above — never in code, and never in a commit.\n\n### Plans\n\nFive of the six tools work on the **free** tier. Only the per-pair history series is gated:\n\n| Plan | Adds |\n|---|---|\n| **BASIC** ($0) | Live quotes on every chain, plus `get_history_summary` so you can size the archive before you buy it |\n| **PRO** ($15/mo) | `get_history` — the measured per-venue series for one pair, 24h window, 1000 calls/mo |\n| **ULTRA** ($49/mo) | No window limit and no history meter, plus depth/slippage and spread alerts |\n| **MEGA** ($149/mo) | Bulk paging over the complete archive for your own store |\n\nCalling `get_history` below PRO returns an explicit `tier_required` error naming the plan and\nthe upgrade URL — it does not fail silently or return an empty series.\n\n## Configuration\n\n| Env var | Default | Purpose |\n|---|---|---|\n| `RAPIDAPI_KEY` | — | Your RapidAPI key. Required for the paid tools. |\n| `ARB_DEX_TIMEOUT_MS` | `45000` | Request timeout. A live full-chain sweep is a real on-chain read and can take ~30s. |\n| `ARB_DEX_FREE_BASE_URL` | production origin | Override the free-surface host. |\n| `ARB_DEX_RAPIDAPI_HOST` | `multi-chain-dex-prices-liquidity.p.rapidapi.com` | Override the RapidAPI host. |\n\nSet these in your MCP client's `env` block (see the configs above). `.env.example` ships in the\npackage and documents the same variables for local runs from a clone.\n\n## Test\n\nThe test suite is not in the npm tarball — run it from a clone:\n\n```bash\ngit clone https://github.com/donnywin85/arb-dex-mcp.git\ncd arb-dex-mcp && npm install\n\nnpm run selftest # keyless: exercises the free fallbacks\nRAPIDAPI_KEY=... npm run selftest # keyed: exercises the paid routes\n```\n\nThe test spawns the server over stdio and calls every tool against the **real production API** —\nnothing is mocked. It asserts on live values (block number, per-venue prices, scanned-pair\ncounts), so a run that passes is evidence the data path works end to end.\n\n## Links\n\n- npm: \n- Docs: \n- Official MCP Registry: `io.github.donnywin85/arb-dex-mcp`\n- TensorBlock MCP Index: \n- Source: \n- The API behind it: \n\n## License\n\nMIT — see [LICENSE](LICENSE).\n", "bytes": 12181, "sha": "2d7d6aaaf6d4db001679d0829e35ca1884f9a8f90400ecb7f568b0e8665256c7", "repo_slug": "donnywin85/arb-dex-mcp", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_donnywin85_arb_dex_mcp_5d706902/readme" }