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