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 문서 | AI 에이전트를 위한 40개 결제 도구

빠른 시작

5분 안에 AI 에이전트가 결제를 시작하게 하세요.

MCP 서버 설치

npm으로 BananaCrystal MCP 서버를 전역 설치하세요.

bash

npm install -g @bananacrystal/mcp-server

API 키 받기

계정 대시보드에서 MCP API 키를 만드세요. 샌드박스 키는 bc_test_로 시작하며 무료입니다.

API 키 받기

샌드박스 키: bc_test_...

Claude Desktop 설정

Claude Desktop 설정 파일에 BananaCrystal을 추가하세요.

claude_desktop_config.json

json

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

에이전트에게 요청하기

이제 에이전트가 40개 결제 도구를 사용할 수 있습니다. 다음 프롬프트를 시도해 보세요:

›"현재 USDb 잔액이 얼마야?"

›"0.0.654321로 50 USDb 보내 줘"

›"현재 환율로 100 USDb를 NGNb로 스왑해 줘"

›"최근 거래 10건 보여 줘"

›"현재 USD 대 NGN 환율이 얼마야?"

MCP 도구

6개 카테고리에 걸친 40개 결제 도구. 읽기 전용 작업은 항상 무료입니다.

읽기 전용24개 도구

ping

read_only무료

상태 확인: pong을 반환합니다

get_server_info

read_only무료

기본 서버 정보를 반환합니다

echo

read_only무료

입력 메시지를 호출자에게 그대로 돌려줍니다

get_my_profile

read_only무료

인증된 사용자의 전체 프로필을 가져옵니다

get_balances

read_only무료

모든 플랫폼 토큰 또는 특정 토큰의 Hedera 계정 잔액을 가져옵니다

get_exchange_rate

read_only무료

통화의 실시간 매수/매도 환율을 가져옵니다

list_supported_currencies

read_only무료

지원되는 모든 통화와 변동 수수료를 나열합니다

list_available_tokens

read_only무료

플랫폼에서 사용 가능한 모든 Hedera 토큰을 나열합니다

get_transaction_history

read_only무료

필터를 적용한 분류별 거래 내역을 가져옵니다

get_my_limits

read_only무료

인증된 API 키의 설정 한도와 실시간 사용량을 가져옵니다

estimate_swap_fees

read_only무료

실행 전에 통화 스왑 수수료를 추정합니다

get_agent_config

read_only무료

다른 사용자의 에이전트 설정을 조회합니다

check_approval_status

read_only무료

대기 중인 에이전트 거래 승인 요청의 상태를 확인합니다

get_kyc_status

read_only무료

Sumsub를 통해 사용자의 KYC 인증 상태를 가져옵니다

get_deposit_status

read_only무료

이체 ID로 법정화폐 입금 상태를 가져옵니다

get_withdrawal_status

read_only무료

Brale를 통해 사용자의 출금 요청을 가져옵니다

get_escrow_balances

read_only무료

에스크로 잔액 내역을 가져옵니다: 총액, 사용 가능 금액, 잠긴 금액

get_escrow_history

read_only무료

잠금, 해제, 승리, 패배를 포함한 전체 에스크로 거래 내역을 가져옵니다

list_offers

read_only무료

거래 통계와 함께 예측 시장의 활성 오퍼를 둘러봅니다

get_offer

read_only무료

거래 통계를 포함한 단일 오퍼의 전체 정보를 가져옵니다

get_my_offers

read_only무료

특정 사용자가 만든 모든 오퍼를 가져옵니다

list_trades

read_only무료

필터를 적용해 플랫폼의 모든 거래를 나열합니다

get_trade

read_only무료

상위 오퍼 통계를 포함한 단일 거래의 전체 정보를 가져옵니다

get_my_trades

read_only무료

사용자가 만들고 받은 거래를 포함한 모든 거래를 가져옵니다

이체2개 도구

request_transfer_otp

transfer0.3%

1단계: 보내는 사람의 이메일로 OTP 인증 코드를 요청합니다

transfer_tokens

transfer0.3%

2단계: OTP 인증으로 토큰 이체를 실행합니다

스왑1개 도구

swap_currency

swap0.5%

환율과 수수료를 자동 계산하여 두 Hedera 토큰 간에 스왑합니다

법정화폐3개 도구

initiate_kyc

fiat

KYC 인증을 시작합니다: SDK용 Sumsub 액세스 토큰을 반환합니다

initiate_deposit

fiat

Brale를 통해 법정화폐 입금을 시작합니다 (KYC 필요)

request_withdrawal

fiat

Brale를 통해 법정화폐 출금을 요청합니다 (KYC 필요)

오퍼 및 거래6개 도구

create_offer

offers

총액을 에스크로에 잠그는 예측 시장 오퍼를 만듭니다

update_offer

offers

기존 오퍼를 수정합니다 (거래가 없을 때만)

delist_offer

offers

마켓플레이스에서 오퍼를 내리고 잠긴 에스크로를 해제합니다

delete_offer

offers

오퍼를 영구 삭제합니다 (활성 거래가 있으면 불가)

engage_offer

offers

같은 금액의 에스크로를 잠가 열린 오퍼에 참여합니다

cancel_trade

offers

활성 거래를 취소하고 잠긴 에스크로를 해제합니다

에이전트 간3개 도구

request_agent_transaction

transfer

다른 사용자의 에이전트를 대신해 거래를 요청합니다 (이메일 승인 필요)

execute_approved_transaction

transfer

실행 토큰으로 이전에 승인된 에이전트 거래를 실행합니다

update_my_agent_settings

read_only무료

에이전트 간 거래에 이메일 승인과 OTP를 요구할지 설정합니다

샌드박스 전용1개 도구

reset_sandbox_balance

read_only무료

샌드박스 잔액을 미리 채워진 기본값으로 초기화합니다 (샌드박스 전용)

Rate API

REST를 통한 고급 환율 작업. rate 범위 API 키가 필요합니다.

MCP 도구와 Rate API의 차이는?

MCP 서버에는 이미 read_only 도구로 get_exchange_rate가 포함되어 있습니다. 에이전트가 이를 직접 호출하여 단일 통화의 USD 대비 매수/매도 환율을 가져올 수 있으며, 대부분의 에이전트 사용 사례에 충분합니다.

Rate API는 더 많은 기능을 제공합니다: 교차 페어 환산, 대량 일괄 처리, 과거 시계열 데이터, 통계 요약. 이 기능은 rate 범위 API 키로 인증하는 HTTP 엔드포인트로 제공됩니다. 계정 대시보드에서 rate 키를 만드세요.

인증

모든 Rate API 엔드포인트에는 x-api-key 헤더로 전달되는 rate 범위 API 키가 필요합니다. 샌드박스용 엔드포인트는 /mcp/sandbox/rate/*에 있으며, 샌드박스 키(bc_test_...)를 사용하고 재현 가능한 테스트를 위해 고정된 모의 환율을 반환합니다.

Base URL

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

GET/mcp/rate/currencies지원되는 모든 통화 나열

지원되는 모든 통화 나열

요청 예시

bash

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

응답 예시

json

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

GET/mcp/rate/current두 통화 간 현재 환율 조회

두 통화 간 현재 환율 조회

매개변수

이름	필수	설명
`from`	필수	출발 통화 코드 (예: USD)
`to`	필수	대상 통화 코드 (예: NGN)

요청 예시

bash

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

응답 예시

json

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

GET/mcp/rate/convert한 통화의 금액을 다른 통화로 환산

한 통화의 금액을 다른 통화로 환산

매개변수

이름	필수	설명
`from`	필수	출발 통화 코드
`to`	필수	대상 통화 코드
`amount`	필수	환산할 금액 (숫자)

요청 예시

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"

응답 예시

json

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

POST/mcp/rate/batch-convert한 번의 요청으로 여러 통화 금액 환산 (최대 100건)

한 번의 요청으로 여러 통화 금액 환산 (최대 100건)

요청 예시

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

응답 예시

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/history통화 페어의 과거 환율 조회

통화 페어의 과거 환율 조회

매개변수

이름	필수	설명
`from`	필수	출발 통화 코드
`to`	필수	대상 통화 코드
`startDate`	필수	시작일 (ISO 8601, 예: 2026-04-01)
`endDate`	필수	종료일 (ISO 8601, 예: 2026-04-30)

요청 예시

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"

응답 예시

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/stats기간 동안의 환율 통계(최고, 최저, 평균, 최신) 조회

기간 동안의 환율 통계(최고, 최저, 평균, 최신) 조회

매개변수

이름	필수	설명
`from`	필수	출발 통화 코드
`to`	필수	대상 통화 코드
`days`	선택	기간(일), 1~365 (기본값: 30)

요청 예시

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"

응답 예시

json

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

샌드박스 Rate API

/mcp/rate/를 /mcp/sandbox/rate/로 바꾸고 샌드박스 키를 사용하면 고정된 모의 환율을 받을 수 있습니다. 과거 데이터는 실제와 비슷한 테스트를 위해 ±2% 변동으로 생성됩니다. 실제 환율 데이터는 사용되지 않습니다.

샌드박스 환경

미리 채워진 잔액으로 실제 돈 없이 안전하게 연동을 테스트하세요.

샌드박스란?

샌드박스는 프로덕션과 똑같은 도구, API, 응답 형식을 갖춘 완전히 격리된 테스트 환경입니다. 실제 돈은 이동하지 않습니다. 샌드박스 API 키는 bc_test_로 시작하며 Hedera testnet에 연결됩니다.

미리 채워진 잔액

모든 샌드박스 계정은 이 잔액으로 시작합니다. 언제든지 reset_sandbox_balance로 복원할 수 있습니다.

토큰	금액	통화
`USDb`	10,000	USD
`NGNb`	5,000,000	NGN
`GHSb`	50,000	GHS
`KESb`	1,000,000	KES
`ZARb`	150,000	ZAR

샌드박스와 라이브 비교

기능	샌드박스	라이브
실제 자금 이동	아니요: 시뮬레이션만	예
OTP 인증	API 응답으로 반환	이메일로 발송
법정화폐 거래 시 KYC 필요	아니요	예
지출 한도 적용	예 (설정 가능)	예
API 키 접두사	bc_test_...	bc_live_...
Hedera 정산	Testnet	Mainnet
미리 채워진 잔액	예 (언제든 초기화)	아니요
요청 한도	완화됨	요금제별

샌드박스의 OTP

샌드박스 모드에서는 OTP 코드가 이메일로 발송되지 않고 request_transfer_otp API 응답으로 바로 반환됩니다. 이메일 접근 없이도 자동화 테스트를 쉽게 할 수 있습니다.

샌드박스 설정

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

설정

BananaCrystal을 원하는 AI 도구나 프레임워크에 연결하세요.

claude_desktop_config.json

json

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

환경 변수

BANANACRYSTAL_API_KEY필수

MCP API 키입니다. 샌드박스 키는 bc_test_, 라이브 키는 bc_live_로 시작합니다.

기본값: N/A

BANANACRYSTAL_API_URL선택

MCP 엔드포인트 URL을 재정의합니다. 테스트에는 샌드박스 URL을 사용하세요.

기본값: https://agentic.bananacrystal.com/mcp

DEBUG선택

true로 설정하면 요청/응답을 상세하게 기록합니다.

기본값: false

변수	필수	기본값	설명
`BANANACRYSTAL_API_KEY`	필수	`N/A`	MCP API 키입니다. 샌드박스 키는 bc_test_, 라이브 키는 bc_live_로 시작합니다.
`BANANACRYSTAL_API_URL`	선택	`https://agentic.bananacrystal.com/mcp`	MCP 엔드포인트 URL을 재정의합니다. 테스트에는 샌드박스 URL을 사용하세요.
`DEBUG`	선택	`false`	true로 설정하면 요청/응답을 상세하게 기록합니다.

프레임워크 연동

가장 많이 쓰이는 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())

MCP 호환 프레임워크라면 모두 작동합니다. 프레임워크가 HTTP 기반 MCP 서버를 지원한다면 API 키를 Bearer 토큰으로 하여 https://agentic.bananacrystal.com/mcp에 연결하세요.

보안 아키텍처

여러 겹의 보호 장치로 에이전트는 사용자가 명시적으로 허용한 작업만 할 수 있습니다.

API 키 범위

각 API 키에는 명시적인 권한 범위가 있습니다. 에이전트는 부여된 범위 안에서만 작업할 수 있습니다.

지출 한도

API 키마다 거래당 최대 금액과 24시간 누적 일일 상한을 설정하세요. 인프라 수준에서 적용됩니다.

OTP 인증

모든 토큰 이체에는 등록된 이메일로 발송되는 6자리 OTP가 필요합니다. 사용자가 코드를 제공하지 않으면 에이전트는 이체를 완료할 수 없습니다.

요청 한도

키별, 분당 요청 상한으로 통제를 벗어난 에이전트가 API에 과도한 요청을 보내는 것을 막습니다. 한도는 요금제 등급에 따라 달라집니다.

변경 불가능한 감사 기록

모든 도구 호출은 Hedera 합의 레이어에 기록됩니다. 타임스탬프가 찍히고, 위변조가 불가능하며, 온체인에서 누구나 검증할 수 있습니다. 전체 감사 내역은 get_transaction_history로 확인할 수 있습니다.

에이전트 승인 절차

에이전트 간 거래는 실행 전에 사람의 이메일 승인을 요구할 수 있습니다. update_my_agent_settings로 require_human_approval을 설정하세요.

API 키 범위

read_only

자금을 이동하지 않고 잔액, 환율, 내역, 한도 확인

transfer

다른 계정으로 토큰 보내기 (OTP 필요)

swap

통화 스테이블코인 간 스왑

fiat

법정화폐 입금 및 출금 (KYC 필요)

offers

예측 시장 오퍼와 거래 생성 및 관리

rate

통화 환율, 과거 데이터, 환산, 환율 통계 이용

범위	허용되는 작업
read_only	자금을 이동하지 않고 잔액, 환율, 내역, 한도 확인
transfer	다른 계정으로 토큰 보내기 (OTP 필요)
swap	통화 스테이블코인 간 스왑
fiat	법정화폐 입금 및 출금 (KYC 필요)
offers	예측 시장 오퍼와 거래 생성 및 관리
rate	통화 환율, 과거 데이터, 환산, 환율 통계 이용

요금

읽기 전용 작업은 항상 무료입니다. 자금을 이동하는 거래에만 비용을 내세요.

작업별 수수료

읽기 전용 작업

get_balances, get_exchange_rate, list_trades, …

무료

토큰 이체

transfer_tokens

0.3%

통화 스왑

swap_currency

0.5%

법정화폐 입금

initiate_deposit

결제망에 따라 다름

법정화폐 출금

request_withdrawal

결제망에 따라 다름

예측 시장

create_offer, engage_offer

정산 시 플랫폼 수수료

작업	도구	수수료
읽기 전용 작업	get_balances, get_exchange_rate, list_trades, …	무료
토큰 이체	transfer_tokens	0.3%
통화 스왑	swap_currency	0.5%
법정화폐 입금	initiate_deposit	결제망에 따라 다름
법정화폐 출금	request_withdrawal	결제망에 따라 다름
예측 시장	create_offer, engage_offer	정산 시 플랫폼 수수료