@guiie/buda-mcp 1.2.2 → 1.4.0

package/dist/tools/market_sentiment.js

@@ -0,0 +1,104 @@
+import { z } from "zod";
+import { BudaApiError } from "../client.js";
+import { CACHE_TTL } from "../cache.js";
+import { validateMarketId } from "../validation.js";
+export const toolSchema = {
+    name: "get_market_sentiment",
+    description: "Computes a composite sentiment score (−100 to +100) for a Buda.com market based on " +
+        "24h price variation (40%), volume vs 7-day average (35%), and bid/ask spread vs baseline (25%). " +
+        "Returns a score, a label (bearish/neutral/bullish), and a full component breakdown. " +
+        "Example: 'Is the BTC-CLP market currently bullish or bearish?'",
+    inputSchema: {
+        type: "object",
+        properties: {
+            market_id: {
+                type: "string",
+                description: "Market ID (e.g. 'BTC-CLP', 'ETH-BTC', 'BTC-USDT').",
+            },
+        },
+        required: ["market_id"],
+    },
+};
+function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}
+function isStablecoinPair(marketId) {
+    return /-(USDT|USDC|DAI|TUSD)$/i.test(marketId);
+}
+export async function handleMarketSentiment({ market_id }, client, cache) {
+    const validationError = validateMarketId(market_id);
+    if (validationError) {
+        return {
+            content: [{ type: "text", text: JSON.stringify({ error: validationError, code: "INVALID_MARKET_ID" }) }],
+            isError: true,
+        };
+    }
+    try {
+        const id = market_id.toLowerCase();
+        const [tickerData, volumeData] = await Promise.all([
+            cache.getOrFetch(`ticker:${id}`, CACHE_TTL.TICKER, () => client.get(`/markets/${id}/ticker`)),
+            client.get(`/markets/${id}/volume`),
+        ]);
+        const ticker = tickerData.ticker;
+        const vol = volumeData.volume;
+        const bid = parseFloat(ticker.max_bid[0]);
+        const ask = parseFloat(ticker.min_ask[0]);
+        const priceVariation24h = parseFloat(ticker.price_variation_24h);
+        const ask24h = parseFloat(vol.ask_volume_24h[0]);
+        const bid24h = parseFloat(vol.bid_volume_24h[0]);
+        const ask7d = parseFloat(vol.ask_volume_7d[0]);
+        const bid7d = parseFloat(vol.bid_volume_7d[0]);
+        const spreadPct = ask > 0 ? ((ask - bid) / ask) * 100 : 0;
+        const spreadBaseline = isStablecoinPair(market_id) ? 0.3 : 1.0;
+        const volume24h = ask24h + bid24h;
+        const volume7d = ask7d + bid7d;
+        const volumeRatio = volume7d > 0 ? (volume24h * 7) / volume7d : 1;
+        // Price component: ±5% daily change → ±100 on this sub-score
+        const priceRaw = clamp(priceVariation24h * 2000, -100, 100);
+        const priceScore = parseFloat((priceRaw * 0.4).toFixed(4));
+        // Volume component: ratio vs 7d daily average
+        const volumeRaw = clamp((volumeRatio - 1) * 100, -100, 100);
+        const volumeScore = parseFloat((volumeRaw * 0.35).toFixed(4));
+        // Spread component: tighter spread is bullish
+        const spreadRaw = clamp((1 - spreadPct / spreadBaseline) * 100, -100, 100);
+        const spreadScore = parseFloat((spreadRaw * 0.25).toFixed(4));
+        const score = parseFloat((priceScore + volumeScore + spreadScore).toFixed(1));
+        const label = score < -20 ? "bearish" : score > 20 ? "bullish" : "neutral";
+        const result = {
+            market_id: ticker.market_id,
+            score,
+            label,
+            component_breakdown: {
+                price_variation_24h_pct: parseFloat((priceVariation24h * 100).toFixed(4)),
+                volume_ratio: parseFloat(volumeRatio.toFixed(4)),
+                spread_pct: parseFloat(spreadPct.toFixed(4)),
+                spread_baseline_pct: spreadBaseline,
+                price_score: priceScore,
+                volume_score: volumeScore,
+                spread_score: spreadScore,
+            },
+            data_timestamp: new Date().toISOString(),
+            disclaimer: "Sentiment is derived from market microstructure data only. Not investment advice.",
+        };
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    }
+    catch (err) {
+        const msg = err instanceof BudaApiError
+            ? { error: err.message, code: err.status, path: err.path }
+            : { error: String(err), code: "UNKNOWN" };
+        return {
+            content: [{ type: "text", text: JSON.stringify(msg) }],
+            isError: true,
+        };
+    }
+}
+export function register(server, client, cache) {
+    server.tool(toolSchema.name, toolSchema.description, {
+        market_id: z
+            .string()
+            .describe("Market ID (e.g. 'BTC-CLP', 'ETH-BTC', 'BTC-USDT')."),
+    }, (args) => handleMarketSentiment(args, client, cache));
+}
+//# sourceMappingURL=market_sentiment.js.map

package/dist/tools/market_summary.d.ts

@@ -0,0 +1,43 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { BudaClient } from "../client.js";
+import { MemoryCache } from "../cache.js";
+export declare const toolSchema: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            market_id: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export interface MarketSummaryResult {
+    market_id: string;
+    last_price: number;
+    last_price_currency: string;
+    bid: number;
+    ask: number;
+    spread_pct: number;
+    volume_24h: number;
+    volume_24h_currency: string;
+    price_change_24h: number;
+    price_change_7d: number;
+    liquidity_rating: "high" | "medium" | "low";
+}
+interface MarketSummaryInput {
+    market_id: string;
+}
+export declare function handleMarketSummary({ market_id }: MarketSummaryInput, client: BudaClient, cache: MemoryCache): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError?: boolean;
+}>;
+export declare function register(server: McpServer, client: BudaClient, cache: MemoryCache): void;
+export {};
+//# sourceMappingURL=market_summary.d.ts.map

package/dist/tools/market_summary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"market_summary.d.ts","sourceRoot":"","sources":["../../src/tools/market_summary.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,EAAE,UAAU,EAAgB,MAAM,cAAc,CAAC;AACxD,OAAO,EAAE,WAAW,EAAa,MAAM,aAAa,CAAC;AAKrD,eAAO,MAAM,UAAU;;;;;;;;;;;;;CAkBtB,CAAC;AAEF,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,gBAAgB,EAAE,MAAM,CAAC;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;CAC7C;AAED,UAAU,kBAAkB;IAC1B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,wBAAsB,mBAAmB,CACvC,EAAE,SAAS,EAAE,EAAE,kBAAkB,EACjC,MAAM,EAAE,UAAU,EAClB,KAAK,EAAE,WAAW,GACjB,OAAO,CAAC;IAAE,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC,CA4DhF;AAED,wBAAgB,QAAQ,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,GAAG,IAAI,CAWxF"}

package/dist/tools/market_summary.js

@@ -0,0 +1,81 @@
+import { z } from "zod";
+import { BudaApiError } from "../client.js";
+import { CACHE_TTL } from "../cache.js";
+import { validateMarketId } from "../validation.js";
+import { flattenAmount, getLiquidityRating } from "../utils.js";
+export const toolSchema = {
+    name: "get_market_summary",
+    description: "One-call summary of everything relevant about a market: last price, best bid/ask, spread %, " +
+        "24h volume, 24h and 7d price change, and a liquidity_rating ('high' / 'medium' / 'low' based on " +
+        "spread thresholds: < 0.3% = high, 0.3–1% = medium, > 1% = low). All prices and volumes are floats. " +
+        "Best first tool to call when a user asks about any specific market. " +
+        "Example: 'Give me a complete overview of the BTC-CLP market right now.'",
+    inputSchema: {
+        type: "object",
+        properties: {
+            market_id: {
+                type: "string",
+                description: "Market ID (e.g. 'BTC-CLP', 'ETH-COP', 'BTC-PEN').",
+            },
+        },
+        required: ["market_id"],
+    },
+};
+export async function handleMarketSummary({ market_id }, client, cache) {
+    try {
+        const validationError = validateMarketId(market_id);
+        if (validationError) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error: validationError, code: "INVALID_MARKET_ID" }) }],
+                isError: true,
+            };
+        }
+        const id = market_id.toLowerCase();
+        // Fetch ticker and volume in parallel
+        const [tickerData, volumeData] = await Promise.all([
+            cache.getOrFetch(`ticker:${id}`, CACHE_TTL.TICKER, () => client.get(`/markets/${id}/ticker`)),
+            client.get(`/markets/${id}/volume`),
+        ]);
+        const t = tickerData.ticker;
+        const v = volumeData.volume;
+        const lastPrice = flattenAmount(t.last_price);
+        const bid = parseFloat(t.max_bid[0]);
+        const ask = parseFloat(t.min_ask[0]);
+        const volume24h = flattenAmount(v.ask_volume_24h);
+        const spreadAbs = ask - bid;
+        const spreadPct = ask > 0 ? parseFloat(((spreadAbs / ask) * 100).toFixed(4)) : 0;
+        const result = {
+            market_id: t.market_id,
+            last_price: lastPrice.value,
+            last_price_currency: lastPrice.currency,
+            bid,
+            ask,
+            spread_pct: spreadPct,
+            volume_24h: volume24h.value,
+            volume_24h_currency: volume24h.currency,
+            price_change_24h: parseFloat((parseFloat(t.price_variation_24h) * 100).toFixed(4)),
+            price_change_7d: parseFloat((parseFloat(t.price_variation_7d) * 100).toFixed(4)),
+            liquidity_rating: getLiquidityRating(spreadPct),
+        };
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    }
+    catch (err) {
+        const msg = err instanceof BudaApiError
+            ? { error: err.message, code: err.status, path: err.path }
+            : { error: String(err), code: "UNKNOWN" };
+        return {
+            content: [{ type: "text", text: JSON.stringify(msg) }],
+            isError: true,
+        };
+    }
+}
+export function register(server, client, cache) {
+    server.tool(toolSchema.name, toolSchema.description, {
+        market_id: z
+            .string()
+            .describe("Market ID (e.g. 'BTC-CLP', 'ETH-COP', 'BTC-PEN')."),
+    }, (args) => handleMarketSummary(args, client, cache));
+}
+//# sourceMappingURL=market_summary.js.map

package/dist/tools/markets.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"markets.d.ts","sourceRoot":"","sources":["../../src/tools/markets.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,EAAE,UAAU,EAAgB,MAAM,cAAc,CAAC;AACxD,OAAO,EAAE,WAAW,EAAa,MAAM,aAAa,CAAC;AAIrD,eAAO,MAAM,UAAU;;;;;;;;;;;;CActB,CAAC;AAEF,wBAAgB,QAAQ,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,GAAG,IAAI,CAsDxF"}
+{"version":3,"file":"markets.d.ts","sourceRoot":"","sources":["../../src/tools/markets.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,EAAE,UAAU,EAAgB,MAAM,cAAc,CAAC;AACxD,OAAO,EAAE,WAAW,EAAa,MAAM,aAAa,CAAC;AAIrD,eAAO,MAAM,UAAU;;;;;;;;;;;;CAgBtB,CAAC;AAEF,wBAAgB,QAAQ,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,GAAG,IAAI,CAsDxF"}

package/dist/tools/markets.js

@@ -4,8 +4,10 @@ import { CACHE_TTL } from "../cache.js";
 import { validateMarketId } from "../validation.js";
 export const toolSchema = {
     name: "get_markets",
-    description: "List all available trading pairs on Buda.com, or get details for a specific market. " +
-        "Returns base/quote currencies, fees, and minimum order sizes.",
+    description: "Lists all available trading pairs on Buda.com, or returns details for a specific market " +
+        "(base/quote currencies, taker/maker fees as decimals, minimum order size in base currency, " +
+        "and fee discount tiers). Omit market_id to get all ~26 markets at once. " +
+        "Example: 'What is the taker fee and minimum order size for BTC-CLP?'",
     inputSchema: {
         type: "object",
         properties: {

package/dist/tools/orderbook.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"orderbook.d.ts","sourceRoot":"","sources":["../../src/tools/orderbook.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,EAAE,UAAU,EAAgB,MAAM,cAAc,CAAC;AACxD,OAAO,EAAE,WAAW,EAAa,MAAM,aAAa,CAAC;AAIrD,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;CAmBtB,CAAC;AAEF,wBAAgB,QAAQ,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,GAAG,IAAI,CAuDxF"}
+{"version":3,"file":"orderbook.d.ts","sourceRoot":"","sources":["../../src/tools/orderbook.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,EAAE,UAAU,EAAgB,MAAM,cAAc,CAAC;AACxD,OAAO,EAAE,WAAW,EAAa,MAAM,aAAa,CAAC;AAIrD,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;CAqBtB,CAAC;AAEF,wBAAgB,QAAQ,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,GAAG,IAAI,CAgExF"}

package/dist/tools/orderbook.js

@@ -4,8 +4,10 @@ import { CACHE_TTL } from "../cache.js";
 import { validateMarketId } from "../validation.js";
 export const toolSchema = {
     name: "get_orderbook",
-    description: "Get the current order book (bids and asks) for a Buda.com market. Returns sorted arrays of " +
-        "bids (buy orders) and asks (sell orders), each as [price, amount] pairs.",
+    description: "Returns the current order book for a Buda.com market as typed objects with float price and amount fields. " +
+        "Bids are sorted highest-price first; asks lowest-price first. " +
+        "Prices are in the quote currency; amounts are in the base currency. " +
+        "Example: 'What are the top 5 buy and sell orders for BTC-CLP right now?'",
     inputSchema: {
         type: "object",
         properties: {
@@ -44,9 +46,17 @@ export function register(server, client, cache) {
             const id = market_id.toLowerCase();
             const data = await cache.getOrFetch(`orderbook:${id}`, CACHE_TTL.ORDERBOOK, () => client.get(`/markets/${id}/order_book`));
             const book = data.order_book;
+            const bids = limit ? book.bids.slice(0, limit) : book.bids;
+            const asks = limit ? book.asks.slice(0, limit) : book.asks;
             const result = {
-                bids: limit ? book.bids.slice(0, limit) : book.bids,
-                asks: limit ? book.asks.slice(0, limit) : book.asks,
+                bids: bids.map(([price, amount]) => ({
+                    price: parseFloat(price),
+                    amount: parseFloat(amount),
+                })),
+                asks: asks.map(([price, amount]) => ({
+                    price: parseFloat(price),
+                    amount: parseFloat(amount),
+                })),
                 bid_count: book.bids.length,
                 ask_count: book.asks.length,
             };

package/dist/tools/orders.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"orders.d.ts","sourceRoot":"","sources":["../../src/tools/orders.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,EAAE,UAAU,EAAgB,MAAM,cAAc,CAAC;AAIxD,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;CA4BtB,CAAC;AAEF,wBAAgB,QAAQ,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,GAAG,IAAI,CAqEpE"}
+{"version":3,"file":"orders.d.ts","sourceRoot":"","sources":["../../src/tools/orders.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,EAAE,UAAU,EAAgB,MAAM,cAAc,CAAC;AAKxD,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;CA+BtB,CAAC;AAMF,wBAAgB,QAAQ,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,GAAG,IAAI,CAsGpE"}

package/dist/tools/orders.js

@@ -1,10 +1,14 @@
 import { z } from "zod";
 import { BudaApiError } from "../client.js";
 import { validateMarketId } from "../validation.js";
+import { flattenAmount } from "../utils.js";
 export const toolSchema = {
     name: "get_orders",
-    description: "Get orders for a given Buda.com market. Filter by state (pending, active, traded, canceled). " +
-        "Requires BUDA_API_KEY and BUDA_API_SECRET environment variables.",
+    description: "Returns orders for a given Buda.com market as flat typed objects. All monetary amounts are floats " +
+        "with separate _currency fields (e.g. amount + amount_currency). Filterable by state: pending, " +
+        "active, traded, canceled. Supports pagination via per and page. " +
+        "Requires BUDA_API_KEY and BUDA_API_SECRET. " +
+        "Example: 'Show my open limit orders on BTC-CLP.'",
     inputSchema: {
         type: "object",
         properties: {
@@ -28,6 +32,9 @@ export const toolSchema = {
         required: ["market_id"],
     },
 };
+function flattenAmountField(amount) {
+    return flattenAmount(amount);
+}
 export function register(server, client) {
     server.tool(toolSchema.name, toolSchema.description, {
         market_id: z
@@ -68,11 +75,42 @@ export function register(server, client) {
             if (page !== undefined)
                 params.page = page;
             const data = await client.get(`/markets/${market_id.toLowerCase()}/orders`, Object.keys(params).length > 0 ? params : undefined);
+            const orders = data.orders.map((o) => {
+                const amount = flattenAmountField(o.amount);
+                const originalAmount = flattenAmountField(o.original_amount);
+                const tradedAmount = flattenAmountField(o.traded_amount);
+                const totalExchanged = flattenAmountField(o.total_exchanged);
+                const paidFee = flattenAmountField(o.paid_fee);
+                const limitPrice = o.limit ? flattenAmountField(o.limit) : null;
+                return {
+                    id: o.id,
+                    type: o.type,
+                    state: o.state,
+                    created_at: o.created_at,
+                    market_id: o.market_id,
+                    fee_currency: o.fee_currency,
+                    price_type: o.price_type,
+                    order_type: o.order_type,
+                    client_id: o.client_id,
+                    limit_price: limitPrice ? limitPrice.value : null,
+                    limit_price_currency: limitPrice ? limitPrice.currency : null,
+                    amount: amount.value,
+                    amount_currency: amount.currency,
+                    original_amount: originalAmount.value,
+                    original_amount_currency: originalAmount.currency,
+                    traded_amount: tradedAmount.value,
+                    traded_amount_currency: tradedAmount.currency,
+                    total_exchanged: totalExchanged.value,
+                    total_exchanged_currency: totalExchanged.currency,
+                    paid_fee: paidFee.value,
+                    paid_fee_currency: paidFee.currency,
+                };
+            });
             return {
                 content: [
                     {
                         type: "text",
-                        text: JSON.stringify({ orders: data.orders, meta: data.meta }, null, 2),
+                        text: JSON.stringify({ orders, meta: data.meta }, null, 2),
                     },
                 ],
             };

package/dist/tools/price_history.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"price_history.d.ts","sourceRoot":"","sources":["../../src/tools/price_history.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,EAAE,UAAU,EAAgB,MAAM,cAAc,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAoB1C,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;CA4BtB,CAAC;AAEF,wBAAgB,QAAQ,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,GAAG,IAAI,CAsHzF"}
+{"version":3,"file":"price_history.d.ts","sourceRoot":"","sources":["../../src/tools/price_history.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,EAAE,UAAU,EAAgB,MAAM,cAAc,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAK1C,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;CA4BtB,CAAC;AAEF,wBAAgB,QAAQ,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,GAAG,IAAI,CAiFzF"}

package/dist/tools/price_history.js

@@ -1,18 +1,14 @@
 import { z } from "zod";
 import { BudaApiError } from "../client.js";
 import { validateMarketId } from "../validation.js";
-const PERIOD_MS = {
-    "1h": 60 * 60 * 1000,
-    "4h": 4 * 60 * 60 * 1000,
-    "1d": 24 * 60 * 60 * 1000,
-};
+import { aggregateTradesToCandles } from "../utils.js";
 export const toolSchema = {
     name: "get_price_history",
     description: "IMPORTANT: Candles are aggregated client-side from raw trades (Buda has no native candlestick " +
         "endpoint) — fetching more trades via the 'limit' parameter gives deeper history but slower " +
-        "responses. Returns OHLCV (open/high/low/close/volume) price history for a Buda.com market. " +
-        "Candle timestamps are UTC bucket boundaries (e.g. '2026-04-10T12:00:00.000Z' for 1h). " +
-        "Supports 1h, 4h, and 1d candle periods.",
+        "responses. Returns OHLCV candles (open/high/low/close as floats in quote currency; volume as float " +
+        "in base currency) for periods 1h, 4h, or 1d. Candle timestamps are UTC bucket boundaries. " +
+        "Example: 'Show me the hourly BTC-CLP price chart for the past 24 hours.'",
     inputSchema: {
         type: "object",
         properties: {
@@ -73,41 +69,7 @@ export function register(server, client, _cache) {
                     ],
                 };
             }
-            // Buda returns trades newest-first; sort ascending so open = first chronological price
-            // and close = last chronological price within each candle bucket.
-            const sortedEntries = [...entries].sort(([a], [b]) => parseInt(a, 10) - parseInt(b, 10));
-            const periodMs = PERIOD_MS[period];
-            const buckets = new Map();
-            for (const [tsMs, amount, price, _direction] of sortedEntries) {
-                const ts = parseInt(tsMs, 10);
-                const bucketStart = Math.floor(ts / periodMs) * periodMs;
-                const p = parseFloat(price);
-                const v = parseFloat(amount);
-                if (!buckets.has(bucketStart)) {
-                    buckets.set(bucketStart, {
-                        time: new Date(bucketStart).toISOString(),
-                        open: price,
-                        high: price,
-                        low: price,
-                        close: price,
-                        volume: amount,
-                        trade_count: 1,
-                    });
-                }
-                else {
-                    const candle = buckets.get(bucketStart);
-                    if (p > parseFloat(candle.high))
-                        candle.high = price;
-                    if (p < parseFloat(candle.low))
-                        candle.low = price;
-                    candle.close = price;
-                    candle.volume = (parseFloat(candle.volume) + v).toFixed(8);
-                    candle.trade_count++;
-                }
-            }
-            const candles = Array.from(buckets.entries())
-                .sort(([a], [b]) => a - b)
-                .map(([, candle]) => candle);
+            const candles = aggregateTradesToCandles(entries, period);
             const result = {
                 market_id: market_id.toUpperCase(),
                 period,

package/dist/tools/simulate_order.d.ts

@@ -0,0 +1,45 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { BudaClient } from "../client.js";
+import { MemoryCache } from "../cache.js";
+export declare const toolSchema: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            market_id: {
+                type: string;
+                description: string;
+            };
+            side: {
+                type: string;
+                description: string;
+            };
+            amount: {
+                type: string;
+                description: string;
+            };
+            price: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+type SimulateOrderArgs = {
+    market_id: string;
+    side: "buy" | "sell";
+    amount: number;
+    price?: number;
+};
+export declare function handleSimulateOrder(args: SimulateOrderArgs, client: BudaClient, cache: MemoryCache): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError?: boolean;
+}>;
+export declare function register(server: McpServer, client: BudaClient, cache: MemoryCache): void;
+export {};
+//# sourceMappingURL=simulate_order.d.ts.map

package/dist/tools/simulate_order.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"simulate_order.d.ts","sourceRoot":"","sources":["../../src/tools/simulate_order.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,EAAE,UAAU,EAAgB,MAAM,cAAc,CAAC;AACxD,OAAO,EAAE,WAAW,EAAa,MAAM,aAAa,CAAC;AAIrD,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;CA+BtB,CAAC;AAEF,KAAK,iBAAiB,GAAG;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,KAAK,GAAG,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,iBAAiB,EACvB,MAAM,EAAE,UAAU,EAClB,KAAK,EAAE,WAAW,GACjB,OAAO,CAAC;IAAE,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC,CAyGhF;AAED,wBAAgB,QAAQ,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,GAAG,IAAI,CAuBxF"}

package/dist/tools/simulate_order.js

@@ -0,0 +1,139 @@
+import { z } from "zod";
+import { BudaApiError } from "../client.js";
+import { CACHE_TTL } from "../cache.js";
+import { validateMarketId } from "../validation.js";
+export const toolSchema = {
+    name: "simulate_order",
+    description: "Simulates a buy or sell order on Buda.com using live ticker data — no order is placed. " +
+        "Returns estimated fill price, fee, total cost, and slippage vs mid-price. " +
+        "Omit 'price' for a market order simulation; supply 'price' for a limit order simulation. " +
+        "All outputs are labelled simulation: true — this tool never places a real order. " +
+        "Example: 'How much would it cost to buy 0.01 BTC on BTC-CLP right now?'",
+    inputSchema: {
+        type: "object",
+        properties: {
+            market_id: {
+                type: "string",
+                description: "Market ID (e.g. 'BTC-CLP', 'ETH-BTC').",
+            },
+            side: {
+                type: "string",
+                description: "'buy' or 'sell'.",
+            },
+            amount: {
+                type: "number",
+                description: "Order size in base currency (e.g. BTC for BTC-CLP).",
+            },
+            price: {
+                type: "number",
+                description: "Limit price in quote currency. Omit for a market order simulation.",
+            },
+        },
+        required: ["market_id", "side", "amount"],
+    },
+};
+export async function handleSimulateOrder(args, client, cache) {
+    const { market_id, side, amount, price } = args;
+    const validationError = validateMarketId(market_id);
+    if (validationError) {
+        return {
+            content: [{ type: "text", text: JSON.stringify({ error: validationError, code: "INVALID_MARKET_ID" }) }],
+            isError: true,
+        };
+    }
+    try {
+        const id = market_id.toLowerCase();
+        const [tickerData, marketData] = await Promise.all([
+            cache.getOrFetch(`ticker:${id}`, CACHE_TTL.TICKER, () => client.get(`/markets/${id}/ticker`)),
+            cache.getOrFetch(`market:${id}`, CACHE_TTL.MARKETS, () => client.get(`/markets/${id}`)),
+        ]);
+        const ticker = tickerData.ticker;
+        const market = marketData.market;
+        const minAsk = parseFloat(ticker.min_ask[0]);
+        const maxBid = parseFloat(ticker.max_bid[0]);
+        const quoteCurrency = ticker.min_ask[1];
+        if (isNaN(minAsk) || isNaN(maxBid) || minAsk <= 0 || maxBid <= 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: "Unable to simulate: invalid or zero bid/ask values in ticker.",
+                            code: "INVALID_TICKER",
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const mid = (minAsk + maxBid) / 2;
+        const takerFeeRate = parseFloat(market.taker_fee);
+        const orderTypeAssumed = price !== undefined ? "limit" : "market";
+        let estimatedFillPrice;
+        if (orderTypeAssumed === "market") {
+            estimatedFillPrice = side === "buy" ? minAsk : maxBid;
+        }
+        else {
+            // Limit order: fill at provided price if it crosses the spread, otherwise at limit price
+            if (side === "buy") {
+                estimatedFillPrice = price >= minAsk ? minAsk : price;
+            }
+            else {
+                estimatedFillPrice = price <= maxBid ? maxBid : price;
+            }
+        }
+        const grossValue = amount * estimatedFillPrice;
+        const feeAmount = parseFloat((grossValue * takerFeeRate).toFixed(8));
+        const totalCost = side === "buy"
+            ? parseFloat((grossValue + feeAmount).toFixed(8))
+            : parseFloat((grossValue - feeAmount).toFixed(8));
+        const slippageVsMidPct = parseFloat((((estimatedFillPrice - mid) / mid) * 100).toFixed(4));
+        const result = {
+            simulation: true,
+            market_id: ticker.market_id,
+            side,
+            amount,
+            order_type_assumed: orderTypeAssumed,
+            estimated_fill_price: parseFloat(estimatedFillPrice.toFixed(2)),
+            price_currency: quoteCurrency,
+            fee_amount: feeAmount,
+            fee_currency: quoteCurrency,
+            fee_rate_pct: parseFloat((takerFeeRate * 100).toFixed(3)),
+            total_cost: totalCost,
+            slippage_vs_mid_pct: slippageVsMidPct,
+            mid_price: parseFloat(mid.toFixed(2)),
+        };
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    }
+    catch (err) {
+        const msg = err instanceof BudaApiError
+            ? { error: err.message, code: err.status, path: err.path }
+            : { error: String(err), code: "UNKNOWN" };
+        return {
+            content: [{ type: "text", text: JSON.stringify(msg) }],
+            isError: true,
+        };
+    }
+}
+export function register(server, client, cache) {
+    server.tool(toolSchema.name, toolSchema.description, {
+        market_id: z
+            .string()
+            .describe("Market ID (e.g. 'BTC-CLP', 'ETH-BTC')."),
+        side: z
+            .enum(["buy", "sell"])
+            .describe("'buy' or 'sell'."),
+        amount: z
+            .number()
+            .positive()
+            .describe("Order size in base currency (e.g. BTC for BTC-CLP)."),
+        price: z
+            .number()
+            .positive()
+            .optional()
+            .describe("Limit price in quote currency. Omit for a market order simulation."),
+    }, (args) => handleSimulateOrder(args, client, cache));
+}
+//# sourceMappingURL=simulate_order.js.map

package/dist/tools/spread.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"spread.d.ts","sourceRoot":"","sources":["../../src/tools/spread.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,EAAE,UAAU,EAAgB,MAAM,cAAc,CAAC;AACxD,OAAO,EAAE,WAAW,EAAa,MAAM,aAAa,CAAC;AAIrD,eAAO,MAAM,UAAU;;;;;;;;;;;;;CAetB,CAAC;AAEF,wBAAgB,QAAQ,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,GAAG,IAAI,CAuExF"}
+{"version":3,"file":"spread.d.ts","sourceRoot":"","sources":["../../src/tools/spread.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,EAAE,UAAU,EAAgB,MAAM,cAAc,CAAC;AACxD,OAAO,EAAE,WAAW,EAAa,MAAM,aAAa,CAAC;AAIrD,eAAO,MAAM,UAAU;;;;;;;;;;;;;CAiBtB,CAAC;AAEF,wBAAgB,QAAQ,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,GAAG,IAAI,CAuExF"}