@guiie/buda-mcp 1.2.2 → 1.4.0

package/marketplace/claude-listing.md

@@ -12,7 +12,9 @@
 
 Real-time market data from [Buda.com](https://www.buda.com/), the leading cryptocurrency exchange operating in Chile, Colombia, and Peru. All public data is sourced from Buda's public REST API v2 — no API key required.
 
-Use this server to query live prices, spreads, order books, OHLCV candles, trade history, and volume for all BTC, ETH, and altcoin markets quoted in CLP, COP, PEN, and USDC. Optional API credentials unlock account tools for balances and order management.
+Use this server to query live prices, spreads, order books, OHLCV candles, trade history, volume, and cross-market arbitrage opportunities for all BTC, ETH, and altcoin markets quoted in CLP, COP, PEN, and USDC. Optional API credentials unlock account tools for balances and order management.
+
+**v1.4.0** adds 5 new tools: `simulate_order`, `calculate_position_size`, `get_market_sentiment`, `get_technical_indicators`, and a dead man's switch (`schedule_cancel_all` + `renew_cancel_timer` + `disarm_cancel_timer`). All response schemas are flat and fully typed.
 
 ---
 
@@ -20,48 +22,71 @@ Use this server to query live prices, spreads, order books, OHLCV candles, trade
 
 ### Public tools (no credentials required)
 
+### `get_market_summary` ⭐ Start here
+One-call summary of everything relevant about a market: last price, bid/ask, spread %, 24h volume, price change, and `liquidity_rating` ("high" / "medium" / "low"). Best first tool to call when a user asks about any specific market.  
+**Parameters:** `market_id` *(required)* — e.g. `BTC-CLP`.
+
 ### `get_markets`
-List all available trading pairs on Buda.com, or retrieve details for a specific market.  
-Returns: base/quote currencies, trading fees, minimum order amounts, fee discount tiers.  
+Lists all available trading pairs on Buda.com, or returns details for a specific market (fees, minimum order size, discount tiers).  
 **Parameters:** `market_id` *(optional)* — e.g. `BTC-CLP`. Omit to list all 26 markets.
 
 ### `get_ticker`
-Current market snapshot: last traded price, best bid and ask, 24h volume, and price change over 24h and 7d.  
+Current market snapshot: last traded price, best bid and ask, 24h volume, and price change over 24h and 7d. All values are floats in the quote currency.  
 **Parameters:** `market_id` *(required)* — e.g. `BTC-CLP`, `ETH-COP`, `ETH-BTC`.
 
 ### `get_orderbook`
-Full order book for a market: sorted bids and asks as `[price, amount]` pairs.  
+Full order book for a market: bids and asks as `{price, amount}` objects (floats). Bids sorted highest-first, asks lowest-first.  
 **Parameters:** `market_id` *(required)*, `limit` *(optional)* — cap levels returned per side.
 
 ### `get_trades`
-Recent trade history. Each entry: `[timestamp_ms, amount, price, direction]`.  
+Recent trade history as typed objects: `{timestamp_ms, amount, price, direction}` with all numeric fields as floats.  
 **Parameters:** `market_id` *(required)*, `limit` *(optional, max 100)*, `timestamp` *(optional, for pagination)*.
 
 ### `get_market_volume`
-24h and 7-day transacted volume broken down by buy (bid) and sell (ask) side.  
+24h and 7-day transacted volume as floats broken down by buy (bid) and sell (ask) side.  
 **Parameters:** `market_id` *(required)*.
 
 ### `get_spread`
-Bid/ask spread for a market: absolute spread and spread as a percentage of the ask price.  
+Bid/ask spread for a market: `best_bid`, `best_ask`, `spread_absolute`, and `spread_percentage` as floats. `spread_percentage` is in percent (e.g. 0.15 = 0.15%).  
 **Parameters:** `market_id` *(required)*.
 
 ### `compare_markets`
-Side-by-side ticker data for all trading pairs of a given base currency across all supported quote currencies.  
+Side-by-side ticker data for all trading pairs of a given base currency across all supported quote currencies. `price_change_*` fields are floats in percent.  
 **Parameters:** `base_currency` *(required)* — e.g. `BTC`, `ETH`, `XRP`.
 
 ### `get_price_history`
-OHLCV (open/high/low/close/volume) candles derived from recent trade history (Buda has no native candlestick endpoint). Supports `1h`, `4h`, and `1d` periods. Candle timestamps are UTC bucket boundaries.  
-**Parameters:** `market_id` *(required)*, `period` *(optional: `1h`/`4h`/`1d`, default `1h`)*, `limit` *(optional, default 100, max 1000 trades — more = deeper history)*.
+OHLCV (open/high/low/close/volume) candles derived from recent trade history (Buda has no native candlestick endpoint). All candle values are floats. Supports `1h`, `4h`, and `1d` periods.  
+**Parameters:** `market_id` *(required)*, `period` *(optional: `1h`/`4h`/`1d`, default `1h`)*, `limit` *(optional, default 100, max 1000 trades)*.
+
+### `get_arbitrage_opportunities`
+Detects cross-country price discrepancies for a given asset across Buda's CLP, COP, and PEN markets, normalized to USDC. Returns pairwise discrepancies above `threshold_pct` sorted by size. Includes a `fees_note` reminding that Buda's 0.8% taker fee per leg (~1.6% round-trip) must be deducted.  
+**Parameters:** `base_currency` *(required)* — e.g. `BTC`, `threshold_pct` *(optional, default 0.5)*.
+
+### `simulate_order`
+Simulates a buy or sell order using live ticker data — no order is ever placed. Returns `estimated_fill_price`, `fee_amount`, `fee_currency`, `total_cost`, and `slippage_vs_mid_pct`. All outputs include `simulation: true`. Uses actual taker fee from market data (0.8% crypto / 0.5% stablecoin).  
+**Parameters:** `market_id` *(required)*, `side` (`buy`|`sell`) *(required)*, `amount` *(required)*, `price` *(optional — omit for market order simulation)*.
+
+### `calculate_position_size`
+Calculates how many units to buy or sell so a stop-loss hit costs exactly `risk_pct`% of `capital`. Fully client-side — no API call. Returns `units`, `capital_at_risk`, `position_value`, `fee_impact`, and a plain-text `risk_reward_note`.  
+**Parameters:** `market_id`, `capital`, `risk_pct` (0.1–10), `entry_price`, `stop_loss_price` *(all required)*.
+
+### `get_market_sentiment`
+Composite sentiment score (−100 to +100) from three components: 24h price variation (40%), volume vs 7-day daily average (35%), spread vs market-type baseline (25%). Returns `score`, `label` (`bearish`/`neutral`/`bullish`), `component_breakdown`, and a `disclaimer`.  
+**Parameters:** `market_id` *(required)*.
+
+### `get_technical_indicators`
+RSI (14), MACD (12/26/9), Bollinger Bands (20, 2σ), SMA 20, and SMA 50 — computed server-side from Buda trade history (no external libraries). Returns latest values + signal interpretations. Returns a structured warning if fewer than 50 candles are available after aggregation. Includes `disclaimer`.  
+**Parameters:** `market_id` *(required)*, `period` (`1h`/`4h`/`1d`, default `1h`), `limit` *(optional, 500–1000)*.
 
 ### Authenticated tools (require `BUDA_API_KEY` + `BUDA_API_SECRET`)
 
 > **Important:** Authenticated instances must run locally only — never expose a server with API credentials publicly.
 
 ### `get_balances`
-All currency balances: total, available, frozen, and pending withdrawal amounts.
+All currency balances as flat typed objects: total, available, frozen, and pending withdrawal amounts as floats with `_currency` suffix fields.
 
 ### `get_orders`
-Orders for a given market, filterable by state (`pending`, `active`, `traded`, `canceled`).  
+Orders for a given market as flat typed objects. All monetary amounts are floats with `_currency` fields. Filterable by state (`pending`, `active`, `traded`, `canceled`).  
 **Parameters:** `market_id` *(required)*, `state` *(optional)*, `per` *(optional)*, `page` *(optional)*.
 
 ### `place_order`
@@ -72,6 +97,19 @@ Place a limit or market order. Requires `confirmation_token="CONFIRM"` to preven
 Cancel an open order by ID. Requires `confirmation_token="CONFIRM"`.  
 **Parameters:** `order_id`, `confirmation_token`.
 
+### `schedule_cancel_all`
+**WARNING: timer state is lost on server restart. Use only on locally-run instances.**  
+Arms an in-memory dead man's switch: if not renewed within `ttl_seconds`, all open orders for the market are automatically cancelled. Requires `confirmation_token="CONFIRM"`.  
+**Parameters:** `market_id`, `ttl_seconds` (10–300), `confirmation_token`.
+
+### `renew_cancel_timer`
+Resets the dead man's switch TTL for a market. No confirmation required. Must have an active timer.  
+**Parameters:** `market_id`.
+
+### `disarm_cancel_timer`
+Disarms the dead man's switch without cancelling any orders. Safe to call even with no active timer.  
+**Parameters:** `market_id`.
+
 ---
 
 ## MCP Resources
@@ -79,13 +117,16 @@ Cancel an open order by ID. Requires `confirmation_token="CONFIRM"`.
 | URI | Description |
 |-----|-------------|
 | `buda://markets` | JSON list of all Buda.com markets |
-| `buda://ticker/{market}` | JSON ticker for a specific market |
+| `buda://ticker/{market}` | Raw ticker for a specific market |
+| `buda://summary/{market}` | Full market summary with liquidity rating |
 
 ---
 
 ## Example prompts
 
+- *"Give me a complete overview of the BTC-CLP market."*
 - *"What is the current Bitcoin price in Chilean pesos?"*
+- *"Is there an arbitrage opportunity for BTC between Chile and Peru?"*
 - *"Show me the BTC-CLP order book — top 10 bids and asks."*
 - *"How much ETH was traded on Buda in the last 7 days?"*
 - *"List all markets available on Buda.com."*
@@ -94,6 +135,11 @@ Cancel an open order by ID. Requires `confirmation_token="CONFIRM"`.
 - *"Show me hourly BTC-CLP candles."*
 - *"What's my available BTC balance?"* *(authenticated)*
 - *"Show my open orders on BTC-CLP."* *(authenticated)*
+- *"How much would it cost to buy 0.1 ETH on ETH-CLP right now?"*
+- *"How many BTC can I buy with 1M CLP if I risk 2% with a stop at 78M?"*
+- *"Is the BTC-CLP market bullish or bearish right now?"*
+- *"Is BTC-CLP RSI overbought on the 4-hour chart?"*
+- *"Arm a 60-second dead man's switch for my BTC-CLP orders."* *(authenticated)*
 
 ---
 

package/marketplace/gemini-tools.json

@@ -1,9 +1,9 @@
 {
-  "_comment": "Gemini function declarations for buda-mcp v1.2.0. Pass this array as the `tools[0].functionDeclarations` field when calling the Gemini API. See: https://ai.google.dev/gemini-api/docs/function-calling",
+  "_comment": "Gemini function declarations for buda-mcp v1.4.0. Pass this array as the `tools[0].functionDeclarations` field when calling the Gemini API. See: https://ai.google.dev/gemini-api/docs/function-calling",
   "functionDeclarations": [
     {
       "name": "get_markets",
-      "description": "List all available cryptocurrency trading pairs on Buda.com (Chile, Colombia, Peru), or get details for a specific market. Returns base/quote currencies, maker/taker 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?'",
       "parameters": {
         "type": "OBJECT",
         "properties": {
@@ -17,7 +17,7 @@
     },
     {
       "name": "get_ticker",
-      "description": "Get the current market ticker for a Buda.com trading pair. Returns the last traded price, best bid (max_bid), best ask (min_ask), 24-hour volume, and price change percentage over 24 hours and 7 days.",
+      "description": "Returns the current market snapshot for a Buda.com market: last traded price, best bid, best ask, 24h volume, and price change over 24h and 7d. All prices are floats in the quote currency (e.g. CLP for BTC-CLP). price_variation_24h is a decimal fraction (0.012 = +1.2%). Example: 'What is the current Bitcoin price in Chilean pesos?'",
       "parameters": {
         "type": "OBJECT",
         "properties": {
@@ -31,7 +31,7 @@
     },
     {
       "name": "get_orderbook",
-      "description": "Get the current limit order book for a Buda.com market. Returns sorted arrays of bids (buy orders) and asks (sell orders). Each entry is a [price, amount] pair. Useful for analyzing market depth and calculating slippage.",
+      "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?'",
       "parameters": {
         "type": "OBJECT",
         "properties": {
@@ -49,7 +49,7 @@
     },
     {
       "name": "get_trades",
-      "description": "Get recent trade history for a Buda.com market. Each trade entry contains [timestamp_ms, amount, price, direction] where direction is 'buy' or 'sell'. Supports pagination via the timestamp parameter.",
+      "description": "Returns recent trade history for a Buda.com market as typed objects. Each entry has timestamp_ms (integer), amount (float, base currency), price (float, quote currency), and direction ('buy' or 'sell'). Example: 'What was the last executed price for BTC-CLP and was it a buy or sell?'",
       "parameters": {
         "type": "OBJECT",
         "properties": {
@@ -71,7 +71,7 @@
     },
     {
       "name": "get_market_volume",
-      "description": "Get 24-hour and 7-day transacted volume for a Buda.com market, broken down by side: ask_volume (sell orders) and bid_volume (buy orders). Amounts are in the market's base currency.",
+      "description": "Returns 24h and 7-day transacted volume for a Buda.com market, split by buy (bid) and sell (ask) side. All volume values are floats in the base currency (e.g. BTC for BTC-CLP). Example: 'How much Bitcoin was sold on BTC-CLP in the last 24 hours?'",
       "parameters": {
         "type": "OBJECT",
         "properties": {
@@ -85,7 +85,7 @@
     },
     {
       "name": "get_spread",
-      "description": "Calculate the bid/ask spread for a Buda.com market. Returns the best bid price, best ask price, absolute spread, and spread as a percentage of the ask price. Useful for assessing market liquidity.",
+      "description": "Returns the best bid, best ask, absolute spread, and spread percentage for a Buda.com market. All prices are floats in the quote currency (e.g. CLP). spread_percentage is a float in percent (e.g. 0.15 means 0.15%). Use this to evaluate liquidity before placing a large order. Example: 'Is BTC-CLP liquid enough to buy 10M CLP without significant slippage?'",
       "parameters": {
         "type": "OBJECT",
         "properties": {
@@ -99,7 +99,7 @@
     },
     {
       "name": "compare_markets",
-      "description": "Compare ticker data side-by-side for all trading pairs of a given base currency across Buda.com's supported quote currencies (CLP, COP, PEN, USDC, BTC, ETH). For example, 'BTC' returns data for BTC-CLP, BTC-COP, BTC-PEN, and BTC-USDC.",
+      "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?'",
       "parameters": {
         "type": "OBJECT",
         "properties": {
@@ -113,7 +113,7 @@
     },
     {
       "name": "get_price_history",
-      "description": "IMPORTANT: Candles are aggregated client-side from raw trades (Buda has no native candlestick endpoint) — increase 'limit' for deeper history. Returns OHLCV (open/high/low/close/volume) price history for a Buda.com market. Candle timestamps are UTC bucket boundaries. Supports 1h, 4h, and 1d candle periods.",
+      "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 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.'",
       "parameters": {
         "type": "OBJECT",
         "properties": {
@@ -132,6 +132,180 @@
         },
         "required": ["market_id"]
       }
+    },
+    {
+      "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.'",
+      "parameters": {
+        "type": "OBJECT",
+        "properties": {
+          "market_id": {
+            "type": "STRING",
+            "description": "Market identifier such as 'BTC-CLP', 'ETH-COP', or 'BTC-PEN'. Case-insensitive."
+          }
+        },
+        "required": ["market_id"]
+      }
+    },
+    {
+      "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?'",
+      "parameters": {
+        "type": "OBJECT",
+        "properties": {
+          "base_currency": {
+            "type": "STRING",
+            "description": "Base asset to scan. Examples: 'BTC', 'ETH', 'XRP'. Case-insensitive."
+          },
+          "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"]
+      }
+    },
+    {
+      "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. Example: 'How much would it cost to buy 0.01 BTC on BTC-CLP right now?'",
+      "parameters": {
+        "type": "OBJECT",
+        "properties": {
+          "market_id": {
+            "type": "STRING",
+            "description": "Market identifier such as 'BTC-CLP' or 'ETH-BTC'. Case-insensitive."
+          },
+          "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"]
+      }
+    },
+    {
+      "name": "calculate_position_size",
+      "description": "Calculates position size based on capital, risk tolerance, entry price, and stop-loss. Determines units so that a stop-loss hit costs exactly risk_pct% of capital. Fully client-side — no API call. Example: 'How many BTC can I buy with 1M CLP at 2% risk, entry 80M, stop 78M?'",
+      "parameters": {
+        "type": "OBJECT",
+        "properties": {
+          "market_id": {
+            "type": "STRING",
+            "description": "Market identifier (e.g. 'BTC-CLP'). Used to derive the quote currency."
+          },
+          "capital": {
+            "type": "NUMBER",
+            "description": "Total available capital in the quote currency."
+          },
+          "risk_pct": {
+            "type": "NUMBER",
+            "description": "Percentage of capital to risk on this trade (0.1–10)."
+          },
+          "entry_price": {
+            "type": "NUMBER",
+            "description": "Planned entry price in quote currency."
+          },
+          "stop_loss_price": {
+            "type": "NUMBER",
+            "description": "Stop-loss price in quote currency. Must be below entry for buys, above for sells."
+          }
+        },
+        "required": ["market_id", "capital", "risk_pct", "entry_price", "stop_loss_price"]
+      }
+    },
+    {
+      "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 score, label (bearish/neutral/bullish), and full component breakdown. Example: 'Is the BTC-CLP market currently bullish or bearish?'",
+      "parameters": {
+        "type": "OBJECT",
+        "properties": {
+          "market_id": {
+            "type": "STRING",
+            "description": "Market identifier such as 'BTC-CLP', 'ETH-BTC', or 'BTC-USDT'. Case-insensitive."
+          }
+        },
+        "required": ["market_id"]
+      }
+    },
+    {
+      "name": "get_technical_indicators",
+      "description": "Computes RSI (14), MACD (12/26/9), Bollinger Bands (20, 2σ), SMA 20, and SMA 50 from Buda trade history. No external libraries. Returns latest indicator values and signal interpretations. Returns a structured warning if fewer than 50 candles are available. Example: 'Is BTC-CLP RSI overbought on the 4-hour chart?'",
+      "parameters": {
+        "type": "OBJECT",
+        "properties": {
+          "market_id": {
+            "type": "STRING",
+            "description": "Market identifier such as 'BTC-CLP' or 'ETH-BTC'. Case-insensitive."
+          },
+          "period": {
+            "type": "STRING",
+            "description": "Candle period: '1h', '4h', or '1d'. Default is '1h'."
+          },
+          "limit": {
+            "type": "INTEGER",
+            "description": "Number of raw trades to fetch (500–1000). Default is 500."
+          }
+        },
+        "required": ["market_id"]
+      }
+    },
+    {
+      "name": "schedule_cancel_all",
+      "description": "WARNING: timer state is lost on server restart. Use only on locally-run instances. Arms an in-memory dead man's switch: if not renewed within ttl_seconds, all open orders for the market are automatically cancelled. Requires confirmation_token='CONFIRM'. Auth-gated.",
+      "parameters": {
+        "type": "OBJECT",
+        "properties": {
+          "market_id": {
+            "type": "STRING",
+            "description": "Market ID to protect (e.g. 'BTC-CLP')."
+          },
+          "ttl_seconds": {
+            "type": "INTEGER",
+            "description": "Seconds before all orders are cancelled if not renewed (10–300)."
+          },
+          "confirmation_token": {
+            "type": "STRING",
+            "description": "Must equal exactly 'CONFIRM' (case-sensitive) to arm the switch."
+          }
+        },
+        "required": ["market_id", "ttl_seconds", "confirmation_token"]
+      }
+    },
+    {
+      "name": "renew_cancel_timer",
+      "description": "Resets the dead man's switch TTL for a market, preventing automatic order cancellation. No confirmation required. Requires an active timer set by schedule_cancel_all. Auth-gated.",
+      "parameters": {
+        "type": "OBJECT",
+        "properties": {
+          "market_id": {
+            "type": "STRING",
+            "description": "Market ID whose timer should be renewed (e.g. 'BTC-CLP')."
+          }
+        },
+        "required": ["market_id"]
+      }
+    },
+    {
+      "name": "disarm_cancel_timer",
+      "description": "Disarms the dead man's switch for a market without cancelling any orders. No confirmation required. Safe to call even if no timer is active. Auth-gated.",
+      "parameters": {
+        "type": "OBJECT",
+        "properties": {
+          "market_id": {
+            "type": "STRING",
+            "description": "Market ID whose timer should be disarmed (e.g. 'BTC-CLP')."
+          }
+        },
+        "required": ["market_id"]
+      }
     }
   ]
 }