What is BananaCrystal MCP?

BananaCrystal MCP is a Model Context Protocol server that gives AI agents the ability to check balances, transfer stablecoins, swap currencies, and handle fiat through a single endpoint settled on Hedera blockchain.

How fast are agent transactions?

Transactions settle in under 5 seconds on the Hedera consensus layer, providing instant finality for autonomous agent operations.

BananaCrystal MCP 文件 | 40 個 AI 代理付款工具

快速入門

5 分鐘內讓您的 AI 代理開始付款。

安裝 MCP 伺服器

透過 npm 全域安裝 BananaCrystal MCP 伺服器。

bash

npm install -g @bananacrystal/mcp-server

取得您的 API 金鑰

從帳戶儀表板建立 MCP API 金鑰。沙盒金鑰以 bc_test_ 開頭，且免費。

取得 API 金鑰

沙盒金鑰： bc_test_...

設定 Claude Desktop

將 BananaCrystal 加入您的 Claude Desktop 設定檔。

claude_desktop_config.json

json

{
  "mcpServers": {
    "bananacrystal": {
      "command": "bananacrystal-mcp",
      "env": {
        "BANANACRYSTAL_API_KEY": "bc_test_your_sandbox_key_here"
      }
    }
  }
}

詢問您的代理

您的代理現在擁有 40 個付款工具。試試這些提示：

›"我目前的 USDb 餘額是多少？"

›"傳送 50 USDb 到 0.0.654321"

›"以目前匯率將 100 USDb 兌換為 NGNb"

›"顯示我最近 10 筆交易"

›"目前 USD 兌 NGN 的匯率是多少？"

MCP 工具

6 個類別共 40 個可直接上線的付款工具。唯讀操作永久免費。

唯讀24 個工具

ping

read_only免費

健康檢查：傳回 pong

get_server_info

read_only免費

傳回基本伺服器資訊

echo

read_only免費

將輸入訊息原樣傳回給呼叫端

get_my_profile

read_only免費

取得已驗證用戶的完整個人資料

get_balances

read_only免費

取得所有平台代幣或特定代幣的 Hedera 帳戶餘額

get_exchange_rate

read_only免費

取得某貨幣的即時買入/賣出匯率

list_supported_currencies

read_only免費

列出所有支援的貨幣及其動態手續費

list_available_tokens

read_only免費

列出平台所有可用的 Hedera 代幣

get_transaction_history

read_only免費

以篩選條件取得分類後的交易紀錄

get_my_limits

read_only免費

取得已驗證 API 金鑰的設定限額與即時使用量

estimate_swap_fees

read_only免費

在執行前估算貨幣兌換的手續費

get_agent_config

read_only免費

查詢其他用戶的代理設定

check_approval_status

read_only免費

查詢待處理的代理交易核准請求狀態

get_kyc_status

read_only免費

透過 Sumsub 取得用戶的 KYC 驗證狀態

get_deposit_status

read_only免費

依轉帳 ID 取得法幣存款狀態

get_withdrawal_status

read_only免費

透過 Brale 取得用戶的提領請求

get_escrow_balances

read_only免費

取得託管餘額明細：總額、可用與鎖定金額

get_escrow_history

read_only免費

取得完整託管交易紀錄，包括鎖定、釋放、獲利與虧損

list_offers

read_only免費

瀏覽預測市場中的有效報價及交易統計

get_offer

read_only免費

取得單一報價的完整詳細資料，包括交易統計

get_my_offers

read_only免費

取得特定用戶建立的所有報價

list_trades

read_only免費

以篩選條件列出平台上的所有交易

get_trade

read_only免費

取得單一交易的完整詳細資料，包括所屬報價統計

get_my_trades

read_only免費

取得用戶的所有交易，包括建立與收到的交易

轉帳2 個工具

request_transfer_otp

transfer0.3%

步驟 1：申請寄送至寄件人電子郵件的 OTP 驗證碼

transfer_tokens

transfer0.3%

步驟 2：以 OTP 驗證執行代幣轉帳

兌換1 個工具

swap_currency

swap0.5%

在兩種 Hedera 代幣之間兌換，自動計算匯率與手續費

法幣3 個工具

initiate_kyc

fiat

發起 KYC 驗證：傳回供 SDK 使用的 Sumsub 存取權杖

initiate_deposit

fiat

透過 Brale 發起法幣存款 (需完成 KYC)

request_withdrawal

fiat

透過 Brale 申請法幣提領 (需完成 KYC)

報價與交易6 個工具

create_offer

offers

建立預測市場報價，並將總金額鎖入託管

update_offer

offers

編輯現有報價 (僅限尚無交易時)

delist_offer

offers

將您的報價從交易市場下架並釋放鎖定的託管資金

delete_offer

offers

永久刪除您的報價 (若有進行中的交易則無法刪除)

engage_offer

offers

鎖定對應的託管資金以參與公開報價

cancel_trade

offers

取消進行中的交易並釋放您鎖定的託管資金

代理對代理3 個工具

request_agent_transaction

transfer

代表其他用戶的代理請求交易 (需電子郵件核准)

execute_approved_transaction

transfer

使用執行權杖執行先前已核准的代理交易

update_my_agent_settings

read_only免費

控制代理對代理交易是否需要電子郵件核准與 OTP

僅限沙盒1 個工具

reset_sandbox_balance

read_only免費

將沙盒餘額重設為預先存入的預設值 (僅限沙盒)

匯率 API

透過 REST 進行進階匯率操作。需要具備匯率權限的 API 金鑰。

MCP 工具與匯率 API：有什麼不同？

MCP 伺服器已包含 get_exchange_rate 這個 read_only 工具：您的代理可直接呼叫它，取得單一貨幣兌 USD 的買入/賣出匯率。這已涵蓋大多數代理的使用情境。

匯率 API 提供更多功能：交叉貨幣對換算、大量批次作業、歷史時間序列資料與統計摘要。這些功能以直接的 HTTP 端點提供，並以具備 rate 權限的 API 金鑰驗證。請從您的帳戶儀表板建立匯率金鑰。

身分驗證

所有匯率 API 端點都需要將具備 rate 權限的 API 金鑰作為 x-api-key 標頭傳入。沙盒版本位於 /mcp/sandbox/rate/*，使用您的沙盒金鑰 (bc_test_...)，並提供固定的模擬匯率以利重現測試。

基礎 URL

https://agentic.bananacrystal.com/mcp/rate

GET/mcp/rate/currencies列出所有支援的貨幣

列出所有支援的貨幣

請求範例

bash

curl "https://agentic.bananacrystal.com/mcp/rate/currencies" \
  -H "x-api-key: bc_live_your_rate_key_here"

回應範例

json

{
  "count": 11,
  "currencies": ["EGP", "EUR", "GBP", "GHS", "KES", "NGN", "TZS", "UGX", "USD", "XOF", "ZAR"]
}

GET/mcp/rate/current取得兩種貨幣之間的目前匯率

取得兩種貨幣之間的目前匯率

參數

名稱	必填	說明
`from`	必填	來源貨幣代碼 (例如 USD)
`to`	必填	目標貨幣代碼 (例如 NGN)

請求範例

bash

curl "https://agentic.bananacrystal.com/mcp/rate/current?from=USD&to=NGN" \
  -H "x-api-key: bc_live_your_rate_key_here"

回應範例

json

{
  "from": "USD",
  "to": "NGN",
  "rate": 1584.75,
  "buyRate": 1590.0,
  "sellRate": 1579.5,
  "timestamp": "2026-04-30T10:22:00.000Z"
}

GET/mcp/rate/convert將金額從一種貨幣換算為另一種貨幣

將金額從一種貨幣換算為另一種貨幣

參數

名稱	必填	說明
`from`	必填	來源貨幣代碼
`to`	必填	目標貨幣代碼
`amount`	必填	要換算的金額 (數字)

請求範例

bash

curl "https://agentic.bananacrystal.com/mcp/rate/convert?from=USD&to=NGN&amount=100" \
  -H "x-api-key: bc_live_your_rate_key_here"

回應範例

json

{
  "from": "USD",
  "to": "NGN",
  "amount": 100,
  "converted": 158475.0,
  "rate": 1584.75,
  "timestamp": "2026-04-30T10:22:00.000Z"
}

POST/mcp/rate/batch-convert在一次請求中換算多筆貨幣金額 (最多 100 筆)

在一次請求中換算多筆貨幣金額 (最多 100 筆)

請求範例

bash

curl -X POST "https://agentic.bananacrystal.com/mcp/rate/batch-convert" \
  -H "x-api-key: bc_live_your_rate_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "conversions": [
      { "from": "USD", "to": "NGN", "amount": 100 },
      { "from": "USD", "to": "GHS", "amount": 50 },
      { "from": "EUR", "to": "GBP", "amount": 200 }
    ]
  }'

回應範例

json

[
  { "from": "USD", "to": "NGN", "amount": 100, "converted": 158475.0, "rate": 1584.75, "timestamp": "..." },
  { "from": "USD", "to": "GHS", "amount": 50,  "converted": 800.0,    "rate": 16.0,    "timestamp": "..." },
  { "from": "EUR", "to": "GBP", "amount": 200, "converted": 172.0,    "rate": 0.86,    "timestamp": "..." }
]

GET/mcp/rate/history取得某貨幣對的歷史匯率

取得某貨幣對的歷史匯率

參數

名稱	必填	說明
`from`	必填	來源貨幣代碼
`to`	必填	目標貨幣代碼
`startDate`	必填	開始日期 (ISO 8601，例如 2026-04-01)
`endDate`	必填	結束日期 (ISO 8601，例如 2026-04-30)

請求範例

bash

curl "https://agentic.bananacrystal.com/mcp/rate/history?from=USD&to=NGN&startDate=2026-04-01&endDate=2026-04-30" \
  -H "x-api-key: bc_live_your_rate_key_here"

回應範例

json

[
  { "date": "2026-04-01T00:00:00.000Z", "from": "USD", "to": "NGN", "buyRate": 1580.0, "sellRate": 1575.0, "midRate": 1577.5 },
  { "date": "2026-04-02T00:00:00.000Z", "from": "USD", "to": "NGN", "buyRate": 1582.0, "sellRate": 1577.0, "midRate": 1579.5 }
]

GET/mcp/rate/stats取得一段期間的匯率統計 (最高、最低、平均、最新)

取得一段期間的匯率統計 (最高、最低、平均、最新)

參數

名稱	必填	說明
`from`	必填	來源貨幣代碼
`to`	必填	目標貨幣代碼
`days`	選填	期間天數，1 至 365 (預設：30)

請求範例

bash

curl "https://agentic.bananacrystal.com/mcp/rate/stats?from=USD&to=NGN&days=30" \
  -H "x-api-key: bc_live_your_rate_key_here"

回應範例

json

{
  "from": "USD",
  "to": "NGN",
  "period": "30d",
  "high": 1598.0,
  "low": 1560.0,
  "avg": 1581.4,
  "latest": 1584.75,
  "count": 30
}

沙盒匯率 API

將 /mcp/rate/ 替換為 /mcp/sandbox/rate/，並使用您的沙盒金鑰取得固定的模擬匯率。歷史資料以 ±2% 的變動產生，以模擬真實測試情境。不使用任何真實匯率資料。

沙盒環境

使用預先存入的餘額安全測試您的整合，不涉及真實資金。

什麼是沙盒？

沙盒是完全隔離的測試環境，與正式環境完全一致，包括相同的工具、相同的 API 與相同的回應格式。不會移動任何真實資金。沙盒 API 金鑰以 bc_test_ 開頭，並連接至 Hedera 測試網。

預先存入的餘額

每個沙盒帳戶都從這些餘額開始。隨時可使用 reset_sandbox_balance 恢復。

代幣	金額	貨幣
`USDb`	10,000	USD
`NGNb`	5,000,000	NGN
`GHSb`	50,000	GHS
`KESb`	1,000,000	KES
`ZARb`	150,000	ZAR

沙盒與正式環境比較

功能	沙盒	正式環境
實際資金流動	否：僅模擬	是
OTP 驗證	於 API 回應中傳回	寄送至您的電子郵件
法幣需要 KYC	否	是
強制執行支出上限	是 (可設定)	是
API 金鑰前綴	bc_test_...	bc_live_...
Hedera 結算	測試網	主網
預先存入的餘額	是 (可隨時重設)	否
速率限制	寬鬆	依方案而定

沙盒中的 OTP

在沙盒模式中，OTP 驗證碼會直接在 request_transfer_otp 的 API 回應中傳回，而不是寄送電子郵件。這讓自動化測試不需存取電子郵件也能輕鬆進行。

沙盒設定

claude_desktop_config.json

json

{
  "mcpServers": {
    "bananacrystal": {
      "command": "bananacrystal-mcp",
      "env": {
        "BANANACRYSTAL_API_KEY": "bc_test_your_sandbox_key_here",
        "BANANACRYSTAL_API_URL": "https://agentic.bananacrystal.com/mcp/sandbox"
      }
    }
  }
}

設定

將 BananaCrystal 連接至您偏好的 AI 工具或框架。

claude_desktop_config.json

json

{
  "mcpServers": {
    "bananacrystal": {
      "command": "bananacrystal-mcp",
      "env": {
        "BANANACRYSTAL_API_KEY": "your_api_key_here"
      }
    }
  }
}

環境變數

BANANACRYSTAL_API_KEY必填

您的 MCP API 金鑰。沙盒金鑰以 bc_test_ 開頭，正式金鑰以 bc_live_ 開頭。

預設： N/A

BANANACRYSTAL_API_URL選填

覆寫 MCP 端點 URL。測試時請使用沙盒 URL。

預設： https://agentic.bananacrystal.com/mcp

DEBUG選填

設為 true 以啟用詳細的請求/回應日誌。

預設： false

變數	必填	預設值	說明
`BANANACRYSTAL_API_KEY`	必填	`N/A`	您的 MCP API 金鑰。沙盒金鑰以 bc_test_ 開頭，正式金鑰以 bc_live_ 開頭。
`BANANACRYSTAL_API_URL`	選填	`https://agentic.bananacrystal.com/mcp`	覆寫 MCP 端點 URL。測試時請使用沙盒 URL。
`DEBUG`	選填	`false`	設為 true 以啟用詳細的請求/回應日誌。

框架整合

適用於最熱門 AI 代理框架、可直接執行的範例。

langchain_agent.py

python

import asyncio
from langchain_mcp_adapters.client import MultiServerMCPClient
from langchain.agents import create_tool_calling_agent, AgentExecutor
from langchain_anthropic import ChatAnthropic
from langchain_core.prompts import ChatPromptTemplate

async def main():
    # Connect to BananaCrystal MCP server
    client = MultiServerMCPClient({
        "bananacrystal": {
            "url": "https://agentic.bananacrystal.com/mcp",
            "transport": "streamable_http",
            "headers": {
                "Authorization": "Bearer your_api_key_here"
            }
        }
    })

    # Get all 40 payment tools
    tools = await client.get_tools()

    # Create an agent with payment capabilities
    llm = ChatAnthropic(model="claude-3-5-sonnet-20241022")
    prompt = ChatPromptTemplate.from_messages([
        ("system", "You are a payment agent. Use the BananaCrystal tools to help users manage their finances."),
        ("human", "{input}"),
        ("placeholder", "{agent_scratchpad}"),
    ])

    agent = create_tool_calling_agent(llm, tools, prompt)
    executor = AgentExecutor(agent=agent, tools=tools, verbose=True)

    # Run the agent
    result = await executor.ainvoke({
        "input": "What is my current USDb balance?"
    })
    print(result["output"])

asyncio.run(main())

任何相容 MCP 的框架都能使用。如果您的框架支援以 HTTP 為基礎的 MCP 伺服器，請將其指向 https://agentic.bananacrystal.com/mcp，並以您的 API 金鑰作為 Bearer 權杖。

安全架構

多層保護，確保您的代理只能執行您明確授權的動作。

API 金鑰權限範圍

每組 API 金鑰都有明確的權限範圍。代理只能在您授予的範圍內執行操作。

支出上限

為每組 API 金鑰設定嚴格的單筆交易上限與 24 小時滾動每日上限。這些限制在基礎設施層級強制執行。

OTP 驗證

每筆代幣轉帳都需要寄送到您註冊電子郵件的 6 位數 OTP。沒有您提供的驗證碼，代理就無法完成轉帳。

速率限制

依金鑰設定的每分鐘速率上限，可防止失控的代理大量呼叫 API。限制會隨您的方案等級調整。

不可竄改的稽核紀錄

每次工具呼叫都會寫入 Hedera 的共識層。紀錄附有時間戳記、防竄改，且可在鏈上公開驗證。可透過 get_transaction_history 取得完整稽核紀錄。

代理核准流程

代理對代理交易可設定為執行前需經人工電子郵件核准。請使用 update_my_agent_settings 設定 require_human_approval。

API 金鑰權限範圍

read_only

查詢餘額、匯率、紀錄與限額，不移動任何資金

transfer

傳送代幣至其他帳戶 (需 OTP)

swap

在貨幣穩定幣之間兌換

fiat

法幣存款與提領 (需完成 KYC)

offers

建立並管理預測市場報價與交易

rate

存取貨幣匯率、歷史資料、換算與匯率統計

權限範圍	允許的操作
read_only	查詢餘額、匯率、紀錄與限額，不移動任何資金
transfer	傳送代幣至其他帳戶 (需 OTP)
swap	在貨幣穩定幣之間兌換
fiat	法幣存款與提領 (需完成 KYC)
offers	建立並管理預測市場報價與交易
rate	存取貨幣匯率、歷史資料、換算與匯率統計

價格

唯讀操作永久免費。只需為移動價值的交易付費。

操作手續費

唯讀操作

get_balances, get_exchange_rate, list_trades, …

免費

代幣轉帳

transfer_tokens

0.3%

貨幣兌換

swap_currency

0.5%

法幣存款

initiate_deposit

依通道而定

法幣提領

request_withdrawal

依通道而定

預測市場

create_offer, engage_offer

結算時收取平台費

操作	工具	手續費
唯讀操作	get_balances, get_exchange_rate, list_trades, …	免費
代幣轉帳	transfer_tokens	0.3%
貨幣兌換	swap_currency	0.5%
法幣存款	initiate_deposit	依通道而定
法幣提領	request_withdrawal	依通道而定
預測市場	create_offer, engage_offer	結算時收取平台費