{"_id":"@bananacrystal/mcp-server","_rev":"2-c54e3d2616c15142034a20de1514bb9f","name":"@bananacrystal/mcp-server","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@bananacrystal/mcp-server","version":"1.0.0","keywords":["mcp","agent-payments","autonomous-payments","ai-agents","agent-wallet","stablecoin","hedera","langchain","claude","model-context-protocol","ai-native-finance","agent-economy","crewai","payment-infrastructure"],"author":{"name":"BananaCrystal"},"license":"MIT","_id":"@bananacrystal/mcp-server@1.0.0","maintainers":[{"name":"bcgeorge","email":"george@bananacrystal.com"},{"name":"brainydel","email":"david@bananacrystal.com"}],"homepage":"https://github.com/BananaCrystal/mcp-server-bananacrystal#readme","bugs":{"url":"https://github.com/BananaCrystal/mcp-server-bananacrystal/issues"},"bin":{"bananacrystal-mcp":"dist/index.js"},"dist":{"shasum":"d97177f172dbf0a9013f411298f2afd853a229ec","tarball":"https://registry.npmjs.org/@bananacrystal/mcp-server/-/mcp-server-1.0.0.tgz","fileCount":24,"integrity":"sha512-3YJMMPRpwF55kiRG82tRloy0LarvLxLt/0Bz6RkLj5Lb7kiNN5dDFGAIzRmTQw7IJe0x7wM3WqFtGTHfziFseQ==","signatures":[{"sig":"MEQCIEcRGXjTKYtXYenqj1YndEyMhk1u2/sZMmOWN41W4cqzAiAFhlX0KFueTaCN/4EU/5693H9V9k0B09vrk/9o5VByOQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":202771},"main":"./dist/index.js","types":"./dist/index.d.ts","engines":{"node":">=20.0.0"},"gitHead":"30dce111cb51f55caded530ed8191ed736886749","scripts":{"dev":"tsx src/index.ts","mock":"tsx mock/server.ts","test":"vitest","build":"tsc && chmod +x dist/index.js","test:watch":"vitest --watch","prepublishOnly":"npm run build"},"_npmUser":{"name":"brainydel","email":"david@bananacrystal.com"},"repository":{"url":"git+https://github.com/BananaCrystal/mcp-server-bananacrystal.git","type":"git"},"_npmVersion":"10.8.1","description":"Agent payment infrastructure MCP server. Give AI agents autonomous payment capability — stablecoin transfers, currency swaps, agent wallets, and fiat operations on Hedera. Works with Claude, LangChain, CrewAI, AutoGPT.","directories":{},"_nodeVersion":"20.16.0","dependencies":{"cors":"^2.8.5","chalk":"^4.1.2","express":"^4.18.2","inquirer":"^8.2.6","commander":"^12.0.0","@modelcontextprotocol/sdk":"^1.0.4"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.7.0","vitest":"^1.2.0","typescript":"^5.3.0","@types/cors":"^2.8.17","@types/node":"^20.0.0","@types/express":"^4.17.21","@types/inquirer":"^8.2.10"},"_npmOperationalInternal":{"tmp":"tmp/mcp-server_1.0.0_1776467124672_0.917777090415429","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@bananacrystal/mcp-server","version":"1.0.1","description":"Agent payment infrastructure MCP server. Give AI agents autonomous payment capability — stablecoin transfers, currency swaps, agent wallets, and fiat operations on Hedera. Works with Claude, LangChain, CrewAI, AutoGPT.","main":"./dist/index.js","types":"./dist/index.d.ts","bin":{"bananacrystal-mcp":"dist/index.js"},"scripts":{"build":"tsc && chmod +x dist/index.js","dev":"tsx src/index.ts","mock":"tsx mock/server.ts","test":"vitest","test:watch":"vitest --watch","prepublishOnly":"npm run build"},"keywords":["mcp","agent-payments","autonomous-payments","ai-agents","agent-wallet","stablecoin","hedera","langchain","claude","model-context-protocol","ai-native-finance","agent-economy","crewai","payment-infrastructure"],"author":{"name":"BananaCrystal"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/BananaCrystal/mcp-server-bananacrystal.git"},"bugs":{"url":"https://github.com/BananaCrystal/mcp-server-bananacrystal/issues"},"homepage":"https://github.com/BananaCrystal/mcp-server-bananacrystal#readme","dependencies":{"@modelcontextprotocol/sdk":"^1.0.4","commander":"^12.0.0","chalk":"^4.1.2","inquirer":"^8.2.6","express":"^4.18.2","cors":"^2.8.5"},"devDependencies":{"@types/node":"^20.0.0","@types/express":"^4.17.21","@types/cors":"^2.8.17","@types/inquirer":"^8.2.10","tsx":"^4.7.0","typescript":"^5.3.0","vitest":"^1.2.0"},"engines":{"node":">=20.0.0"},"_id":"@bananacrystal/mcp-server@1.0.1","gitHead":"c617ce09a3fdd7241df19e42758214dd066cbbbd","_nodeVersion":"20.16.0","_npmVersion":"10.8.1","dist":{"integrity":"sha512-7tn9GYdcNDmD8R5nWPQOWfNQpkji0zKbZkoID2mqkx7cW/cHs1Ki2mKORSgUViHk2aLNbaV1k+5xTimk9f8Q8g==","shasum":"ba4cfc497fe1b61434e98620e66a5f9630a30c39","tarball":"https://registry.npmjs.org/@bananacrystal/mcp-server/-/mcp-server-1.0.1.tgz","fileCount":25,"unpackedSize":211189,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDKHpTVNnhBRD0VJ7Te+tiKxGhe/0sRxaJ/xCif8Z2qNgIhALsaihGpRyoA7hsbHogXVDKO70Nh10en9At25CNR/PBZ"}]},"_npmUser":{"name":"brainydel","email":"david@bananacrystal.com"},"directories":{},"maintainers":[{"name":"bcgeorge","email":"george@bananacrystal.com"},{"name":"brainydel","email":"david@bananacrystal.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-server_1.0.1_1776579881289_0.5397498752229379"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-17T23:05:24.562Z","modified":"2026-04-19T06:24:41.594Z","1.0.0":"2026-04-17T23:05:24.845Z","1.0.1":"2026-04-19T06:24:41.441Z"},"bugs":{"url":"https://github.com/BananaCrystal/mcp-server-bananacrystal/issues"},"author":{"name":"BananaCrystal"},"license":"MIT","homepage":"https://github.com/BananaCrystal/mcp-server-bananacrystal#readme","keywords":["mcp","agent-payments","autonomous-payments","ai-agents","agent-wallet","stablecoin","hedera","langchain","claude","model-context-protocol","ai-native-finance","agent-economy","crewai","payment-infrastructure"],"repository":{"type":"git","url":"git+https://github.com/BananaCrystal/mcp-server-bananacrystal.git"},"description":"Agent payment infrastructure MCP server. Give AI agents autonomous payment capability — stablecoin transfers, currency swaps, agent wallets, and fiat operations on Hedera. Works with Claude, LangChain, CrewAI, AutoGPT.","maintainers":[{"name":"bcgeorge","email":"george@bananacrystal.com"},{"name":"brainydel","email":"david@bananacrystal.com"}],"readme":"\n\n
\n\n\"BananaCrystal\"\n\n# Agent Payment Infrastructure\n\n### The MCP Server That Gives AI Agents a Wallet\n\n_One endpoint. Every payment capability. The financial primitive of the agent economy._\n\n
\n\n[![Get API Key](https://img.shields.io/badge/Get%20Free%20API%20Key-agents.bananacrystal.com-F5821F?style=for-the-badge)](https://agents.bananacrystal.com/account)\n[![npm](https://img.shields.io/npm/v/@bananacrystal/mcp-server?style=for-the-badge&color=5B63A4)](https://www.npmjs.com/package/@bananacrystal/mcp-server)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge)](https://opensource.org/licenses/MIT)\n[![Hedera](https://img.shields.io/badge/Settled%20on-Hedera%20%3C5s-6b48ff?style=for-the-badge)](https://hedera.com)\n[![MCP](https://img.shields.io/badge/MCP-Compatible-0ea5e9?style=for-the-badge)](https://modelcontextprotocol.io)\n\n
\n\n**Works with Claude · LangChain · CrewAI · AutoGPT · Cursor · Windsurf · Any MCP client**\n\n
\n\n> _\"The agent economy is forming now. Developers who integrate payment rails first_\n> _will define how AI agents transact. This is that infrastructure.\"_\n\n
\n\n---\n\n**If this project helps you build payment-capable agents, please star the repo on [GitHub](https://github.com/BananaCrystal/mcp-server-bananacrystal) — it helps other developers find it.**\n\n[![Star on GitHub](https://img.shields.io/github/stars/BananaCrystal/mcp-server-bananacrystal?style=social)](https://github.com/BananaCrystal/mcp-server-bananacrystal)\n\n> **How to star:** Open the repo, then click the ⭐ **Star** button in the top-right corner (free GitHub account required).\n\n---\n\n
\n\n
\n\n## What this is\n\n**BananaCrystal** provides **agent payment infrastructure** — the missing financial layer of the AI agent stack.\n\nTraditional 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 that make micropayments economically impossible, KYC requirements agents cannot satisfy, 3–5 day settlement windows that break autonomous workflows.\n\nThis MCP server is the alternative. **One configuration line gives any AI agent:**\n\n- An **agent wallet** with a real stablecoin balance\n- **Autonomous payment authority** within operator-defined spending limits\n- **150+ currencies** — USDb, EURb, NGNb, GBPb, CADb and more\n- **On-chain settlement in under 5 seconds** on Hedera\n- An **immutable audit trail** every agent action is written to\n\nThis 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.\n\n
\n\n---\n\n## Why AI agents need their own payment rails\n\n| | Traditional rails | BananaCrystal |\n| ----------------------- | ------------------------------------- | ------------------------------------------------- |\n| **Fee per transaction** | $0.30 + 2.9% (Stripe) · $15–35 (wire) | **0.3% transfers · 0.5% swaps · free for reads** |\n| **Settlement speed** | 1–5 business days | **Under 5 seconds, absolute finality** |\n| **Identity model** | Human KYC required | **Agent ID — programmatic** |\n| **Authorization** | Human approval per transaction | **Programmatic policy — autonomous** |\n| **Operating hours** | Banking hours, weekdays | **24/7/365** |\n| **Micropayments** | Impossible at $0.30/tx | **Native — sub-cent viable** |\n| **Spending controls** | Card limit only | **Per-tx caps, daily limits, allowlists, scopes** |\n| **Audit trail** | Monthly statements | **Immutable on-chain, machine-readable** |\n\n> 1,000 transactions/day on Stripe: **$109,500/year** in fees alone.\n> 1,000 transactions/day on BananaCrystal: **$365/year**.\n> The agent economy runs on micropayments. The infrastructure fee must be microscopic — or the economics collapse entirely.\n\n
\n\n---\n\n## Quick start — working agent in 5 minutes\n\n**Step 1 — Install**\n\n```bash\nnpm install -g @bananacrystal/mcp-server\n```\n\n**Step 2 — Get a free API key**\n\nSign up at **[agents.bananacrystal.com](https://agents.bananacrystal.com)** → **[Account → API Keys](https://agents.bananacrystal.com/account)** → Create MCP key.\n\nFirst 1,000 API calls free. No monthly fees. No seat pricing. No lock-in.\n\n**Fees:** Transfers: 0.3% of amount · Swaps: 0.5% of amount · Read-only operations (balances, history, rates): free.\n\n> **Start with a Sandbox key** — fake money, zero risk, 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.\n\n**Step 3 — Pick your agent framework**\n\n
\nSandbox mode — test without real money\n\nCreate a **Sandbox key** at **[agents.bananacrystal.com/account](https://agents.bananacrystal.com/account)** → API Keys → Create Sandbox Key.\n\nSandbox 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.\n\n```json\n{\n \"mcpServers\": {\n \"bananacrystal\": {\n \"command\": \"bananacrystal-mcp\",\n \"env\": {\n \"BANANACRYSTAL_API_KEY\": \"bc_test_your_sandbox_key_here\"\n }\n }\n }\n}\n```\n\n**Sandbox behaviour:**\n\n- Pre-seeded balances: 10,000 USDb · 5,000,000 NGNb · 50,000 GHSb · 1,000,000 KESb · 150,000 ZARb\n- OTP codes returned directly in the API response — no email sent\n- KYC always approved\n- Spend limits unlimited\n- Reset balances anytime with the `reset_sandbox_balance` tool\n\nSwitch to a live key when you're ready. Same tools, same config, real money.\n\n
\n\n
\nClaude Desktop\n\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)\nor `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):\n\n```json\n{\n \"mcpServers\": {\n \"bananacrystal\": {\n \"command\": \"bananacrystal-mcp\",\n \"env\": {\n \"BANANACRYSTAL_API_KEY\": \"bc_live_your_key_here\"\n }\n }\n }\n}\n```\n\nRestart Claude Desktop. Then ask it:\n\n```\n\"Check my BananaCrystal balance\"\n\"Transfer 50 USDb to 0.0.12345 — payment for the data report\"\n\"Swap 100 USDb to NGNb at the current rate\"\n\"Show my last 10 transactions\"\n```\n\nYour agent now has a payment wallet.\n\n
\n\n
\nCursor / Windsurf / Cline\n\nAdd to your IDE MCP config:\n\n```json\n{\n \"mcpServers\": {\n \"bananacrystal\": {\n \"command\": \"bananacrystal-mcp\",\n \"env\": {\n \"BANANACRYSTAL_API_KEY\": \"bc_live_your_key_here\"\n }\n }\n }\n}\n```\n\nYour coding agent can now pay for API calls, data feeds, and compute per use.\n\n
\n\n
\nLangChain (Python)\n\n```python\nfrom langchain_mcp_adapters.client import MultiServerMCPClient\nfrom langchain.agents import AgentExecutor, create_openai_tools_agent\nfrom langchain_openai import ChatOpenAI\nfrom langchain.prompts import ChatPromptTemplate, MessagesPlaceholder\nimport asyncio, os\n\nasync def create_payment_agent():\n client = MultiServerMCPClient({\n \"bananacrystal\": {\n \"command\": \"bananacrystal-mcp\",\n \"env\": {\n \"BANANACRYSTAL_API_KEY\": os.getenv(\"BANANACRYSTAL_API_KEY\")\n },\n \"transport\": \"stdio\"\n }\n })\n tools = await client.get_tools()\n llm = ChatOpenAI(model=\"gpt-4o\", temperature=0)\n prompt = ChatPromptTemplate.from_messages([\n (\"system\", \"\"\"You are a financial operations AI agent with an\n agent wallet on BananaCrystal agent payment infrastructure.\n Always check balance before large transfers.\n Always include a memo with every payment.\n Report the transaction ID for every settled payment.\"\"\"),\n (\"human\", \"{input}\"),\n MessagesPlaceholder(variable_name=\"agent_scratchpad\")\n ])\n agent = create_openai_tools_agent(llm, tools, prompt)\n return AgentExecutor(agent=agent, tools=tools, verbose=True)\n\nagent = asyncio.run(create_payment_agent())\nresult = agent.invoke({\n \"input\": \"Check balance, then pay 12.50 USDb to vendor:data-provider-01 for today's market data report\"\n})\n# Agent checks balance → verifies limits → requests OTP → executes transfer\n# Settlement confirmed on Hedera in 3.2s · txId: 0.0.789@1711234567\n```\n\n
\n\n
\nCrewAI\n\n```python\nfrom crewai import Agent, Task, Crew\nfrom langchain_mcp_adapters.client import MultiServerMCPClient\nimport asyncio, os\n\nasync def setup_payment_tools():\n client = MultiServerMCPClient({\n \"bananacrystal\": {\n \"command\": \"bananacrystal-mcp\",\n \"env\": {\"BANANACRYSTAL_API_KEY\": os.getenv(\"BANANACRYSTAL_API_KEY\")},\n \"transport\": \"stdio\"\n }\n })\n return await client.get_tools()\n\npayment_tools = asyncio.run(setup_payment_tools())\n\ntreasury_agent = Agent(\n role=\"Autonomous Treasury Manager\",\n goal=\"Monitor stablecoin balances and execute payments within defined limits\",\n backstory=\"\"\"You are an AI-native finance agent on the BananaCrystal\n agent payment infrastructure. You manage a multi-currency stablecoin\n treasury, executing transfers, swaps, and vendor payments autonomously.\"\"\",\n tools=payment_tools,\n verbose=True\n)\n\ntreasury_task = Task(\n description=\"\"\"Check USDb balance. If above 10,000 USDb, swap 5,000 USDb\n to EURb. Then pay vendor invoice of 500 USDb to vendor:accounting-service-01.\"\"\",\n agent=treasury_agent,\n expected_output=\"Balance checked, swap executed, vendor paid. All transaction IDs logged.\"\n)\n\nresult = Crew(agents=[treasury_agent], tasks=[treasury_task]).kickoff()\n```\n\n
\n\n
\nAutoGPT\n\n```yaml\nplugins:\n - name: BananaCrystal Payments\n package: \"@bananacrystal/mcp-server\"\n description: >\n Agent payment infrastructure — autonomous stablecoin transfers, \n currency swaps, and fiat operations on Hedera blockchain.\n env:\n BANANACRYSTAL_API_KEY: \"${BC_API_KEY}\"\n```\n\n
\n\n
\n\n---\n\n## 40 production-ready payment tools\n\nEvery tool an agent needs for complete autonomous payment capability. All live. All guarded.\n\n
\nRead-only tools — free, safe for any agent\n\n| Tool | What it does |\n| --------------------------- | ----------------------------------------- |\n| `ping` | Health check |\n| `get_server_info` | Server version and environment |\n| `echo` | Echo a message |\n| `get_my_profile` | Your profile, wallets, and MCP key info |\n| `get_balances` | Token balances (all or specific token) |\n| `get_exchange_rate` | Live buy/sell rates for any currency |\n| `list_supported_currencies` | All supported stablecoins |\n| `list_available_tokens` | All Hedera token IDs |\n| `get_transaction_history` | Paginated transaction log with filters |\n| `get_my_limits` | API key spending limits and current usage |\n| `estimate_swap_fees` | Calculate fees before swapping |\n| `get_agent_config` | Look up another agent's payment config |\n| `check_approval_status` | Status of a pending approval request |\n| `get_kyc_status` | KYC verification status |\n| `get_deposit_status` | Fiat deposit status by transfer ID |\n| `get_withdrawal_status` | Fiat withdrawal requests |\n| `get_escrow_balances` | Escrow balance breakdown |\n| `get_escrow_history` | Full escrow transaction history |\n| `list_offers` | Browse prediction market offers |\n| `get_offer` | Single offer details |\n| `get_my_offers` | Your offers |\n| `list_trades` | Browse all trades |\n| `get_trade` | Single trade details |\n| `get_my_trades` | Your trades |\n\n
\n\n
\nTransfer tools — require transfer scope · fee: 0.3% of amount\n\n| Tool | What it does |\n| ---------------------- | ----------------------------------------------------------------------- |\n| `request_transfer_otp` | Step 1 — request OTP code (email in live, returned directly in sandbox) |\n| `transfer_tokens` | Step 2 — execute transfer with OTP |\n\n
\n\n
\nSwap tools — require swap scope · fee: 0.5% of amount\n\n| Tool | What it does |\n| --------------- | ------------------------------------------ |\n| `swap_currency` | Swap between any two supported stablecoins |\n\n
\n\n
\nFiat tools — require fiat scope + KYC\n\n| Tool | What it does |\n| -------------------- | ------------------------ |\n| `initiate_kyc` | Start KYC verification |\n| `initiate_deposit` | Deposit via ACH or wire |\n| `request_withdrawal` | Withdraw to bank account |\n\n
\n\n
\nOffers & trades tools — require offers scope\n\n| Tool | What it does |\n| -------------- | --------------------------------- |\n| `create_offer` | Create a prediction market offer |\n| `update_offer` | Edit an offer (before any trades) |\n| `delist_offer` | Remove offer from marketplace |\n| `delete_offer` | Permanently delete offer |\n| `engage_offer` | Trade against an offer |\n| `cancel_trade` | Cancel an active trade |\n\n
\n\n
\nAgent-to-agent tools — require transfer scope\n\n| Tool | What it does |\n| ------------------------------ | ----------------------------------------------- |\n| `request_agent_transaction` | Request a transaction from another user's agent |\n| `execute_approved_transaction` | Execute after approval |\n| `update_my_agent_settings` | Configure approval rules and webhook URL |\n\n
\n\n
\nSandbox-only tools\n\n| Tool | What it does |\n| ----------------------- | ------------------------------- |\n| `reset_sandbox_balance` | Reset fake balances to defaults |\n\n
\n\n
\n\n---\n\n## Real-world agent economy use cases\n\n
\nAutonomous treasury management\n\n```\nTask: \"Monitor USDb balance. If above 50,000, swap 20% to EURb.\"\n\nFlow: get_balances → check threshold → estimate_swap_fees\n → swap_currency → audit log written to Hedera\n\nResult: Rebalanced $42,000 in 4.2 seconds.\n Human involvement: zero.\n Fee: 0.5% of swap amount.\n```\n\n
\n\n
\nAI customer service refunds\n\n```\nTask: \"Process refund for order #84921. Customer verified. Amount: 45.00 USDb.\"\n\nFlow: Verify eligibility → transfer_tokens → settlement confirmed\n\nResult: Before: 48-hour queue, 3 staff touchpoints.\n After: 2.8 second settlement. Zero staff involvement.\n```\n\n
\n\n
\nMulti-agent payroll\n\n```\nTask: \"Verify task completion by agent:worker-03. If verified, pay 12.50 USDb.\"\n\nFlow: Orchestrator verifies output → request_agent_transaction\n → agent:worker-03 receives payment atomically\n\nThis is the agent economy: agents hiring agents, paying for output.\n```\n\n
\n\n
\nCross-border vendor payments\n\n```\nTask: \"Pay Nigerian vendor 500 USD equivalent in NGNb.\"\n\nFlow: get_exchange_rate (USDb/NGNb: 1,580)\n → swap_currency (500 USDb → 790,000 NGNb)\n → transfer_tokens to vendor wallet\n\nTraditional wire: 3–5 days, $35 fee.\nBananaCrystal: 4.1 seconds, 0.3% fee.\n```\n\n
\n\n
\nPer-call API billing for research agents\n\n```\nTask: \"Query the pricing data API. Pay per result.\"\n\nFlow: Agent calls data provider → provider returns HTTP 402\n → agent calls transfer_tokens (0.3% of transfer amount)\n → data unlocked → agent continues workflow\n\n1,000 queries/day = $1.00 in payments + $1.00 in fees.\nEconomically impossible on Stripe ($300/day in fees alone).\n```\n\n
\n\n
\n\n---\n\n## Security architecture\n\n| Layer | Mechanism | What it prevents |\n| ---------------- | ------------------------------------------------- | ---------------------------- |\n| API Key Scopes | `read_only`, `transfer`, `swap`, `fiat` per key | Agent scope creep |\n| Spending Limits | Per-tx max + daily cap enforced server-side | Runaway agent spending |\n| OTP Verification | 6-digit code to registered email for transfers | Unauthorized payments |\n| Idempotency Keys | Redis deduplication per request | Double-spend on retries |\n| Rate Limiting | Per-key per-minute and per-day caps | Runaway agent loops |\n| Immutable Audit | Every tool call written to Hedera consensus layer | Tampered transaction history |\n\n**What this package does NOT have access to:**\n\n- Your private keys — managed server-side\n- Other users' wallets or data\n- The ability to modify its own spending limits\n- Anything outside your API key's scope\n\nThis MCP server is a thin authenticated client. All security enforcement executes server-side at BananaCrystal's infrastructure layer — not in this package.\n\n
\n\n---\n\n## Configuration\n\n| Variable | Required | Default | Description |\n| ----------------------- | -------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |\n| `BANANACRYSTAL_API_KEY` | **Yes** | — | Your API key from agents.bananacrystal.com/account. Sandbox keys start with `bc_test_` (no real money). Live keys have no prefix. |\n| `BANANACRYSTAL_API_URL` | No | `https://agentic.bananacrystal.com/mcp` | Override API endpoint |\n| `DEBUG` | No | `false` | Enable verbose debug logging |\n\n
\n\n---\n\n## Pricing\n\n**Read-only operations are always free.** Fees only apply when moving money.\n\n| Operation | Fee |\n| --------------------------------------- | --------------------------- |\n| Balance checks, history, rates, profile | **Free** |\n| Token transfers (`transfer_tokens`) | **0.3%** of transfer amount |\n| Currency swaps (`swap_currency`) | **0.5%** of swap amount |\n| Fiat deposits / withdrawals | Varies by rail (ACH, wire) |\n\n| Tier | Volume | Cost | For |\n| --------------- | --------------------------- | --------------------------- | --------------------------------------- |\n| **Free** | First 1,000 API calls/month | $0 | Development and testing |\n| **Pay-per-use** | 1,001+ /month | 0.3% transfers · 0.5% swaps | Production agents at any scale |\n| **Enterprise** | Unlimited | Contact us | High-volume autonomous payment networks |\n\nNo monthly fee. No seat pricing. No lock-in.\n\n
\n\n---\n\n## Frequently asked questions\n\n
\nWhat exactly is agent payment infrastructure?\n\nAgent 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.\n\nTraditional 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.\n\n
\n\n
\nHow is this different from Stripe or traditional payment APIs?\n\nSeven architectural differences:\n\n1. **Identity** — Stripe requires human KYC and a legal entity. BananaCrystal issues agent wallets with programmatic identity in seconds.\n2. **Authorization** — Stripe requires a human to authorize each transaction (3DS2, card PIN, etc.). BananaCrystal uses programmatic spending policy set once by the operator.\n3. **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.\n4. **Settlement** — Stripe settlements take 2–3 days. BananaCrystal settles on Hedera in under 5 seconds with absolute finality.\n5. **Hours** — Banks and card networks have operating hours. BananaCrystal is 24/7/365.\n6. **Fraud detection** — Stripe's fraud system is trained on human transaction patterns and flags automated agent behavior as suspicious. BananaCrystal is designed for machine transaction patterns.\n7. **Spending controls** — Stripe offers card limits only. BananaCrystal offers per-transaction caps, daily limits, recipient allowlists, and currency restrictions — all enforced at infrastructure level, not application layer.\n\n
\n\n
\nIs this safe to give to an AI agent? What stops it spending everything?\n\nSpending controls are enforced at the infrastructure layer — not in your application code, and not in the agent's code. The agent cannot override them.\n\nYou set:\n\n- **Daily spending cap** — hard limit on total daily spend (e.g. $100/day)\n- **Per-transaction maximum** — no single payment over a threshold (e.g. $25 max)\n- **Recipient allowlist** — agent can only pay pre-approved wallet addresses\n- **Currency restrictions** — agent can only transact in currencies you permit\n- **OTP requirement** — transfers above a threshold require a 6-digit email code\n\nA runaway agent hitting its limit receives a `SpendingLimitExceeded` error and stops. No funds move.\n\n
\n\n
\nWhat is an agent wallet?\n\nAn agent wallet is a non-custodial financial account owned and operated by an AI agent — not a human. Its identity derives from a programmatic agent ID, not from government documents or KYC verification of a person. 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.\n\nWhen you sign up at [agents.bananacrystal.com/account](https://agents.bananacrystal.com/account) and create an API key, an agent wallet is automatically provisioned. Your agents reference it via the API key — they never need to know private keys or manage cryptographic identity directly.\n\n
\n\n
\nWhich AI frameworks work with this MCP server?\n\nAny framework that supports the Model Context Protocol (MCP). Confirmed integrations:\n\n- **Claude Desktop** (Anthropic) — native MCP support\n- **Cursor, Windsurf, Cline** — IDE agents with MCP support\n- **LangChain** — via `langchain-mcp-adapters` package\n- **CrewAI** — via LangChain MCP adapter\n- **AutoGPT** — via plugin configuration\n- **Custom agents** — any agent that can call JSON-RPC over stdio or HTTP\n\nOpenAI adopted MCP in March 2025. Microsoft added it to Copilot Studio in May 2025. Gartner projects 75% of API gateway vendors will support MCP by 2026. This is the standard — build on it.\n\n
\n\n
\nWhat currencies are supported?\n\n150+ stablecoin currency pairs. The core flow:\n\n1. Deposit USDC (external stablecoin) into your BananaCrystal account\n2. Convert to USDb (BananaCrystal's native 1:1 USD stablecoin)\n3. Swap USDb to any of 150+ local currency stablecoins\n4. Withdraw back to USDC or your local bank anytime\n\nEvery swap settles on Hedera in under 5 seconds. No banks. No SWIFT. No weekends.\n\n**Fees:** Token transfers cost **0.3%** of the transfer amount. Currency swaps cost **0.5%** of the swap amount. All other operations are free.\n\nA sample of supported currencies:\n\n| Currency | Token | | Currency | Token |\n| ----------------- | ----- | --- | ------------------ | ----- |\n| US Dollar | USDb | | Nigerian Naira | NGNb |\n| Euro | EURb | | Ghanaian Cedi | GHSb |\n| British Pound | GBPb | | Kenyan Shilling | KESb |\n| UAE Dirham | AEDb | | South African Rand | ZARb |\n| Indian Rupee | INRb | | Egyptian Pound | EGPb |\n| Canadian Dollar | CADb | | Ethiopian Birr | ETBb |\n| Australian Dollar | AUDb | | Moroccan Dirham | MADb |\n| Japanese Yen | JPYb | | Ugandan Shilling | UGXb |\n\n**[View all 150+ supported currencies →](./CURRENCIES.md)**\n\nUse `list_available_tokens` to get the live list with Hedera token IDs and current exchange rates.\n\n
\n\n
\nWhat is Hedera and why does it matter for agent payments?\n\nHedera is an enterprise-grade public distributed ledger chosen for three properties critical to autonomous agent payments:\n\n- **Absolute finality in under 5 seconds** — unlike Ethereum (probabilistic finality over minutes) or Bitcoin (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 — absolute finality is a functional requirement, not a preference.\n- **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.\n- **Carbon-negative network** — the only carbon-negative public distributed ledger, which matters for enterprises running agents at millions of transactions per month.\n\n
\n\n
\nIs the MCP server open source? Can I self-host it?\n\nYes — 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.\n\nTo run locally without an API key:\n\n```bash\ngit clone https://github.com/BananaCrystal/mcp-server-bananacrystal.git\ncd mcp-server-bananacrystal\nnpm install && npm run mock\n```\n\nThe mock server returns realistic data so you can build integrations, write tests, and explore all 40 tools without touching production.\n\n
\n\n
\nWhat is the agent economy?\n\nThe agent economy is the emerging economic layer in which AI agents participate as independent economic actors — not just tools that assist humans, but participants that earn, spend, negotiate, and operate on their own financial behalf.\n\nIt 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).\n\nBananaCrystal is the agent payment infrastructure layer. We don't sell a product. We represent a category: **AI-native finance** — the financial system built for machines, not adapted from the one built for humans. The agent economy is forming now. Developers who integrate payment rails first will define how it works.\n\n
\n\n
\nHow do I report a security vulnerability?\n\nDo not open a public GitHub issue for security vulnerabilities. Email security@bananacrystal.com with:\n\n1. Description of the vulnerability\n2. Steps to reproduce\n3. Potential impact\n\nWe 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.\n\n
\n\n
\n\n---\n\n## Development and local testing\n\n```bash\n# Clone\ngit clone https://github.com/BananaCrystal/mcp-server-bananacrystal.git\ncd mcp-server-bananacrystal\n\n# Install\nnpm install\n\n# Start mock server — no API key needed, all 40 tools return realistic data\nnpm run mock\n\n# Build from source\nnpm run build\n\n# Run in development mode\nnpm run dev\n\n# Test with MCP Inspector\nexport BANANACRYSTAL_API_KEY=bc_test_your_key_here\nnpx @modelcontextprotocol/inspector node dist/index.js\n```\n\n**Configure your agent to use the mock server:**\n\n```json\n{\n \"mcpServers\": {\n \"bananacrystal\": {\n \"command\": \"bananacrystal-mcp\",\n \"env\": {\n \"BANANACRYSTAL_API_KEY\": \"test_key\",\n \"BANANACRYSTAL_API_URL\": \"http://localhost:3000\"\n }\n }\n }\n}\n```\n\n
\n\n---\n\n## Troubleshooting\n\n
\n\"API key invalid\"\n\n- Verify the key is copied correctly from [agents.bananacrystal.com/account](https://agents.bananacrystal.com/account)\n- Sandbox keys start with `bc_test_` (testing only — no real money). Live keys have no prefix.\n- Verify key is active at [agents.bananacrystal.com/account](https://agents.bananacrystal.com/account) → API Keys\n- Check the key has the required scope for the tool being called (`transfer` scope for `transfer_tokens`, `swap` scope for `swap_currency`)\n- Check for whitespace or truncation in the environment variable\n\n
\n\n
\n\"Spending limit exceeded\"\n\nThis is working as designed — limits are enforced at infrastructure level and cannot be bypassed.\n\nTo increase limits: [agents.bananacrystal.com/account](https://agents.bananacrystal.com/account) → API Keys → Edit → adjust daily cap or per-transaction maximum.\n\nIf you are building a production agent, set limits conservatively first and increase after observing real usage patterns.\n\n
\n\n
\nMCP server not appearing in Claude / Cursor\n\n1. Validate config file is valid JSON at [jsonlint.com](https://jsonlint.com)\n2. Confirm file is at the correct path for your OS\n3. Restart the application completely (full quit, not just reload)\n4. Check the application's MCP logs for the exact error message\n\n
\n\n
\nOTP not received\n\n- Check spam/junk folder for email from BananaCrystal\n- OTP expires in 10 minutes — request a fresh one if needed\n- Verify your registered email at [agents.bananacrystal.com/account](https://agents.bananacrystal.com/account)\n\n
\n\n
\n\"Rate limit exceeded\"\n\n- Implement exponential backoff in your agent retry logic\n- The error response includes a `retry_after` field in seconds — respect it\n- For high-volume production agents, contact support to increase rate limits\n\n
\n\n
\n\n---\n\n## Contributing\n\n**We are building the financial infrastructure of the agent economy. This is early. Your contributions shape the category.**\n\n```bash\ngit clone https://github.com/BananaCrystal/mcp-server-bananacrystal.git\ncd mcp-server-bananacrystal\nnpm install\nnpm run mock # develop against mock — no API key needed\nnpm run dev\n```\n\n### What to work on\n\nThe highest-impact contributions right now:\n\n| Area | What we need | Impact |\n| --------------------------- | ------------------------------------------------------- | ------------------------------------------------------ |\n| **Framework guides** | Eliza, Dify, n8n, Zapier AI integration examples | Expands reach to new developer communities |\n| **Language SDKs** | Python wrapper (`pip install bananacrystal`), Go client | Makes the package accessible to non-JS developers |\n| **Agent workflow examples** | Refund bots, treasury agents, payroll orchestrators | Developers copy real-world patterns directly |\n| **Test coverage** | Unit and integration tests against mock server | Makes every PR reviewable with confidence |\n| **Documentation** | Edge cases, error handling, advanced patterns | Reduces support burden, accelerates adoption |\n| **Platform integrations** | OpenWebUI, LibreChat, Continue.dev MCP configs | Puts BananaCrystal in front of new developer audiences |\n\n### How to contribute\n\n1. Check open issues on [GitHub](https://github.com/BananaCrystal/mcp-server-bananacrystal/issues) for `good first issue` labels\n2. Fork the repo and create a branch: `git checkout -b feature/your-contribution`\n3. Make your changes against the mock server (no API key needed)\n4. Submit a PR with a clear description of what you built and why\n5. We review within 48 hours\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md) for the full guide and [GETTING_STARTED.md](./GETTING_STARTED.md) for a developer walkthrough.\n\n### Recognition\n\nAll contributors are credited in the commit history. Significant contributions (new framework integrations, language SDKs, major examples) are highlighted in the project README and on [bananacrystal.com](https://bananacrystal.com).\n\n**If you build something interesting with this MCP server, open an issue tagged `showcase` and we will feature it.**\n\n
\n\n---\n\n## Star, share, and spread the category\n\nIf BananaCrystal has been useful:\n\n**Star the repo** — it helps other developers find agent payment infrastructure when they need it.\nVisit [github.com/BananaCrystal/mcp-server-bananacrystal](https://github.com/BananaCrystal/mcp-server-bananacrystal) to star.\n\n**Share it** — post in your AI agent community, Discord, or newsletter. The agent economy needs infrastructure. Developers building agents need to know this exists.\n\n**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.\n\n
\n\n---\n\n## Links\n\n| | |\n| ----------------- | --------------------------------------------------------------------------------------------------- |\n| **Get API key** | [agents.bananacrystal.com/account](https://agents.bananacrystal.com/account) |\n| **Platform** | [bananacrystal.com](https://www.bananacrystal.com) |\n| **Documentation** | [agents.bananacrystal.com/docs](https://agents.bananacrystal.com/docs) |\n| **GitHub** | [BananaCrystal/mcp-server-bananacrystal](https://github.com/BananaCrystal/mcp-server-bananacrystal) |\n| **npm** | [@bananacrystal/mcp-server](https://www.npmjs.com/package/@bananacrystal/mcp-server) |\n| **MCP Protocol** | [modelcontextprotocol.io](https://modelcontextprotocol.io) |\n| **Hedera** | [hedera.com](https://hedera.com) |\n| **Support** | support@bananacrystal.com |\n\n
\n\n---\n\n
\n\n**MIT licensed · Built by [BananaCrystal](https://bananacrystal.com)**\n\n_Agent Payment Infrastructure · Autonomous Payments · AI-Native Finance_\n\n[Get started free](https://agents.bananacrystal.com/account) · [Read the docs](https://agents.bananacrystal.com/docs) · [View on GitHub](https://github.com/BananaCrystal/mcp-server-bananacrystal)\n\n
\n\n\n","readmeFilename":"README.md"}