Agent Payment Infrastructure

The MCP Server That Gives AI Agents a Wallet

One endpoint. Every payment capability. The financial primitive of the agent economy.

Works with Claude · LangChain · CrewAI · AutoGPT · Cursor · Windsurf · Any MCP client

"The agent economy is forming now. Developers who integrate payment rails first will define how AI agents transact. This is that infrastructure."

---

If this project helps you build payment-capable agents, please star the repo on GitHub because it helps other developers find it.

How to star: Open the repo, then click the ⭐ Star button in the top-right corner (free GitHub account required).

---

What this is

BananaCrystal provides agent payment infrastructure, which is the missing financial layer of the AI agent stack.

Traditional payment rails (banks, card networks, legacy APIs) were built for humans: human identity, human authorization, human operating hours. When AI agents try to use them they fail architecturally. Fixed fees make micropayments economically impossible, KYC requirements are difficult for agents to satisfy, and 3 to 5 day settlement windows break autonomous workflows.

This MCP server is the alternative. One configuration line gives any AI agent:

• An agent wallet with a real stablecoin balance
• Autonomous payment authority within operator-defined spending limits
• 150+ currencies, including USDb, EURb, NGNb, GBPb, CADb, and more
• On-chain settlement in under 5 seconds on Hedera
• An immutable audit trail where every agent action is recorded
• Real-time currency data via the dedicated rate service for current rates, historical data, batch conversions, and statistics

This is not a product feature. This is a new category: autonomous payments, the financial primitive of the agent economy built for machines from first principles.

---

Why AI agents need their own payment rails

	Traditional rails	BananaCrystal
Fee per transaction	$0.30 + 2.9% (Stripe) · $15–35 (wire)	0.3% transfers · 0.5% swaps · free for reads
Settlement speed	1–5 business days	Under 5 seconds, absolute finality
Identity model	Human KYC required	Programmatic Agent ID
Authorization	Human approval per transaction	Autonomous programmatic policy
Operating hours	Banking hours, weekdays	24/7/365
Micropayments	Impossible at $0.30/tx	Native and sub-cent viable
Spending controls	Card limit only	Per-tx caps, daily limits, allowlists, scopes
Audit trail	Monthly statements	Immutable on-chain, machine-readable

1,000 transactions/day on Stripe: $109,500/year in fees alone. 1,000 transactions/day on BananaCrystal: $365/year. The agent economy runs on micropayments. The infrastructure fee must be microscopic or the economics will collapse entirely.

---

Quick start: A working agent in 5 minutes

Step 1: Install

npm install -g @bananacrystal/mcp-server

Step 2: Get a free API key

Sign up at agents.bananacrystal.com → Account → API Keys → Create MCP key.

Fees: Transfers: 0.3% of amount · Swaps: 0.5% of amount · Read-only operations (balances, history, rates): free. Rate service (historical data, batch conversions, statistics): free with "rate" scope key.

Start with a Sandbox key for fake money, zero risk, and full functionality. Sandbox keys start with bc_test_ so you can always tell them apart from live keys. Switch to a Live key (no prefix) when ready.

Step 3: Pick your agent framework

Sandbox mode: Test without real money

Create a Sandbox key at agents.bananacrystal.com/account → API Keys → Create Sandbox Key.

Sandbox keys start with bc_test_. This prefix is how you and the package know it's a test key with no real money. Live keys have no prefix. The package automatically routes each key to the correct endpoint.

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

Sandbox behaviour:

• Pre-seeded balances: 10,000 USDb · 5,000,000 NGNb · 50,000 GHSb · 1,000,000 KESb · 150,000 ZARb
• All 40 MCP payment tools available
• Rate service endpoints available at /mcp/sandbox/rate/* (no auth needed)
• OTP codes are returned directly in the API response, so no email is sent
• KYC always approved
• Spend limits unlimited
• Reset balances anytime with the reset_sandbox_balance tool

Switch to a live key when you're ready. Same tools, same config, real money and live rates.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

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

Restart Claude Desktop. Then ask it:

"Check my BananaCrystal balance"
"Transfer 50 USDb to 0.0.12345 as payment for the data report"
"Swap 100 USDb to NGNb at the current rate"
"Show my last 10 transactions"

Your agent now has a payment wallet.

Cursor / Windsurf / Cline

Add to your IDE MCP config:

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

Your coding agent can now pay for API calls, data feeds, and compute per use.

LangChain (Python)

from langchain_mcp_adapters.client import MultiServerMCPClient
from langchain.agents import AgentExecutor, create_openai_tools_agent
from langchain_openai import ChatOpenAI
from langchain.prompts import ChatPromptTemplate, MessagesPlaceholder
import asyncio, os

async def create_payment_agent():
    client = MultiServerMCPClient({
        "bananacrystal": {
            "command": "bananacrystal-mcp",
            "env": {
                "BANANACRYSTAL_API_KEY": os.getenv("BANANACRYSTAL_API_KEY")
            },
            "transport": "stdio"
        }
    })
    tools = await client.get_tools()
    llm = ChatOpenAI(model="gpt-4o", temperature=0)
    prompt = ChatPromptTemplate.from_messages([
        ("system", """You are a financial operations AI agent with an
        agent wallet on BananaCrystal agent payment infrastructure.
        Always check balance before large transfers.
        Always include a memo with every payment.
        Report the transaction ID for every settled payment."""),
        ("human", "{input}"),
        MessagesPlaceholder(variable_name="agent_scratchpad")
    ])
    agent = create_openai_tools_agent(llm, tools, prompt)
    return AgentExecutor(agent=agent, tools=tools, verbose=True)

agent = asyncio.run(create_payment_agent())
result = agent.invoke({
    "input": "Check balance, then pay 12.50 USDb to vendor:data-provider-01 for today's market data report"
})
# Agent checks balance → verifies limits → requests OTP → executes transfer
# Settlement confirmed on Hedera in 3.2s · txId: 0.0.789@1711234567

CrewAI

from crewai import Agent, Task, Crew
from langchain_mcp_adapters.client import MultiServerMCPClient
import asyncio, os

async def setup_payment_tools():
    client = MultiServerMCPClient({
        "bananacrystal": {
            "command": "bananacrystal-mcp",
            "env": {"BANANACRYSTAL_API_KEY": os.getenv("BANANACRYSTAL_API_KEY")},
            "transport": "stdio"
        }
    })
    return await client.get_tools()

payment_tools = asyncio.run(setup_payment_tools())

treasury_agent = Agent(
    role="Autonomous Treasury Manager",
    goal="Monitor stablecoin balances and execute payments within defined limits",
    backstory="""You are an AI-native finance agent on the BananaCrystal
    agent payment infrastructure. You manage a multi-currency stablecoin
    treasury, executing transfers, swaps, and vendor payments autonomously.""",
    tools=payment_tools,
    verbose=True
)

treasury_task = Task(
    description="""Check USDb balance. If above 10,000 USDb, swap 5,000 USDb
    to EURb. Then pay vendor invoice of 500 USDb to vendor:accounting-service-01.""",
    agent=treasury_agent,
    expected_output="Balance checked, swap executed, vendor paid. All transaction IDs logged."
)

result = Crew(agents=[treasury_agent], tasks=[treasury_task]).kickoff()

AutoGPT

plugins:
  - name: BananaCrystal Payments
    package: "@bananacrystal/mcp-server"
    description: >
      Agent payment infrastructure with autonomous stablecoin transfers, 
      currency swaps, and fiat operations on the Hedera blockchain.
    env:
      BANANACRYSTAL_API_KEY: "${BC_API_KEY}"

---

40 production-ready payment tools

Every tool an agent needs for complete autonomous payment capability. All live. All guarded.

Read-only tools: Free and safe for any agent

Tool	What it does
ping	Health check
get_server_info	Server version and environment
echo	Echo a message
get_my_profile	Your profile, wallets, and MCP key info
get_balances	Token balances (all or specific token)
get_exchange_rate	Live buy/sell rates for any currency
list_supported_currencies	All supported stablecoins
list_available_tokens	All Hedera token IDs
get_transaction_history	Paginated transaction log with filters
get_my_limits	API key spending limits and current usage
estimate_swap_fees	Calculate fees before swapping
get_agent_config	Look up another agent's payment config
check_approval_status	Status of a pending approval request
get_kyc_status	KYC verification status
get_deposit_status	Fiat deposit status by transfer ID
get_withdrawal_status	Fiat withdrawal requests
get_escrow_balances	Escrow balance breakdown
get_escrow_history	Full escrow transaction history
list_offers	Browse prediction market offers
get_offer	Single offer details
get_my_offers	Your offers
list_trades	Browse all trades
get_trade	Single trade details
get_my_trades	Your trades

Transfer tools (require transfer scope · fee: 0.3% of amount)

Tool	What it does
request_transfer_otp	Step 1: Request OTP code (email in live, returned directly in sandbox)
transfer_tokens	Step 2: Execute transfer with OTP

Swap tools (require swap scope · fee: 0.5% of amount)

Tool	What it does
swap_currency	Swap between any two supported stablecoins

Fiat tools (require fiat scope + KYC)

Tool	What it does
initiate_kyc	Start KYC verification
initiate_deposit	Deposit via ACH or wire
request_withdrawal	Withdraw to bank account

Offers & trades tools (require offers scope)

Tool	What it does
create_offer	Create a prediction market offer
update_offer	Edit an offer (before any trades)
delist_offer	Remove offer from marketplace
delete_offer	Permanently delete offer
engage_offer	Trade against an offer
cancel_trade	Cancel an active trade

Agent-to-agent tools (require transfer scope)

Tool	What it does
request_agent_transaction	Request a transaction from another user's agent
execute_approved_transaction	Execute after approval
update_my_agent_settings	Configure approval rules and webhook URL

Sandbox-only tools

Tool	What it does
reset_sandbox_balance	Reset fake balances to defaults

---

Backend rate service (separate from MCP tools)

Beyond the 40 MCP tools above, BananaCrystal backend provides a separate rate service for comprehensive currency exchange operations:

Rate service endpoints: Accessed via API with a rate scope key

The rate service is a backend HTTP API, not an MCP tool. It's available to agents via REST endpoints (not through this MCP server's tool interface):

Endpoint	What it does
GET /mcp/rate/currencies	List all supported currencies
GET /mcp/rate/current?from=USD&to=NGN	Get current exchange rate between two currencies
GET /mcp/rate/convert?from=USD&to=NGN&amount=100	Convert amount from one currency to another
POST /mcp/rate/batch-convert	Convert multiple currency pairs in one request
GET /mcp/rate/history?from=USD&to=NGN&startDate=...&endDate=...	Get historical rates over a date range
GET /mcp/rate/stats?from=USD&to=NGN&days=30	Get rate statistics (high/low/average) for a period

How to use: Create an API key with rate scope, then call these endpoints directly from your agent or backend:

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

# Response:
{
  "from": "USD",
  "to": "NGN",
  "rate": 1250.50,
  "timestamp": "2026-04-28T17:08:24Z"
}

Note: These are backend HTTP endpoints, not MCP tools. If you need real-time rate data in your agent workflows, integrate these endpoints directly into your agent logic rather than using the MCP tool interface.

Sandbox testing: Use /mcp/sandbox/rate/* endpoints (no authentication required) to test rate operations.

---

Real-world agent economy use cases

Autonomous treasury management

Task:    "Monitor USDb balance. If above 50,000, swap 20% to EURb."

Flow:    get_balances → check threshold → estimate_swap_fees
         → swap_currency → audit log written to Hedera

Result:  Rebalanced $42,000 in 4.2 seconds.
         Human involvement: zero.
         Fee: 0.5% of swap amount.

AI customer service refunds

Task:    "Process refund for order #84921. Customer verified. Amount: 45.00 USDb."

Flow:    Verify eligibility → transfer_tokens → settlement confirmed

Result:  Before: 48-hour queue, 3 staff touchpoints.
         After:  2.8 second settlement. Zero staff involvement.

Multi-agent payroll

Task:    "Verify task completion by agent:worker-03. If verified, pay 12.50 USDb."

Flow:    Orchestrator verifies output → request_agent_transaction
         → agent:worker-03 receives payment atomically

This is the agent economy: agents hiring agents, paying for output.

Cross-border vendor payments

Task:    "Pay Nigerian vendor 500 USD equivalent in NGNb."

Flow:    get_exchange_rate (USDb/NGNb: 1,580)
         → swap_currency (500 USDb → 790,000 NGNb)
         → transfer_tokens to vendor wallet

Traditional wire: 3–5 days, $35 fee.
BananaCrystal:    4.1 seconds, 0.3% fee.

Per-call API billing for research agents

Task:    "Query the pricing data API. Pay per result."

Flow:    Agent calls data provider → provider returns HTTP 402
         → agent calls transfer_tokens (0.3% of transfer amount)
         → data unlocked → agent continues workflow

1,000 queries/day = $1.00 in payments + $1.00 in fees.
Economically impossible on Stripe ($300/day in fees alone).

Real-time currency conversion with rate service

Task:    "Show me rates and convert amounts for USD/NGN/EUR/GHS."

Flow:    Agent calls rate service (no MCP needed):
         GET /api/v1/mcp/rate/current?from=USD&to=NGN
         → returns {rate: 1580.50, timestamp, source}

         For batch: POST /api/v1/mcp/rate/batch-convert
         → converts [USD→NGN, EUR→GHS, GBP→NGN] in one call

         For analytics: GET /api/v1/mcp/rate/history
         → retrieves historical rates (high/low/average over days/weeks)

Rate service is a free query; use it alongside payment tools for complete
currency workflows. Create a "rate" scope key for access.

---

Security architecture

Layer	Mechanism	What it prevents
API Key Scopes	read_only, transfer, swap, fiat per key	Agent scope creep
Spending Limits	Per-tx max + daily cap enforced server-side	Runaway agent spending
OTP Verification	6-digit code to registered email for transfers	Unauthorized payments
Idempotency Keys	Redis deduplication per request	Double-spend on retries
Rate Limiting	Per-key per-minute and per-day caps	Runaway agent loops
Immutable Audit	Every tool call written to Hedera consensus layer	Tampered transaction history

What this package does NOT have access to:

• Your private keys, which are managed server-side
• Other users' wallets or data
• The ability to modify its own spending limits
• Anything outside your API key's scope

This MCP server is a thin authenticated client. All security enforcement executes server-side at BananaCrystal's infrastructure layer, not in this package.

---

Configuration

Variable	Required	Default	Description
BANANACRYSTAL_API_KEY	Yes	N/A	Your API key from agents.bananacrystal.com/account. Sandbox keys start with bc_test_ (no real money). Live keys have no prefix.
BANANACRYSTAL_API_URL	No	https://agentic.bananacrystal.com/mcp	Override API endpoint (for MCP tools). Rate service uses /api/v1/mcp/rate/* endpoints on same domain.
DEBUG	No	false	Enable verbose debug logging

API Scopes: Different API keys can have different scopes:

• All keys access the 40 MCP payment tools
• "rate" scope keys also access the rate service API (historical rates, batch conversions, statistics)
• Create scope-specific keys at agents.bananacrystal.com/account for fine-grained access control

---

Pricing

All MCP payment tools (40 tools) included with any API key. Rate service adds optional enhanced currency operations.

Read-only operations are always free. Fees only apply when moving money or accessing advanced rate features.

Operation	Fee
Balance checks, history, rates, profile	Free
Basic rate lookups (MCP tools)	Free
Advanced rate service (historical, batch, stats)	Free (with "rate" scope)
Token transfers (transfer_tokens)	0.3% of transfer amount
Currency swaps (swap_currency)	0.5% of swap amount
Fiat deposits / withdrawals	Varies by rail (ACH, wire)

Tier	Volume	Cost	For
Free	First 1,000 API calls/month	$0	Development and testing
Pay-per-use	1,001+ /month	0.3% transfers · 0.5% swaps	Production agents at any scale
Enterprise	Unlimited	Contact us	High-volume autonomous payment networks

No monthly fee. No seat pricing. No lock-in.

Note: Rate service queries (historical data, statistics, batch conversions) are included in your API call tier. Create a "rate" scope key to use these operations; see Rate Service for details.

---

Frequently asked questions

What exactly is agent payment infrastructure?

Agent payment infrastructure is the class of financial technology designed from first principles for AI agents as the primary economic actor. It provides agent wallets with programmatic identity (no human KYC), autonomous transaction authorization without per-transaction human approval, machine-speed settlement, and machine-readable audit trails.

Traditional payment infrastructure (Stripe, bank APIs, card networks) assumes a human is the accountable party behind every payment. Agent payment infrastructure assumes the payer may be an autonomous software process operating 24/7 at machine speed. These are architecturally different requirements, which is why BananaCrystal exists as a category, not just a product.

How is this different from Stripe or traditional payment APIs?

Seven architectural differences:

1. Identity: Stripe requires human KYC and a legal entity, whereas BananaCrystal issues agent wallets with programmatic identity in seconds.
2. Authorization: Stripe requires a human to authorize each transaction (3DS2, card PIN, etc.), while BananaCrystal uses programmatic spending policy set once by the operator.
3. Fees: Stripe charges $0.30 + 2.9% per transaction, making micropayments economically impossible. BananaCrystal charges a percentage of the amount (0.3% for transfers, 0.5% for swaps) with no fixed fee, making micropayments viable.
4. Settlement: Stripe settlements take 2 to 3 days, but BananaCrystal settles on Hedera in under 5 seconds with absolute finality.
5. Hours: Banks and card networks have operating hours, while BananaCrystal is available 24/7/365.
6. Fraud detection: Stripe's fraud system is trained on human transaction patterns and flags automated agent behavior as suspicious, but BananaCrystal is designed for machine transaction patterns.
7. Spending controls: Stripe offers card limits only, whereas BananaCrystal offers per-transaction caps, daily limits, recipient allowlists, and currency restrictions, all enforced at the infrastructure level.

Is this safe to give to an AI agent? What stops it spending everything?

Spending controls are enforced at the infrastructure layer rather than in your application or agent's code, so the agent cannot override them.

You set:

• Daily spending cap: A hard limit on total daily spend (e.g. $100/day)
• Per-transaction maximum: No single payment over a threshold (e.g. $25 max)
• Recipient allowlist: The agent can only pay pre-approved wallet addresses
• Currency restrictions: The agent can only transact in currencies you permit
• OTP requirement: Transfers above a threshold require a 6-digit email code

A runaway agent hitting its limit receives a SpendingLimitExceeded error and stops. No funds move.

What is an agent wallet?

An agent wallet is a non-custodial financial account owned and operated by an AI agent instead of a human. Its identity derives from a programmatic agent ID rather than government documents or personal KYC verification. The wallet holds a real stablecoin balance, has an on-chain Hedera address, and can send and receive value autonomously within the spending limits you configure.

When you sign up at agents.bananacrystal.com/account and create an API key, an agent wallet is automatically provisioned. Your agents reference it via the API key, so they never need to know private keys or manage cryptographic identity directly.

Which AI frameworks work with this MCP server?

Any framework that supports the Model Context Protocol (MCP). Confirmed integrations:

• Claude Desktop (Anthropic) has native MCP support
• Cursor, Windsurf, and Cline are IDE agents with MCP support
• LangChain support is available via the langchain-mcp-adapters package
• CrewAI works via the LangChain MCP adapter
• AutoGPT works via plugin configuration
• Custom agents, or any agent that can call JSON-RPC over stdio or HTTP, are supported

OpenAI adopted MCP in March 2025, and Microsoft added it to Copilot Studio in May 2025. Gartner projects that 75% of API gateway vendors will support MCP by 2026. Since this is the standard, you should build on it.

What currencies are supported?

150+ stablecoin currency pairs. The core flow:

1. Deposit USDC (external stablecoin) into your BananaCrystal account
2. Convert to USDb (BananaCrystal's native 1:1 USD stablecoin)
3. Swap USDb to any of 150+ local currency stablecoins
4. Withdraw back to USDC or your local bank anytime

Every swap settles on Hedera in under 5 seconds. No banks. No SWIFT. No weekends.

Fees: Token transfers cost 0.3% of the transfer amount. Currency swaps cost 0.5% of the swap amount. All other operations are free.

A sample of supported currencies:

Currency	Token		Currency	Token
US Dollar	USDb		Nigerian Naira	NGNb
Euro	EURb		Ghanaian Cedi	GHSb
British Pound	GBPb		Kenyan Shilling	KESb
UAE Dirham	AEDb		South African Rand	ZARb
Indian Rupee	INRb		Egyptian Pound	EGPb
Canadian Dollar	CADb		Ethiopian Birr	ETBb
Australian Dollar	AUDb		Moroccan Dirham	MADb
Japanese Yen	JPYb		Ugandan Shilling	UGXb

View all 150+ supported currencies →

Use list_available_tokens to get the live list with Hedera token IDs and current exchange rates.

What is Hedera and why does it matter for agent payments?

Hedera is an enterprise-grade public distributed ledger chosen for three properties critical to autonomous agent payments:

• Absolute finality in under 5 seconds: Unlike Ethereum's probabilistic finality or Bitcoin's 10-minute blocks, Hedera's hashgraph consensus provides certainty that a transaction has cleared. An agent's next action depends on knowing the payment settled, making absolute finality a functional requirement rather than a preference.
• Low transaction fees: Hedera's fee structure makes agent micropayments economically viable at scale. No other production blockchain offers this combination of speed and cost.
• Carbon-negative network: This is the only carbon-negative public distributed ledger, which matters for enterprises running agents at millions of transactions per month.

Is the MCP server open source? Can I self-host it?

Yes, it is MIT licensed. The server is a thin authenticated client that makes HTTP requests to BananaCrystal's API. You can fork it, modify it, and run it locally. A mock server is included for development without a real API key.

To run locally without an API key:

git clone https://github.com/BananaCrystal/mcp-server-bananacrystal.git
cd mcp-server-bananacrystal
npm install && npm run mock

The mock server returns realistic data so you can build integrations, write tests, and explore all 40 tools without touching production.

What is the agent economy?

The agent economy is the emerging economic layer where AI agents participate as independent economic actors. They are not just tools that assist humans, but participants that earn, spend, negotiate, and operate on their own financial behalf.

It requires three new infrastructure primitives: agent wallets (programmatic identity, no human KYC), autonomous payments (programmatic spending policy, not per-transaction human approval), and machine-speed settlement (on-chain, under 5 seconds, machine-readable confirmation).

BananaCrystal is the agent payment infrastructure layer. We don't sell a product; we represent a category called AI-native finance, which is a financial system built for machines rather than adapted from one built for humans. The agent economy is forming now, and developers who integrate payment rails first will define how it works.

How do I report a security vulnerability?

Do not open a public GitHub issue for security vulnerabilities. Email support@bananacrystal.com with:

1. Description of the vulnerability
2. Steps to reproduce
3. Potential impact

We will acknowledge within 24 hours and aim to resolve critical issues within 72 hours. We do not currently have a formal bug bounty program but we recognize responsible disclosures publicly and in our changelog.

Is there a sandbox environment for testing?

Yes, and you should always start there.

Create a Sandbox key at agents.bananacrystal.com/account → API Keys → Create Sandbox Key. Sandbox keys start with bc_test_ so you can always tell them apart from live keys (which have no prefix). The package automatically routes each key to the correct endpoint.

What sandbox gives you:

• Pre-seeded balances: 10,000 USDb · 5,000,000 NGNb · 50,000 GHSb · 1,000,000 KESb · 150,000 ZARb
• OTP codes are returned directly in the API response, so there is no email sent and no waiting
• KYC always approved instantly
• Spending limits are unlimited
• Reset balances anytime with the reset_sandbox_balance tool

All 40 MCP tools work identically in sandbox. Additionally, rate service endpoints are available in sandbox at /mcp/sandbox/rate/* without requiring authentication, which is perfect for testing currency exchange operations.

When you're ready to go live, swap bc_test_your_key for a live key. It uses the same configuration and tools but with real money.

There is also a local mock server for contributors who want to develop without any API key at all:

git clone https://github.com/BananaCrystal/mcp-server-bananacrystal.git
cd mcp-server-bananacrystal
npm install && npm run mock

The mock server runs on http://localhost:3000 and returns realistic data for all tools.

What is the rate service? How is it different from MCP tools?

The rate service is a separate backend HTTP API (not part of the 40 MCP tools). It provides comprehensive currency exchange operations:

• List all supported currencies
• Get current exchange rates between any two currencies
• Convert amounts instantly
• Batch convert multiple currency pairs
• Retrieve historical rate data over date ranges
• Get rate statistics (high/low/average)

Key difference: MCP tools are accessed through the MCP server interface (as described above). The rate service is accessed directly via HTTP REST endpoints.

How to use rate service:

1. Create an API key with rate scope at agents.bananacrystal.com/account
2. Call rate endpoints directly:

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

Sandbox testing: Use /mcp/sandbox/rate/* endpoints (no authentication required).

When to use rate service vs MCP tools:

• Use rate service for standalone rate lookups or integration into backend systems
• Use MCP tools for autonomous agent workflows with full payment capabilities
• They are complementary, so you can use both if you need rates and payments

See Backend rate service section for full endpoint reference.

What CLI tools are available?

After installing the package globally (npm install -g @bananacrystal/mcp-server), the bananacrystal-mcp binary is available on your PATH.

Primary use: Running the MCP server

bananacrystal-mcp
# Starts the MCP server over stdio, ready for Claude Desktop or any MCP client

Check version:

bananacrystal-mcp --version

Debug mode: Verbose logging to stderr

DEBUG=true bananacrystal-mcp

Override the API endpoint (e.g. point to local mock):

BANANACRYSTAL_API_URL=http://localhost:3001 bananacrystal-mcp

Test with MCP Inspector (interactive tool explorer):

export BANANACRYSTAL_API_KEY=bc_test_your_key_here
npx @modelcontextprotocol/inspector node dist/index.js

The MCP Inspector opens a browser UI where you can call any of the 40 tools interactively. This is useful for exploring the API before wiring it into an agent.

---

Development and local testing

# Clone
git clone https://github.com/BananaCrystal/mcp-server-bananacrystal.git
cd mcp-server-bananacrystal

# Install
npm install

# Start mock server: No API key needed
# All 40 MCP tools + rate service endpoints return realistic mock data
npm run mock

# Build from source
npm run build

# Run in development mode (requires real API key with appropriate scopes)
export BANANACRYSTAL_API_KEY=bc_test_your_sandbox_key
npm run dev

# Test rate service endpoints on mock server (no auth needed):
curl http://localhost:3001/api/v1/mcp/sandbox/rate/currencies
curl http://localhost:3001/api/v1/mcp/sandbox/rate/current?from=USD&to=NGN

# Test with MCP Inspector (for 40 MCP tools)
export BANANACRYSTAL_API_KEY=bc_test_your_key_here
npx @modelcontextprotocol/inspector node dist/index.js

Configure your agent to use the mock server (includes rate service):

{
  "mcpServers": {
    "bananacrystal": {
      "command": "bananacrystal-mcp",
      "env": {
        "BANANACRYSTAL_API_KEY": "bc_mock_test",
        "BANANACRYSTAL_API_URL": "http://localhost:3001"
      }
    }
  }
}

---

Troubleshooting

"API key invalid"

• Verify the key is copied correctly from agents.bananacrystal.com/account
• Sandbox keys start with bc_test_ for testing without real money. Live keys have no prefix.
• Verify key is active at agents.bananacrystal.com/account → API Keys
• Check the key has the required scope for the tool being called (transfer scope for transfer_tokens, swap scope for swap_currency, rate scope for rate service)
• Check for whitespace or truncation in the environment variable

"Spending limit exceeded"

This is working as designed; limits are enforced at the infrastructure level and cannot be bypassed.

To increase limits: agents.bananacrystal.com/account → API Keys → Edit → adjust daily cap or per-transaction maximum.

If you are building a production agent, set limits conservatively first and increase after observing real usage patterns.

MCP server not appearing in Claude / Cursor

1. Validate config file is valid JSON at jsonlint.com
2. Confirm file is at the correct path for your OS
3. Restart the application completely (full quit, not just reload)
4. Check the application's MCP logs for the exact error message

OTP not received

• Check spam/junk folder for email from BananaCrystal
• OTP expires in 10 minutes, so request a fresh one if needed
• Verify your registered email at agents.bananacrystal.com/account

"Rate limit exceeded"

• Implement exponential backoff in your agent retry logic
• The error response includes a retry_after field in seconds, which you should respect
• For high-volume production agents, contact support to increase rate limits

"Rate service returning 401 Unauthorized"

Rate service endpoints (/api/v1/mcp/rate/* and /api/v1/mcp/sandbox/rate/*) require keys with rate scope:

• Create a new key at agents.bananacrystal.com/account
• When creating the key, enable rate scope
• Sandbox rate endpoints (/mcp/sandbox/rate/*) require no authentication, so you can use them for free testing

---

Contributing

We are building the financial infrastructure of the agent economy. This is early. Your contributions shape the category.

git clone https://github.com/BananaCrystal/mcp-server-bananacrystal.git
cd mcp-server-bananacrystal
npm install
npm run mock   # develop against mock: No API key needed
npm run dev

What to work on

The highest-impact contributions right now:

Area	What we need	Impact
Framework guides	Eliza, Dify, n8n, Zapier AI integration examples	Expands reach to new developer communities
Language SDKs	Python wrapper (pip install bananacrystal), Go client	Makes the package accessible to non-JS developers
Agent workflow examples	Refund bots, treasury agents, payroll orchestrators	Developers copy real-world patterns directly
Test coverage	Unit and integration tests against mock server	Makes every PR reviewable with confidence
Documentation	Edge cases, error handling, advanced patterns	Reduces support burden, accelerates adoption
Platform integrations	OpenWebUI, LibreChat, Continue.dev MCP configs	Puts BananaCrystal in front of new developer audiences

How to contribute

1. Check open issues on GitHub for good first issue labels
2. Fork the repo and create a branch: git checkout -b feature/your-contribution
3. Make your changes against the mock server (no API key needed)
4. Submit a PR with a clear description of what you built and why
5. We review within 48 hours

See CONTRIBUTING.md for the full guide and GETTING_STARTED.md for a developer walkthrough.

Recognition

All contributors are credited in the commit history. Significant contributions (new framework integrations, language SDKs, major examples) are highlighted in the project README.

If you build something interesting with this MCP server, open an issue tagged showcase and we will feature it.

---

Star, share, and spread the category

If BananaCrystal has been useful:

Star the repo to help other developers find agent payment infrastructure when they need it. Visit github.com/BananaCrystal/mcp-server-bananacrystal to star.

Share it by posting in your AI agent community, Discord, or newsletter. The agent economy needs infrastructure, and developers building agents need to know this exists.

Open an issue if something doesn't work, if you need a framework that isn't supported, or if you have ideas. Every issue makes the project more useful for everyone.

---

Links

Get API key	agents.bananacrystal.com/account
Platform	agents.bananacrystal.com
Documentation	agents.bananacrystal.com/docs
GitHub	BananaCrystal/mcp-server-bananacrystal
npm	@bananacrystal/mcp-server
MCP Protocol	modelcontextprotocol.io
Hedera	hedera.com
Support	support@bananacrystal.com

---

MIT licensed · Built by BananaCrystal

Agent Payment Infrastructure · Autonomous Payments · AI-Native Finance

Get started free · Read the docs · View on GitHub