What is BananaCrystal?

BananaCrystal is agent payment infrastructure — a payment layer built specifically for AI agents. It exposes a Model Context Protocol (MCP) server that gives any AI agent 40 production-ready payment tools across read, transfer, swap, fiat, and offers categories — all settled on the Hedera blockchain in under 5 seconds.

What is MCP and why does it matter for AI agents?

MCP (Model Context Protocol) is an open standard created by Anthropic and adopted by OpenAI, Google, and the Linux Foundation. It lets AI agents discover and call external tools — like payment APIs — without custom integration code. BananaCrystal exposes a single MCP endpoint at agentic.bananacrystal.com/mcp. Any MCP-compatible agent connects with one config line and immediately sees all 40 payment tools.

Which AI frameworks work with BananaCrystal MCP?

Any framework that supports MCP works out of the box: Claude (Anthropic), ChatGPT and the OpenAI Responses API, LangChain via langchain-mcp-adapters, AutoGPT, CrewAI, Cursor, Windsurf, and any custom agent built on the MCP SDK.

Can an AI agent move money without my permission?

No. Every API key has explicit permission scopes — read_only, transfer, swap, fiat, offers, or rate. An agent can only perform operations within the scopes you grant. Every transfer also requires a 6-digit OTP sent to your registered email. The agent cannot complete a transfer without you providing that code.

What happens if an AI agent tries to send the same payment twice?

Nothing. Every write operation is protected by idempotency keys stored in Redis. If an agent retries a request — which is common when agents encounter timeouts — the duplicate is detected and rejected automatically. No double-spends, ever.

How do I limit how much an AI agent can spend?

Each API key has configurable per-transaction limits and rolling 24-hour spending caps. You set the ceiling when you create the key. The agent cannot exceed those limits regardless of what instructions it receives.

What tools does the BananaCrystal MCP server expose?

Forty production-ready tools across six scopes: Read, Transfer, Swap, Fiat, Offers, and Rate. All tools are live and guarded by the full security stack.

How is every agent action audited?

Every MCP tool call — read or write — is written to a dedicated topic on the Hedera consensus layer. Entries are timestamped, immutable, and publicly verifiable on-chain. You get a tamper-proof audit trail of everything your agent did, forever.

How fast are transactions?

Transactions settle in under 5 seconds. This includes transfers, swaps, and withdrawals — dramatically faster than traditional banking and most other blockchains. Hedera Hashgraph achieves absolute finality — transactions cannot be reversed or reorganised.

What currencies does BananaCrystal support?

BananaCrystal supports 150+ currencies across Africa, Asia, Europe, the Americas, and Oceania. Major stablecoins include USDb (USD), EURb (EUR), GBPb (GBP), CADb (CAD), NGNb (NGN), GHSb (GHS), and many more.

What are BananaCrystal stablecoins?

BananaCrystal creates digital stablecoins like USDb, EURb, NGNb, and GBPb that are backed 1:1 by real fiat currency reserves. They are stable digital versions of traditional currencies — no volatility, no speculation, just the convenience of blockchain with the stability of fiat.

What is the difference between USDb and USDC?

USDC is the standard USD stablecoin used to fund your account. USDb is the native platform token — also pegged 1:1 to USD — used within the BananaCrystal ecosystem to swap into other local currency stablecoins. Think of USDC as the on-ramp and USDb as the trading currency.

Can multiple AI agents share one API key?

Technically yes, but one key per agent is recommended for production. Separate keys give you granular spending limits, independent audit trails, and the ability to revoke a single agent's access without affecting others.

What does the OTP flow look like from an agent's perspective?

When an agent calls transfer_tokens, the MCP server first calls the OTP endpoint and returns a transactionRef. The agent surfaces a message to the user asking for the 6-digit code sent to their email. The user provides the code, the agent retries with it, and the transfer executes. The agent cannot bypass this step — it is enforced at the API level.

Is there a rate limit on how many requests an agent can make?

Yes. Each API key has per-minute and per-day request caps enforced in Redis. This prevents runaway agents from hammering the API or racking up unexpected costs. Limits are configurable per key from the dashboard.

Yes. Every stablecoin is backed 1:1 by real currency reserves. OTP verification is required on every transfer. Per-key spending limits prevent agents from exceeding authorised amounts. Every operation is logged to an immutable audit trail on Hedera. AI agents can only move funds within the permission scopes you explicitly grant.

How do I get started with BananaCrystal?

Sign up at agents.bananacrystal.com — free, no credit card required. Your wallet is created instantly. Generate an API key from your dashboard, point your agent at agentic.bananacrystal.com/mcp, and your agent auto-discovers all 40 payment tools.

BananaCrystal MCP Documentation | 40 Payment Tools for AI Agents

Quick Start

Get your AI agent making payments in under 5 minutes.

Install the MCP server

Install the BananaCrystal MCP server globally via npm.

bash

npm install -g @bananacrystal/mcp-server

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.

claude_desktop_config.json

json

{
  "mcpServers": {
    "bananacrystal": {
      "command": "bananacrystal-mcp",
      "env": {
        "BANANACRYSTAL_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-only24 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_deposit_status

read_onlyfree

Get the status of a fiat deposit by transfer ID

get_withdrawal_status

read_onlyfree

Get withdrawal requests for a user via Brale

get_escrow_balances

read_onlyfree

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

get_escrow_history

read_onlyfree

Get full escrow transaction history — locks, releases, wins, losses

list_offers

read_onlyfree

Browse the prediction market — 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 — 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 — rate and fees calculated automatically

Fiat3 tools

initiate_kyc

fiat

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

initiate_deposit

fiat

Initiate a fiat deposit via Brale (KYC required)

request_withdrawal

fiat

Request a fiat withdrawal via Brale (KYC required)

Offers & Trades6 tools

create_offer

offers

Create a prediction market offer — locks totalAmount 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 (trade against) an open offer — locks 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/currenciesList all supported currencies

List all supported currencies

Example request

bash

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

Example response

json

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

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

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

bash

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

Example response

json

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

GET/mcp/rate/convertConvert an amount from one currency to another

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

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"

Example response

json

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

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

Convert multiple currency amounts in one request (max 100)

Example request

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 }
    ]
  }'

Example response

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/historyFetch historical exchange rates for a currency pair

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

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"

Example response

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/statsGet rate statistics (high, low, avg, latest) over a period

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–365 (default: 30)

Example request

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"

Example response

json

{
  "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 — same tools, same API, 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_...	bc_live_...
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 — no email is sent. This makes automated testing easy without needing email access.

Sandbox configuration

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

Configuration

Connect BananaCrystal to your preferred AI tool or framework.

claude_desktop_config.json

json

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

Environment variables

BANANACRYSTAL_API_KEYrequired

Your MCP API key. Sandbox keys start with bc_test_, live keys with bc_live_.

Default: —

BANANACRYSTAL_API_URLoptional

Override the MCP endpoint URL. Use the sandbox URL for testing.

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

DEBUGoptional

Set to true to enable verbose request/response logging.

Default: false

Variable	Required	Default	Description
`BANANACRYSTAL_API_KEY`	required	`—`	Your MCP API key. Sandbox keys start with bc_test_, live keys with bc_live_.
`BANANACRYSTAL_API_URL`	optional	`https://agentic.bananacrystal.com/mcp`	Override the MCP endpoint URL. Use the sandbox URL for testing.
`DEBUG`	optional	`false`	Set to true to enable verbose request/response logging.

Framework Integrations

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

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

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 — nothing more.

Spending Limits

Set hard per-transaction maximums and rolling 24-hour daily caps per API key. Enforced at the infrastructure level — no agent can exceed what you configure.

OTP Verification

Every token transfer requires a 6-digit OTP sent to your registered email. The agent cannot complete a transfer without you providing that code.

Rate Limiting

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

Immutable Audit Trail

Every tool call is written to Hedera's consensus layer — timestamped, tamper-proof, and publicly verifiable on-chain. Full audit history available via get_transaction_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

read_only

Check balances, rates, history, limits — no funds move

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

Scope	What it allows
read_only	Check balances, rates, history, limits — no funds move
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

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

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