@missionsquad/mcp-defillama 1.0.0 → 1.2.0

package/README.md

@@ -1,37 +1,96 @@
 # MCP Server for DefiLlama
 
-A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that gives MCP-compatible clients (Claude Desktop, etc.) access to DeFi data via the [DefiLlama](https://defillama.com) API. It can retrieve protocol TVL, chain TVL, token prices, and stablecoin information.
+A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that gives MCP-compatible clients (Claude Desktop, etc.) access to DeFi data via the [DefiLlama](https://defillama.com) API. It covers all 31 endpoints of DefiLlama's free, keyless API — protocol and chain TVL, token prices, stablecoins, yield pools, DEX and options volume, perps open interest, and fees/revenue.
 
-Published on npm as [`@missionsquad/mcp-defillama`](https://www.npmjs.com/package/@missionsquad/mcp-defillama).
-
-## Tools
+No API key is required. The server routes each request to DefiLlama's category-specific hosts (`api.llama.fi`, `coins.llama.fi`, `stablecoins.llama.fi`, `yields.llama.fi`) automatically.
 
-The server exposes the following tools:
-
-### Protocol Data
+Published on npm as [`@missionsquad/mcp-defillama`](https://www.npmjs.com/package/@missionsquad/mcp-defillama).
 
-- `defillama_get_protocols` — List all protocols tracked by DefiLlama.
-- `defillama_get_protocol_tvl` — Get TVL data for a specific protocol.
-  - `protocol` (string, required): protocol slug, e.g. `aave`.
+## Conventions
 
-### Chain Data
+These apply to every tool:
 
-- `defillama_get_chain_tvl` — Get historical TVL data for a specific chain.
-  - `chain` (string, required): chain name, e.g. `ethereum`.
+- **Dates are human-readable.** Any datetime parameter accepts a 12-hour string such as `06/15/2024 03:30 PM` (UTC is assumed), `06/15/2024 03:30 PM America/New_York`, or `06/15/2024 03:30 PM +05:30`. A timezone, when supplied, is converted to UTC before the request is made. Raw UNIX seconds are also accepted. Date/timestamp fields in **responses** are likewise rendered as UTC strings (e.g. `01/01/2024 12:00:00 AM UTC`).
+- **Responses are compact by default.** To stay within model context limits, large payloads are trimmed: lists are sorted and capped, time series are downsampled (≈30 points), and noisy/heavy fields (logos, descriptions, token-level histories) are dropped. The output is minified JSON.
+- **Opt into more data** with these optional parameters where applicable:
+  - `full` (boolean) — return the complete, untrimmed response.
+  - `points` (number) — max time-series data points to keep (default 30).
+  - `limit` (number) — max items to keep for list endpoints.
+  - `includeTokens` (boolean) — include token-level breakdowns (`protocol_tvl`, `stablecoin_data`).
+  - For the DEX/options/fees overview & summary tools, the aggregate charts are excluded by default; set `excludeTotalDataChart: false` (or `full: true`) to include them.
 
-### Token Data
+## Tools
 
-- `defillama_get_token_prices` — Get current prices of tokens.
-  - `coins` (string[], required): coin identifiers, e.g. `["ethereum:0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"]`.
-- `defillama_get_historical_prices` — Get historical prices of tokens at a point in time.
-  - `coins` (string[], required): coin identifiers.
-  - `timestamp` (number, required): UNIX timestamp (seconds).
+The server exposes all **31** endpoints of the free (keyless) DefiLlama API as MCP tools. Required parameters are marked accordingly; everything else is optional. Each tool's description includes a ready-to-use example.
 
-### Stablecoin Data
+### TVL
 
-- `defillama_get_stablecoins` — List all stablecoins tracked by DefiLlama.
-- `defillama_get_stablecoin_data` — Get data for a specific stablecoin.
-  - `asset` (string, required): stablecoin asset id/name.
+- `defillama_get_protocols` — List all protocols and their TVL.
+- `defillama_get_protocol_tvl` — Full historical TVL breakdown for a protocol.
+  - `protocol` (string, required): protocol slug, e.g. `aave`.
+- `defillama_get_historical_chain_tvl` — Historical TVL across all chains combined.
+- `defillama_get_chain_tvl` — Historical TVL for a specific chain.
+  - `chain` (string, required): chain name, e.g. `ethereum`.
+- `defillama_get_current_protocol_tvl` — Current TVL of a protocol as a single number.
+  - `protocol` (string, required).
+- `defillama_get_chains` — Current TVL of every chain.
+
+### Coins / Prices
+
+- `defillama_get_token_prices` — Current prices of tokens.
+  - `coins` (string[], required): e.g. `["ethereum:0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"]`.
+- `defillama_get_historical_prices` — Token prices at a historical date/time.
+  - `coins` (string[], required), `timestamp` (datetime, required).
+- `defillama_get_batch_historical_prices` — Prices for many coins at many dates/times.
+  - `coins` (object, required): map of coin id → array of datetime strings. `searchWidth` (string, optional).
+- `defillama_get_price_chart` — Price chart over time for the given coins.
+  - `coins` (string[], required); optional `start` (datetime), `end` (datetime), `span`, `period`, `searchWidth`, `points`.
+- `defillama_get_price_percentage_change` — Percentage price change over a period.
+  - `coins` (string[], required); optional `timestamp` (datetime), `lookForward`, `period`.
+- `defillama_get_first_prices` — Earliest recorded price for the given coins.
+  - `coins` (string[], required).
+- `defillama_get_block` — Block height closest to a date/time on a chain.
+  - `chain` (string, required), `timestamp` (datetime, required).
+
+### Stablecoins
+
+- `defillama_get_stablecoins` — List all stablecoins with circulating amounts.
+  - `includePrices` (boolean, optional).
+- `defillama_get_stablecoin_charts_all` — Historical market cap sum of all stablecoins.
+  - `stablecoin` (number, optional): filter by stablecoin ID.
+- `defillama_get_stablecoin_charts_chain` — Historical stablecoin market cap on a chain.
+  - `chain` (string, required), `stablecoin` (number, optional).
+- `defillama_get_stablecoin_data` — Historical data for a specific stablecoin.
+  - `asset` (string, required): stablecoin ID or name.
+- `defillama_get_stablecoin_chains` — Current stablecoin totals per chain.
+- `defillama_get_stablecoin_prices` — Historical stablecoin prices.
+
+### Yields / APY
+
+- `defillama_get_pools` — Latest TVL and APY for all yield pools.
+- `defillama_get_pool_chart` — Historical APY and TVL for a pool.
+  - `pool` (string, required): pool ID (uuid from `defillama_get_pools`).
+
+### DEX / Options volume
+
+- `defillama_get_dexs_overview` — DEX volume overview across all chains.
+- `defillama_get_dexs_overview_by_chain` — DEX volume overview for a chain. `chain` (string, required).
+- `defillama_get_dex_summary` — DEX volume summary for a protocol. `protocol` (string, required).
+- `defillama_get_options_overview` — Options volume overview across all chains.
+- `defillama_get_options_overview_by_chain` — Options volume overview for a chain. `chain` (string, required).
+- `defillama_get_option_summary` — Options volume summary for a protocol. `protocol` (string, required).
+
+The overview/summary tools above (and the fees tools below) also accept optional `excludeTotalDataChart` (boolean), `excludeTotalDataChartBreakdown` (boolean), and `dataType` (string, e.g. `dailyVolume`, `dailyFees`, `dailyRevenue`).
+
+### Perps / Open interest
+
+- `defillama_get_open_interest_overview` — Perpetuals open interest overview.
+
+### Fees / Revenue
+
+- `defillama_get_fees_overview` — Fees and revenue overview across all chains.
+- `defillama_get_fees_overview_by_chain` — Fees and revenue overview for a chain. `chain` (string, required).
+- `defillama_get_fee_summary` — Fees and revenue summary for a protocol. `protocol` (string, required).
 
 ## Requirements
 

package/dist/clients/defillama.client.d.ts

@@ -1,7 +1,28 @@
 /**
  * DefiLlama API Client
- * Provides methods to interact with the DefiLlama API
+ * Provides methods to interact with the free (keyless) DefiLlama API.
+ *
+ * DefiLlama splits its free API across a few category-specific hosts. The
+ * canonical routing is:
+ *   - TVL, DEX/options volume, fees/revenue, open interest -> api.llama.fi
+ *   - Coins / prices / blocks                              -> coins.llama.fi
+ *   - Stablecoins                                          -> stablecoins.llama.fi
+ *   - Yields / pools                                       -> yields.llama.fi
  */
+export declare const DEFILLAMA_HOSTS: {
+    readonly api: "https://api.llama.fi";
+    readonly coins: "https://coins.llama.fi";
+    readonly stablecoins: "https://stablecoins.llama.fi";
+    readonly yields: "https://yields.llama.fi";
+};
+export type QueryValue = string | number | boolean | undefined;
+export type QueryParams = Record<string, QueryValue>;
+/** Common query options for the DEX/options/fees overview & summary endpoints. */
+export interface OverviewOptions {
+    excludeTotalDataChart?: boolean;
+    excludeTotalDataChartBreakdown?: boolean;
+    dataType?: string;
+}
 export interface Protocol {
     id: string;
     name: string;
@@ -39,15 +60,26 @@ export interface ProtocolTvl {
     symbol: string;
     url: string;
     description: string;
-    tvl: number;
+    /** Current TVL (number) or an aggregate historical series, depending on the endpoint shape. */
+    tvl: number | TvlItem[];
     tokensInUsd?: Array<{
         date: number;
         tokens: Record<string, number>;
     }>;
-    tokens?: Record<string, TokenBalance>;
-    chainTvls: Record<string, number>;
+    tokens?: Record<string, TokenBalance> | Array<{
+        date: number;
+        tokens: Record<string, number>;
+    }>;
+    /** Current TVL per chain (present on the live API). */
+    currentChainTvls?: Record<string, number>;
+    /** Per-chain TVL: flat current numbers, or historical {tvl,tokens,tokensInUsd} objects. */
+    chainTvls: Record<string, number | {
+        tvl?: TvlItem[];
+        tokens?: unknown;
+        tokensInUsd?: unknown;
+    }>;
     tvlPriceChange?: Record<string, number>;
-    tvlList: TvlItem[];
+    tvlList?: TvlItem[];
 }
 export interface ChainTvlItem {
     date: number;
@@ -55,11 +87,20 @@ export interface ChainTvlItem {
     tvl?: number;
     totalLiquidityETH?: number;
 }
+export interface Chain {
+    gecko_id: string | null;
+    tvl: number;
+    tokenSymbol: string | null;
+    cmcId: string | null;
+    name: string;
+    chainId: number | null;
+}
 export interface TokenPrice {
     price: number;
     symbol: string;
     timestamp: number;
     confidence: number;
+    decimals?: number;
 }
 export interface TokenPricesResponse {
     coins: Record<string, TokenPrice>;
@@ -90,39 +131,89 @@ export interface StablecoinData extends StablecoinAsset {
     delisted: boolean;
 }
 export declare class DefiLlamaClient {
-    private baseUrl;
-    constructor(baseUrl?: string);
-    /**
-     * Makes a GET request to the DefiLlama API
-     */
-    private get;
     /**
-     * Get all protocols
+     * Makes a GET request to one of the DefiLlama hosts.
      */
+    protected request<T>(host: string, path: string, query?: QueryParams): Promise<T>;
+    /** Joins coin identifiers into the comma-separated form DefiLlama expects. */
+    private joinCoins;
+    /** GET /protocols — list all protocols. */
     getProtocols(): Promise<Protocol[]>;
-    /**
-     * Get TVL data for a specific protocol
-     */
+    /** GET /protocol/{protocol} — full TVL breakdown for a protocol. */
     getProtocolTvl(protocol: string): Promise<ProtocolTvl>;
-    /**
-     * Get historical TVL data for a specific chain
-     */
+    /** GET /v2/historicalChainTvl — historical TVL across all chains. */
+    getHistoricalChainTvl(): Promise<ChainTvlItem[]>;
+    /** GET /v2/historicalChainTvl/{chain} — historical TVL for one chain. */
     getChainTvl(chain: string): Promise<ChainTvlItem[]>;
-    /**
-     * Get current prices for specified tokens/coins
-     */
+    /** GET /tvl/{protocol} — current TVL of a protocol as a single number. */
+    getCurrentProtocolTvl(protocol: string): Promise<number>;
+    /** GET /v2/chains — current TVL of all chains. */
+    getChains(): Promise<Chain[]>;
+    /** GET /prices/current/{coins} — current prices for the given coins. */
     getTokenPrices(coins: string[]): Promise<TokenPricesResponse>;
-    /**
-     * Get historical prices for specified tokens/coins at a specific timestamp
-     */
+    /** GET /prices/historical/{timestamp}/{coins} — prices at a timestamp. */
     getHistoricalPrices(coins: string[], timestamp: number): Promise<TokenPricesResponse>;
     /**
-     * Get all stablecoins data
-     */
-    getStablecoins(): Promise<StablecoinsResponse>;
-    /**
-     * Get data for a specific stablecoin
+     * GET /batchHistorical — historical prices for many coins at many timestamps.
+     * @param coins Map of coin identifier to an array of UNIX timestamps.
      */
+    getBatchHistoricalPrices(coins: Record<string, number[]>, searchWidth?: string): Promise<TokenPricesResponse>;
+    /** GET /chart/{coins} — price chart for the given coins. */
+    getPriceChart(coins: string[], options?: {
+        start?: number;
+        end?: number;
+        span?: number;
+        period?: string;
+        searchWidth?: string;
+    }): Promise<unknown>;
+    /** GET /percentage/{coins} — percentage price change for the given coins. */
+    getPricePercentageChange(coins: string[], options?: {
+        timestamp?: number;
+        lookForward?: boolean;
+        period?: string;
+    }): Promise<unknown>;
+    /** GET /prices/first/{coins} — earliest recorded price for the given coins. */
+    getFirstPrices(coins: string[]): Promise<TokenPricesResponse>;
+    /** GET /block/{chain}/{timestamp} — closest block to a timestamp on a chain. */
+    getBlock(chain: string, timestamp: number): Promise<{
+        height: number;
+        timestamp: number;
+    }>;
+    /** GET /stablecoins — list all stablecoins with circulating amounts. */
+    getStablecoins(includePrices?: boolean): Promise<StablecoinsResponse>;
+    /** GET /stablecoincharts/all — historical mcap sum of all stablecoins. */
+    getStablecoinChartsAll(stablecoin?: number | string): Promise<unknown>;
+    /** GET /stablecoincharts/{chain} — historical mcap of stablecoins on a chain. */
+    getStablecoinChartsChain(chain: string, stablecoin?: number | string): Promise<unknown>;
+    /** GET /stablecoin/{asset} — historical data for a single stablecoin. */
     getStablecoinData(asset: string): Promise<StablecoinData>;
+    /** GET /stablecoinchains — current stablecoin totals per chain. */
+    getStablecoinChains(): Promise<unknown>;
+    /** GET /stablecoinprices — historical stablecoin prices. */
+    getStablecoinPrices(): Promise<unknown>;
+    /** GET /pools — latest data for all yield pools. */
+    getPools(): Promise<unknown>;
+    /** GET /chart/{pool} — historical APY and TVL for a pool. */
+    getPoolChart(pool: string): Promise<unknown>;
+    /** GET /overview/dexs — DEX volume overview across all chains. */
+    getDexsOverview(options?: OverviewOptions): Promise<unknown>;
+    /** GET /overview/dexs/{chain} — DEX volume overview for a chain. */
+    getDexsOverviewByChain(chain: string, options?: OverviewOptions): Promise<unknown>;
+    /** GET /summary/dexs/{protocol} — DEX volume summary for a protocol. */
+    getDexSummary(protocol: string, options?: OverviewOptions): Promise<unknown>;
+    /** GET /overview/options — options volume overview across all chains. */
+    getOptionsOverview(options?: OverviewOptions): Promise<unknown>;
+    /** GET /overview/options/{chain} — options volume overview for a chain. */
+    getOptionsOverviewByChain(chain: string, options?: OverviewOptions): Promise<unknown>;
+    /** GET /summary/options/{protocol} — options volume summary for a protocol. */
+    getOptionSummary(protocol: string, options?: OverviewOptions): Promise<unknown>;
+    /** GET /overview/open-interest — perps open interest overview. */
+    getOpenInterestOverview(options?: OverviewOptions): Promise<unknown>;
+    /** GET /overview/fees — fees/revenue overview across all chains. */
+    getFeesOverview(options?: OverviewOptions): Promise<unknown>;
+    /** GET /overview/fees/{chain} — fees/revenue overview for a chain. */
+    getFeesOverviewByChain(chain: string, options?: OverviewOptions): Promise<unknown>;
+    /** GET /summary/fees/{protocol} — fees/revenue summary for a protocol. */
+    getFeeSummary(protocol: string, options?: OverviewOptions): Promise<unknown>;
 }
 export declare const defiLlamaClient: DefiLlamaClient;