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.

Tài liệu BananaCrystal MCP | 40 công cụ thanh toán cho tác nhân AI

Bắt đầu nhanh

Giúp tác nhân AI của bạn thực hiện thanh toán trong chưa đầy 5 phút.

Cài đặt máy chủ MCP

Cài đặt máy chủ BananaCrystal MCP ở phạm vi toàn cục qua npm.

bash

npm install -g @bananacrystal/mcp-server

Lấy khóa API

Tạo khóa API MCP từ bảng điều khiển tài khoản. Khóa sandbox bắt đầu bằng bc_test_ và miễn phí.

Nhận khóa API

Khóa sandbox: bc_test_...

Cấu hình Claude Desktop

Thêm BananaCrystal vào tệp cấu hình Claude Desktop của bạn.

claude_desktop_config.json

json

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

Hỏi tác nhân của bạn

Tác nhân của bạn giờ đã có 40 công cụ thanh toán. Hãy thử các câu lệnh sau:

›"Số dư USDb hiện tại của tôi là bao nhiêu?"

›"Gửi 50 USDb đến 0.0.654321"

›"Hoán đổi 100 USDb sang NGNb theo tỷ giá hiện tại"

›"Cho tôi xem 10 giao dịch gần nhất"

›"Tỷ giá USD sang NGN hiện tại là bao nhiêu?"

Công cụ MCP

40 công cụ thanh toán sẵn sàng cho môi trường thực trong 6 nhóm. Thao tác chỉ đọc luôn miễn phí.

Chỉ đọc24 công cụ

ping

read_onlymiễn phí

Kiểm tra tình trạng: trả về pong

get_server_info

read_onlymiễn phí

Trả về thông tin cơ bản của máy chủ

echo

read_onlymiễn phí

Trả lại nguyên văn tin nhắn đầu vào cho bên gọi

get_my_profile

read_onlymiễn phí

Lấy toàn bộ hồ sơ của người dùng đã xác thực

get_balances

read_onlymiễn phí

Lấy số dư tài khoản Hedera cho mọi token của nền tảng hoặc một token cụ thể

get_exchange_rate

read_onlymiễn phí

Lấy tỷ giá mua/bán trực tiếp của một loại tiền

list_supported_currencies

read_onlymiễn phí

Liệt kê mọi loại tiền được hỗ trợ kèm phí động

list_available_tokens

read_onlymiễn phí

Liệt kê mọi token Hedera có sẵn trên nền tảng

get_transaction_history

read_onlymiễn phí

Lấy lịch sử giao dịch đã phân loại, có bộ lọc

get_my_limits

read_onlymiễn phí

Lấy các giới hạn đã cấu hình và mức sử dụng hiện tại của khóa API đã xác thực

estimate_swap_fees

read_onlymiễn phí

Ước tính phí hoán đổi tiền tệ trước khi thực hiện

get_agent_config

read_onlymiễn phí

Tra cứu cấu hình tác nhân của người dùng khác

check_approval_status

read_onlymiễn phí

Kiểm tra trạng thái yêu cầu phê duyệt giao dịch tác nhân đang chờ

get_kyc_status

read_onlymiễn phí

Lấy trạng thái xác minh KYC của người dùng qua Sumsub

get_deposit_status

read_onlymiễn phí

Lấy trạng thái khoản nạp tiền pháp định theo ID chuyển khoản

get_withdrawal_status

read_onlymiễn phí

Lấy các yêu cầu rút tiền của người dùng qua Brale

get_escrow_balances

read_onlymiễn phí

Lấy chi tiết số dư ký quỹ: tổng, khả dụng và đang khóa

get_escrow_history

read_onlymiễn phí

Lấy toàn bộ lịch sử giao dịch ký quỹ gồm khóa, giải phóng, thắng và thua

list_offers

read_onlymiễn phí

Duyệt các lệnh chào đang hoạt động trên thị trường dự đoán kèm thống kê giao dịch

get_offer

read_onlymiễn phí

Lấy đầy đủ chi tiết một lệnh chào kèm thống kê giao dịch

get_my_offers

read_onlymiễn phí

Lấy mọi lệnh chào do một người dùng cụ thể tạo

list_trades

read_onlymiễn phí

Liệt kê mọi giao dịch trên nền tảng, có bộ lọc

get_trade

read_onlymiễn phí

Lấy đầy đủ chi tiết một giao dịch kèm thống kê của lệnh chào gốc

get_my_trades

read_onlymiễn phí

Lấy mọi giao dịch của người dùng, gồm giao dịch đã tạo và đã nhận

Chuyển tiền2 công cụ

request_transfer_otp

transfer0.3%

Bước 1: Yêu cầu mã xác minh OTP gửi tới email người gửi

transfer_tokens

transfer0.3%

Bước 2: Thực hiện chuyển token với xác minh OTP

Hoán đổi1 công cụ

swap_currency

swap0.5%

Hoán đổi giữa hai token Hedera, tỷ giá và phí được tính tự động

Tiền pháp định3 công cụ

initiate_kyc

fiat

Khởi tạo xác minh KYC: trả về access token Sumsub cho SDK

initiate_deposit

fiat

Khởi tạo nạp tiền pháp định qua Brale (yêu cầu KYC)

request_withdrawal

fiat

Yêu cầu rút tiền pháp định qua Brale (yêu cầu KYC)

Lệnh chào và giao dịch6 công cụ

create_offer

offers

Tạo lệnh chào trên thị trường dự đoán, khóa toàn bộ số tiền trong ký quỹ

update_offer

offers

Sửa một lệnh chào hiện có (chỉ khi chưa có giao dịch)

delist_offer

offers

Gỡ lệnh chào khỏi thị trường và giải phóng ký quỹ đang khóa

delete_offer

offers

Xóa vĩnh viễn lệnh chào của bạn (bị chặn nếu còn giao dịch đang hoạt động)

engage_offer

offers

Tham gia một lệnh chào đang mở bằng cách khóa khoản ký quỹ tương ứng

cancel_trade

offers

Hủy một giao dịch đang hoạt động và giải phóng ký quỹ đang khóa của bạn

Giữa các tác nhân3 công cụ

request_agent_transaction

transfer

Yêu cầu giao dịch thay mặt tác nhân của người dùng khác (cần phê duyệt qua email)

execute_approved_transaction

transfer

Thực hiện một giao dịch tác nhân đã được phê duyệt bằng execution token

update_my_agent_settings

read_onlymiễn phí

Kiểm soát việc giao dịch giữa các tác nhân có cần phê duyệt qua email và OTP hay không

Chỉ trong sandbox1 công cụ

reset_sandbox_balance

read_onlymiễn phí

Đặt lại số dư sandbox về mặc định nạp sẵn (chỉ trong sandbox)

Rate API

Các thao tác tỷ giá nâng cao qua REST. Yêu cầu khóa API có phạm vi rate.

Công cụ MCP và Rate API: khác nhau thế nào?

Máy chủ MCP đã có sẵn get_exchange_rate là một công cụ read_only: tác nhân của bạn có thể gọi trực tiếp để lấy tỷ giá mua/bán của một loại tiền so với USD. Điều đó đáp ứng phần lớn nhu cầu của tác nhân.

Rate API làm được nhiều hơn: quy đổi chéo giữa các cặp, xử lý hàng loạt theo lô, dữ liệu chuỗi thời gian lịch sử và tóm tắt thống kê. Các tính năng này có dưới dạng endpoint HTTP trực tiếp, xác thực bằng khóa API có phạm vi rate. Tạo khóa rate từ bảng điều khiển tài khoản của bạn.

Xác thực

Mọi endpoint Rate API đều yêu cầu khóa API có phạm vi rate, truyền qua header x-api-key. Các endpoint sandbox tương ứng có tại /mcp/sandbox/rate/* và dùng khóa sandbox của bạn (bc_test_...) với tỷ giá giả lập cố định để kiểm thử có thể lặp lại.

URL gốc

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

GET/mcp/rate/currenciesLiệt kê mọi loại tiền tệ được hỗ trợ

Liệt kê mọi loại tiền tệ được hỗ trợ

Ví dụ yêu cầu

bash

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

Ví dụ phản hồi

json

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

GET/mcp/rate/currentLấy tỷ giá hiện tại giữa hai loại tiền

Lấy tỷ giá hiện tại giữa hai loại tiền

Tham số

Tên	Bắt buộc	Mô tả
`from`	bắt buộc	Mã tiền tệ nguồn (ví dụ USD)
`to`	bắt buộc	Mã tiền tệ đích (ví dụ NGN)

Ví dụ yêu cầu

bash

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

Ví dụ phản hồi

json

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

GET/mcp/rate/convertQuy đổi một số tiền từ loại tiền này sang loại tiền khác

Quy đổi một số tiền từ loại tiền này sang loại tiền khác

Tham số

Tên	Bắt buộc	Mô tả
`from`	bắt buộc	Mã tiền tệ nguồn
`to`	bắt buộc	Mã tiền tệ đích
`amount`	bắt buộc	Số tiền cần quy đổi (số)

Ví dụ yêu cầu

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"

Ví dụ phản hồi

json

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

POST/mcp/rate/batch-convertQuy đổi nhiều số tiền trong một yêu cầu (tối đa 100)

Quy đổi nhiều số tiền trong một yêu cầu (tối đa 100)

Ví dụ yêu cầu

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

Ví dụ phản hồi

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/historyLấy tỷ giá lịch sử của một cặp tiền tệ

Lấy tỷ giá lịch sử của một cặp tiền tệ

Tham số

Tên	Bắt buộc	Mô tả
`from`	bắt buộc	Mã tiền tệ nguồn
`to`	bắt buộc	Mã tiền tệ đích
`startDate`	bắt buộc	Ngày bắt đầu (ISO 8601, ví dụ 2026-04-01)
`endDate`	bắt buộc	Ngày kết thúc (ISO 8601, ví dụ 2026-04-30)

Ví dụ yêu cầu

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"

Ví dụ phản hồi

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/statsLấy thống kê tỷ giá (cao nhất, thấp nhất, trung bình, mới nhất) trong một khoảng thời gian

Lấy thống kê tỷ giá (cao nhất, thấp nhất, trung bình, mới nhất) trong một khoảng thời gian

Tham số

Tên	Bắt buộc	Mô tả
`from`	bắt buộc	Mã tiền tệ nguồn
`to`	bắt buộc	Mã tiền tệ đích
`days`	không bắt buộc	Số ngày, từ 1 đến 365 (mặc định: 30)

Ví dụ yêu cầu

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"

Ví dụ phản hồi

json

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

Rate API trong sandbox

Thay /mcp/rate/ bằng /mcp/sandbox/rate/ và dùng khóa sandbox để nhận tỷ giá giả lập cố định. Dữ liệu lịch sử được tạo với biên độ ±2% để kiểm thử sát thực tế. Không dùng dữ liệu tỷ giá thật.

Môi trường sandbox

Kiểm thử tích hợp an toàn với số dư nạp sẵn và không dùng tiền thật.

Sandbox là gì?

Sandbox là môi trường kiểm thử hoàn toàn tách biệt, phản ánh chính xác môi trường production, gồm cùng công cụ, cùng API và cùng định dạng phản hồi. Không có tiền thật được chuyển. Khóa API sandbox bắt đầu bằng bc_test_ và kết nối với Hedera testnet.

Số dư nạp sẵn

Mọi tài khoản sandbox đều bắt đầu với các số dư này. Dùng reset_sandbox_balance để khôi phục bất cứ lúc nào.

Token	Số lượng	Loại tiền
`USDb`	10,000	USD
`NGNb`	5,000,000	NGN
`GHSb`	50,000	GHS
`KESb`	1,000,000	KES
`ZARb`	150,000	ZAR

Sandbox và Live

Tính năng	Sandbox	Live
Chuyển tiền thật	Không: chỉ mô phỏng	Có
Xác minh OTP	Trả về trong phản hồi API	Gửi tới email của bạn
Yêu cầu KYC cho tiền pháp định	Không	Có
Áp dụng hạn mức chi tiêu	Có (có thể cấu hình)	Có
Tiền tố khóa API	bc_test_...	bc_live_...
Tất toán trên Hedera	Testnet	Mainnet
Số dư nạp sẵn	Có (đặt lại bất cứ lúc nào)	Không
Giới hạn tần suất	Nới lỏng	Theo gói

OTP trong sandbox

Ở chế độ sandbox, mã OTP được trả về trực tiếp trong phản hồi API request_transfer_otp thay vì gửi qua email. Nhờ vậy, kiểm thử tự động trở nên dễ dàng mà không cần truy cập email.

Cấu hình 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"
      }
    }
  }
}

Cấu hình

Kết nối BananaCrystal với công cụ hoặc framework AI bạn ưa dùng.

claude_desktop_config.json

json

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

Biến môi trường

BANANACRYSTAL_API_KEYbắt buộc

Khóa API MCP của bạn. Khóa sandbox bắt đầu bằng bc_test_, khóa live bắt đầu bằng bc_live_.

Mặc định: N/A

BANANACRYSTAL_API_URLkhông bắt buộc

Ghi đè URL endpoint MCP. Dùng URL sandbox để kiểm thử.

Mặc định: https://agentic.bananacrystal.com/mcp

DEBUGkhông bắt buộc

Đặt thành true để bật ghi nhật ký chi tiết yêu cầu/phản hồi.

Mặc định: false

Biến	Bắt buộc	Mặc định	Mô tả
`BANANACRYSTAL_API_KEY`	bắt buộc	`N/A`	Khóa API MCP của bạn. Khóa sandbox bắt đầu bằng bc_test_, khóa live bắt đầu bằng bc_live_.
`BANANACRYSTAL_API_URL`	không bắt buộc	`https://agentic.bananacrystal.com/mcp`	Ghi đè URL endpoint MCP. Dùng URL sandbox để kiểm thử.
`DEBUG`	không bắt buộc	`false`	Đặt thành true để bật ghi nhật ký chi tiết yêu cầu/phản hồi.

Tích hợp framework

Ví dụ chạy được ngay cho các framework tác nhân AI phổ biến nhất.

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

Mọi framework tương thích MCP đều dùng được. Nếu framework của bạn hỗ trợ máy chủ MCP dựa trên HTTP, hãy trỏ nó đến https://agentic.bananacrystal.com/mcp với khóa API của bạn làm Bearer token.

Kiến trúc bảo mật

Nhiều lớp bảo vệ để tác nhân của bạn chỉ làm được những gì bạn cho phép rõ ràng.

Phạm vi khóa API

Mỗi khóa API có các phạm vi quyền rõ ràng. Tác nhân chỉ có thể thực hiện thao tác trong phạm vi bạn cấp.

Hạn mức chi tiêu

Đặt mức tối đa cứng cho mỗi giao dịch và mức trần cuốn chiếu 24 giờ cho mỗi khóa API. Các giới hạn này được áp dụng ở cấp hạ tầng.

Xác minh OTP

Mọi lệnh chuyển token đều cần mã OTP 6 chữ số gửi tới email bạn đã đăng ký. Tác nhân không thể hoàn tất lệnh chuyển nếu bạn không cung cấp mã đó.

Giới hạn tần suất

Giới hạn tần suất theo khóa, theo phút giúp ngăn tác nhân mất kiểm soát gửi dồn dập yêu cầu tới API. Giới hạn tăng theo gói của bạn.

Nhật ký kiểm toán bất biến

Mọi lệnh gọi công cụ đều được ghi vào lớp đồng thuận của Hedera. Bản ghi có dấu thời gian, chống giả mạo và ai cũng có thể kiểm chứng trên chuỗi. Toàn bộ lịch sử kiểm toán có thể xem qua get_transaction_history.

Quy trình phê duyệt tác nhân

Giao dịch giữa các tác nhân có thể yêu cầu con người phê duyệt qua email trước khi thực hiện. Dùng update_my_agent_settings để cấu hình require_human_approval.

Phạm vi khóa API

read_only

Kiểm tra số dư, tỷ giá, lịch sử và hạn mức mà không chuyển tiền

transfer

Gửi token đến tài khoản khác (yêu cầu OTP)

swap

Hoán đổi giữa các stablecoin tiền tệ

fiat

Nạp và rút tiền pháp định (yêu cầu KYC)

offers

Tạo và quản lý lệnh chào và giao dịch trên thị trường dự đoán

rate

Truy cập tỷ giá, dữ liệu lịch sử, quy đổi và thống kê tỷ giá

Phạm vi	Cho phép làm gì
read_only	Kiểm tra số dư, tỷ giá, lịch sử và hạn mức mà không chuyển tiền
transfer	Gửi token đến tài khoản khác (yêu cầu OTP)
swap	Hoán đổi giữa các stablecoin tiền tệ
fiat	Nạp và rút tiền pháp định (yêu cầu KYC)
offers	Tạo và quản lý lệnh chào và giao dịch trên thị trường dự đoán
rate	Truy cập tỷ giá, dữ liệu lịch sử, quy đổi và thống kê tỷ giá

Bảng giá

Thao tác chỉ đọc luôn miễn phí. Bạn chỉ trả phí cho giao dịch có chuyển giá trị.

Phí theo thao tác

Thao tác chỉ đọc

get_balances, get_exchange_rate, list_trades, …

Miễn phí

Chuyển token

transfer_tokens

0.3%

Hoán đổi tiền tệ

swap_currency

0.5%

Nạp tiền pháp định

initiate_deposit

Tùy theo kênh

Rút tiền pháp định

request_withdrawal

Tùy theo kênh

Thị trường dự đoán

create_offer, engage_offer

Phí nền tảng khi tất toán

Thao tác	Công cụ	Phí
Thao tác chỉ đọc	get_balances, get_exchange_rate, list_trades, …	Miễn phí
Chuyển token	transfer_tokens	0.3%
Hoán đổi tiền tệ	swap_currency	0.5%
Nạp tiền pháp định	initiate_deposit	Tùy theo kênh
Rút tiền pháp định	request_withdrawal	Tùy theo kênh
Thị trường dự đoán	create_offer, engage_offer	Phí nền tảng khi tất toán