io.github.donnywin85/bsc-dex-spread

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:

npx -y bsc-dex-spread-mcp

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

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 and 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 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 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:

{
  "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

npm install -g bsc-dex-spread-mcp

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

{
  "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 (6 chains) or dex-data-mcp (22 tools).
• Paid general-purpose agent utilities — agent-utils-mcp.
• The human-approval job queue behind these services — approval-queue-starter.
• Live proof of usage — https://x402.donnyautomation.com/stats.

License

MIT