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.

Dokumentacja BananaCrystal MCP | 40 narzędzi płatniczych dla agentów AI

Szybki start

Niech Twój agent AI wykonuje płatności w mniej niż 5 minut.

Zainstaluj serwer MCP

Zainstaluj serwer BananaCrystal MCP globalnie przez npm.

bash

npm install -g @bananacrystal/mcp-server

Pobierz klucz API

Utwórz klucz API MCP w panelu konta. Klucze sandboksowe zaczynają się od bc_test_ i są darmowe.

Pobierz klucz API

Klucze sandboksowe: bc_test_...

Skonfiguruj Claude Desktop

Dodaj BananaCrystal do pliku konfiguracyjnego Claude Desktop.

claude_desktop_config.json

json

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

Zapytaj agenta

Twój agent ma teraz 40 narzędzi płatniczych. Wypróbuj te polecenia:

›"Jakie jest moje obecne saldo USDb?"

›"Wyślij 50 USDb na 0.0.654321"

›"Wymień 100 USDb na NGNb po aktualnym kursie"

›"Pokaż moje ostatnie 10 transakcji"

›"Jaki jest aktualny kurs wymiany USD na NGN?"

Narzędzia MCP

40 gotowych do produkcji narzędzi płatniczych w 6 kategoriach. Operacje tylko do odczytu są zawsze darmowe.

Tylko odczyt24 narzędzia

ping

read_onlyza darmo

Sprawdzenie stanu: zwraca pong

get_server_info

read_onlyza darmo

Zwraca podstawowe informacje o serwerze

echo

read_onlyza darmo

Odsyła wywołującemu otrzymaną wiadomość

get_my_profile

read_onlyza darmo

Pobiera pełny profil uwierzytelnionego użytkownika

get_balances

read_onlyza darmo

Pobiera saldo konta Hedera dla wszystkich tokenów platformy lub wybranego tokena

get_exchange_rate

read_onlyza darmo

Pobiera aktualne kursy kupna/sprzedaży dla waluty

list_supported_currencies

read_onlyza darmo

Wyświetla wszystkie obsługiwane waluty wraz z ich dynamicznymi opłatami

list_available_tokens

read_onlyza darmo

Wyświetla wszystkie dostępne tokeny Hedera na platformie

get_transaction_history

read_onlyza darmo

Pobiera skategoryzowaną historię transakcji z filtrami

get_my_limits

read_onlyza darmo

Pobiera skonfigurowane limity i bieżące wykorzystanie dla uwierzytelnionego klucza API

estimate_swap_fees

read_onlyza darmo

Szacuje opłaty za wymianę walut przed jej wykonaniem

get_agent_config

read_onlyza darmo

Sprawdza konfigurację agenta innego użytkownika

check_approval_status

read_onlyza darmo

Sprawdza status oczekującej prośby o zatwierdzenie transakcji agenta

get_kyc_status

read_onlyza darmo

Pobiera status weryfikacji KYC użytkownika przez Sumsub

get_deposit_status

read_onlyza darmo

Pobiera status wpłaty fiat według ID przelewu

get_withdrawal_status

read_onlyza darmo

Pobiera wnioski o wypłatę użytkownika przez Brale

get_escrow_balances

read_onlyza darmo

Pobiera zestawienie salda escrow: kwoty łączne, dostępne i zablokowane

get_escrow_history

read_onlyza darmo

Pobiera pełną historię transakcji escrow, w tym blokady, zwolnienia, wygrane i przegrane

list_offers

read_onlyza darmo

Przegląda rynek prognoz w poszukiwaniu aktywnych ofert ze statystykami transakcji

get_offer

read_onlyza darmo

Pobiera pełne szczegóły pojedynczej oferty wraz ze statystykami transakcji

get_my_offers

read_onlyza darmo

Pobiera wszystkie oferty utworzone przez danego użytkownika

list_trades

read_onlyza darmo

Wyświetla wszystkie transakcje na platformie z filtrami

get_trade

read_onlyza darmo

Pobiera pełne szczegóły pojedynczej transakcji wraz ze statystykami oferty nadrzędnej

get_my_trades

read_onlyza darmo

Pobiera wszystkie transakcje użytkownika, zarówno utworzone, jak i otrzymane

Przelewy2 narzędzia

request_transfer_otp

transfer0.3%

Krok 1: żądanie kodu weryfikacyjnego OTP wysyłanego na e-mail nadawcy

transfer_tokens

transfer0.3%

Krok 2: wykonanie przelewu tokenów z weryfikacją OTP

Wymiana1 narzędzie

swap_currency

swap0.5%

Wymienia dwa tokeny Hedera, automatycznie obliczając kurs i opłaty

Fiat3 narzędzia

initiate_kyc

fiat

Inicjuje weryfikację KYC: zwraca token dostępu Sumsub dla SDK

initiate_deposit

fiat

Inicjuje wpłatę fiat przez Brale (wymagane KYC)

request_withdrawal

fiat

Składa wniosek o wypłatę fiat przez Brale (wymagane KYC)

Oferty i transakcje6 narzędzi

create_offer

offers

Tworzy ofertę na rynku prognoz, blokując całą kwotę w escrow

update_offer

offers

Edytuje istniejącą ofertę (tylko gdy nie ma do niej transakcji)

delist_offer

offers

Wycofuje Twoją ofertę z rynku i zwalnia zablokowane środki escrow

delete_offer

offers

Trwale usuwa Twoją ofertę (zablokowane, jeśli istnieją aktywne transakcje)

engage_offer

offers

Przyjmuje otwartą ofertę, blokując odpowiadające jej środki w escrow

cancel_trade

offers

Anuluje aktywną transakcję i zwalnia Twoje zablokowane środki escrow

Między agentami3 narzędzia

request_agent_transaction

transfer

Zleca transakcję w imieniu agenta innego użytkownika (wymaga zatwierdzenia e-mailem)

execute_approved_transaction

transfer

Wykonuje wcześniej zatwierdzoną transakcję agenta przy użyciu tokena wykonania

update_my_agent_settings

read_onlyza darmo

Określa, czy transakcje między agentami wymagają zatwierdzenia e-mailem i OTP

Tylko sandbox1 narzędzie

reset_sandbox_balance

read_onlyza darmo

Przywraca salda sandboksa do wstępnie ustawionych wartości (tylko sandbox)

Rate API

Zaawansowane operacje na kursach walut przez REST. Wymaga klucza API z zakresem rate.

Narzędzie MCP a Rate API: na czym polega różnica?

Serwer MCP zawiera już get_exchange_rate jako narzędzie read_only: agent może wywołać je bezpośrednio, aby pobrać kurs kupna/sprzedaży jednej waluty względem USD. To wystarcza w większości zastosowań agentów.

Rate API idzie dalej: przeliczenia między parami, operacje zbiorcze, historyczne szeregi czasowe i podsumowania statystyczne. Są dostępne jako bezpośrednie endpointy HTTP uwierzytelniane kluczem API z zakresem rate. Utwórz klucz rate w panelu konta.

Uwierzytelnianie

Wszystkie endpointy Rate API wymagają klucza API z zakresem rate przekazanego w nagłówku x-api-key. Odpowiedniki sandboksowe są dostępne pod /mcp/sandbox/rate/* i używają Twojego klucza sandboksowego (bc_test_...) ze stałymi kursami testowymi, co pozwala na powtarzalne testy.

Bazowy URL

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

GET/mcp/rate/currenciesWyświetla wszystkie obsługiwane waluty

Wyświetla wszystkie obsługiwane waluty

Przykładowe żądanie

bash

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

Przykładowa odpowiedź

json

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

GET/mcp/rate/currentPobiera aktualny kurs wymiany między dwiema walutami

Pobiera aktualny kurs wymiany między dwiema walutami

Parametry

Nazwa	Wymagane	Opis
`from`	wymagane	Kod waluty źródłowej (np. USD)
`to`	wymagane	Kod waluty docelowej (np. NGN)

Przykładowe żądanie

bash

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

Przykładowa odpowiedź

json

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

GET/mcp/rate/convertPrzelicza kwotę z jednej waluty na inną

Przelicza kwotę z jednej waluty na inną

Parametry

Nazwa	Wymagane	Opis
`from`	wymagane	Kod waluty źródłowej
`to`	wymagane	Kod waluty docelowej
`amount`	wymagane	Kwota do przeliczenia (liczba)

Przykładowe żądanie

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"

Przykładowa odpowiedź

json

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

POST/mcp/rate/batch-convertPrzelicza wiele kwot w jednym żądaniu (maks. 100)

Przelicza wiele kwot w jednym żądaniu (maks. 100)

Przykładowe żądanie

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

Przykładowa odpowiedź

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/historyPobiera historyczne kursy wymiany dla pary walut

Pobiera historyczne kursy wymiany dla pary walut

Parametry

Nazwa	Wymagane	Opis
`from`	wymagane	Kod waluty źródłowej
`to`	wymagane	Kod waluty docelowej
`startDate`	wymagane	Data początkowa (ISO 8601, np. 2026-04-01)
`endDate`	wymagane	Data końcowa (ISO 8601, np. 2026-04-30)

Przykładowe żądanie

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"

Przykładowa odpowiedź

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/statsPobiera statystyki kursu (maksimum, minimum, średnia, ostatni) za okres

Pobiera statystyki kursu (maksimum, minimum, średnia, ostatni) za okres

Parametry

Nazwa	Wymagane	Opis
`from`	wymagane	Kod waluty źródłowej
`to`	wymagane	Kod waluty docelowej
`days`	opcjonalne	Okres w dniach, od 1 do 365 (domyślnie: 30)

Przykładowe żądanie

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"

Przykładowa odpowiedź

json

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

Sandboksowe Rate API

Zastąp /mcp/rate/ ścieżką /mcp/sandbox/rate/ i użyj klucza sandboksowego, aby otrzymywać stałe kursy testowe. Dane historyczne są generowane z odchyleniem ±2% dla realistycznych testów. Nie są używane prawdziwe dane kursowe.

Środowisko Sandbox

Testuj integrację bezpiecznie, z wstępnie zasilonymi saldami i bez prawdziwych pieniędzy.

Czym jest sandbox?

Sandbox to w pełni odizolowane środowisko testowe, które dokładnie odwzorowuje produkcję: te same narzędzia, to samo API i ten sam format odpowiedzi. Prawdziwe pieniądze nie są przenoszone. Klucze API sandboksa zaczynają się od bc_test_ i łączą się z testnetem Hedera.

Wstępnie zasilone salda

Każde konto sandboksowe zaczyna z tymi saldami. Użyj reset_sandbox_balance, aby przywrócić je w dowolnym momencie.

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

Sandbox a produkcja

Funkcja	Sandbox	Produkcja
Ruch prawdziwych pieniędzy	Nie: tylko symulacja	Tak
Weryfikacja OTP	Zwracana w odpowiedzi API	Wysyłana na Twój e-mail
KYC wymagane dla fiat	Nie	Tak
Egzekwowane limity wydatków	Tak (konfigurowalne)	Tak
Prefiks klucza API	bc_test_...	bc_live_...
Rozliczenie na Hedera	Testnet	Mainnet
Wstępnie zasilone salda	Tak (reset w dowolnym momencie)	Nie
Limity żądań	Łagodne	Zależne od planu

OTP w sandboksie

W trybie sandbox kod OTP jest zwracany bezpośrednio w odpowiedzi API request_transfer_otp zamiast wysyłki e-mailem. Ułatwia to automatyczne testy bez dostępu do poczty.

Konfiguracja sandboksa

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

Konfiguracja

Połącz BananaCrystal z ulubionym narzędziem AI lub frameworkiem.

claude_desktop_config.json

json

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

Zmienne środowiskowe

BANANACRYSTAL_API_KEYwymagane

Twój klucz API MCP. Klucze sandboksowe zaczynają się od bc_test_, produkcyjne od bc_live_.

Domyślnie: N/A

BANANACRYSTAL_API_URLopcjonalne

Nadpisuje URL endpointu MCP. Do testów użyj URL sandboksa.

Domyślnie: https://agentic.bananacrystal.com/mcp

DEBUGopcjonalne

Ustaw na true, aby włączyć szczegółowe logowanie żądań i odpowiedzi.

Domyślnie: false

Zmienna	Wymagana	Domyślnie	Opis
`BANANACRYSTAL_API_KEY`	wymagane	`N/A`	Twój klucz API MCP. Klucze sandboksowe zaczynają się od bc_test_, produkcyjne od bc_live_.
`BANANACRYSTAL_API_URL`	opcjonalne	`https://agentic.bananacrystal.com/mcp`	Nadpisuje URL endpointu MCP. Do testów użyj URL sandboksa.
`DEBUG`	opcjonalne	`false`	Ustaw na true, aby włączyć szczegółowe logowanie żądań i odpowiedzi.

Integracje z frameworkami

Gotowe do uruchomienia przykłady dla najpopularniejszych frameworków agentów 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())

Działa każdy framework zgodny z MCP. Jeśli Twój framework obsługuje serwery MCP przez HTTP, skieruj go na https://agentic.bananacrystal.com/mcp, podając klucz API jako token Bearer.

Architektura bezpieczeństwa

Wiele warstw ochrony sprawia, że agent może robić tylko to, na co wyraźnie pozwolisz.

Zakresy kluczy API

Każdy klucz API ma jawne zakresy uprawnień. Agent może wykonywać tylko operacje w przyznanych przez Ciebie zakresach.

Limity wydatków

Ustaw twarde maksima na transakcję i kroczące limity dzienne (24 godziny) dla każdego klucza API. Są egzekwowane na poziomie infrastruktury.

Weryfikacja OTP

Każdy przelew tokenów wymaga 6-cyfrowego kodu OTP wysyłanego na Twój zarejestrowany e-mail. Agent nie może dokończyć przelewu bez tego kodu od Ciebie.

Limity żądań

Limity na minutę dla każdego klucza chronią API przed wymykającymi się spod kontroli agentami. Limity rosną wraz z poziomem planu.

Niezmienna ścieżka audytu

Każde wywołanie narzędzia jest zapisywane w warstwie konsensusu Hedera. Wpisy mają znacznik czasu, są odporne na manipulacje i publicznie weryfikowalne on-chain. Pełna historia audytu jest dostępna przez get_transaction_history.

Zatwierdzanie transakcji agentów

Transakcje między agentami mogą wymagać zatwierdzenia e-mailem przez człowieka przed wykonaniem. Użyj update_my_agent_settings, aby skonfigurować require_human_approval.

Zakresy kluczy API

read_only

Sprawdzanie sald, kursów, historii i limitów bez przenoszenia środków

transfer

Wysyłanie tokenów na inne konta (wymaga OTP)

swap

Wymiana stablecoinów walutowych

fiat

Wpłaty i wypłaty fiat (wymaga KYC)

offers

Tworzenie ofert i transakcji na rynku prognoz oraz zarządzanie nimi

rate

Dostęp do kursów wymiany walut, danych historycznych, przeliczeń i statystyk kursowych

Zakres	Na co pozwala
read_only	Sprawdzanie sald, kursów, historii i limitów bez przenoszenia środków
transfer	Wysyłanie tokenów na inne konta (wymaga OTP)
swap	Wymiana stablecoinów walutowych
fiat	Wpłaty i wypłaty fiat (wymaga KYC)
offers	Tworzenie ofert i transakcji na rynku prognoz oraz zarządzanie nimi
rate	Dostęp do kursów wymiany walut, danych historycznych, przeliczeń i statystyk kursowych

Cennik

Operacje tylko do odczytu są zawsze darmowe. Płacisz tylko za transakcje, które przenoszą wartość.

Opłaty za operacje

Operacje tylko do odczytu

get_balances, get_exchange_rate, list_trades, …

Za darmo

Przelewy tokenów

transfer_tokens

0.3%

Wymiana walut

swap_currency

0.5%

Wpłaty fiat

initiate_deposit

Zależnie od kanału

Wypłaty fiat

request_withdrawal

Zależnie od kanału

Rynek prognoz

create_offer, engage_offer

Opłata platformy przy rozliczeniu

Operacja	Narzędzia	Opłata
Operacje tylko do odczytu	get_balances, get_exchange_rate, list_trades, …	Za darmo
Przelewy tokenów	transfer_tokens	0.3%
Wymiana walut	swap_currency	0.5%
Wpłaty fiat	initiate_deposit	Zależnie od kanału
Wypłaty fiat	request_withdrawal	Zależnie od kanału
Rynek prognoz	create_offer, engage_offer	Opłata platformy przy rozliczeniu