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ドキュメント | AIエージェント向けの40の決済ツール

クイックスタート

5分以内にAIエージェントが決済を行えるようになります。

MCPサーバーをインストール

npmでBananaCrystal MCPサーバーをグローバルにインストールします。

bash

npm install -g @bananacrystal/mcp-server

APIキーを取得

アカウントダッシュボードでMCP APIキーを作成します。サンドボックスキーは bc_test_ で始まり、無料です。

APIキーを取得

サンドボックスキー： bc_test_...

Claude Desktopを設定

Claude Desktopの設定ファイルにBananaCrystalを追加します。

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無料

取引統計を含む、1件のオファーの詳細を取得します

get_my_offers

read_only無料

特定のユーザーが作成したすべてのオファーを取得します

list_trades

read_only無料

フィルター付きで、プラットフォーム上のすべての取引を一覧表示します

get_trade

read_only無料

親オファーの統計を含む、1件の取引の詳細を取得します

get_my_trades

read_only無料

作成したものと受けたものを含む、ユーザーのすべての取引を取得します

送金2 ツール

request_transfer_otp

transfer0.3%

ステップ1：送金者のメールに送信されるOTP認証コードをリクエストします

transfer_tokens

transfer0.3%

ステップ2：OTP認証付きでトークン送金を実行します

スワップ1 ツール

swap_currency

swap0.5%

2つの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無料

サンドボックスの残高を事前投入された初期値にリセットします（サンドボックスのみ）

Rate API

RESTによる高度な為替レート操作です。rateスコープのAPIキーが必要です。

MCPツールとRate APIの違いは？

MCPサーバーには、read_only ツールとして get_exchange_rate がすでに含まれています。エージェントはこれを直接呼び出して、1つの通貨のUSDに対する買値/売値のレートを取得できます。エージェントのほとんどのユースケースはこれで対応できます。

Rate APIはさらに多くの機能を提供します：クロスペアの換算、一括処理、過去の時系列データ、統計の要約。これらは rate スコープのAPIキーで認証する直接のHTTPエンドポイントとして利用できます。rateキーはアカウントダッシュボードで作成してください。

認証

すべてのRate 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/current2つの通貨間の現在の為替レートを取得

2つの通貨間の現在の為替レートを取得

パラメーター

名前	必須	説明
`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-convert1回のリクエストで複数の通貨金額を換算（最大100件）

1回のリクエストで複数の通貨金額を換算（最大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
}

サンドボックスRate API

/mcp/rate/ を /mcp/sandbox/rate/ に置き換え、サンドボックスキーを使用すると固定のモックレートを取得できます。過去データは現実的なテストのために ±2% の変動で生成されます。実際の為替データは使用されません。

サンドボックス環境

事前投入された残高を使い、実際のお金を使わずに安全に統合をテストできます。

サンドボックスとは？

サンドボックスは、本番環境を正確に再現した完全に分離されたテスト環境です。同じツール、同じAPI、同じレスポンス形式を備えています。実際のお金は動きません。サンドボックスAPIキーは bc_test_ で始まり、Hedera testnetに接続します。

事前投入済みの残高

すべてのサンドボックスアカウントは次の残高から始まります。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での決済	Testnet	Mainnet
事前投入済みの残高	あり（いつでもリセット可能）	なし
レート制限	緩和	プランごと

サンドボックスでの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"
      }
    }
  }
}

設定

お好みのAIツールやフレームワークにBananaCrystalを接続します。

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サーバーに対応していれば、APIキーをBearerトークンとして指定し、接続先を https://agentic.bananacrystal.com/mcp に設定してください。

セキュリティアーキテクチャ

複数の防御層により、エージェントはあなたが明示的に許可したことしか実行できません。

APIキーのスコープ

各APIキーには明示的な権限スコープがあります。エージェントは許可されたスコープ内の操作しか実行できません。

支出上限

APIキーごとに、取引ごとの厳格な上限と24時間ローリングの1日の上限を設定できます。これらはインフラのレベルで適用されます。

OTP認証

すべてのトークン送金には、登録メールアドレスに送信される6桁のOTPが必要です。あなたがそのコードを提供しない限り、エージェントは送金を完了できません。

レート制限

キーごと、1分ごとのレート上限により、暴走したエージェントがAPIに過剰な負荷をかけるのを防ぎます。上限はプランの階層に応じて変わります。

変更できない監査証跡

すべてのツール呼び出しはHederaのコンセンサスレイヤーに記録されます。タイムスタンプ付きで改ざんできず、オンチェーンで誰でも検証できます。完全な監査履歴は get_transaction_history で取得できます。

エージェント承認フロー

エージェント間取引では、実行前に人間によるメール承認を必須にできます。require_human_approval の設定には update_my_agent_settings を使用してください。

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	決済時にプラットフォーム手数料