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.

Documentazione MCP di BananaCrystal | 40 strumenti di pagamento per agenti AI

Avvio rapido

Il suo agente AI effettua pagamenti in meno di 5 minuti.

Installi il server MCP

Installi il server MCP di BananaCrystal a livello globale tramite npm.

bash

npm install -g @bananacrystal/mcp-server

Ottenga la sua chiave API

Crei una chiave API MCP dalla dashboard del suo account. Le chiavi sandbox iniziano con bc_test_ e sono gratuite.

Ottieni la chiave API

Chiavi sandbox: bc_test_...

Configuri Claude Desktop

Aggiunga BananaCrystal al file di configurazione di Claude Desktop.

claude_desktop_config.json

json

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

Chieda al suo agente

Ora il suo agente ha 40 strumenti di pagamento. Provi questi prompt:

›"Qual è il mio saldo USDb attuale?"

›"Invia 50 USDb a 0.0.654321"

›"Converti 100 USDb in NGNb al tasso attuale"

›"Mostrami le mie ultime 10 transazioni"

›"Qual è il tasso di cambio attuale tra USD e NGN?"

Strumenti MCP

40 strumenti di pagamento pronti per la produzione in 6 categorie. Le operazioni in sola lettura sono sempre gratuite.

Sola lettura24 strumenti

ping

read_onlygratis

Controllo di stato: restituisce pong

get_server_info

read_onlygratis

Restituisce le informazioni di base del server

echo

read_onlygratis

Restituisce al chiamante il messaggio ricevuto

get_my_profile

read_onlygratis

Ottiene il profilo completo dell'utente autenticato

get_balances

read_onlygratis

Ottiene il saldo dell'account Hedera per tutti i token della piattaforma o per un token specifico

get_exchange_rate

read_onlygratis

Ottiene i tassi di cambio di acquisto/vendita in tempo reale per una valuta

list_supported_currencies

read_onlygratis

Elenca tutte le valute supportate con le relative commissioni dinamiche

list_available_tokens

read_onlygratis

Elenca tutti i token Hedera disponibili per la piattaforma

get_transaction_history

read_onlygratis

Ottiene lo storico delle transazioni per categoria, con filtri

get_my_limits

read_onlygratis

Ottiene i limiti configurati e l'utilizzo attuale della chiave API autenticata

estimate_swap_fees

read_onlygratis

Stima le commissioni di una conversione di valuta prima di eseguirla

get_agent_config

read_onlygratis

Consulta la configurazione dell'agente di un altro utente

check_approval_status

read_onlygratis

Controlla lo stato di una richiesta di approvazione di transazione dell'agente in sospeso

get_kyc_status

read_onlygratis

Ottiene lo stato della verifica KYC di un utente tramite Sumsub

get_deposit_status

read_onlygratis

Ottiene lo stato di un deposito fiat tramite ID del trasferimento

get_withdrawal_status

read_onlygratis

Ottiene le richieste di prelievo di un utente tramite Brale

get_escrow_balances

read_onlygratis

Ottiene il dettaglio del saldo in escrow: importi totali, disponibili e bloccati

get_escrow_history

read_onlygratis

Ottiene lo storico completo delle transazioni in escrow, inclusi blocchi, sblocchi, vincite e perdite

list_offers

read_onlygratis

Esplora il mercato predittivo per trovare offerte attive con le statistiche delle operazioni

get_offer

read_onlygratis

Ottiene i dettagli completi di una singola offerta, incluse le statistiche delle operazioni

get_my_offers

read_onlygratis

Ottiene tutte le offerte create da un utente specifico

list_trades

read_onlygratis

Elenca tutte le operazioni sulla piattaforma, con filtri

get_trade

read_onlygratis

Ottiene i dettagli completi di una singola operazione, incluse le statistiche dell'offerta di origine

get_my_trades

read_onlygratis

Ottiene tutte le operazioni di un utente, sia create sia ricevute

Trasferimento2 strumenti

request_transfer_otp

transfer0.3%

Passo 1: richiede un codice di verifica OTP inviato all'email del mittente

transfer_tokens

transfer0.3%

Passo 2: esegue il trasferimento di token con verifica OTP

Conversione1 strumento

swap_currency

swap0.5%

Converte tra due token Hedera con tasso e commissioni calcolati automaticamente

Fiat3 strumenti

initiate_kyc

fiat

Avvia la verifica KYC: restituisce un token di accesso Sumsub per l'SDK

initiate_deposit

fiat

Avvia un deposito fiat tramite Brale (KYC obbligatorio)

request_withdrawal

fiat

Richiede un prelievo fiat tramite Brale (KYC obbligatorio)

Offerte e operazioni6 strumenti

create_offer

offers

Crea un'offerta sul mercato predittivo che blocca l'importo totale in escrow

update_offer

offers

Modifica un'offerta esistente (solo se non ci sono operazioni)

delist_offer

offers

Ritira la sua offerta dal marketplace e sblocca l'escrow

delete_offer

offers

Elimina definitivamente la sua offerta (bloccato se ci sono operazioni attive)

engage_offer

offers

Partecipa a un'offerta aperta bloccando un escrow corrispondente

cancel_trade

offers

Annulla un'operazione attiva e sblocca il suo escrow

Da agente ad agente3 strumenti

request_agent_transaction

transfer

Richiede una transazione per conto dell'agente di un altro utente (richiede approvazione via email)

execute_approved_transaction

transfer

Esegue una transazione dell'agente già approvata usando il token di esecuzione

update_my_agent_settings

read_onlygratis

Stabilisce se le transazioni da agente ad agente richiedono approvazione via email e OTP

Solo sandbox1 strumento

reset_sandbox_balance

read_onlygratis

Ripristina i saldi sandbox ai valori precaricati (solo sandbox)

Rate API

Operazioni avanzate sui tassi di cambio via REST. Richiede una chiave API con ambito rate.

Strumento MCP o Rate API: qual è la differenza?

Il server MCP include già get_exchange_rate come strumento read_only: il suo agente può chiamarlo direttamente per ottenere il tasso di acquisto/vendita di una singola valuta rispetto all'USD. Questo copre la maggior parte dei casi d'uso degli agenti.

La Rate API va oltre: conversioni tra coppie incrociate, operazioni in batch, serie storiche e riepiloghi statistici. Sono disponibili come endpoint HTTP diretti, autenticati con una chiave API con ambito rate. Crei una chiave rate dalla dashboard del suo account.

Autenticazione

Tutti gli endpoint della Rate API richiedono una chiave API con ambito rate passata nell'header x-api-key. Gli equivalenti sandbox sono disponibili su /mcp/sandbox/rate/* e usano la sua chiave sandbox (bc_test_...) con tassi fittizi fissi per test riproducibili.

URL di base

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

GET/mcp/rate/currenciesElenca tutte le valute supportate

Elenca tutte le valute supportate

Esempio di richiesta

bash

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

Esempio di risposta

json

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

GET/mcp/rate/currentOttiene il tasso di cambio attuale tra due valute

Ottiene il tasso di cambio attuale tra due valute

Parametri

Nome	Obbligatorio	Descrizione
`from`	obbligatorio	Codice della valuta di origine (ad es. USD)
`to`	obbligatorio	Codice della valuta di destinazione (ad es. NGN)

Esempio di richiesta

bash

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

Esempio di risposta

json

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

GET/mcp/rate/convertConverte un importo da una valuta a un'altra

Converte un importo da una valuta a un'altra

Parametri

Nome	Obbligatorio	Descrizione
`from`	obbligatorio	Codice della valuta di origine
`to`	obbligatorio	Codice della valuta di destinazione
`amount`	obbligatorio	Importo da convertire (numero)

Esempio di richiesta

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"

Esempio di risposta

json

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

POST/mcp/rate/batch-convertConverte più importi in un'unica richiesta (max 100)

Converte più importi in un'unica richiesta (max 100)

Esempio di richiesta

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

Esempio di risposta

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/historyRecupera i tassi di cambio storici per una coppia di valute

Recupera i tassi di cambio storici per una coppia di valute

Parametri

Nome	Obbligatorio	Descrizione
`from`	obbligatorio	Codice della valuta di origine
`to`	obbligatorio	Codice della valuta di destinazione
`startDate`	obbligatorio	Data di inizio (ISO 8601, ad es. 2026-04-01)
`endDate`	obbligatorio	Data di fine (ISO 8601, ad es. 2026-04-30)

Esempio di richiesta

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"

Esempio di risposta

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/statsOttiene le statistiche del tasso (massimo, minimo, media, ultimo) su un periodo

Ottiene le statistiche del tasso (massimo, minimo, media, ultimo) su un periodo

Parametri

Nome	Obbligatorio	Descrizione
`from`	obbligatorio	Codice della valuta di origine
`to`	obbligatorio	Codice della valuta di destinazione
`days`	facoltativo	Periodo in giorni, da 1 a 365 (predefinito: 30)

Esempio di richiesta

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"

Esempio di risposta

json

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

Rate API in sandbox

Sostituisca /mcp/rate/ con /mcp/sandbox/rate/ e usi la sua chiave sandbox per ottenere tassi fittizi fissi. I dati storici vengono generati con una variazione di ±2% per test realistici. Non vengono usati dati di cambio reali.

Ambiente sandbox

Testi la sua integrazione in sicurezza con saldi precaricati e senza denaro reale.

Che cos'è la sandbox?

La sandbox è un ambiente di test completamente isolato che replica esattamente la produzione, con gli stessi strumenti, la stessa API e lo stesso formato di risposta. Non si muove denaro reale. Le chiavi API sandbox iniziano con bc_test_ e si collegano alla testnet di Hedera.

Saldi precaricati

Ogni account sandbox parte con questi saldi. Usi reset_sandbox_balance per ripristinarli in qualsiasi momento.

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

Sandbox e live a confronto

Funzionalità	Sandbox	Live
Movimenti di denaro reale	No: solo simulati	Sì
Verifica OTP	Restituito nella risposta API	Inviato alla sua email
KYC obbligatorio per il fiat	No	Sì
Limiti di spesa applicati	Sì (configurabili)	Sì
Prefisso della chiave API	bc_test_...	bc_live_...
Regolamento su Hedera	Testnet	Mainnet
Saldi precaricati	Sì (azzerabili in qualsiasi momento)	No
Limiti di frequenza	Più permissivi	In base al piano

OTP in sandbox

In modalità sandbox, il codice OTP viene restituito direttamente nella risposta API di request_transfer_otp invece di essere inviato via email. Questo rende semplici i test automatizzati senza bisogno di accedere all'email.

Configurazione sandbox

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

Configurazione

Colleghi BananaCrystal al suo strumento o framework AI preferito.

claude_desktop_config.json

json

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

Variabili d'ambiente

BANANACRYSTAL_API_KEYobbligatorio

La sua chiave API MCP. Le chiavi sandbox iniziano con bc_test_, quelle live con bc_live_.

Predefinito: N/A

BANANACRYSTAL_API_URLfacoltativo

Sovrascrive l'URL dell'endpoint MCP. Per i test usi l'URL sandbox.

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

DEBUGfacoltativo

Imposti true per attivare il logging dettagliato di richieste e risposte.

Predefinito: false

Variabile	Obbligatoria	Predefinito	Descrizione
`BANANACRYSTAL_API_KEY`	obbligatorio	`N/A`	La sua chiave API MCP. Le chiavi sandbox iniziano con bc_test_, quelle live con bc_live_.
`BANANACRYSTAL_API_URL`	facoltativo	`https://agentic.bananacrystal.com/mcp`	Sovrascrive l'URL dell'endpoint MCP. Per i test usi l'URL sandbox.
`DEBUG`	facoltativo	`false`	Imposti true per attivare il logging dettagliato di richieste e risposte.

Integrazioni con i framework

Esempi pronti all'uso per i framework di agenti AI più diffusi.

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

Funziona qualsiasi framework compatibile con MCP. Se il suo framework supporta server MCP basati su HTTP, lo punti a https://agentic.bananacrystal.com/mcp con la sua chiave API come Bearer token.

Architettura di sicurezza

Più livelli di protezione, così il suo agente può fare solo ciò che lei autorizza esplicitamente.

Ambiti delle chiavi API

Ogni chiave API ha ambiti di autorizzazione espliciti. Un agente può eseguire solo operazioni negli ambiti che lei concede.

Limiti di spesa

Imposti massimali rigidi per transazione e tetti giornalieri mobili sulle 24 ore per ogni chiave API. Sono applicati a livello di infrastruttura.

Verifica OTP

Ogni trasferimento di token richiede un OTP a 6 cifre inviato alla sua email registrata. L'agente non può completare un trasferimento senza che lei fornisca quel codice.

Limitazione della frequenza

Tetti di frequenza al minuto per chiave impediscono ad agenti fuori controllo di sovraccaricare l'API. I limiti crescono con il livello del suo piano.

Traccia di audit immutabile

Ogni chiamata a uno strumento viene scritta nel livello di consenso di Hedera. Le voci hanno una marca temporale, sono a prova di manomissione e verificabili pubblicamente on-chain. Lo storico di audit completo è disponibile tramite get_transaction_history.

Flusso di approvazione degli agenti

Le transazioni da agente ad agente possono richiedere l'approvazione umana via email prima dell'esecuzione. Usi update_my_agent_settings per configurare require_human_approval.

Ambiti delle chiavi API

read_only

Controllare saldi, tassi, storico e limiti senza muovere fondi

transfer

Inviare token ad altri account (richiede OTP)

swap

Convertire tra stablecoin in valuta

fiat

Depositi e prelievi fiat (richiede KYC)

offers

Creare e gestire offerte e operazioni sui mercati predittivi

rate

Accedere a tassi di cambio, dati storici, conversioni e statistiche sui tassi

Ambito	Cosa consente
read_only	Controllare saldi, tassi, storico e limiti senza muovere fondi
transfer	Inviare token ad altri account (richiede OTP)
swap	Convertire tra stablecoin in valuta
fiat	Depositi e prelievi fiat (richiede KYC)
offers	Creare e gestire offerte e operazioni sui mercati predittivi
rate	Accedere a tassi di cambio, dati storici, conversioni e statistiche sui tassi

Prezzi

Le operazioni in sola lettura sono sempre gratuite. Paga solo per le transazioni che muovono valore.

Commissioni per operazione

Operazioni in sola lettura

get_balances, get_exchange_rate, list_trades, …

Gratis

Trasferimenti di token

transfer_tokens

0.3%

Conversioni di valuta

swap_currency

0.5%

Depositi fiat

initiate_deposit

Variabile in base al circuito

Prelievi fiat

request_withdrawal

Variabile in base al circuito

Mercato predittivo

create_offer, engage_offer

Commissione della piattaforma al regolamento

Operazione	Strumenti	Commissione
Operazioni in sola lettura	get_balances, get_exchange_rate, list_trades, …	Gratis
Trasferimenti di token	transfer_tokens	0.3%
Conversioni di valuta	swap_currency	0.5%
Depositi fiat	initiate_deposit	Variabile in base al circuito
Prelievi fiat	request_withdrawal	Variabile in base al circuito
Mercato predittivo	create_offer, engage_offer	Commissione della piattaforma al regolamento