@guiie/buda-mcp 1.0.0 → 1.1.1

package/marketplace/claude-listing.md

@@ -1,7 +1,7 @@
 # Buda.com Market Data
 
 **Category:** Finance / Cryptocurrency  
-**Auth:** None required  
+**Auth:** Optional (public mode requires no key; authenticated mode needs `BUDA_API_KEY` + `BUDA_API_SECRET`)  
 **Transport:** stdio  
 **npm:** `@guiie/buda-mcp`  
 **Registry name:** `io.github.gtorreal/buda-mcp`
@@ -10,14 +10,16 @@
 
 ## Description
 
-Real-time market data from [Buda.com](https://www.buda.com/), the leading cryptocurrency exchange operating in Chile, Colombia, and Peru. All data is sourced from Buda's public REST API v2 — no API key required.
+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, order books, trade history, and volume for all BTC, ETH, and altcoin markets quoted in CLP, COP, and PEN.
+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.
 
 ---
 
 ## Tools
 
+### Public tools (no credentials required)
+
 ### `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.  
@@ -39,6 +41,46 @@ Recent trade history. Each entry: `[timestamp_ms, amount, price, direction]`.
 24h and 7-day transacted volume 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.  
+**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.  
+**Parameters:** `base_currency` *(required)* — e.g. `BTC`, `ETH`, `XRP`.
+
+### `get_price_history`
+OHLCV (open/high/low/close/volume) candles derived from recent trade history. Supports `1h`, `4h`, and `1d` periods.  
+**Parameters:** `market_id` *(required)*, `period` *(optional: `1h`/`4h`/`1d`, default `1h`)*, `limit` *(optional, max 100 trades)*.
+
+### 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.
+
+### `get_orders`
+Orders for a given market, filterable by state (`pending`, `active`, `traded`, `canceled`).  
+**Parameters:** `market_id` *(required)*, `state` *(optional)*, `per` *(optional)*, `page` *(optional)*.
+
+### `place_order`
+Place a limit or market order. Requires `confirmation_token="CONFIRM"` to prevent accidental execution.  
+**Parameters:** `market_id`, `type` (Bid/Ask), `price_type` (limit/market), `amount`, `limit_price` *(for limit orders)*, `confirmation_token`.
+
+### `cancel_order`
+Cancel an open order by ID. Requires `confirmation_token="CONFIRM"`.  
+**Parameters:** `order_id`, `confirmation_token`.
+
+---
+
+## MCP Resources
+
+| URI | Description |
+|-----|-------------|
+| `buda://markets` | JSON list of all Buda.com markets |
+| `buda://ticker/{market}` | JSON ticker for a specific market |
+
 ---
 
 ## Example prompts
@@ -48,11 +90,20 @@ Recent trade history. Each entry: `[timestamp_ms, amount, price, direction]`.
 - *"How much ETH was traded on Buda in the last 7 days?"*
 - *"List all markets available on Buda.com."*
 - *"What's the spread on BTC-COP right now?"*
+- *"Compare the Bitcoin price across all Buda markets."*
+- *"Show me hourly BTC-CLP candles."*
+- *"What's my available BTC balance?"* *(authenticated)*
+- *"Show my open orders on BTC-CLP."* *(authenticated)*
 
 ---
 
 ## Installation
 
+**Quick start (npx)**
+```bash
+npx @guiie/buda-mcp
+```
+
 **Claude Code (claude CLI)**
 ```bash
 claude mcp add buda-mcp -- npx -y @guiie/buda-mcp
@@ -70,11 +121,27 @@ claude mcp add buda-mcp -- npx -y @guiie/buda-mcp
 }
 ```
 
+**With authentication**
+```json
+{
+  "mcpServers": {
+    "buda-mcp": {
+      "command": "npx",
+      "args": ["-y", "@guiie/buda-mcp"],
+      "env": {
+        "BUDA_API_KEY": "your_api_key",
+        "BUDA_API_SECRET": "your_api_secret"
+      }
+    }
+  }
+}
+```
+
 **From source**
 ```bash
 git clone https://github.com/gtorreal/buda-mcp.git
 cd buda-mcp && npm install && npm run build
-# Then point to: node /absolute/path/buda-mcp/dist/index.js
+node dist/index.js
 ```
 
 ---
@@ -86,6 +153,7 @@ cd buda-mcp && npm install && npm run build
 | CLP | Chile | BTC-CLP, ETH-CLP, XRP-CLP |
 | COP | Colombia | BTC-COP, ETH-COP, XRP-COP |
 | PEN | Peru | BTC-PEN, ETH-PEN |
+| USDC | USD-pegged | BTC-USDC, ETH-USDC |
 | BTC | Cross | ETH-BTC, XRP-BTC, BCH-BTC |
 
 ---

package/marketplace/cursor-mcp.json

@@ -3,7 +3,7 @@
     "buda-mcp": {
       "command": "npx",
       "args": ["-y", "@guiie/buda-mcp"],
-      "description": "Buda.com cryptocurrency exchange — real-time market data for Chile, Colombia, and Peru"
+      "description": "Buda.com cryptocurrency exchange — real-time market data, spreads, OHLCV history, and account tools for Chile, Colombia, and Peru"
     }
   }
 }

package/marketplace/gemini-tools.json

@@ -1,5 +1,5 @@
 {
-  "_comment": "Gemini function declarations for buda-mcp. 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.1.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",
@@ -82,6 +82,56 @@
         },
         "required": ["market_id"]
       }
+    },
+    {
+      "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.",
+      "parameters": {
+        "type": "OBJECT",
+        "properties": {
+          "market_id": {
+            "type": "STRING",
+            "description": "Market identifier such as 'BTC-CLP', 'ETH-COP', or 'ETH-BTC'. Case-insensitive."
+          }
+        },
+        "required": ["market_id"]
+      }
+    },
+    {
+      "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.",
+      "parameters": {
+        "type": "OBJECT",
+        "properties": {
+          "base_currency": {
+            "type": "STRING",
+            "description": "Base currency to compare across all available markets. Examples: 'BTC', 'ETH', 'XRP'. Case-insensitive."
+          }
+        },
+        "required": ["base_currency"]
+      }
+    },
+    {
+      "name": "get_price_history",
+      "description": "Get OHLCV (open/high/low/close/volume) price history for a Buda.com market, derived from recent trade history. Candles are aggregated client-side from up to 100 raw trades. Supports 1h, 4h, and 1d candle periods.",
+      "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' (1 hour), '4h' (4 hours), or '1d' (1 day). Default is '1h'."
+          },
+          "limit": {
+            "type": "INTEGER",
+            "description": "Number of raw trades to fetch before aggregation. Default is 100, maximum is 100."
+          }
+        },
+        "required": ["market_id"]
+      }
     }
   ]
 }

package/marketplace/openapi.yaml

@@ -4,14 +4,14 @@ info:
   description: |
     Real-time cryptocurrency market data from Buda.com — the leading exchange
     in Chile (CLP), Colombia (COP), and Peru (PEN).
-    Provides live prices, order books, trade history, and volume for all markets.
-    No authentication required.
+    Provides live prices, spreads, OHLCV history, order books, trade history, and volume for all markets.
+    No authentication required for public tools.
 
     **Note:** This spec describes a deployed HTTP wrapper around the buda-mcp
     stdio server. Deploy locally with mcp-proxy:
       mcp-proxy --port 8000 -- npx -y @guiie/buda-mcp
     Or point `servers[0].url` at your hosted instance.
-  version: 1.0.0
+  version: 1.1.0
   contact:
     url: https://github.com/gtorreal/buda-mcp
 
@@ -175,6 +175,99 @@ paths:
         "404":
           $ref: "#/components/responses/NotFound"
 
+  /get_spread:
+    get:
+      operationId: getSpread
+      summary: Bid/ask spread for a market
+      description: |
+        Returns the best bid price, best ask price, absolute spread, and spread as a percentage
+        of the ask price. Useful for assessing market liquidity.
+      parameters:
+        - name: market_id
+          in: query
+          required: true
+          description: Market identifier (e.g. "BTC-CLP"). Case-insensitive.
+          schema:
+            type: string
+            example: BTC-CLP
+      responses:
+        "200":
+          description: Spread data
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SpreadResponse"
+        "404":
+          $ref: "#/components/responses/NotFound"
+
+  /compare_markets:
+    get:
+      operationId: compareMarkets
+      summary: Compare all pairs of a base currency side by side
+      description: |
+        Returns ticker data for all trading pairs of a given base currency across all supported
+        quote currencies (CLP, COP, PEN, USDC, BTC, ETH). For example, base_currency=BTC returns
+        data for BTC-CLP, BTC-COP, BTC-PEN, and BTC-USDC.
+      parameters:
+        - name: base_currency
+          in: query
+          required: true
+          description: Base currency to compare (e.g. "BTC", "ETH"). Case-insensitive.
+          schema:
+            type: string
+            example: BTC
+      responses:
+        "200":
+          description: Comparison of all pairs for the given base currency
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CompareMarketsResponse"
+        "404":
+          $ref: "#/components/responses/NotFound"
+
+  /get_price_history:
+    get:
+      operationId: getPriceHistory
+      summary: OHLCV price history derived from trade history
+      description: |
+        Returns OHLCV (open/high/low/close/volume) candles derived from recent trade history.
+        Buda.com has no native candlestick endpoint; candles are aggregated client-side from
+        up to 100 raw trades. Supports 1h, 4h, and 1d candle periods.
+      parameters:
+        - name: market_id
+          in: query
+          required: true
+          description: Market identifier (e.g. "BTC-CLP"). Case-insensitive.
+          schema:
+            type: string
+            example: BTC-CLP
+        - name: period
+          in: query
+          required: false
+          description: Candle period. One of "1h", "4h", "1d". Default is "1h".
+          schema:
+            type: string
+            enum: ["1h", "4h", "1d"]
+            default: "1h"
+        - name: limit
+          in: query
+          required: false
+          description: Number of raw trades to fetch before aggregation (default 100, max 100).
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 100
+      responses:
+        "200":
+          description: OHLCV candles
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PriceHistoryResponse"
+        "404":
+          $ref: "#/components/responses/NotFound"
+
 components:
   schemas:
     Amount:
@@ -334,11 +427,118 @@ components:
             bid_volume_7d:
               $ref: "#/components/schemas/Amount"
 
+    SpreadResponse:
+      type: object
+      properties:
+        market_id:
+          type: string
+          example: BTC-CLP
+        currency:
+          type: string
+          example: CLP
+        best_bid:
+          type: string
+          example: "65221128.0"
+        best_ask:
+          type: string
+          example: "65727568.0"
+        spread_absolute:
+          type: string
+          example: "506440.00"
+        spread_percentage:
+          type: string
+          example: "0.7705%"
+        last_price:
+          type: string
+          example: "65221078.43"
+
+    CompareMarketsResponse:
+      type: object
+      properties:
+        base_currency:
+          type: string
+          example: BTC
+        markets:
+          type: array
+          items:
+            type: object
+            properties:
+              market_id:
+                type: string
+                example: BTC-CLP
+              last_price:
+                type: string
+                example: "65221078.43"
+              currency:
+                type: string
+                example: CLP
+              best_bid:
+                type: string
+              best_ask:
+                type: string
+              volume_24h:
+                type: string
+              price_change_24h:
+                type: string
+                example: "0.30%"
+              price_change_7d:
+                type: string
+                example: "-1.20%"
+
+    OhlcvCandle:
+      type: object
+      properties:
+        time:
+          type: string
+          format: date-time
+          example: "2026-04-10T12:00:00.000Z"
+        open:
+          type: string
+          example: "65221078.43"
+        high:
+          type: string
+          example: "65975364.0"
+        low:
+          type: string
+          example: "65164404.87"
+        close:
+          type: string
+          example: "65386647.0"
+        volume:
+          type: string
+          example: "0.52341200"
+        trade_count:
+          type: integer
+          example: 12
+
+    PriceHistoryResponse:
+      type: object
+      properties:
+        market_id:
+          type: string
+          example: BTC-CLP
+        period:
+          type: string
+          example: "1h"
+        candle_count:
+          type: integer
+          example: 6
+        note:
+          type: string
+        candles:
+          type: array
+          items:
+            $ref: "#/components/schemas/OhlcvCandle"
+
     Error:
       type: object
       properties:
         error:
           type: string
+        code:
+          oneOf:
+            - type: string
+            - type: integer
 
   responses:
     NotFound:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guiie/buda-mcp",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "mcpName": "io.github.gtorreal/buda-mcp",
   "description": "MCP server for Buda.com's public cryptocurrency exchange API (Chile, Colombia, Peru)",
   "type": "module",
@@ -10,7 +10,9 @@
   },
   "scripts": {
     "build": "tsc",
-    "start": "node dist/index.js",
+    "start": "node dist/http.js",
+    "start:stdio": "node dist/index.js",
+    "dev:http": "tsx src/http.ts",
     "dev": "tsx src/index.ts",
     "test": "tsx test/run-all.ts"
   },
@@ -43,9 +45,11 @@
   "author": "Guille <guillermo@buda.com>",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "express": "^5.2.1",
     "zod": "^4.3.6"
   },
   "devDependencies": {
+    "@types/express": "^5.0.6",
     "@types/node": "^25.6.0",
     "tsx": "^4.21.0",
     "typescript": "^6.0.2"

package/railway.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://railway.com/railway.schema.json",
+  "build": {
+    "builder": "NIXPACKS"
+  },
+  "deploy": {
+    "startCommand": "npm start",
+    "healthcheckPath": "/health",
+    "restartPolicyType": "ON_FAILURE",
+    "restartPolicyMaxRetries": 3
+  }
+}

package/server.json

@@ -1,17 +1,17 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.gtorreal/buda-mcp",
-  "description": "Real-time cryptocurrency market data from Buda.com — prices, order books, trades, and volume for markets in Chile (CLP), Colombia (COP), and Peru (PEN). No API key required.",
+  "description": "Buda.com market data: prices, spreads, OHLCV, order books, trades, and volume for CLP, COP, PEN.",
   "repository": {
     "url": "https://github.com/gtorreal/buda-mcp",
     "source": "github"
   },
-  "version": "1.0.0",
+  "version": "1.1.1",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@guiie/buda-mcp",
-      "version": "1.0.0",
+      "version": "1.1.1",
       "transport": {
         "type": "stdio"
       }

package/src/cache.ts

@@ -0,0 +1,34 @@
+interface CacheEntry<T> {
+  data: T;
+  expiry: number;
+}
+
+export class MemoryCache {
+  private store = new Map<string, CacheEntry<unknown>>();
+
+  async getOrFetch<T>(key: string, ttlMs: number, fetcher: () => Promise<T>): Promise<T> {
+    const entry = this.store.get(key) as CacheEntry<T> | undefined;
+    if (entry && Date.now() < entry.expiry) {
+      return entry.data;
+    }
+    const data = await fetcher();
+    this.store.set(key, { data, expiry: Date.now() + ttlMs });
+    return data;
+  }
+
+  invalidate(key: string): void {
+    this.store.delete(key);
+  }
+
+  clear(): void {
+    this.store.clear();
+  }
+}
+
+export const CACHE_TTL = {
+  MARKETS: 60_000,
+  TICKER: 5_000,
+  ORDERBOOK: 3_000,
+} as const;
+
+export const cache = new MemoryCache();

package/src/client.ts

@@ -1,3 +1,5 @@
+import { createHmac } from "crypto";
+
 const BASE_URL = "https://www.buda.com/api/v2";
 
 export class BudaApiError extends Error {
@@ -13,18 +15,47 @@ export class BudaApiError extends Error {
 
 export class BudaClient {
   private readonly baseUrl: string;
+  private readonly apiKey: string | undefined;
+  private readonly apiSecret: string | undefined;
 
-  constructor(baseUrl: string = BASE_URL) {
+  constructor(
+    baseUrl: string = BASE_URL,
+    apiKey?: string,
+    apiSecret?: string,
+  ) {
     this.baseUrl = baseUrl;
+    this.apiKey = apiKey;
+    this.apiSecret = apiSecret;
+  }
+
+  hasAuth(): boolean {
+    return Boolean(this.apiKey && this.apiSecret);
+  }
+
+  private nonce(): string {
+    return String(Math.floor(Date.now() * 1000));
+  }
+
+  private sign(method: string, pathWithQuery: string, body: string, nonce: string): string {
+    const encodedBody = body ? Buffer.from(body).toString("base64") : "";
+    const parts = [method, pathWithQuery];
+    if (encodedBody) parts.push(encodedBody);
+    parts.push(nonce);
+    const msg = parts.join(" ");
+    return createHmac("sha384", this.apiSecret!).update(msg).digest("hex");
+  }
+
+  private authHeaders(method: string, path: string, body?: string): Record<string, string> {
+    if (!this.hasAuth()) return {};
+    const nonce = this.nonce();
+    const signature = this.sign(method, path, body ?? "", nonce);
+    return {
+      "X-SBTC-APIKEY": this.apiKey!,
+      "X-SBTC-NONCE": nonce,
+      "X-SBTC-SIGNATURE": signature,
+    };
   }
 
-  /**
-   * Perform an authenticated GET request.
-   *
-   * Private endpoints (balances, orders, etc.) require HMAC-SHA2 signing.
-   * To add auth later, extend this method with the `apiKey` + `apiSecret`
-   * constructor params and sign the nonce/path headers here before fetching.
-   */
   async get<T>(path: string, params?: Record<string, string | number>): Promise<T> {
     const url = new URL(`${this.baseUrl}${path}.json`);
 
@@ -34,11 +65,75 @@ export class BudaClient {
       }
     }
 
+    const urlPath = url.pathname + url.search;
+    const headers: Record<string, string> = {
+      Accept: "application/json",
+      "User-Agent": "buda-mcp/1.1.0",
+      ...this.authHeaders("GET", urlPath),
+    };
+
+    const response = await fetch(url.toString(), { headers });
+
+    if (!response.ok) {
+      let detail = response.statusText;
+      try {
+        const body = (await response.json()) as { message?: string };
+        if (body.message) detail = body.message;
+      } catch {
+        // ignore parse error, use statusText
+      }
+      throw new BudaApiError(response.status, path, `Buda API ${response.status}: ${detail}`);
+    }
+
+    return response.json() as Promise<T>;
+  }
+
+  async post<T>(path: string, payload: unknown): Promise<T> {
+    const url = new URL(`${this.baseUrl}${path}.json`);
+    const bodyStr = JSON.stringify(payload);
+    const urlPath = url.pathname + url.search;
+    const headers: Record<string, string> = {
+      Accept: "application/json",
+      "Content-Type": "application/json",
+      "User-Agent": "buda-mcp/1.1.0",
+      ...this.authHeaders("POST", urlPath, bodyStr),
+    };
+
+    const response = await fetch(url.toString(), {
+      method: "POST",
+      headers,
+      body: bodyStr,
+    });
+
+    if (!response.ok) {
+      let detail = response.statusText;
+      try {
+        const body = (await response.json()) as { message?: string };
+        if (body.message) detail = body.message;
+      } catch {
+        // ignore parse error, use statusText
+      }
+      throw new BudaApiError(response.status, path, `Buda API ${response.status}: ${detail}`);
+    }
+
+    return response.json() as Promise<T>;
+  }
+
+  async put<T>(path: string, payload: unknown): Promise<T> {
+    const url = new URL(`${this.baseUrl}${path}.json`);
+    const bodyStr = JSON.stringify(payload);
+    const urlPath = url.pathname + url.search;
+    const headers: Record<string, string> = {
+      Accept: "application/json",
+      "Content-Type": "application/json",
+      "User-Agent": "buda-mcp/1.1.0",
+      ...this.authHeaders("PUT", urlPath, bodyStr),
+    };
+
     const response = await fetch(url.toString(), {
-      headers: {
-        Accept: "application/json",
-        "User-Agent": "buda-mcp/1.0.0",
-      },
+      method: "PUT",
+      headers,
+      body: bodyStr,
     });
 
     if (!response.ok) {