BananaCrystal

Give your AI agent a wallet: live FX rates, swaps and payments in 140+ local currencies.

Hosted MCP Server

npx add-mcp 'https://agentic.bananacrystal.com/mcp'

Installs into Claude Code, Codex, Cursor and more

Documentation

Quick Start

Get your AI agent making payments in under 5 minutes.

Get your API key

Create an MCP API key from your account dashboard. Sandbox keys start with bc_test_ and are free.

Get API Key

Sandbox keys: bc_test_...

Configure Claude Desktop

Add BananaCrystal to your Claude Desktop config file.

{
  "mcpServers": {
    "bananacrystal": {
      "url": "https://agentic.bananacrystal.com/mcp",
      "headers": {
        "x-api-key": "bc_test_your_sandbox_key_here"
      }
    }
  }
}

Ask your agent

Your agent now has 40 payment tools. Try these prompts:

›"What's my current USDb balance?"

›"Send 50 USDb to 0.0.654321"

›"Swap 100 USDb to NGNb at the current rate"

›"Show me my last 10 transactions"

›"What's the current USD to NGN exchange rate?"

MCP Tools

40 production-ready payment tools across 6 categories. Read-only operations are always free.

Read-only22 tools

ping

read_onlyfree

Health check: returns pong

get_server_info

read_onlyfree

Returns basic server information

echo

read_onlyfree

Echoes the input message back to the caller

get_my_profile

read_onlyfree

Get the full profile of the authenticated user

get_balances

read_onlyfree

Get Hedera account balance for all platform tokens or a specific token

get_exchange_rate

read_onlyfree

Get live buy/sell exchange rates for a currency

list_supported_currencies

read_onlyfree

List all supported currencies with their dynamic fees

list_available_tokens

read_onlyfree

List all available Hedera tokens for the platform

get_transaction_history

read_onlyfree

Get categorized transaction history with filters

get_my_limits

read_onlyfree

Get configured limits and live usage for the authenticated API key

estimate_swap_fees

read_onlyfree

Estimate fees for a currency swap before executing

get_agent_config

read_onlyfree

Look up another user's agent configuration

check_approval_status

read_onlyfree

Check the status of a pending agent transaction approval request

get_kyc_status

read_onlyfree

Get KYC verification status for a user via Sumsub

get_escrow_balances

read_onlyfree

Get escrow balance breakdown: total, available, and locked amounts

get_escrow_history

read_onlyfree

Get full escrow transaction history including locks, releases, wins, and losses

list_offers

read_onlyfree

Browse the prediction market for active offers with trade stats

get_offer

read_onlyfree

Get full details of a single offer including trade stats

get_my_offers

read_onlyfree

Get all offers created by a specific user

list_trades

read_onlyfree

List all trades on the platform with filters

get_trade

read_onlyfree

Get full details of a single trade including parent offer stats

get_my_trades

read_onlyfree

Get all trades for a user, including created and received

Transfer2 tools

request_transfer_otp

transfer0.3%

Step 1: Request an OTP verification code sent to the sender's email

transfer_tokens

transfer0.3%

Step 2: Execute the token transfer with OTP verification

Swap1 tool

swap_currency

swap0.5%

Swap between two Hedera tokens with the rate and fees calculated automatically

Fiat1 tool

initiate_kyc

fiat

Initiate KYC verification: returns a Sumsub access token for the SDK

Offers & Trades6 tools

create_offer

offers

Create a prediction market offer that locks the total amount in escrow

update_offer

offers

Edit an existing offer (only when no trades exist)

delist_offer

offers

Delist your offer from the marketplace and release locked escrow

delete_offer

offers

Permanently delete your offer (blocked if active trades exist)

engage_offer

offers

Engage with an open offer by locking matching escrow

cancel_trade

offers

Cancel an active trade and release your locked escrow

Agent-to-Agent3 tools

request_agent_transaction

transfer

Request a transaction on behalf of another user's agent (requires email approval)

execute_approved_transaction

transfer

Execute a previously approved agent transaction using the execution token

update_my_agent_settings

read_onlyfree

Control whether agent-to-agent transactions require email approval and OTP

Sandbox-only1 tool

reset_sandbox_balance

read_onlyfree

Reset sandbox balances to pre-seeded defaults (sandbox only)

Rate API

Advanced currency rate operations via REST. Requires a rate-scoped API key.

MCP tool vs Rate API: what's the difference?

The MCP server already includes get_exchange_rate as a read_only tool: your agent can call it directly to get the buy/sell rate for a single currency against USD. That covers most agent use cases.

The Rate API goes further: cross-pair conversions, bulk batch operations, historical time-series data, and statistical summaries. These are available as direct HTTP endpoints authenticated with a rate-scoped API key. Create a rate key from your account dashboard.

Authentication

All Rate API endpoints require a rate-scoped API key passed as the x-api-key header. The sandbox equivalents are available at /mcp/sandbox/rate/* and use your sandbox key (bc_test_...) with fixed mock rates for reproducible testing.

Base URL

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

GET /mcp/rate/currencies List all supported currencies

Example request

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

Example response

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

GET /mcp/rate/current Get current exchange rate between two currencies

Parameters

Name	Required	Description
`from`	required	Source currency code (e.g. USD)
`to`	required	Target currency code (e.g. NGN)

Example request

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

Example response

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

GET /mcp/rate/convert Convert an amount from one currency to another

Parameters

Name	Required	Description
`from`	required	Source currency code
`to`	required	Target currency code
`amount`	required	Amount to convert (number)

Example request

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

Example response

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

POST /mcp/rate/batch-convert Convert multiple currency amounts in one request (max 100)

Example request

curl -X POST "https://agentic.bananacrystal.com/mcp/rate/batch-convert" \
  -H "x-api-key: your_api_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 }
    ]
  }'

Example response

[
  { "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 Fetch historical exchange rates for a currency pair

Parameters

Name	Required	Description
`from`	required	Source currency code
`to`	required	Target currency code
`startDate`	required	Start date (ISO 8601, e.g. 2026-04-01)
`endDate`	required	End date (ISO 8601, e.g. 2026-04-30)

Example request

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

Example response

[
  { "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 Get rate statistics (high, low, avg, latest) over a period

Parameters

Name	Required	Description
`from`	required	Source currency code
`to`	required	Target currency code
`days`	optional	Period in days, 1 to 365 (default: 30)

Example request

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

Example response

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

Sandbox Rate API

Replace /mcp/rate/ with /mcp/sandbox/rate/ and use your sandbox key to get fixed mock rates. Historical data is generated with ±2% variation for realistic testing. No real exchange data is used.

Sandbox Environment

Test your integration safely with pre-seeded balances and no real money.

What is the sandbox?

The sandbox is a fully isolated test environment that mirrors production exactly, including the same tools, the same API, and the same response format. No real money moves. Sandbox API keys start with bc_test_ and connect to the Hedera testnet.

Pre-seeded balances

Every sandbox account starts with these balances. Use reset_sandbox_balance to restore them at any time.

Token	Amount	Currency
`USDb`	10,000	USD
`NGNb`	5,000,000	NGN
`GHSb`	50,000	GHS
`KESb`	1,000,000	KES
`ZARb`	150,000	ZAR

Sandbox vs Live

Feature	Sandbox	Live
Real money moves	No: simulated only	Yes
OTP verification	Returned in API response	Sent to your email
KYC required for fiat	No	Yes
Spending limits enforced	Yes (configurable)	Yes
API key prefix	bc_test_...	3f9a1c...
Hedera settlement	Testnet	Mainnet
Pre-seeded balances	Yes (reset anytime)	No
Rate limits	Relaxed	Per-plan

OTP in sandbox

In sandbox mode, the OTP code is returned directly in the request_transfer_otp API response instead of being sent via email. This makes automated testing easy without needing email access.

Sandbox configuration

{
  "mcpServers": {
    "bananacrystal": {
      "url": "https://agentic.bananacrystal.com/mcp/sandbox",
      "headers": {
        "x-api-key": "bc_test_your_sandbox_key_here"
      }
    }
  }
}

Configuration

Connect BananaCrystal to your preferred AI tool or framework.

{
  "mcpServers": {
    "bananacrystal": {
      "url": "https://agentic.bananacrystal.com/mcp",
      "headers": {
        "x-api-key": "your_api_key_here"
      }
    }
  }
}

Framework Integrations

Ready-to-run examples for the most popular AI agent frameworks.

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())

Any MCP-compatible framework works. If your framework supports HTTP-based MCP servers, point it at https://agentic.bananacrystal.com/mcp with your API key as a Bearer token.

Security Architecture

Multiple layers of protection so your agent can only do what you explicitly authorize.

API Key Scopes

Each API key has explicit permission scopes. An agent can only perform operations within the scopes you grant.

Spending Limits

Set hard per-transaction maximums and rolling 24-hour daily caps per API key. These are enforced at the infrastructure level.

OTP Verification

Transfers need a 6-digit code sent to your registered email, on by default. The agent can't finish a transfer without that code.

Rate Limiting

Per-key, per-minute rate caps prevent runaway agents from hammering the API. Limits scale with your plan tier.

Activity history

Every tool call is logged and available in your account history.

Agent Approval Flow

Agent-to-agent transactions can require human email approval before execution. Use update_my_agent_settings to configure require_human_approval.

API Key Scopes

Scope	What it allows
read_only	Check balances, rates, history, and limits without moving any funds
transfer	Send tokens to other accounts (requires OTP)
swap	Swap between currency stablecoins
fiat	Fiat deposits and withdrawals (requires KYC)
offers	Create and manage prediction market offers and trades
rate	Access currency exchange rates, historical data, conversions, and rate statistics

Pricing

Read-only operations are always free. Pay only for transactions that move value.

Operation fees

Operation	Tools	Fee
Read-only operations	get_balances, get_exchange_rate, list_trades, …	Free
Token transfers	transfer_tokens	0.3%
Currency swaps	swap_currency	0.5%
Fiat deposits	initiate_deposit	Varies by rail
Fiat withdrawals	request_withdrawal	Varies by rail
Prediction market	create_offer, engage_offer	Platform fee on settlement

Plans

Free

$0read-only operations

All read-only tools are always free. No account is needed to check rates or balances.

All read-only tools free forever
Sandbox environment included
get_balances, get_exchange_rate, and 22 more
Community support
Hedera testnet settlement Get API Key

Pay-per-use

Usage-basedno monthly fee

Scale as you grow. Only pay for what you use.

Unlimited API calls
0.3% on transfers
0.5% on swaps
Fiat rails (varies by method)
Email + priority support
Hedera mainnet settlement
Full activity history Get API key

Enterprise

Customcontact us

Volume discounts, SLAs, and dedicated infrastructure.

Custom fee tiers
Dedicated MCP endpoint
SLA guarantees
Custom spending limits
Dedicated support
On-premise option Contact sales

FAQ

Common questions about BananaCrystal and the MCP server.

What is the BananaCrystal MCP server?

How do I connect it to Claude Desktop, Cursor or ChatGPT?

Does it cost anything to try?

What does a transfer cost?

How do you stop an agent from draining my wallet?

Which currencies are supported?

Is BananaCrystal regulated?

Can I self-host it?

How do I report a security issue?

What error codes does the API return?

What are the rate limits per plan?

How it compares

	BananaCrystal MCP	Card API	Bank transfer
Setup	5 minutes, one URL	Days, merchant account	Days, KYB
Cost to send	0.3%	2.9% + $0.30	$15 to $45 wire
Settles	Under 5 seconds	2 to 3 days	1 to 5 days
Currencies	140+ local	Card currencies	Per bank
Agent limits	Built in, server-side	None	None

Ready to give your agent a wallet?

Create your API key and connect your agent to 40 payment tools in under 5 minutes. Read-only tools are always free.

Get API Key