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 Documentation | 40 Payment Tool para sa mga AI Agent

Quick Start

Pabayarin ang iyong AI agent sa loob ng 5 minuto.

I-install ang MCP server

I-install ang BananaCrystal MCP server nang global gamit ang npm.

bash

npm install -g @bananacrystal/mcp-server

Kunin ang iyong API key

Gumawa ng MCP API key mula sa iyong account dashboard. Nagsisimula sa bc_test_ ang mga sandbox key at libre ang mga ito.

Kumuha ng API Key

Mga sandbox key: bc_test_...

I-configure ang Claude Desktop

Idagdag ang BananaCrystal sa config file ng iyong Claude Desktop.

claude_desktop_config.json

json

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

Tanungin ang iyong agent

May 40 payment tool na ngayon ang iyong agent. Subukan ang mga prompt na ito:

›"Magkano ang kasalukuyang USDb balance ko?"

›"Magpadala ng 50 USDb sa 0.0.654321"

›"I-swap ang 100 USDb sa NGNb sa kasalukuyang rate"

›"Ipakita ang huling 10 transaksyon ko"

›"Ano ang kasalukuyang exchange rate ng USD sa NGN?"

MCP Tools

40 production-ready na payment tool sa 6 na kategorya. Laging libre ang mga read-only operation.

Read-only24 tool

ping

read_onlylibre

Health check: nagbabalik ng pong

get_server_info

read_onlylibre

Nagbabalik ng basic na impormasyon ng server

echo

read_onlylibre

Ibinabalik sa tumawag ang input message

get_my_profile

read_onlylibre

Kunin ang buong profile ng authenticated na user

get_balances

read_onlylibre

Kunin ang Hedera account balance para sa lahat ng platform token o sa isang partikular na token

get_exchange_rate

read_onlylibre

Kunin ang live na buy/sell exchange rate ng isang currency

list_supported_currencies

read_onlylibre

Ilista ang lahat ng suportadong currency kasama ang kanilang dynamic fee

list_available_tokens

read_onlylibre

Ilista ang lahat ng available na Hedera token para sa platform

get_transaction_history

read_onlylibre

Kunin ang naka-kategoryang history ng transaksyon gamit ang mga filter

get_my_limits

read_onlylibre

Kunin ang naka-configure na limit at live na paggamit ng authenticated na API key

estimate_swap_fees

read_onlylibre

Tantiyahin ang fee ng isang currency swap bago ito i-execute

get_agent_config

read_onlylibre

Tingnan ang agent configuration ng ibang user

check_approval_status

read_onlylibre

I-check ang status ng isang pending na agent transaction approval request

get_kyc_status

read_onlylibre

Kunin ang KYC verification status ng isang user gamit ang Sumsub

get_deposit_status

read_onlylibre

Kunin ang status ng isang fiat deposit gamit ang transfer ID

get_withdrawal_status

read_onlylibre

Kunin ang mga withdrawal request ng isang user gamit ang Brale

get_escrow_balances

read_onlylibre

Kunin ang breakdown ng escrow balance: kabuuan, available, at naka-lock na halaga

get_escrow_history

read_onlylibre

Kunin ang buong history ng escrow transaction kasama ang mga lock, release, panalo, at talo

list_offers

read_onlylibre

Tingnan ang mga active na offer sa prediction market kasama ang trade stats

get_offer

read_onlylibre

Kunin ang buong detalye ng isang offer kasama ang trade stats

get_my_offers

read_onlylibre

Kunin ang lahat ng offer na ginawa ng isang partikular na user

list_trades

read_onlylibre

Ilista ang lahat ng trade sa platform gamit ang mga filter

get_trade

read_onlylibre

Kunin ang buong detalye ng isang trade kasama ang stats ng parent offer

get_my_trades

read_onlylibre

Kunin ang lahat ng trade ng isang user, kasama ang ginawa at natanggap

Transfer2 tool

request_transfer_otp

transfer0.3%

Hakbang 1: Humingi ng OTP verification code na ipapadala sa email ng sender

transfer_tokens

transfer0.3%

Hakbang 2: I-execute ang token transfer gamit ang OTP verification

Swap1 tool

swap_currency

swap0.5%

Mag-swap sa pagitan ng dalawang Hedera token, awtomatikong kinukwenta ang rate at fee

Fiat3 tool

initiate_kyc

fiat

Simulan ang KYC verification: nagbabalik ng Sumsub access token para sa SDK

initiate_deposit

fiat

Magsimula ng fiat deposit gamit ang Brale (kailangan ng KYC)

request_withdrawal

fiat

Humingi ng fiat withdrawal gamit ang Brale (kailangan ng KYC)

Offers at Trades6 tool

create_offer

offers

Gumawa ng prediction market offer na nagla-lock ng kabuuang halaga sa escrow

update_offer

offers

I-edit ang isang existing na offer (kapag wala pang trade lang)

delist_offer

offers

Alisin ang iyong offer sa marketplace at i-release ang naka-lock na escrow

delete_offer

offers

Permanenteng i-delete ang iyong offer (hindi puwede kung may active na trade)

engage_offer

offers

Sumali sa isang bukas na offer sa pag-lock ng katumbas na escrow

cancel_trade

offers

Kanselahin ang isang active na trade at i-release ang iyong naka-lock na escrow

Agent-to-Agent3 tool

request_agent_transaction

transfer

Humingi ng transaksyon para sa agent ng ibang user (kailangan ng email approval)

execute_approved_transaction

transfer

I-execute ang naaprubahang agent transaction gamit ang execution token

update_my_agent_settings

read_onlylibre

Kontrolin kung kailangan ng email approval at OTP ang mga agent-to-agent na transaksyon

Sandbox lang1 tool

reset_sandbox_balance

read_onlylibre

I-reset ang sandbox balance sa pre-seeded na default (sandbox lang)

Rate API

Mga advanced na operasyon sa currency rate gamit ang REST. Kailangan ng rate-scoped na API key.

MCP tool kumpara sa Rate API: ano ang pagkakaiba?

Kasama na sa MCP server ang get_exchange_rate bilang read_only tool: direkta itong matatawag ng iyong agent para makuha ang buy/sell rate ng isang currency laban sa USD. Sapat na iyan para sa karamihan ng use case ng agent.

Mas malawak ang Rate API: cross-pair conversion, bulk batch operation, historical time-series data, at statistical summary. Available ang mga ito bilang direktang HTTP endpoint na naka-authenticate gamit ang rate-scoped na API key. Gumawa ng rate key mula sa iyong account dashboard.

Authentication

Kailangan ng lahat ng Rate API endpoint ng rate-scoped na API key na ipinapasa bilang x-api-key header. Available ang katumbas sa sandbox sa /mcp/sandbox/rate/* at ginagamit nito ang iyong sandbox key (bc_test_...) na may fixed na mock rate para sa testing na nauulit ang resulta.

Base URL

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

GET/mcp/rate/currenciesIlista ang lahat ng suportadong currency

Ilista ang lahat ng suportadong currency

Halimbawang request

bash

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

Halimbawang response

json

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

GET/mcp/rate/currentKunin ang kasalukuyang exchange rate sa pagitan ng dalawang currency

Kunin ang kasalukuyang exchange rate sa pagitan ng dalawang currency

Mga Parameter

Pangalan	Kailangan	Paglalarawan
`from`	kailangan	Source currency code (hal. USD)
`to`	kailangan	Target currency code (hal. NGN)

Halimbawang request

bash

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

Halimbawang 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/convertI-convert ang isang halaga mula sa isang currency papunta sa iba

I-convert ang isang halaga mula sa isang currency papunta sa iba

Mga Parameter

Pangalan	Kailangan	Paglalarawan
`from`	kailangan	Source currency code
`to`	kailangan	Target currency code
`amount`	kailangan	Halagang iko-convert (numero)

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

Halimbawang 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-convertI-convert ang maraming halaga ng currency sa iisang request (max 100)

I-convert ang maraming halaga ng currency sa iisang request (max 100)

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

Halimbawang 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/historyKunin ang historical exchange rate ng isang currency pair

Kunin ang historical exchange rate ng isang currency pair

Mga Parameter

Pangalan	Kailangan	Paglalarawan
`from`	kailangan	Source currency code
`to`	kailangan	Target currency code
`startDate`	kailangan	Petsa ng simula (ISO 8601, hal. 2026-04-01)
`endDate`	kailangan	Petsa ng pagtatapos (ISO 8601, hal. 2026-04-30)

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

Halimbawang 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/statsKunin ang rate statistics (pinakamataas, pinakamababa, average, pinakabago) sa loob ng isang panahon

Kunin ang rate statistics (pinakamataas, pinakamababa, average, pinakabago) sa loob ng isang panahon

Mga Parameter

Pangalan	Kailangan	Paglalarawan
`from`	kailangan	Source currency code
`to`	kailangan	Target currency code
`days`	opsyonal	Panahon sa araw, 1 hanggang 365 (default: 30)

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

Halimbawang 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

Palitan ang /mcp/rate/ ng /mcp/sandbox/rate/ at gamitin ang iyong sandbox key para makakuha ng fixed na mock rate. Ginagawa ang historical data na may ±2% na pagbabago para sa makatotohanang testing. Walang ginagamit na totoong exchange data.

Sandbox Environment

Ligtas na subukan ang iyong integration gamit ang pre-seeded na balanse at walang totoong pera.

Ano ang sandbox?

Ang sandbox ay isang ganap na hiwalay na test environment na eksaktong kahawig ng production, kasama ang parehong mga tool, parehong API, at parehong format ng response. Walang totoong perang gumagalaw. Nagsisimula sa bc_test_ ang mga sandbox API key at kumokonekta ang mga ito sa Hedera testnet.

Mga pre-seeded na balanse

Nagsisimula ang bawat sandbox account sa mga balanseng ito. Gamitin ang reset_sandbox_balance para maibalik ang mga ito anumang oras.

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

Sandbox kumpara sa Live

Feature	Sandbox	Live
Gumagalaw ang totoong pera	Hindi: simulated lang	Oo
OTP verification	Ibinabalik sa API response	Ipinapadala sa iyong email
Kailangan ng KYC para sa fiat	Hindi	Oo
Ipinapatupad ang spending limit	Oo (configurable)	Oo
Prefix ng API key	bc_test_...	bc_live_...
Hedera settlement	Testnet	Mainnet
Mga pre-seeded na balanse	Oo (puwedeng i-reset anumang oras)	Hindi
Mga rate limit	Maluwag	Depende sa plan

OTP sa sandbox

Sa sandbox mode, direktang ibinabalik ang OTP code sa request_transfer_otp API response sa halip na ipadala sa email. Pinapadali nito ang automated testing nang hindi kailangan ng access sa email.

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

Ikonekta ang BananaCrystal sa gusto mong AI tool o framework.

claude_desktop_config.json

json

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

Mga environment variable

BANANACRYSTAL_API_KEYkailangan

Ang iyong MCP API key. Nagsisimula sa bc_test_ ang mga sandbox key, at sa bc_live_ ang mga live key.

Default: N/A

BANANACRYSTAL_API_URLopsyonal

Palitan ang MCP endpoint URL. Gamitin ang sandbox URL para sa testing.

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

DEBUGopsyonal

I-set sa true para ma-enable ang detalyadong request/response logging.

Default: false

Variable	Kailangan	Default	Paglalarawan
`BANANACRYSTAL_API_KEY`	kailangan	`N/A`	Ang iyong MCP API key. Nagsisimula sa bc_test_ ang mga sandbox key, at sa bc_live_ ang mga live key.
`BANANACRYSTAL_API_URL`	opsyonal	`https://agentic.bananacrystal.com/mcp`	Palitan ang MCP endpoint URL. Gamitin ang sandbox URL para sa testing.
`DEBUG`	opsyonal	`false`	I-set sa true para ma-enable ang detalyadong request/response logging.

Mga Framework Integration

Mga handang patakbuhing halimbawa para sa mga pinakasikat na AI agent framework.

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

Gumagana ang kahit anong MCP-compatible na framework. Kung sinusuportahan ng iyong framework ang HTTP-based na MCP server, ituro ito sa https://agentic.bananacrystal.com/mcp gamit ang iyong API key bilang Bearer token.

Security Architecture

Maraming layer ng proteksyon para magawa lang ng iyong agent ang eksaktong pinahintulutan mo.

Mga API Key Scope

Bawat API key ay may malinaw na permission scope. Magagawa lang ng agent ang mga operasyon sa loob ng mga scope na ibinigay mo.

Mga Spending Limit

Mag-set ng mahigpit na maximum kada transaksyon at rolling na 24-hour daily cap kada API key. Ipinapatupad ang mga ito sa infrastructure level.

OTP Verification

Bawat token transfer ay nangangailangan ng 6-digit na OTP na ipinapadala sa iyong nakarehistrong email. Hindi makukumpleto ng agent ang transfer hangga't hindi mo ibinibigay ang code na iyon.

Rate Limiting

Pinipigilan ng rate cap kada key at kada minuto ang mga nagwawalang agent na paulit-ulit na tumawag sa API. Tumataas ang limit ayon sa plan tier mo.

Audit Trail na Hindi Nababago

Bawat tool call ay isinusulat sa consensus layer ng Hedera. May timestamp ang mga ito, hindi nababago, at puwedeng i-verify ng publiko on-chain. Available ang buong audit history gamit ang get_transaction_history.

Agent Approval Flow

Puwedeng mangailangan ng email approval ng tao ang mga agent-to-agent na transaksyon bago i-execute. Gamitin ang update_my_agent_settings para i-configure ang require_human_approval.

Mga API Key Scope

read_only

Mag-check ng balanse, rate, history, at limit nang hindi gumagalaw ang anumang pondo

transfer

Magpadala ng token sa ibang account (kailangan ng OTP)

swap

Mag-swap sa pagitan ng mga currency stablecoin

fiat

Fiat deposit at withdrawal (kailangan ng KYC)

offers

Gumawa at mamahala ng prediction market offer at trade

rate

I-access ang currency exchange rate, historical data, conversion, at rate statistics

Scope	Ang pinapayagan nito
read_only	Mag-check ng balanse, rate, history, at limit nang hindi gumagalaw ang anumang pondo
transfer	Magpadala ng token sa ibang account (kailangan ng OTP)
swap	Mag-swap sa pagitan ng mga currency stablecoin
fiat	Fiat deposit at withdrawal (kailangan ng KYC)
offers	Gumawa at mamahala ng prediction market offer at trade
rate	I-access ang currency exchange rate, historical data, conversion, at rate statistics

Presyo

Laging libre ang mga read-only operation. Magbabayad ka lang para sa mga transaksyong naglilipat ng halaga.

Mga fee sa operasyon

Mga read-only operation

get_balances, get_exchange_rate, list_trades, …

Libre

Mga token transfer

transfer_tokens

0.3%

Mga currency swap

swap_currency

0.5%

Mga fiat deposit

initiate_deposit

Depende sa rail

Mga fiat withdrawal

request_withdrawal

Depende sa rail

Prediction market

create_offer, engage_offer

Platform fee sa settlement

Operasyon	Mga Tool	Fee
Mga read-only operation	get_balances, get_exchange_rate, list_trades, …	Libre
Mga token transfer	transfer_tokens	0.3%
Mga currency swap	swap_currency	0.5%
Mga fiat deposit	initiate_deposit	Depende sa rail
Mga fiat withdrawal	request_withdrawal	Depende sa rail
Prediction market	create_offer, engage_offer	Platform fee sa settlement