@guiie/buda-mcp 1.2.2 → 1.3.0

package/CHANGELOG.md

@@ -7,6 +7,43 @@ This project uses [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [1.3.0] – 2026-04-11
+
+### Added
+
+- **`src/utils.ts`** — shared `flattenAmount(amount: Amount)` helper (returns `{ value: number, currency: string }`) and `getLiquidityRating(spreadPct: number)` helper (`"high"` / `"medium"` / `"low"`) used across multiple tools and unit-testable in isolation.
+
+- **`get_arbitrage_opportunities`** (`src/tools/arbitrage.ts`) — new public tool that detects cross-country price discrepancies for a given asset across Buda's CLP, COP, and PEN markets, normalised to USDC. Inputs: `base_currency` (e.g. `"BTC"`) and optional `threshold_pct` (default `0.5`). Algorithm: fetches all tickers, converts each local price to USDC via the current USDC-CLP / USDC-COP / USDC-PEN rates, computes all pairwise discrepancy percentages, filters by threshold, and sorts descending. Output includes a `fees_note` reminding callers that Buda's 0.8% taker fee per leg (~1.6% round-trip) must be deducted. Exports `handleArbitrageOpportunities` for unit testing.
+
+- **`get_market_summary`** (`src/tools/market_summary.ts`) — new public tool that returns a single unified object with everything relevant about a market: `last_price`, `last_price_currency`, `bid`, `ask`, `spread_pct`, `volume_24h`, `volume_24h_currency`, `price_change_24h`, `price_change_7d`, and `liquidity_rating` (`"high"` when spread < 0.3%, `"medium"` when 0.3–1%, `"low"` when > 1%). Makes 2 API calls in parallel (ticker + volume); spread is derived from the ticker without a third call. Exports `handleMarketSummary` for unit testing.
+
+- **`buda://summary/{market}`** MCP Resource — registered in both stdio (`src/index.ts`) and HTTP (`src/http.ts`) transports. Returns the same JSON as `get_market_summary`. Added to the server-card `resources` array.
+
+- **Unit tests (12 new, 35 total)** in `test/unit.ts`:
+  - **f. Numeric flattening** (4 tests): `flattenAmount` returns a `number`, not a string; handles decimals and zero correctly; result is not an array.
+  - **g. `get_arbitrage_opportunities`** (3 tests): mocked tickers verify correct USDC-normalised discrepancy calculation (~3.95% for BTC CLP vs PEN at the given rates); threshold 5% correctly excludes the opportunity; returns `isError` when fewer than 2 markets have USDC rates.
+  - **h. `get_market_summary` / `getLiquidityRating`** (5 tests): boundary tests for all three liquidity tiers; end-to-end mock verifies `liquidity_rating: "high"` at 0.2% spread and that `last_price` is a number type.
+
+### Changed
+
+- **Flat response schemas across all tools** — every tool that previously returned Buda `[amount_string, currency_string]` tuples now returns flat, typed fields. All numeric strings are cast to `parseFloat`; the currency is separated into a `_currency`-suffixed sibling field. Specific changes per tool:
+  - **`get_ticker`** — `last_price`, `min_ask`, `max_bid`, `volume` flattened; `price_variation_24h` / `price_variation_7d` cast to float.
+  - **`get_market_volume`** — all four `*_volume_*` Amount fields flattened with `_currency` suffix.
+  - **`get_orderbook`** — bids and asks converted from `[price, amount]` tuples to `{ price: float, amount: float }` objects.
+  - **`get_trades`** — entries converted from `[timestamp_ms, amount, price, direction]` tuples to `{ timestamp_ms: int, amount: float, price: float, direction: string }` objects.
+  - **`get_spread`** — `best_bid`, `best_ask`, `spread_absolute`, `last_price` → floats; `spread_percentage` → float (the "%" suffix is dropped); `currency` renamed to `price_currency`.
+  - **`compare_markets`** — per-market `last_price` + `last_price_currency` (was `last_price` + `currency`); `best_bid`, `best_ask`, `volume_24h` → floats; `price_change_*` → floats in percent (was strings like `"1.23%"`).
+  - **`get_price_history`** — OHLCV candle fields `open`, `high`, `low`, `close`, `volume` → floats (were strings).
+  - **`get_balances`** — all four Amount fields per balance entry (`amount`, `available_amount`, `frozen_amount`, `pending_withdraw_amount`) flattened with `_currency` suffix.
+  - **`get_orders`** — all Amount fields (`limit`, `amount`, `original_amount`, `traded_amount`, `total_exchanged`, `paid_fee`) flattened; `limit` renamed to `limit_price` / `limit_price_currency`.
+
+- **Improved tool descriptions** — all 12 tool descriptions (10 public + 2 auth) rewritten to be specific about return shape, include units, and give a concrete example question an LLM might ask.
+
+- **`package.json`** version bumped to `1.3.0`.
+- **`marketplace/`** and **`PUBLISH_CHECKLIST.md`** updated to reflect v1.3.0 changes.
+
+---
+
 ## [1.2.0] – 2026-04-11
 
 ### Added

package/PUBLISH_CHECKLIST.md

@@ -1,6 +1,6 @@
-# Publish Checklist — buda-mcp v1.2.0
+# Publish Checklist — buda-mcp v1.3.0
 
-Steps to publish `v1.2.0` to npm, the MCP registry, and notify community directories.
+Steps to publish `v1.3.0` to npm, the MCP registry, and notify community directories.
 
 ---
 
@@ -8,7 +8,7 @@ Steps to publish `v1.2.0` to npm, the MCP registry, and notify community directo
 
 ```bash
 # Confirm version
-node -e "console.log(require('./package.json').version)"  # should print 1.2.0
+node -e "console.log(require('./package.json').version)"  # should print 1.3.0
 
 # Build and test
 npm run build
@@ -39,18 +39,17 @@ Verify: https://www.npmjs.com/package/@guiie/buda-mcp
 
 ```bash
 git add -A
-git commit -m "chore: release v1.2.0
-
-- Single version source-of-truth via src/version.ts (no more hardcoded strings)
-- Programmatic server-card in http.ts (toolSchema exported per tool)
-- .env.example with documented BUDA_API_KEY / BUDA_API_SECRET
-- Input sanitization: validateMarketId regex on all market_id inputs
-- 429 retry with Retry-After (seconds, per RFC 7231), default 1s
-- get_price_history: limit raised to 1000, UTC bucketing documented
-- 23 unit tests: HMAC signing, cache dedup, confirmation guard, sanitization, 429 retry
-- Integration tests: graceful skip when Buda API is unreachable"
-
-git tag v1.2.0
+git commit -m "chore: release v1.3.0
+
+- Flatten all response schemas: all monetary amounts now floats with _currency fields
+- get_arbitrage_opportunities: cross-country price discrepancy detection (USDC-normalized)
+- get_market_summary: one-call market overview with liquidity_rating
+- buda://summary/{market} MCP Resource
+- Rewritten tool descriptions with concrete examples and units
+- 35 unit tests (12 new: flattenAmount, arbitrage discrepancy, liquidity_rating thresholds)
+- src/utils.ts: shared flattenAmount() and getLiquidityRating() helpers"
+
+git tag v1.3.0
 git push origin main --tags
 ```
 
@@ -61,27 +60,35 @@ Then create a GitHub Release from the tag with the following release notes:
 **Release notes template (GitHub):**
 
 ```
-## buda-mcp v1.2.0
+## buda-mcp v1.3.0 — Output Quality
 
 ### What's new
 
-**Bug fixes & maintenance**
-- Single version source-of-truth: all version strings now read from `package.json` at startup via `src/version.ts` — no more drift between files
-- `http.ts` server-card assembled programmatically from exported `toolSchema` constants — adding a tool no longer requires touching `http.ts`
+**Flat, typed response schemas (breaking change for field consumers)**
+All tools now return floats instead of `["amount", "currency"]` arrays.
+Every monetary Amount is split into a `value` (float) and `_currency` (string) field.
+For example, `last_price: ["65000000", "CLP"]` → `last_price: 65000000, last_price_currency: "CLP"`.
+Affected tools: get_ticker, get_market_volume, get_orderbook, get_trades, get_spread,
+compare_markets, get_price_history, get_balances, get_orders.
+
+**New tool: `get_market_summary`**
+One-call summary: last price, bid/ask, spread %, 24h volume, price change 24h/7d, and
+`liquidity_rating` ("high" < 0.3%, "medium" 0.3–1%, "low" > 1%). Best first tool to call.
+
+**New tool: `get_arbitrage_opportunities`**
+Detects cross-country price discrepancies for an asset across CLP/COP/PEN markets,
+normalized to USDC. Includes pairwise discrepancy %, sorted by size.
+Fees note: 0.8% taker fee per leg (~1.6% round-trip) included in every response.
 
-**Security / reliability**
-- Input sanitization: all `market_id` inputs validated against `/^[A-Z0-9]{2,10}-[A-Z0-9]{2,10}$/i` before URL interpolation — rejects path traversal and malformed IDs with structured errors
-- 429 retry: `BudaClient` retries once on rate-limit responses, honoring the `Retry-After` header (seconds, per RFC 7231; defaults to 1s if absent). Double-429 throws `BudaApiError` with `retryAfterMs`.
+**New MCP Resource: `buda://summary/{market}`**
+Same data as get_market_summary, served as an MCP Resource in both stdio and HTTP transports.
 
-**DX improvements**
-- `.env.example` added for easy credential setup
-- `get_price_history` limit raised from 100 to 1000 trades; UTC bucketing documented prominently
-- `npm run sync-version` syncs `server.json` from `package.json` automatically
+**Improved tool descriptions**
+All 12 tool descriptions rewritten: specific return types, units, and concrete example questions.
 
-**Test suite**
-- 23 new unit tests (no live API needed): HMAC signing exactness, cache deduplication, confirmation_token guards, input sanitization, 429 retry behavior
-- Integration tests skip gracefully when Buda API is unreachable (CI-friendly)
-- New scripts: `npm run test:unit`, `npm run test:integration`
+**Test suite: 35 unit tests (was 23)**
+New sections: flattenAmount type correctness, arbitrage discrepancy calculation with mock data,
+liquidity_rating boundary tests.
 
 ```bash
 npx @guiie/buda-mcp
@@ -117,19 +124,19 @@ Verify: https://smithery.ai/server/@guiie/buda-mcp
 **Email/message template:**
 
 ```
-Subject: [Update] buda-mcp v1.2.0 — input sanitization, 429 retry, 23 unit tests
+Subject: [Update] buda-mcp v1.3.0 — flat schemas, arbitrage tool, market summary tool
 
 Hi mcp.so team,
 
-I've released v1.2.0 of buda-mcp (@guiie/buda-mcp on npm).
+I've released v1.3.0 of buda-mcp (@guiie/buda-mcp on npm).
 
 Key changes:
-- Input sanitization: all market IDs validated against a strict regex before URL use
-- 429 rate-limit retry: honors Retry-After header (seconds, RFC 7231), defaults to 1s
-- get_price_history: limit raised to 1000 trades for deeper history
-- 23 unit tests added (no live API required): HMAC, cache dedup, confirmation guards, sanitization, retry
-- Single version source-of-truth (package.json → all files via src/version.ts)
-- .env.example added for easy credential setup
+- All tools now return flat typed objects: floats + _currency fields instead of [amount, currency] arrays
+- New tool: get_market_summary — one-call overview with liquidity_rating (high/medium/low)
+- New tool: get_arbitrage_opportunities — cross-country BTC/ETH/etc price discrepancy detection (USDC-normalized)
+- New MCP Resource: buda://summary/{market}
+- All tool descriptions rewritten with concrete example questions and units
+- 35 unit tests (12 new)
 
 Links:
 - npm: https://www.npmjs.com/package/@guiie/buda-mcp
@@ -148,22 +155,23 @@ Thank you!
 **Message template:**
 
 ```
-Subject: [Update] buda-mcp v1.2.0
+Subject: [Update] buda-mcp v1.3.0
 
 Hi Glama team,
 
-buda-mcp has been updated to v1.2.0.
+buda-mcp has been updated to v1.3.0.
 
 Package: @guiie/buda-mcp (npm)
 Registry: io.github.gtorreal/buda-mcp (MCP Registry)
-Version: 1.2.0
+Version: 1.3.0
 
 Changes:
-- Input validation on all market_id inputs (structured isError: true on failure)
-- 429 retry with Retry-After support (RFC 7231 seconds; default 1s)
-- get_price_history limit raised to 1000 trades; UTC bucket timestamps documented
-- 23 unit tests: HMAC signing, cache deduplication, confirmation guards, sanitization, retry
-- Single version source (package.json); .env.example added
+- Flat response schemas: all monetary amounts now floats with _currency fields (LLM-friendly)
+- New tool: get_market_summary (one-call overview, liquidity_rating)
+- New tool: get_arbitrage_opportunities (cross-country USDC-normalized price discrepancy)
+- New MCP Resource: buda://summary/{market}
+- Rewritten descriptions with examples and units for all 12 tools
+- 35 unit tests
 
 Quick start:
   npx @guiie/buda-mcp
@@ -178,12 +186,13 @@ Thank you!
 
 ## 8. Post-publish verification
 
-- [ ] `npx @guiie/buda-mcp@1.2.0` starts successfully
-- [ ] `npm info @guiie/buda-mcp version` returns `1.2.0`
-- [ ] GitHub release tag `v1.2.0` is visible
-- [ ] MCP Registry entry reflects v1.2.0
-- [ ] Smithery server card lists 8 public tools (with updated get_price_history description)
-- [ ] `GET /health` returns `"version":"1.2.0"` on Railway deployment
-- [ ] `GET /.well-known/mcp/server-card.json` returns tools with updated schemas (no hardcoded JSON)
+- [ ] `npx @guiie/buda-mcp@1.3.0` starts successfully
+- [ ] `npm info @guiie/buda-mcp version` returns `1.3.0`
+- [ ] GitHub release tag `v1.3.0` is visible
+- [ ] MCP Registry entry reflects v1.3.0
+- [ ] Smithery server card lists 10 public tools (including get_market_summary, get_arbitrage_opportunities)
+- [ ] `GET /health` returns `"version":"1.3.0"` on Railway deployment
+- [ ] `GET /.well-known/mcp/server-card.json` returns 3 resources (including buda://summary/{market})
+- [ ] get_ticker response has `last_price: <number>` not `last_price: ["...", "CLP"]`
 - [ ] mcp.so listing updated
 - [ ] Glama.ai listing updated

package/dist/http.js

@@ -12,10 +12,13 @@ import * as volume from "./tools/volume.js";
 import * as spread from "./tools/spread.js";
 import * as compareMarkets from "./tools/compare_markets.js";
 import * as priceHistory from "./tools/price_history.js";
+import * as arbitrage from "./tools/arbitrage.js";
+import * as marketSummary from "./tools/market_summary.js";
 import * as balances from "./tools/balances.js";
 import * as orders from "./tools/orders.js";
 import * as placeOrder from "./tools/place_order.js";
 import * as cancelOrder from "./tools/cancel_order.js";
+import { handleMarketSummary } from "./tools/market_summary.js";
 const PORT = parseInt(process.env.PORT ?? "3000", 10);
 const client = new BudaClient(undefined, process.env.BUDA_API_KEY, process.env.BUDA_API_SECRET);
 const authEnabled = client.hasAuth();
@@ -30,6 +33,8 @@ const PUBLIC_TOOL_SCHEMAS = [
     spread.toolSchema,
     compareMarkets.toolSchema,
     priceHistory.toolSchema,
+    arbitrage.toolSchema,
+    marketSummary.toolSchema,
 ];
 const AUTH_TOOL_SCHEMAS = [
     balances.toolSchema,
@@ -49,6 +54,8 @@ function createServer() {
     spread.register(server, client, reqCache);
     compareMarkets.register(server, client, reqCache);
     priceHistory.register(server, client, reqCache);
+    arbitrage.register(server, client, reqCache);
+    marketSummary.register(server, client, reqCache);
     if (authEnabled) {
         balances.register(server, client);
         orders.register(server, client);
@@ -81,6 +88,20 @@ function createServer() {
             ],
         };
     });
+    server.resource("buda-summary", new ResourceTemplate("buda://summary/{market}", { list: undefined }), async (uri, params) => {
+        const marketId = params.market.toUpperCase();
+        const result = await handleMarketSummary({ market_id: marketId }, client, reqCache);
+        const text = result.content[0].text;
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    mimeType: "application/json",
+                    text,
+                },
+            ],
+        };
+    });
     return server;
 }
 const app = express();
@@ -104,6 +125,7 @@ app.get("/.well-known/mcp/server-card.json", (_req, res) => {
         resources: [
             { uri: "buda://markets", name: "All Buda.com markets", mimeType: "application/json" },
             { uri: "buda://ticker/{market}", name: "Ticker for a specific market", mimeType: "application/json" },
+            { uri: "buda://summary/{market}", name: "Full market summary with liquidity rating", mimeType: "application/json" },
         ],
         prompts: [],
     });

package/dist/index.js

@@ -13,10 +13,13 @@ import * as volume from "./tools/volume.js";
 import * as spread from "./tools/spread.js";
 import * as compareMarkets from "./tools/compare_markets.js";
 import * as priceHistory from "./tools/price_history.js";
+import * as arbitrage from "./tools/arbitrage.js";
+import * as marketSummary from "./tools/market_summary.js";
 import * as balances from "./tools/balances.js";
 import * as orders from "./tools/orders.js";
 import * as placeOrder from "./tools/place_order.js";
 import * as cancelOrder from "./tools/cancel_order.js";
+import { handleMarketSummary } from "./tools/market_summary.js";
 const client = new BudaClient(undefined, process.env.BUDA_API_KEY, process.env.BUDA_API_SECRET);
 const server = new McpServer({
     name: "buda-mcp",
@@ -31,6 +34,8 @@ volume.register(server, client, cache);
 spread.register(server, client, cache);
 compareMarkets.register(server, client, cache);
 priceHistory.register(server, client, cache);
+arbitrage.register(server, client, cache);
+marketSummary.register(server, client, cache);
 // Auth-gated tools — only registered when API credentials are present
 if (client.hasAuth()) {
     balances.register(server, client);
@@ -64,6 +69,20 @@ server.resource("buda-ticker", new ResourceTemplate("buda://ticker/{market}", {
         ],
     };
 });
+server.resource("buda-summary", new ResourceTemplate("buda://summary/{market}", { list: undefined }), async (uri, params) => {
+    const marketId = params.market.toUpperCase();
+    const result = await handleMarketSummary({ market_id: marketId }, client, cache);
+    const text = result.content[0].text;
+    return {
+        contents: [
+            {
+                uri: uri.href,
+                mimeType: "application/json",
+                text,
+            },
+        ],
+    };
+});
 const transport = new StdioServerTransport();
 await server.connect(transport);
 //# sourceMappingURL=index.js.map

package/dist/tools/arbitrage.d.ts

@@ -0,0 +1,35 @@
+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: {
+            base_currency: {
+                type: string;
+                description: string;
+            };
+            threshold_pct: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+interface ArbitrageInput {
+    base_currency: string;
+    threshold_pct?: number;
+}
+export declare function handleArbitrageOpportunities({ base_currency, threshold_pct }: ArbitrageInput, 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=arbitrage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"arbitrage.d.ts","sourceRoot":"","sources":["../../src/tools/arbitrage.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;AAGrD,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;CAyBtB,CAAC;AAYF,UAAU,cAAc;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,wBAAsB,4BAA4B,CAChD,EAAE,aAAa,EAAE,aAAmB,EAAE,EAAE,cAAc,EACtD,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,CAgIhF;AAED,wBAAgB,QAAQ,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,GAAG,IAAI,CAmBxF"}

package/dist/tools/arbitrage.js

@@ -0,0 +1,142 @@
+import { z } from "zod";
+import { BudaApiError } from "../client.js";
+import { CACHE_TTL } from "../cache.js";
+export const toolSchema = {
+    name: "get_arbitrage_opportunities",
+    description: "Detects cross-country price discrepancies for a given asset across Buda's CLP, COP, and PEN markets, " +
+        "normalized to USDC. Fetches all relevant tickers, converts each local price to USDC using the " +
+        "current USDC-CLP / USDC-COP / USDC-PEN rates, then computes pairwise discrepancy percentages. " +
+        "Results above threshold_pct are returned sorted by opportunity size. Note: Buda taker fee is 0.8% " +
+        "per leg (~1.6% round-trip) — always deduct fees before acting on any discrepancy. " +
+        "Example: 'Is there an arbitrage opportunity for BTC between Chile and Peru right now?'",
+    inputSchema: {
+        type: "object",
+        properties: {
+            base_currency: {
+                type: "string",
+                description: "Base asset to scan (e.g. 'BTC', 'ETH', 'XRP').",
+            },
+            threshold_pct: {
+                type: "number",
+                description: "Minimum price discrepancy percentage to include in results (default: 0.5). " +
+                    "Buda taker fee is 0.8% per leg, so a round-trip requires > 1.6% to be profitable.",
+            },
+        },
+        required: ["base_currency"],
+    },
+};
+export async function handleArbitrageOpportunities({ base_currency, threshold_pct = 0.5 }, client, cache) {
+    try {
+        const base = base_currency.toUpperCase();
+        const data = await cache.getOrFetch("tickers:all", CACHE_TTL.TICKER, () => client.get("/tickers"));
+        const tickerMap = new Map();
+        for (const t of data.tickers) {
+            tickerMap.set(t.market_id, t);
+        }
+        // Find USDC conversion rates for each fiat currency
+        const usdcClpTicker = tickerMap.get("USDC-CLP");
+        const usdcCopTicker = tickerMap.get("USDC-COP");
+        const usdcPenTicker = tickerMap.get("USDC-PEN");
+        const marketPrices = [];
+        const candidates = [
+            { suffix: "CLP", usdcTicker: usdcClpTicker },
+            { suffix: "COP", usdcTicker: usdcCopTicker },
+            { suffix: "PEN", usdcTicker: usdcPenTicker },
+        ];
+        for (const { suffix, usdcTicker } of candidates) {
+            const marketId = `${base}-${suffix}`;
+            const baseTicker = tickerMap.get(marketId);
+            if (!baseTicker || !usdcTicker)
+                continue;
+            const localPrice = parseFloat(baseTicker.last_price[0]);
+            const usdcRate = parseFloat(usdcTicker.last_price[0]);
+            if (isNaN(localPrice) || isNaN(usdcRate) || usdcRate === 0)
+                continue;
+            marketPrices.push({
+                market_id: marketId,
+                local_price: localPrice,
+                usdc_rate: usdcRate,
+                price_usdc: localPrice / usdcRate,
+            });
+        }
+        if (marketPrices.length < 2) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: `Not enough markets found for base currency '${base}' to compute arbitrage. ` +
+                                `Need at least 2 of: ${base}-CLP, ${base}-COP, ${base}-PEN with USDC rates available.`,
+                            code: "INSUFFICIENT_MARKETS",
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        // Compute all pairwise discrepancies
+        const opportunities = [];
+        for (let i = 0; i < marketPrices.length; i++) {
+            for (let j = i + 1; j < marketPrices.length; j++) {
+                const a = marketPrices[i];
+                const b = marketPrices[j];
+                const minPrice = Math.min(a.price_usdc, b.price_usdc);
+                const discrepancyPct = (Math.abs(a.price_usdc - b.price_usdc) / minPrice) * 100;
+                if (discrepancyPct < threshold_pct)
+                    continue;
+                const higherMarket = a.price_usdc > b.price_usdc ? a.market_id : b.market_id;
+                const lowerMarket = a.price_usdc < b.price_usdc ? a.market_id : b.market_id;
+                opportunities.push({
+                    market_a: a.market_id,
+                    market_b: b.market_id,
+                    price_a_usdc: parseFloat(a.price_usdc.toFixed(4)),
+                    price_b_usdc: parseFloat(b.price_usdc.toFixed(4)),
+                    discrepancy_pct: parseFloat(discrepancyPct.toFixed(4)),
+                    higher_market: higherMarket,
+                    lower_market: lowerMarket,
+                });
+            }
+        }
+        opportunities.sort((a, b) => b.discrepancy_pct - a.discrepancy_pct);
+        const result = {
+            base_currency: base,
+            threshold_pct,
+            markets_analyzed: marketPrices.map((m) => ({
+                market_id: m.market_id,
+                price_usdc: parseFloat(m.price_usdc.toFixed(4)),
+                local_price: m.local_price,
+                usdc_rate: m.usdc_rate,
+            })),
+            opportunities_found: opportunities.length,
+            opportunities,
+            fees_note: "Buda taker fee is 0.8% per leg. A round-trip arbitrage (buy on one market, sell on another) " +
+                "costs approximately 1.6% in fees. Only discrepancies well above 1.6% are likely profitable.",
+        };
+        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, {
+        base_currency: z
+            .string()
+            .describe("Base asset to scan (e.g. 'BTC', 'ETH', 'XRP')."),
+        threshold_pct: z
+            .number()
+            .min(0)
+            .default(0.5)
+            .describe("Minimum price discrepancy percentage to include in results (default: 0.5). " +
+            "Buda taker fee is 0.8% per leg, so a round-trip requires > 1.6% to be profitable."),
+    }, (args) => handleArbitrageOpportunities(args, client, cache));
+}
+//# sourceMappingURL=arbitrage.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"balances.d.ts","sourceRoot":"","sources":["../../src/tools/balances.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,UAAU,EAAgB,MAAM,cAAc,CAAC;AAGxD,eAAO,MAAM,UAAU;;;;;;;CAUtB,CAAC;AAEF,wBAAgB,QAAQ,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,GAAG,IAAI,CAuBpE"}
+{"version":3,"file":"balances.d.ts","sourceRoot":"","sources":["../../src/tools/balances.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,UAAU,EAAgB,MAAM,cAAc,CAAC;AAIxD,eAAO,MAAM,UAAU;;;;;;;CAYtB,CAAC;AAEF,wBAAgB,QAAQ,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,GAAG,IAAI,CA2CpE"}

package/dist/tools/balances.js

@@ -1,9 +1,12 @@
 import { BudaApiError } from "../client.js";
+import { flattenAmount } from "../utils.js";
 export const toolSchema = {
     name: "get_balances",
-    description: "Get all currency balances for the authenticated Buda.com account. " +
-        "Returns total, available, frozen, and pending withdrawal amounts per currency. " +
-        "Requires BUDA_API_KEY and BUDA_API_SECRET environment variables.",
+    description: "Returns all currency balances for the authenticated Buda.com account as flat typed objects. " +
+        "Each currency entry includes total amount, available amount (not frozen), frozen amount, and " +
+        "pending withdrawal amount — all as floats with separate _currency fields. " +
+        "Requires BUDA_API_KEY and BUDA_API_SECRET. " +
+        "Example: 'How much BTC do I have available to trade right now?'",
     inputSchema: {
         type: "object",
         properties: {},
@@ -13,8 +16,25 @@ export function register(server, client) {
     server.tool(toolSchema.name, toolSchema.description, {}, async () => {
         try {
             const data = await client.get("/balances");
+            const result = data.balances.map((b) => {
+                const amount = flattenAmount(b.amount);
+                const available = flattenAmount(b.available_amount);
+                const frozen = flattenAmount(b.frozen_amount);
+                const pending = flattenAmount(b.pending_withdraw_amount);
+                return {
+                    id: b.id,
+                    amount: amount.value,
+                    amount_currency: amount.currency,
+                    available_amount: available.value,
+                    available_amount_currency: available.currency,
+                    frozen_amount: frozen.value,
+                    frozen_amount_currency: frozen.currency,
+                    pending_withdraw_amount: pending.value,
+                    pending_withdraw_amount_currency: pending.currency,
+                };
+            });
             return {
-                content: [{ type: "text", text: JSON.stringify(data.balances, null, 2) }],
+                content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
             };
         }
         catch (err) {

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

@@ -1 +1 @@
-{"version":3,"file":"compare_markets.d.ts","sourceRoot":"","sources":["../../src/tools/compare_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;AAGrD,eAAO,MAAM,UAAU;;;;;;;;;;;;;CAiBtB,CAAC;AAEF,wBAAgB,QAAQ,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,GAAG,IAAI,CAyExF"}
+{"version":3,"file":"compare_markets.d.ts","sourceRoot":"","sources":["../../src/tools/compare_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;AAGrD,eAAO,MAAM,UAAU;;;;;;;;;;;;;CAkBtB,CAAC;AAEF,wBAAgB,QAAQ,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,GAAG,IAAI,CAyExF"}

package/dist/tools/compare_markets.js

@@ -3,9 +3,10 @@ import { BudaApiError } from "../client.js";
 import { CACHE_TTL } from "../cache.js";
 export const toolSchema = {
     name: "compare_markets",
-    description: "Compare ticker data for all trading pairs of a given base currency across Buda.com's " +
-        "supported quote currencies (CLP, COP, PEN, BTC, USDC, ETH). " +
-        "For example, passing 'BTC' returns side-by-side data for BTC-CLP, BTC-COP, BTC-PEN, etc.",
+    description: "Returns side-by-side ticker data for all trading pairs of a given base currency across Buda.com's " +
+        "supported quote currencies (CLP, COP, PEN, BTC, USDC, ETH). All prices are floats; " +
+        "price_change_24h and price_change_7d are floats in percent (e.g. 1.23 means +1.23%). " +
+        "Example: 'In which country is Bitcoin currently most expensive on Buda?'",
     inputSchema: {
         type: "object",
         properties: {
@@ -48,16 +49,16 @@ export function register(server, client, cache) {
                 base_currency: base,
                 markets: matching.map((t) => ({
                     market_id: t.market_id,
-                    last_price: t.last_price[0],
-                    currency: t.last_price[1],
-                    best_bid: t.max_bid ? t.max_bid[0] : null,
-                    best_ask: t.min_ask ? t.min_ask[0] : null,
-                    volume_24h: t.volume ? t.volume[0] : null,
+                    last_price: parseFloat(t.last_price[0]),
+                    last_price_currency: t.last_price[1],
+                    best_bid: t.max_bid ? parseFloat(t.max_bid[0]) : null,
+                    best_ask: t.min_ask ? parseFloat(t.min_ask[0]) : null,
+                    volume_24h: t.volume ? parseFloat(t.volume[0]) : null,
                     price_change_24h: t.price_variation_24h
-                        ? (parseFloat(t.price_variation_24h) * 100).toFixed(2) + "%"
+                        ? parseFloat((parseFloat(t.price_variation_24h) * 100).toFixed(4))
                         : null,
                     price_change_7d: t.price_variation_7d
-                        ? (parseFloat(t.price_variation_7d) * 100).toFixed(2) + "%"
+                        ? parseFloat((parseFloat(t.price_variation_7d) * 100).toFixed(4))
                         : null,
                 })),
             };