# dex-data MCP server [![dex-data-mcp MCP server](https://glama.ai/mcp/servers/donnywin85/dex-data-mcp/badges/score.svg)](https://glama.ai/mcp/servers/donnywin85/dex-data-mcp) --- # For an agent Everything you need to decide whether to call this server, and what it will cost, is in this section. Read no further unless a human is asking. ## Install ```bash claude mcp add dex-data -- npx -y dex-data-mcp ``` Or, for any MCP host that reads a JSON config: ```json { "mcpServers": { "dex-data": { "command": "npx", "args": ["-y", "dex-data-mcp"] } } } ``` ## Cost model **The first 25 calls each day are free on every tool.** No wallet, no signup, no API key, no account. The free answer is the full answer — nothing is stubbed, truncated or degraded. What the free tier limits is how many calls you make, not what is in them. After 25 calls in a day, a tool returns a payment challenge instead of an answer. If — and only if — a wallet is configured, this server settles that challenge in USDC on Base and returns the answer. With no wallet it tells you the price and spends nothing. ## Environment | variable | what it does | default | |---|---|---| | `DEX_WALLET_KEY` | EVM private key that pays. **Omit it and this server can never spend anything.** `EVM_PRIVATE_KEY` is read as a fallback. | unset — free tier only | | `DEX_MAX_PRICE_USD` | Per-call ceiling. A call costing more is refused **before** paying. | `0.05` | | `DEX_MAX_SPEND_USD` | Total for the life of the process. | `1.00` | | `DEX_MAX_CALLS` | Number of paid calls for the life of the process. | `200` | | `DEX_MCP_TIMEOUT_MS` | Upstream request timeout. | `45000` | The default ceiling is `$0.05`, which is exactly the dearest tool here. Lower it below that and the `$0.05` tools stop working — deliberately, and they say so. ## The cap, and what "fails closed" means Every paid call passes the same four gates, in this order, and any one of them refuses without paying: 1. **No wallet** → never pays. This is the state you are in unless someone set a key. 2. **Price unreadable** → refuses. A challenge whose amount cannot be parsed is not treated as free or as cheap; it is treated as unknown, and unknown does not get paid. 3. **Price above `DEX_MAX_PRICE_USD`** → refuses, and names the price and the cap. 4. **Would cross `DEX_MAX_SPEND_USD` or `DEX_MAX_CALLS`** → refuses. Accounting is in integer micro-USD, so a `$1.00` budget at `$0.05` a call buys exactly 20 calls and not 19 — floating-point drift cannot quietly close the budget early. **Call `get_spend_budget` before any loop over paid tools.** It is free, local and makes no network call, and it returns what has been spent and every cap in force. ## Tools Thirteen tools. Twelve fetch from the gateway; one is local. Each of the twelve targets exactly one route, and together they are exactly the routes the storefront lists — there is no hidden catalogue and no tool pointing at something that was withdrawn. | tool | price/call | what it returns | example | |---|---|---|---| | `get_base_liquidity` | $0.01 | DEX liquidity, depth and TVL per venue on Base | `{"pair":"WETH/USDC"}` | | `get_polygon_token_price` | $0.01 | Live USD price from Polygon pools, with the backing liquidity and a confidence rating | `{"symbol":"WMATIC"}` | | `get_avalanche_pool_reserves` | $0.01 | Raw AMM reserves, fee, implied price and TVL at one block height | `{"pair":"WAVAX/USDC"}` | | `find_polygon_arbitrage` | $0.01 | Cross-venue price gaps on Polygon, ranked by gross spread | `{"minSpreadBps":25}` | | `find_avalanche_arbitrage` | $0.01 | The same scan on Avalanche C-Chain | `{"minSpreadBps":25}` | | `get_v4_hook_risk` | $0.01 | Uniswap v4 hook permission bits, custody class and verified-source consensus | `{"address":"0x…80"}` | | `lookup_lei` | $0.03 | GLEIF legal-entity record **by name**, lapsed entities flagged not hidden | `{"q":"Apple Inc."}` | | `get_treasury_yield_curve` | $0.03 | US Treasury par yield curve, 1 month to 30 years | `{}` for the latest | | `get_company_dossier` | $0.05 | Identity, OFAC screening and SEC registration for one entity, joined | `{"ticker":"AAPL"}` | | `get_sec_filings` | $0.05 | Everything an issuer has filed since your cursor | `{"ticker":"AAPL","since":"2026-09-01"}` | | `get_sec_events` | $0.05 | 8-K material events since your cursor, decoded by item code | `{"ticker":"TSLA","since":"2026-09-01","items":"5.02"}` | | `get_sec_insiders` | $0.05 | Forms 3/4/5, SC 13D/G ownership changes since your cursor | `{"ticker":"NVDA","since":"2026-09-01"}` | | `get_spend_budget` | free, local | What this session has spent and every cap in force | `{}` | Prices are USDC on Base (`eip155:8453`) and are read from the gateway's own `x-payment-info`, not kept in step by hand. ## Three things that will save you a wasted call - **The three `get_sec_*` tools return DELTAS, not dumps.** `since` is required and inclusive. Pass the date you last read; you get what has landed since. They report `matched` and `truncated`, so a cut-off delta is never mistaken for a complete one. - **Missing arguments are refused here, not upstream.** A call with a required argument absent or empty is stopped before any request is made, and says `Nothing was requested and nothing was spent`. It does not become `?symbol=undefined` and it does not cost you a call. - **`get_v4_hook_risk` never outputs SAFE.** It is capability analysis: it tells you what a hook is *able* to do to your trade, not whether its author intends to. Treat `OPAQUE` as unresolved, not as clean. --- # For a human ## What this is Thirteen MCP tools over live on-chain and regulatory data: DEX market state on Base, Polygon and Avalanche, Uniswap v4 hook security, GLEIF legal-entity lookup, OFAC-screened counterparty dossiers, SEC EDGAR change oracles and the US Treasury yield curve. Zero dependencies, stdio, Node 18+. The payment packages are optional and are only loaded if a wallet is configured. ## Why the tool list shrank in 1.7.0 1.6.1 shipped 23 tools. This release ships 13, and the nine-tool difference is the point. The gateway behind this server sold 62 priced routes, and this package carried a tool for most of them — including geocoding, weather, web search, public holidays, RSS and IP lookup. Then the demand was measured across the whole recorded history of the storefront: 12 routes have either organic buyers or no substitute anywhere in the catalogue. The other 50 had between zero and two calls each, every one of them from a single wallet. On 2026-09-16 the storefront was cut to those 12, and this release follows it. A tool list is not free. It is loaded into the model's context in every session, whether or not a single tool is called, and a tool that advertises a shelf the storefront no longer stocks costs the agent a turn to discover the gap. Removing nine tools makes the list shorter and every entry in it true. **The 50 dropped routes still work.** They are served, priced and payable by anyone holding the URL. Removing a tool withdrew a recommendation, not a product. Three of the nine went for a second, independent reason: the upstreams behind `geocode`, `reverse_geocode` and `get_weather` retire on 2026-09-27. A tool that will 404 in eleven days should not ship in a release today. ## Upgrading from 1.6.x Breaking, and deliberately so: - **No tool takes a `chain` argument any more.** Each tool targets one chain's route and writes the whole path itself. Sending `chain` is now an error rather than being silently ignored — ignoring it would have sent a Polygon question to a Base route and charged for the answer. - **These tools are gone**, with the routes they used to call, which are all still live: `get_token_price` (`/price`), `get_liquidity` (`/liquidity`), `get_pool_reserves` (`/reserves`), `find_arbitrage` (`/scan`), `get_best_venue` (`/route`), `get_slippage` (`/slippage`), `get_liquidity_risk` (`/risk`), `geocode`, `reverse_geocode`, `get_weather`, `search`, `get_search_suggestions`, `get_holidays`, `read_feed`, `get_random`, `url_to_markdown`, `geolocate_ip`, `get_gas`, `list_chains` and `get_dex_spread` (`/call`). - **Chain-specific replacements** exist for the routes the storefront kept: `get_base_liquidity`, `get_polygon_token_price`, `get_avalanche_pool_reserves`, `find_polygon_arbitrage`, `find_avalanche_arbitrage`. - **New**: `get_v4_hook_risk`, `get_company_dossier`, `get_sec_filings`, `get_sec_events`, `get_sec_insiders`. - `lookup_lei`, `get_treasury_yield_curve` and `get_spend_budget` are unchanged. If you were calling a removed tool, the route behind it still answers. Call it directly, at list price, at `https://x402.donnyautomation.com`. ## Paying Set `DEX_WALLET_KEY` to an EVM private key holding USDC on Base, and install the optional payment packages: ```bash npm i @x402/fetch @x402/core @x402/evm viem ``` Without both, this server cannot spend anything: it returns the price and the payment instructions and stops. With them, it pays only what the caps in the agent section above allow. Use a wallet you funded for this and nothing else. This server holds no custody, takes no fee and sends nothing anywhere except the payment the challenge asks for — but the key is yours to scope. ## Development ```bash node test/arg-validation.test.mjs # argument validation over real stdio, no network node test/budget.test.mjs # spend-cap accounting, no wallet, no network node test/paywall-402.test.mjs # every tool against a recorded 402, loopback only node test/spend-cap.test.mjs # the cap refuses each price point, loopback only node scripts/check-coverage.mjs # tools vs the gateway's listed catalogue (needs the network) ``` The three no-network suites run in CI on every push and pull request. The coverage check runs at release, because it is the only one that needs the gateway to be up. `test/fixtures/challenge-402.json` is a verbatim recording of the live gateway's 402 challenge for each of the twelve routes. Re-record it if prices change; the suites assert that each tool's description quotes the same price the challenge asks for. ## Links - Gateway and full API: - Source: - MIT licensed.