buda-mcp

MCP server for Buda.com — the leading cryptocurrency exchange in Chile, Colombia, and Peru. Gives any MCP-compatible AI assistant live access to market data, order books, trade history, spreads, and (when credentials are provided) full private account tools including order management, withdrawals, deposits, and Lightning Network payments.

Quick Start

npx @guiie/buda-mcp

Or install permanently:

npm install -g @guiie/buda-mcp
buda-mcp

Install in your MCP client

Claude Code

claude mcp add buda-mcp -- npx -y @guiie/buda-mcp

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "buda-mcp": {
      "command": "npx",
      "args": ["-y", "@guiie/buda-mcp"]
    }
  }
}

Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "buda-mcp": {
      "command": "npx",
      "args": ["-y", "@guiie/buda-mcp"]
    }
  }
}

Tools

Public tools (no credentials required)

get_market_summary ⭐ Start here

One-call summary: last price, bid/ask, spread %, 24h volume, price change, and liquidity_rating (high / medium / low). Best first tool when a user asks about any specific market.

get_markets

List all 26 trading pairs on Buda.com, or get details for a specific market (fees, minimum order size, discount tiers).

get_ticker

Current snapshot: last price, best bid/ask, 24h volume, and price change over 24h and 7d.

get_orderbook

Current order book: sorted bids and asks as {price, amount} objects.

get_trades

Recent trade history as typed objects: {timestamp_ms, amount, price, direction}.

get_market_volume

24h and 7-day transacted volume by side (bid = buys, ask = sells).

get_spread

Bid/ask spread: absolute value and percentage of the ask price.

compare_markets

Side-by-side ticker data for all pairs of a given base currency across all quote currencies.

get_price_history

OHLCV candles aggregated from raw trade history (Buda has no native candlestick endpoint). Supports 5m, 15m, 30m, 1h, 4h, 1d periods.

get_arbitrage_opportunities

Detects cross-country price discrepancies for an asset across Buda's CLP, COP, and PEN markets, normalized to USDC.

simulate_order

Simulates a buy or sell order using live ticker data — no order is ever placed. Returns estimated_fill_price, fee_amount, total_cost, slippage_vs_mid_pct. All responses include simulation: true.

calculate_position_size

Kelly-style position sizing from capital, risk %, entry, and stop-loss. Fully client-side — no API call.

get_market_sentiment

Composite sentiment score (−100 to +100) from three components: 24h price variation (40%), volume vs 7-day average (35%), spread vs market-type baseline (25%). Returns score, label, component_breakdown, and a disclaimer.

get_technical_indicators

RSI (14), MACD (12/26/9), Bollinger Bands (20, 2σ), SMA 20, SMA 50 — computed server-side from Buda trade history (no external libraries). Returns signal interpretations and a structured warning if fewer than 20 candles are available. Includes disclaimer.

get_real_quotation

Returns a real-time quotation for a given order amount and direction, showing exact fill price, fee, and balance changes without placing an order.

get_available_banks

Lists available banks for fiat deposits/withdrawals in a given currency's country.

Authenticated tools

Available only when BUDA_API_KEY and BUDA_API_SECRET environment variables are set. See Authentication mode below.

Warning: Authenticated instances must be run locally only. Never expose a server with API credentials to the internet.

get_account_info

Returns the authenticated account profile: email, name, and monthly transacted amount.

get_balances

All currency balances: total, available, frozen, and pending withdrawal — as floats with _currency fields.

Example prompts:

• "What's my BTC balance on Buda?"
• "Show all my balances"

get_balance

Balance for a single currency.

get_orders

Orders for a given market, filterable by state.

get_order

Returns a single order by its numeric ID.

get_order_by_client_id

Returns an order by the client-assigned string ID set at placement.

place_order

Place a limit or market order. Supports optional time-in-force flags and stop orders.

Requires confirmation_token="CONFIRM" — prevents accidental execution.

cancel_order

Cancel an open order by numeric ID.

Requires confirmation_token="CONFIRM".

cancel_order_by_client_id

Cancel an open order by its client-assigned string ID.

Requires confirmation_token="CONFIRM".

cancel_all_orders

Cancel all open orders in a specific market or across all markets.

Requires confirmation_token="CONFIRM".

place_batch_orders

Place up to 20 orders sequentially. All orders are pre-validated before any API call — a validation failure aborts with zero orders placed. Partial API failures do not roll back placed orders; a warning field surfaces this.

Requires confirmation_token="CONFIRM".

get_network_fees

Returns withdrawal fee information for a currency.

get_deposit_history

Deposit history for a currency, filterable by state with pagination.

create_fiat_deposit

Record a fiat deposit. Calling twice creates duplicate records — the confirmation guard is critical.

Requires confirmation_token="CONFIRM".

get_withdrawal_history

Withdrawal history for a currency, filterable by state with pagination.

create_withdrawal

Create a crypto or fiat withdrawal. Exactly one of address (crypto) or bank_account_id (fiat) must be provided.

Requires confirmation_token="CONFIRM".

list_receive_addresses

Lists all receive addresses for a currency.

get_receive_address

Returns the current active receive address for a currency.

create_receive_address

Generate a new receive address for a crypto currency. Not idempotent — each call creates a distinct address.

Requires confirmation_token="CONFIRM".

list_remittances

Lists remittances on the account with pagination.

get_remittance

Returns a single remittance by ID.

quote_remittance

Request a remittance quote for a given recipient and amount. Not idempotent — each call creates a new remittance record.

Requires confirmation_token="CONFIRM".

accept_remittance_quote

Accept a remittance quote to execute the transfer.

Requires confirmation_token="CONFIRM".

list_remittance_recipients

Lists saved remittance recipients with pagination.

get_remittance_recipient

Returns a single remittance recipient by ID.

lightning_withdrawal

Pay a Bitcoin Lightning Network BOLT-11 invoice from the LN-BTC reserve. Funds leave immediately on success.

Requires confirmation_token="CONFIRM".

create_lightning_invoice

Create a Bitcoin Lightning Network receive invoice. No confirmation required — no funds leave the account.

schedule_cancel_all

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".

Warning: Timer state is lost on server restart. Use only on locally-run instances — never Railway or hosted deployments.

renew_cancel_timer

Resets the dead man's switch TTL for a market. No confirmation required.

disarm_cancel_timer

Disarms the dead man's switch without cancelling any orders. Safe to call with no active timer.

MCP Resources

In addition to tools, the server exposes MCP Resources that clients can read directly:

Authentication mode

The server defaults to public-only mode — no API key needed, no breaking changes for existing users.

To enable authenticated tools, set environment variables before running:

BUDA_API_KEY=your_api_key BUDA_API_SECRET=your_api_secret npx @guiie/buda-mcp

Or in Claude Desktop config:

{
  "mcpServers": {
    "buda-mcp": {
      "command": "npx",
      "args": ["-y", "@guiie/buda-mcp"],
      "env": {
        "BUDA_API_KEY": "your_api_key",
        "BUDA_API_SECRET": "your_api_secret"
      }
    }
  }
}

Authentication uses HMAC-SHA384 signing per the Buda API docs. Keys are never logged.

Security: Never expose an authenticated instance on a public server. Always run locally when using API credentials.

Markets covered

Build from source

git clone https://github.com/gtorreal/buda-mcp.git
cd buda-mcp
npm install
npm run build
node dist/index.js        # stdio (for MCP clients)
node dist/http.js         # HTTP on port 3000 (for Railway / hosted)

Run tests:

npm run test:unit        # 138 unit tests, no network required
npm run test:integration # live API tests (skips if unreachable)
npm test                 # both

HTTP / Railway deployment

The dist/http.js entrypoint runs an Express server with:

• POST /mcp — Streamable HTTP MCP transport
• GET /mcp — SSE streaming transport
• GET /health — health check ({ status, version, auth_mode })
• GET /.well-known/mcp/server-card.json — Smithery-compatible static tool manifest

Environment variables

Security: Never expose the HTTP server publicly without setting MCP_AUTH_TOKEN. The server will exit at startup if credentials are present but the token is missing.

Project structure

src/
  client.ts                   BudaClient (HTTP + HMAC auth + 429 retry)
  cache.ts                    In-memory TTL cache with in-flight deduplication
  types.ts                    TypeScript types for Buda API responses
  validation.ts               validateMarketId(), validateCurrency(), validateCryptoAddress()
  utils.ts                    flattenAmount(), aggregateTradesToCandles(), getLiquidityRating()
  version.ts                  Single source of truth for version string
  index.ts                    stdio MCP server entrypoint
  http.ts                     HTTP/SSE MCP server entrypoint
  tools/
    markets.ts                get_markets
    ticker.ts                 get_ticker
    orderbook.ts              get_orderbook
    trades.ts                 get_trades
    volume.ts                 get_market_volume
    spread.ts                 get_spread
    compare_markets.ts        compare_markets
    price_history.ts          get_price_history
    arbitrage.ts              get_arbitrage_opportunities
    market_summary.ts         get_market_summary
    simulate_order.ts         simulate_order
    calculate_position_size.ts calculate_position_size
    market_sentiment.ts       get_market_sentiment
    technical_indicators.ts   get_technical_indicators
    banks.ts                  get_available_banks
    quotation.ts              get_real_quotation
    account.ts                get_account_info (auth)
    balance.ts                get_balance (auth)
    balances.ts               get_balances (auth)
    orders.ts                 get_orders (auth)
    order_lookup.ts           get_order, get_order_by_client_id (auth)
    place_order.ts            place_order (auth)
    cancel_order.ts           cancel_order (auth)
    cancel_all_orders.ts      cancel_all_orders (auth)
    cancel_order_by_client_id.ts  cancel_order_by_client_id (auth)
    batch_orders.ts           place_batch_orders (auth)
    fees.ts                   get_network_fees (auth)
    deposits.ts               get_deposit_history, create_fiat_deposit (auth)
    withdrawals.ts            get_withdrawal_history, create_withdrawal (auth)
    receive_addresses.ts      list/get/create_receive_address (auth)
    remittances.ts            list/get/quote/accept remittances (auth)
    remittance_recipients.ts  list/get remittance recipients (auth)
    lightning.ts              lightning_withdrawal, create_lightning_invoice (auth)
    dead_mans_switch.ts       schedule_cancel_all, renew/disarm_cancel_timer (auth)
marketplace/
  cursor-mcp.json             Cursor MCP config example
  claude-listing.md           Claude registry listing
  openapi.yaml                OpenAPI spec (GPT Actions / HTTP wrapper)
  gemini-tools.json           Gemini function declarations

License

MIT — Buda.com API docs