# bsc-dex-spread [Health: Active]

**Category:** 💰 Finance & Fintech  
**Repository:** https://github.com/donnywin85/bsc-dex-spread-mcp  
**GitHub Stars:** 0  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/bsc-dex-spread

## Description
Cross-DEX price & spread for PancakeSwap v2+v3 on BSC via x402. Tool get_dex_spread(pair, fee?).

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "bsc-dex-spread": {
    "command": "npx",
    "args": ["-y","bsc-dex-spread-mcp"]
  }
}
```

## Documentation & README

# bsc-dex-spread

**One MCP tool — `get_dex_spread` — returning live cross-DEX price and spread for
PancakeSwap v2 + v3 on BSC, paid $0.01 USDC per call from your own wallet.**

## Try it in 30 seconds

Inspecting the server costs nothing and needs no wallet:

```bash
npx -y bsc-dex-spread-mcp
```

It starts on stdio and lists its one tool. Add it to Claude Code:

```bash
claude mcp add bsc-dex-spread --env EVM_PRIVATE_KEY=0xyour_disposable_base_key -- npx -y bsc-dex-spread-mcp
```

Without a key the tool is still listed, and a call tells you exactly what is
missing rather than failing obscurely:

```
get_dex_spread failed: EVM_PRIVATE_KEY is not set. Add your funded Base-mainnet
buyer wallet key (0x-prefixed, USDC-only, low balance) to the MCP server env config.
```

**Before you fund anything, know the free alternative.** If you do not
specifically need the paid, uncapped path, [`arb-dex-mcp`](https://github.com/donnywin85/arb-dex-mcp)
and [`dex-data-mcp`](https://github.com/donnywin85/dex-data-mcp) return cross-DEX
spread **keyless and free** on six chains. This server exists for callers who
want per-call billing with no free-tier ceiling — it is not the cheapest way in.

An [MCP](https://modelcontextprotocol.io) server that gives your agent one tool —
**`get_dex_spread`** — returning **real-time cross-DEX price & spread data for
PancakeSwap v2 + v3 on BSC**. Each call is a paid API call: **$0.01 USDC on Base
mainnet**, settled automatically over [x402](https://x402.org) from *your own*
wallet. No subscription, no account, no API key to request — the agent pays
per call.

Backed by a live x402 gateway: <https://x402.donnyautomation.com>
Public usage/proof page: <https://x402.donnyautomation.com/stats>

## The tool

### `get_dex_spread(pair, fee?)`

Real-time cross-DEX price & spread for PancakeSwap v2+v3 on BSC.

- `pair` (required) — token pair as `SYM/SYM`; the first symbol is the
  USD-priceable side. Examples: `WBNB/USDC`, `WBNB/USDT`, `CAKE/WBNB`.
- `fee` (optional) — a PancakeSwap v3 fee tier (`100`, `500`, `2500`, `10000`)
  to restrict the v3 probe. Omit to probe all v3 tiers **and** v2.

Returns per-venue prices, best buy / best sell venue, the gross cross-DEX spread
in bps, liquidity (per-venue TVL + totals), and the source block number. Example:

```jsonc
{
  "pair": "WBNB/USDC", "network": "bsc", "chainId": 56,
  "blockNumber": 107562007, "nativeUsd": 546.6,
  "pricesByVenue": [ { "venue": "pancake", "surface": "v2", "price": 546.6, "tvlUsd": 1234567 }, ... ],
  "bestBuy":  { "venue": "pancakeV3:500", "price": ... },
  "bestSell": { "venue": "biswap",        "price": ... },
  "midSpreadBps": 27.4,
  "crossDex": { "grossSpreadBps": 14.05, "buyVenue": "...", "sellVenue": "...", "surface": "v2v3" },
  "liquidity": { "venues": 7, "totalTvlUsd": ... },
  "ts": "2026-07-01T...", "source": "rpc"
}
```

## Why an agent wants this

Cross-DEX spread is the raw signal behind arbitrage, best-execution routing, and
slippage estimation. Instead of running BSC RPC infrastructure and multi-DEX pool
math itself, an agent calls one tool and pays a cent for a fresh, block-stamped
answer across PancakeSwap v2 + v3 venues.

## Cost & wallet model — read this

**You bring the wallet. This package ships no keys.** The server signs each
payment with a private key it reads from its own environment
(`EVM_PRIVATE_KEY`), which you set in your MCP client's server config. That is
the design: the buyer (you) pays for the data with the buyer's wallet.

- **Per call:** $0.01 USDC on **Base mainnet** (`eip155:8453`).
- **Fund USDC only — zero ETH needed.** x402's `exact` scheme is EIP-3009
  `transferWithAuthorization`: you sign an off-chain USDC authorization and the
  facilitator broadcasts it and pays the gas. A 0-ETH wallet settles fine.
- **Use a low-balance, dedicated wallet.** Fund it with just a few dollars of
  USDC on Base and top it up as needed. Do not point this at your main wallet —
  the key sits in your MCP client config in plaintext, so treat it as a hot,
  disposable spending wallet.

## Install & configure

```bash
npm install -g bsc-dex-spread-mcp
```

Add it to your MCP client. Claude Desktop / Claude Code
(`claude_desktop_config.json` or `.mcp.json`):

```jsonc
{
  "mcpServers": {
    "bsc-dex-spread": {
      "command": "npx",
      "args": ["-y", "bsc-dex-spread-mcp"],
      "env": {
        "EVM_PRIVATE_KEY": "0xYOUR_BASE_MAINNET_BUYER_KEY"
      }
    }
  }
}
```

`EVM_PRIVATE_KEY` — your Base-mainnet buyer wallet key (0x-prefixed), funded with
a few dollars of USDC on Base. Optional `GATEWAY_URL` overrides the endpoint
(defaults to `https://x402.donnyautomation.com`).

Restart your client; the agent will have `get_dex_spread` available and will pay
$0.01 USDC each time it calls it.

## How it works

```
agent → get_dex_spread(pair)
      → GET https://x402.donnyautomation.com/call?pair=...  (HTTP 402 PAYMENT-REQUIRED)
      → sign EIP-3009 USDC auth with EVM_PRIVATE_KEY → x402 facilitator settles on Base
      → gateway proxies to its BSC DEX reader → 200 with the cross-DEX payload
```

## What has been verified, and what has not

Checked against the published artifacts on 2026-08-21:

- `npm install -g bsc-dex-spread-mcp` and `npx -y bsc-dex-spread-mcp` both
  install and start; npm `0.1.0` matches this repo.
- The gateway is live and answers `GET /call?pair=WBNB/USDC` with a valid x402
  **V2** challenge — `402`, a `payment-required` header, $0.01 USDC
  (`10000` at 6 decimals) on Base `eip155:8453`.
- A keyless call reports the missing key clearly, as shown above.
- **Not verified: end-to-end paid settlement.** Confirming it would mean spending
  real USDC, which this documentation pass was not authorised to do. The payment
  path is unexercised here, so treat it as untested rather than proven, and make
  your first call a small one.

## Where to go next

- **Free, keyless cross-DEX data** — [`arb-dex-mcp`](https://github.com/donnywin85/arb-dex-mcp)
  (6 chains) or [`dex-data-mcp`](https://github.com/donnywin85/dex-data-mcp) (22 tools).
- **Paid general-purpose agent utilities** — [`agent-utils-mcp`](https://github.com/donnywin85/agent-utils-mcp).
- **The human-approval job queue behind these services** —
  [`approval-queue-starter`](https://github.com/donnywin85/approval-queue-starter).
- **Live proof of usage** — <https://x402.donnyautomation.com/stats>.

## License

MIT