@guiie/buda-mcp 1.0.0

package/dist/types.d.ts

@@ -0,0 +1,61 @@
+export type Amount = [string, string];
+export interface Market {
+    id: string;
+    name: string;
+    base_currency: string;
+    quote_currency: string;
+    minimum_order_amount: Amount;
+    taker_fee: string;
+    maker_fee: string;
+    max_orders_per_minute: number;
+    maker_discount_percentage: string;
+    taker_discount_percentage: string;
+    maker_discount_tiers: Record<string, number>;
+    taker_discount_tiers: Record<string, number>;
+}
+export interface MarketsResponse {
+    markets: Market[];
+}
+export interface MarketResponse {
+    market: Market;
+}
+export interface Ticker {
+    market_id: string;
+    last_price: Amount;
+    min_ask: Amount;
+    max_bid: Amount;
+    volume: Amount;
+    price_variation_24h: string;
+    price_variation_7d: string;
+}
+export interface TickerResponse {
+    ticker: Ticker;
+}
+export interface OrderBook {
+    asks: [string, string][];
+    bids: [string, string][];
+}
+export interface OrderBookResponse {
+    order_book: OrderBook;
+}
+export interface Trades {
+    timestamp: string;
+    last_timestamp: string;
+    market_id: string;
+    /** Each entry: [timestamp, amount, price, direction] */
+    entries: [string, string, string, string][];
+}
+export interface TradesResponse {
+    trades: Trades;
+}
+export interface MarketVolume {
+    market_id: string;
+    ask_volume_24h: Amount;
+    ask_volume_7d: Amount;
+    bid_volume_24h: Amount;
+    bid_volume_7d: Amount;
+}
+export interface VolumeResponse {
+    volume: MarketVolume;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAItC,MAAM,WAAW,MAAM;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,yBAAyB,EAAE,MAAM,CAAC;IAClC,yBAAyB,EAAE,MAAM,CAAC;IAClC,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7C,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9C;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;CAChB;AAID,MAAM,WAAW,MAAM;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,mBAAmB,EAAE,MAAM,CAAC;IAC5B,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;CAChB;AAID,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;IACzB,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,SAAS,CAAC;CACvB;AAID,MAAM,WAAW,MAAM;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;CAC7C;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;CAChB;AAID,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,YAAY,CAAC;CACtB"}

package/dist/types.js

@@ -0,0 +1,4 @@
+// Buda.com REST API v2 — shared response types
+// All monetary amounts are returned as [amount_string, currency_string] tuples.
+export {};
+//# sourceMappingURL=types.js.map

package/marketplace/README.md

@@ -0,0 +1,67 @@
+# Marketplace Submission Assets
+
+Ready-to-use assets for submitting buda-mcp to every major AI marketplace.
+Replace `gtorreal` / `gtorreal` with your actual handles before submitting.
+
+---
+
+## `cursor-mcp.json` — Cursor
+
+Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per project).
+Uses `npx` so users don't need to clone the repo.
+
+**PR submission:** Open a PR against the [Cursor MCP directory](https://github.com/getcursor/cursor) following their contribution guide. Include this file and a link to the npm package.
+
+---
+
+## `claude-listing.md` — Claude / Anthropic MCP Registry
+
+Paste this content into the Anthropic MCP server submission form, or use it as the
+body of a GitHub issue on the [modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers) repo.
+
+For the official registry (`registry.modelcontextprotocol.io`), the listing is generated
+automatically from `server.json` via `mcp-publisher` — see the main README for those steps.
+
+---
+
+## `openapi.yaml` — ChatGPT GPT Actions
+
+Used to register buda-mcp as a ChatGPT Action inside a custom GPT.
+
+**Steps:**
+1. Deploy the server over HTTP:
+   ```bash
+   pip install mcp-proxy
+   mcp-proxy --port 8000 -- npx -y @guiie/buda-mcp
+   ```
+2. Replace `https://YOUR_DEPLOYED_DOMAIN` in `openapi.yaml` with your public URL.
+3. In the GPT editor → "Actions" → "Add action" → paste the YAML.
+4. Set authentication to "None".
+
+For production, deploy to Railway, Fly.io, or Render so the URL is stable.
+
+---
+
+## `gemini-tools.json` — Gemini API / Google AI Studio
+
+Paste the `functionDeclarations` array into your Gemini API call:
+
+```python
+import google.generativeai as genai
+import json
+
+with open("gemini-tools.json") as f:
+    tool_config = json.load(f)
+
+model = genai.GenerativeModel(
+    model_name="gemini-2.0-flash",
+    tools=[{"function_declarations": tool_config["functionDeclarations"]}],
+)
+```
+
+For **Google AI Studio**, go to *System instructions → Tools → Add function* and paste
+each `functionDeclaration` object individually.
+
+For the **Gemini marketplace / Extensions** (once generally available), submit via the
+[Google AI Extensions portal](https://ai.google.dev/) using these declarations as the
+tool schema.

package/marketplace/claude-listing.md

@@ -0,0 +1,97 @@
+# Buda.com Market Data
+
+**Category:** Finance / Cryptocurrency  
+**Auth:** None required  
+**Transport:** stdio  
+**npm:** `@guiie/buda-mcp`  
+**Registry name:** `io.github.gtorreal/buda-mcp`
+
+---
+
+## 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.
+
+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.
+
+---
+
+## Tools
+
+### `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.  
+**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.  
+**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.  
+**Parameters:** `market_id` *(required)*, `limit` *(optional)* — cap levels returned per side.
+
+### `get_trades`
+Recent trade history. Each entry: `[timestamp_ms, amount, price, direction]`.  
+**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.  
+**Parameters:** `market_id` *(required)*.
+
+---
+
+## Example prompts
+
+- *"What is the current Bitcoin price in Chilean pesos?"*
+- *"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."*
+- *"What's the spread on BTC-COP right now?"*
+
+---
+
+## Installation
+
+**Claude Code (claude CLI)**
+```bash
+claude mcp add buda-mcp -- npx -y @guiie/buda-mcp
+```
+
+**Claude Desktop (`claude_desktop_config.json`)**
+```json
+{
+  "mcpServers": {
+    "buda-mcp": {
+      "command": "npx",
+      "args": ["-y", "@guiie/buda-mcp"]
+    }
+  }
+}
+```
+
+**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
+```
+
+---
+
+## Markets covered
+
+| Quote | Country | Sample pairs |
+|---|---|---|
+| CLP | Chile | BTC-CLP, ETH-CLP, XRP-CLP |
+| COP | Colombia | BTC-COP, ETH-COP, XRP-COP |
+| PEN | Peru | BTC-PEN, ETH-PEN |
+| BTC | Cross | ETH-BTC, XRP-BTC, BCH-BTC |
+
+---
+
+## Source
+
+- GitHub: https://github.com/gtorreal/buda-mcp  
+- npm: https://www.npmjs.com/package/@guiie/buda-mcp  
+- Buda.com API docs: https://api.buda.com/en/

package/marketplace/cursor-mcp.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "buda-mcp": {
+      "command": "npx",
+      "args": ["-y", "@guiie/buda-mcp"],
+      "description": "Buda.com cryptocurrency exchange — real-time market data for Chile, Colombia, and Peru"
+    }
+  }
+}

package/marketplace/gemini-tools.json

@@ -0,0 +1,87 @@
+{
+  "_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",
+  "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.",
+      "parameters": {
+        "type": "OBJECT",
+        "properties": {
+          "market_id": {
+            "type": "STRING",
+            "description": "Optional market identifier such as 'BTC-CLP', 'ETH-BTC', or 'BTC-COP'. Case-insensitive. Omit to list all available markets."
+          }
+        },
+        "required": []
+      }
+    },
+    {
+      "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.",
+      "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": "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.",
+      "parameters": {
+        "type": "OBJECT",
+        "properties": {
+          "market_id": {
+            "type": "STRING",
+            "description": "Market identifier such as 'BTC-CLP' or 'ETH-BTC'. Case-insensitive."
+          },
+          "limit": {
+            "type": "INTEGER",
+            "description": "Maximum number of price levels to return per side (bids and asks). Defaults to all levels if omitted."
+          }
+        },
+        "required": ["market_id"]
+      }
+    },
+    {
+      "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.",
+      "parameters": {
+        "type": "OBJECT",
+        "properties": {
+          "market_id": {
+            "type": "STRING",
+            "description": "Market identifier such as 'BTC-CLP' or 'ETH-BTC'. Case-insensitive."
+          },
+          "limit": {
+            "type": "INTEGER",
+            "description": "Number of trades to return. Default is 50, maximum is 100."
+          },
+          "timestamp": {
+            "type": "INTEGER",
+            "description": "Unix timestamp in seconds. When provided, returns trades that occurred before this timestamp, enabling pagination through historical data."
+          }
+        },
+        "required": ["market_id"]
+      }
+    },
+    {
+      "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.",
+      "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"]
+      }
+    }
+  ]
+}

package/marketplace/openapi.yaml

@@ -0,0 +1,349 @@
+openapi: 3.1.0
+info:
+  title: Buda.com Market Data API
+  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.
+
+    **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
+  contact:
+    url: https://github.com/gtorreal/buda-mcp
+
+servers:
+  - url: https://YOUR_DEPLOYED_DOMAIN
+    description: Deployed buda-mcp HTTP instance
+
+paths:
+  /get_markets:
+    get:
+      operationId: getMarkets
+      summary: List all trading pairs
+      description: |
+        Returns all available markets on Buda.com, or details for a single market.
+        Each market entry includes base/quote currencies, trading fees, and minimum order amounts.
+      parameters:
+        - name: market_id
+          in: query
+          required: false
+          description: |
+            Market identifier (e.g. "BTC-CLP", "ETH-BTC"). Case-insensitive.
+            Omit to return all markets.
+          schema:
+            type: string
+            example: BTC-CLP
+      responses:
+        "200":
+          description: Market list or single market details
+          content:
+            application/json:
+              schema:
+                oneOf:
+                  - $ref: "#/components/schemas/MarketsResponse"
+                  - $ref: "#/components/schemas/SingleMarketResponse"
+        "404":
+          $ref: "#/components/responses/NotFound"
+
+  /get_ticker:
+    get:
+      operationId: getTicker
+      summary: Current price and volume for a market
+      description: |
+        Returns the current market snapshot: last traded price, best bid (max_bid),
+        best ask (min_ask), 24h volume, and price change over 24h and 7d.
+      parameters:
+        - name: market_id
+          in: query
+          required: true
+          description: Market identifier (e.g. "BTC-CLP", "ETH-COP"). Case-insensitive.
+          schema:
+            type: string
+            example: BTC-CLP
+      responses:
+        "200":
+          description: Current ticker snapshot
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/TickerResponse"
+        "404":
+          $ref: "#/components/responses/NotFound"
+
+  /get_orderbook:
+    get:
+      operationId: getOrderbook
+      summary: Order book for a market
+      description: |
+        Returns the current limit order book: sorted arrays of bids (buy orders)
+        and asks (sell orders). Each entry is [price, amount].
+      parameters:
+        - name: market_id
+          in: query
+          required: true
+          description: Market identifier (e.g. "BTC-CLP"). Case-insensitive.
+          schema:
+            type: string
+            example: BTC-CLP
+        - name: limit
+          in: query
+          required: false
+          description: Max number of price levels to return per side. Defaults to all.
+          schema:
+            type: integer
+            minimum: 1
+            example: 20
+      responses:
+        "200":
+          description: Order book bids and asks
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/OrderBookResponse"
+        "404":
+          $ref: "#/components/responses/NotFound"
+
+  /get_trades:
+    get:
+      operationId: getTrades
+      summary: Recent trade history for a market
+      description: |
+        Returns recent trades. Each entry is [timestamp_ms, amount, price, direction]
+        where direction is "buy" or "sell".
+      parameters:
+        - name: market_id
+          in: query
+          required: true
+          description: Market identifier (e.g. "BTC-CLP"). Case-insensitive.
+          schema:
+            type: string
+            example: BTC-CLP
+        - name: limit
+          in: query
+          required: false
+          description: Number of trades to return (default 50, max 100).
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 100
+            example: 50
+        - name: timestamp
+          in: query
+          required: false
+          description: |
+            Unix timestamp in seconds. Returns trades older than this value,
+            for pagination through history.
+          schema:
+            type: integer
+            example: 1712000000
+      responses:
+        "200":
+          description: Trade history
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/TradesResponse"
+        "404":
+          $ref: "#/components/responses/NotFound"
+
+  /get_market_volume:
+    get:
+      operationId: getMarketVolume
+      summary: 24h and 7-day volume for a market
+      description: |
+        Returns transacted volume broken down by side (ask = sell, bid = buy)
+        and time window (24h and 7d). Amounts are in the market's base currency.
+      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: Volume data
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/VolumeResponse"
+        "404":
+          $ref: "#/components/responses/NotFound"
+
+components:
+  schemas:
+    Amount:
+      type: array
+      description: Monetary amount as [value_string, currency_code]
+      items:
+        type: string
+      minItems: 2
+      maxItems: 2
+      example: ["65929908.0", "CLP"]
+
+    Market:
+      type: object
+      properties:
+        id:
+          type: string
+          example: BTC-CLP
+        name:
+          type: string
+          example: btc-clp
+        base_currency:
+          type: string
+          example: BTC
+        quote_currency:
+          type: string
+          example: CLP
+        minimum_order_amount:
+          $ref: "#/components/schemas/Amount"
+        taker_fee:
+          type: string
+          example: "0.8"
+        maker_fee:
+          type: string
+          example: "0.4"
+        max_orders_per_minute:
+          type: integer
+          example: 100
+        maker_discount_percentage:
+          type: string
+        taker_discount_percentage:
+          type: string
+
+    MarketsResponse:
+      type: object
+      properties:
+        markets:
+          type: array
+          items:
+            $ref: "#/components/schemas/Market"
+
+    SingleMarketResponse:
+      type: object
+      properties:
+        market:
+          $ref: "#/components/schemas/Market"
+
+    Ticker:
+      type: object
+      properties:
+        market_id:
+          type: string
+          example: BTC-CLP
+        last_price:
+          $ref: "#/components/schemas/Amount"
+        max_bid:
+          $ref: "#/components/schemas/Amount"
+        min_ask:
+          $ref: "#/components/schemas/Amount"
+        volume:
+          $ref: "#/components/schemas/Amount"
+        price_variation_24h:
+          type: string
+          description: Decimal fraction (e.g. "0.014" = +1.4%)
+          example: "0.014"
+        price_variation_7d:
+          type: string
+          example: "-0.032"
+
+    TickerResponse:
+      type: object
+      properties:
+        ticker:
+          $ref: "#/components/schemas/Ticker"
+
+    OrderBookResponse:
+      type: object
+      properties:
+        bids:
+          type: array
+          description: Buy orders sorted best-first, each [price, amount]
+          items:
+            type: array
+            items:
+              type: string
+            minItems: 2
+            maxItems: 2
+        asks:
+          type: array
+          description: Sell orders sorted best-first, each [price, amount]
+          items:
+            type: array
+            items:
+              type: string
+            minItems: 2
+            maxItems: 2
+        bid_count:
+          type: integer
+          description: Total number of bid levels in the full book
+        ask_count:
+          type: integer
+          description: Total number of ask levels in the full book
+
+    TradeEntry:
+      type: array
+      description: "[timestamp_ms, amount, price, direction]"
+      items:
+        type: string
+      minItems: 4
+      maxItems: 4
+      example: ["1775857164247", "0.00113757", "65929908.0", "buy"]
+
+    TradesResponse:
+      type: object
+      properties:
+        trades:
+          type: object
+          properties:
+            market_id:
+              type: string
+              example: BTC-CLP
+            timestamp:
+              type: string
+              description: Most recent trade timestamp (ms)
+            last_timestamp:
+              type: string
+              description: Oldest trade timestamp in this response (ms)
+            entries:
+              type: array
+              items:
+                $ref: "#/components/schemas/TradeEntry"
+
+    VolumeResponse:
+      type: object
+      properties:
+        volume:
+          type: object
+          properties:
+            market_id:
+              type: string
+              example: BTC-CLP
+            ask_volume_24h:
+              $ref: "#/components/schemas/Amount"
+            ask_volume_7d:
+              $ref: "#/components/schemas/Amount"
+            bid_volume_24h:
+              $ref: "#/components/schemas/Amount"
+            bid_volume_7d:
+              $ref: "#/components/schemas/Amount"
+
+    Error:
+      type: object
+      properties:
+        error:
+          type: string
+
+  responses:
+    NotFound:
+      description: Market not found
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/Error"