# Changelog

All notable changes to the DexPaprika MCP Server will be documented in this file.

## [2.3.3] - 2026-08-05

### Changed

- **`getCapabilities` reports the real free-tier numbers instead of `free: true` / `requires_api_key: false`.** Those two booleans read as "unmetered and never needs a key", which is wrong now that paid plans exist. `stats` now carries `free_tier`, `key_required_to_start`, `free_tier_credits_per_month` (200,000 keyless per IP), `free_key_credits_per_month` (500,000), `free_tier_requests_per_minute` (30), `free_tier_max_data_delay_seconds` (15) and `pricing_url`. The `getCapabilities` output schema was updated to match, so `structuredContent` still validates.
- README: the rate-limit section said "Free Tier Limits: 10,000 requests per day". There is no daily quota. It now states the monthly credit allowances, the per-minute rate and the 15 second free-tier data delay.
- README: the install section claimed "The server runs on port 8010 by default. You'll see `MCP server is running at http://localhost:8010`". It does not. This is a stdio server, it binds no port, and it prints `DexPaprika MCP server v<version> (tool contract v<contract>) is running...` to stderr. The `dexpaprika-mcp --version` verification step did not work either: the flag is ignored and the server just starts.
- README: the JSON-RPC transport endpoint was listed as `https://mcp.dexpaprika.com/mcp`, which returns 404 Not found. The working path is `https://mcp.dexpaprika.com/json-rpc`; a live `tools/list` there returns the same 17 tools as the streamable-http transport.
- README: fixed the Smithery install command and link (the `@coinpaprika/dexpaprika-mcp` slug 404s; the live listing is `coinpaprika/dexpaprika`), replaced the dead Model Context Protocol link, dropped the stale "Version 1.3.0 Update Highlights" block, and noted that self-host exposes 16 tools while the hosted server exposes 17.

## [2.3.2] - 2026-07-30

### Changed

- **Stopped calling `order_by`/`sort` deprecated.** They are the parameter names the REST API at `api.dexpaprika.com` actually requires, so labelling them deprecated pushed people toward using `sort_by` against REST, where an unrecognized parameter *name* is silently dropped and the default `volume_usd_24h desc` ordering makes it look like the sort worked. Both spellings remain accepted here; the descriptions now say so and point at which name each layer uses.
- `sort_by` and `sort_dir` descriptions now cross-reference their REST equivalents (`order_by`, `sort`).
- Added a `getCapabilities` pitfall spelling out the MCP versus REST naming difference, including that an unrecognized `order_by` *value* does return a 400 listing the valid fields.

## [2.3.1] - 2026-07-29

### Changed

- **Sharpened all 16 read-tool descriptions for tool-definition quality.** Each now surfaces the sort options (canonical `sort_by`/`sort_dir` with their legacy `order_by`/`sort` aliases), pagination model and defaults, key filters, and the returned shape into the description prose (previously only in the schema), plus clearer differentiation among the pool/token tools. Corrected the stated return envelope for `getNetworkDexes` (`dexes`), `getDexPools` (`pools`), and `getPoolTransactions` (`transactions`) with `page_info`, versus the `results`+cursor tools. No behavior, parameter, or output change.

## [2.3.0] - 2026-07-27

### Removed

- **`submitFeedback` tool removed from the self-host build.** The stdio build had no analytics sink, so the tool only returned an acknowledgement and persisted nothing. Feedback collection now lives solely on the hosted MCP (`mcp.dexpaprika.com`), where it is actually stored. Self-host now exposes 16 read tools; the hosted server keeps `submitFeedback`. Agents that previously called it should submit feedback via the hosted server or open a GitHub issue.

### Changed

- **Intent-first tool descriptions.** Every tool description was rewritten so agents pick the right tool from the description alone: each leads with what the tool returns and adds `Use when asked '...'` cues (e.g. `getNetworkPools` for "the biggest pools on Base", `getTokenPools` for "which pools hold WETH"). The `z.coerce.number()` parameter schemas and all output schemas are unchanged. Matches the descriptions now served by the hosted worker so hosted and self-host read identically.

## [2.2.1] - 2026-07-22

### Fixed

- **Numeric tool parameters now accept string-encoded numbers.** Every numeric input param (`limit`, `page`, `from`, `to`, and the `*_min`/`*_max`/`created_after`/`created_before` filters) used a strict `z.number()` schema, which rejected values like `"3"` with `-32602 Input validation error: Expected number, received string`. Several LLMs serialize numeric tool arguments as strings, and because the error is deterministic the model re-sends the same call and the agent loops until it hits its recursion limit and gives up with no answer. Switched these params to `z.coerce.number()` so `"3"` and `3` both validate. Output-schema fields are unchanged. Verified end-to-end: a model that previously looped on `getTokenPools(..., limit: "3")` now completes on the first call.

Migrate `getTokenPools` to the unified pool search endpoint. DexPaprika removed `/networks/{network}/tokens/{token_address}/pools` (HTTP 410 with `"replacement": "/networks/:network/pools/search"`), so `getTokenPools` was returning the deprecation error from 2.1.1 until this release. `/networks/{network}/pools/search` gained a `token_address` query param that restricts results to pools containing that token.

### Breaking changes

- **`getTokenPools` now returns rows under `results`** (was `pools` + `page_info`) with cursor pagination (`has_next_page` + `next_cursor`), matching the four tools migrated in 2.1.0. The `page` parameter is replaced by `cursor`. Rows use the canonical field names (`volume_usd_24h`, `liquidity_usd`, `price_change_percentage_24h`, ...).
- **`inversed`/`reorder` and `paired_token_address`/`address` are dropped**: the replacement endpoint has no pair-perspective flip and no second-token pair filter (repeating `token_address` does not act as a pair filter; the API uses only one of the values, not guaranteed by order; spec is final per the API team). The parameters stay in the input schema so existing callers do not fail validation, but supplying `inversed`/`reorder: true` or a `paired_token_address`/`address` value returns a structured `DP400_UNSUPPORTED_PARAM` error with a client-side workaround (compute `1/price` for the flipped pair; filter `results[].tokens` for pair queries).

### Changed

- `getTokenPools` proxies `/networks/{network}/pools/search?token_address=...`, reusing the shared `src/search-mapping.js` normalization: legacy sort values (`volume_usd`, `transactions`, ...) map to the canonical search names, so existing callers keep working.
- Tool description, server instructions, and `getCapabilities.common_pitfalls` now spell out that the token filter is network-scoped only (the cross-network `/pools/search` accepts `token_address` but silently ignores it) and that an unknown `token_address` returns an empty `results` array with HTTP 200, not an error.

### Fixed

- **Structured errors now actually reach clients**: error results set `isError: true` per the MCP spec. Without the flag, SDK 1.29 validates every result against the tool's `outputSchema` and rejects results that lack `structuredContent`, so any tool error on a schema-bearing tool (including the 2.1.1 deprecation-aware 410 errors) surfaced as an opaque JSON-RPC `-32602 Output validation error` instead of the structured `code`/`suggestion` payload. Found while testing the unsupported-parameter errors in this release.

## [2.1.3] - 2026-07-14

### Fixed
- **Repackage of 2.1.2, which is broken on npm**: the 2.1.2 tarball was published without the dist/ directory, so its bin target (dist/bin.js) does not exist and fresh `npx dexpaprika-mcp` installs fail or silently fall back to an older binary on PATH. 2.1.2 is deprecated on the registry; no source changes besides packaging.
- Added a `prepack` hook that runs the build automatically, so any future `npm pack`/`npm publish` always includes dist/.

## [2.1.2] - 2026-07-14

### Fixed
- Startup banner reports the real package version instead of a hardcoded v2.0.0; the hosted tool-contract version is shown separately.
- `getCapabilities` stats refreshed to live coverage: 36 networks, 33M+ tokens, 36M+ pools.
- README tool count corrected from 14 to 17; added the missing `getTopTokens`, `filterNetworkTokens`, and `submitFeedback` rows to the tools tables.

## [2.1.1] - 2026-07-01

### Added
- **Deprecation-aware errors**: when the API returns an error whose body carries a `replacement` field, the error now includes the API's message plus `Use <replacement> instead.` and a `metadata.replacement`, so agents are pointed at the new endpoint instead of a bare status line. Generic across any error status, not hardcoded to specific endpoints.

## [2.1.0] - 2026-06-30

Migrate the pool and token list/filter tools to the unified search endpoints. DexPaprika removed `/networks/{network}/pools`, `/networks/{network}/pools/filter`, `/networks/{network}/tokens/top`, and `/networks/{network}/tokens/filter` (HTTP 410), so `getNetworkPools`, `getNetworkPoolsFilter`, `getTopTokens`, and `filterNetworkTokens` were erroring until this release.

### Breaking changes

- **`getNetworkPools`, `getNetworkPoolsFilter`, `getTopTokens`, and `filterNetworkTokens` now return rows under `results`** (was `pools` / `tokens` / `data`) with cursor pagination (`has_next_page` + `next_cursor`) instead of `page_info` and page numbers. The `page` parameter is replaced by `cursor`. Rows use the canonical field names (`volume_usd_24h`, `txns_24h`, `liquidity_usd`, `fdv_usd`, `price_change_percentage_24h`). This mirrors the upstream API change and is unavoidable.
- **`getTopTokens` no longer supports ordering by price**: the search endpoint rejects it, so a supplied `price_usd` falls back to `volume_usd_24h`.

### Changed

- `getNetworkPools` and `getNetworkPoolsFilter` now proxy `/networks/{network}/pools/search`; `getTopTokens` and `filterNetworkTokens` proxy `/networks/{network}/tokens/search`. Tool names are unchanged for client back-compat.
- Legacy sort-field values (`volume_usd`, `transactions`, `last_price_change_usd_24h`, `volume_24h`, `liquidity`, ...) and legacy filter param names (`volume_24h_min` → `volume_usd_24h_min`, ...) are auto-mapped to the canonical search names, so existing callers keep working. A shared `src/search-mapping.js` does the normalization.
- Output schemas and the README examples updated to the search response shape.

## [2.0.0] - 2026-06-03

Full 1:1 contract parity with the hosted DexPaprika MCP worker (`mcp.dexpaprika.com`) v2.0.0. Only the transport differs (stdio vs HTTP); tools, parameters, aliases, synonym resolution, sort normalization, output schemas, server instructions and version now match the worker.

### Breaking changes

- **Response shape — the `{ data, meta }` wrapper is gone.** Previously every tool wrapped its payload as `{ data: <payload>, meta: { rate_limit, response_time_ms, cached, timestamp } }`. Now each tool returns the upstream payload directly, in two forms: `content[0].text` (the JSON string, for older clients) and `structuredContent` (the same object, validated against the tool's `outputSchema`, MCP 2025-06-18+). The per-request `meta` block (rate-limit counters, response time) is no longer emitted. Consumers that read `response.data` must now read the top level. This is intentional and aligns the self-host build with the worker's wire shape.
- **Array tools wrap under named keys** in `structuredContent`: `getNetworks` → `{ networks: [...] }`, `getPoolOHLCV` → `{ ohlcv: [...] }`. `getTokenMultiPrices` now returns `{ prices: [{id, chain, price_usd}], missing_tokens: [...] }` — tokens upstream could not price are surfaced in `missing_tokens` instead of being silently dropped.
- **`rationale` is now required on every read tool** (all tools except `submitFeedback`): a 20-500 char string explaining why the call is made. The self-host build accepts it to satisfy the schema and does not persist it (no analytics sink). `submitFeedback` is the one tool with no `rationale` field — its `goal`/`expected`/`observed` fields serve that purpose.
- **Minimum SDK bump**: `@modelcontextprotocol/sdk` is now `^1.29.0` (was `^1.4.1`). Tools migrated from the deprecated `server.tool()` signature to `server.registerTool()` with explicit `inputSchema`/`outputSchema`/`annotations`.

### Added

- **Network synonym resolution at the wire layer** — `eth` → `ethereum`, `matic` → `polygon`, `sol` → `solana`, and 30+ more across 35 canonical networks. The rewrite happens at the single fetch chokepoint, so advertised synonyms now actually resolve instead of 404ing. The same map drives `getCapabilities.network_synonyms`.
- **Canonical sort aliases** — `sort_dir` (canonical) alongside `sort` (legacy), and `sort_by` (canonical) alongside `order_by` (legacy), on `getNetworkDexes`, `getNetworkPools`, `getDexPools`, `getTokenPools`, `getTopTokens`. The two filter tools (`getNetworkPoolsFilter`, `filterNetworkTokens`) gain the legacy `sort`/`order_by` aliases. Canonical wins when both are supplied; the legacy wire param each tool already used is preserved.
- **`getTokenPools` aliases** — `inversed` (canonical, alias of legacy `reorder`) and `paired_token_address` (canonical, alias of legacy `address`).
- **`submitFeedback` tool (17th tool)** — low-friction feedback channel with `goal`/`attempted_tools`/`blocked_at`/`expected`/`observed`/`severity`. The self-host build returns a structured ack (`{ ok: true, tracking_id: null, ... }`) rather than persisting; the hosted worker writes to its analytics DB.
- **Per-tool output schemas** — every tool advertises an `outputSchema` (permissive `.passthrough()` so extra upstream fields don't break strict validators like Cursor / Claude Desktop).
- **Server `instructions`** — onboarding notes (rationale convention, parameter naming, time formats, output shape) advertised once per session via the initialize result.

### Changed

- `getCapabilities` is now a lean, local-only doc matching the worker: top-level `name`/`aliases`/`server`/`tools_count: 17`/`stats` (35 networks, ~29M tokens, ~31M pools, free, no API key)/`network_synonyms`/`workflows`/`common_pitfalls`/`documentation`/`agent_skills`. The previous sprawling capabilities object (validation rules, rate limits, parameter examples, version history, etc.) was replaced. Stale "33 networks" corrected to 35.
- `page=0` is coerced to `page=1` in all paginated handlers (1-indexed, backward-compat).
- The structured error handling (`parseAPIError`) is preserved and still surfaces actionable `code`/`suggestion` payloads.

### Notes

- `filterNetworkTokens` advertises a `results` array in its output schema for parity, but the live API returns its rows under `data` (plus a `query` echo). Both pass through `structuredContent` via the schema's outer passthrough; the documented key is optional so real responses validate.

## [1.3.0] - 2026-03-19

### ⚠️ BREAKING CHANGES

#### Parameter Naming — snake_case Alignment
All tool parameters now use snake_case to match the hosted MCP server at `mcp.dexpaprika.com`:
- `poolAddress` → `pool_address` (getPoolDetails, getPoolOHLCV, getPoolTransactions)
- `tokenAddress` → `token_address` (getTokenDetails, getTokenPools)
- `orderBy` → `order_by` (getNetworkDexes, getNetworkPools, getDexPools, getTokenPools)

#### Pagination — 1-indexed
All `page` parameters now default to `1` (1-indexed) instead of `0` (0-indexed), matching the hosted server behavior.

#### Token Multi Prices — Comma-Separated Format
`getTokenMultiPrices` now serializes tokens as a single comma-separated query param (`?tokens=a,b,c`) instead of repeated params (`?tokens=a&tokens=b`).

### ✨ Added

- **New tool: `getCapabilities`** — Returns server capabilities, workflow patterns, network synonyms, common pitfalls, and best-practice sequences. Essential for agent onboarding.
- **New tool: `getNetworkPoolsFilter`** — Server-side pool filtering by volume (`volume_24h_min`, `volume_24h_max`), transactions (`txns_24h_min`), and creation time (`created_after`, `created_before`). More efficient than client-side filtering.
- **Structured error handling** — All errors now return structured objects with `code`, `message`, `retryable`, `suggestion`, `corrected_example`, and `metadata` fields. Error codes include `DP400_INVALID_NETWORK`, `DP404_NOT_FOUND`, `DP429_RATE_LIMIT`, etc.
- **Response metadata** — All successful responses now include `meta` with `rate_limit` info, `response_time_ms`, and `timestamp`.
- **Batch validation** — `getTokenMultiPrices` now validates max 10 tokens and returns a structured error if exceeded.
- **OHLCV interval validation** — `interval` parameter on `getPoolOHLCV` now uses `z.enum()` for strict validation of allowed values.

### 🔧 Changed

- All tool descriptions updated to match the hosted MCP server exactly (added TIP references, REQUIRED/OPTIONAL labels).
- Server name changed from `dexpaprika-mcp` to `dexpaprika` to match hosted server.
- JSON responses are now pretty-printed (`JSON.stringify(data, null, 2)`).
- Startup log uses `console.error` instead of `console.log` (proper MCP stdio convention).
- Version bumped to 1.3.0.

### 📝 Notes

- The npm package now matches the hosted MCP server at `mcp.dexpaprika.com` exactly — same tools, same schemas, same error handling, same response format.
- All 14 tools are now available: getCapabilities, getNetworks, getNetworkDexes, getNetworkPools, getDexPools, getNetworkPoolsFilter, getPoolDetails, getPoolOHLCV, getPoolTransactions, getTokenDetails, getTokenPools, getTokenMultiPrices, search, getStats.
- For users who prefer a hosted solution with zero setup, use `mcp.dexpaprika.com/streamable-http` directly.

### 🔄 Migration Guide

**Parameter renames:**
```javascript
// Before (v1.2.0)
getPoolDetails({ network: 'ethereum', poolAddress: '0x...', inversed: false })
getTokenDetails({ network: 'ethereum', tokenAddress: '0x...' })
getNetworkPools({ network: 'ethereum', orderBy: 'volume_usd' })

// After (v1.3.0)
getPoolDetails({ network: 'ethereum', pool_address: '0x...', inversed: false })
getTokenDetails({ network: 'ethereum', token_address: '0x...' })
getNetworkPools({ network: 'ethereum', order_by: 'volume_usd' })
```

**Pagination:**
```javascript
// Before: 0-indexed
getNetworkPools({ network: 'ethereum', page: 0 })

// After: 1-indexed
getNetworkPools({ network: 'ethereum', page: 1 })
```

## [1.2.0] - 2025-10-14

### ✨ Added

- New MCP tool: `getTokenMultiPrices` for batched token price retrieval via repeatable `tokens` query parameters (e.g., `?tokens=a&tokens=b`). Unknown tokens are omitted from the response.

### 🔧 Changed

- `getNetworkDexes` now supports `sort` (asc|desc) and `order_by=pool` to align with the latest OpenAPI.
- Updated tests to cover the new batched prices endpoint and expanded parameter combinations.
- Documentation updates in README for 1.2.0 usage examples and configuration notes.
- Version bumped to 1.2.0.

### 📝 Notes for 1.2.0

- No breaking changes in this release.
- The batched prices endpoint improves efficiency when you only need current USD prices for multiple tokens.

## [1.1.0] - 2025-01-27

### ⚠️ BREAKING CHANGES

#### API Deprecation - Global Pools Endpoint Removed
- **REMOVED**: `getTopPools` function that used the deprecated global `/pools` endpoint
- The global `/pools` endpoint has been permanently removed and now returns `410 Gone`
- All pool queries now require a specific network to improve performance and provide more relevant results

### 🔄 Migration Guide

#### For users who were using `getTopPools`:

**Before (v1.0.x):**
```javascript
// This will no longer work
getTopPools({ page: 0, limit: 10, sort: 'desc', orderBy: 'volume_usd' })
```

**After (v1.1.0):**
```javascript
// Use network-specific queries instead
getNetworkPools({ network: 'ethereum', page: 0, limit: 10, sort: 'desc', orderBy: 'volume_usd' })
getNetworkPools({ network: 'solana', page: 0, limit: 10, sort: 'desc', orderBy: 'volume_usd' })
```

### ✨ Added

- **Enhanced Error Handling**: Added specific error handling for `410 Gone` responses with helpful migration messages
- **Improved Function Descriptions**: All functions now include better guidance on parameter usage
- **New Parameter Support**: Added `reorder` parameter to `getTokenPools` function
- **Better Documentation**: Enhanced parameter descriptions with references to helper functions (e.g., "use getNetworks to see all available networks")
- **Network Guidance**: All network-dependent functions now reference `getNetworks` for discovering valid network IDs

### 🔧 Changed

- **Version**: Updated from 1.0.5 to 1.1.0 to reflect breaking changes
- **Primary Pool Method**: `getNetworkPools` is now highlighted as the primary method for pool data retrieval
- **Parameter Limits**: Updated limit descriptions to reflect API maximum of 100 items per page
- **OHLCV Documentation**: Improved parameter descriptions for better clarity on supported formats
- **Transaction Pagination**: Enhanced documentation for both page-based and cursor-based pagination options

### 🛠️ Technical Improvements

- **Better Error Messages**: More descriptive error messages that guide users toward correct usage patterns
- **Consistent Parameter Descriptions**: Standardized network parameter descriptions across all functions
- **Enhanced Type Safety**: Maintained strong typing with Zod schemas while improving usability

### 📝 Notes

- This update aligns with DexPaprika API v1.3.0 changes
- The API is now considered stable (no longer in beta)
- No API key is required for any endpoints
- All existing network-specific endpoints remain unchanged and fully functional

## [1.0.5] - Previous Release

### 🔧 Changed
- Updated dependencies
- Minor bug fixes and improvements

## [1.0.4] - Previous Release

### ✨ Added
- Initial stable release with full DexPaprika API coverage
- Support for networks, DEXes, pools, tokens, and search functionality
- OHLCV data retrieval for price analysis
- Transaction history access
- Comprehensive error handling and rate limiting support

---

## Migration Support

If you need help migrating from v1.0.x to v1.1.0, please:

1. **Replace all `getTopPools` calls** with `getNetworkPools` calls specifying the desired network
2. **Use `getNetworks`** first to discover available networks if you need to query multiple networks
3. **Update any error handling** to account for the new `410 Gone` error messages
4. **Consider the performance benefits** of network-specific queries for your use case

For additional support, please refer to the [DexPaprika API documentation](https://docs.dexpaprika.com/) or open an issue in this repository.