crossfin-mcp 1.8.8 → 1.12.0

package/README.md

@@ -1,14 +1,31 @@
 # CrossFin MCP Server
 
-**Give your AI agent access to Asian crypto markets.** 16 tools for real-time Korean exchange data, cross-exchange routing, and x402 paid API execution.
+[![npm version](https://img.shields.io/npm/v/crossfin-mcp)](https://www.npmjs.com/package/crossfin-mcp)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18.17-brightgreen)](https://nodejs.org)
+[![MCP](https://img.shields.io/badge/MCP-compatible-blue)](https://modelcontextprotocol.io)
+[![x402](https://img.shields.io/badge/payments-x402%20USDC-purple)](https://x402.org)
 
-## Install
+**Give your AI agent access to Asian crypto markets.** 16 tools for real-time Korean exchange data, cross-exchange routing, and x402 paid API execution across 9 exchanges.
+
+---
+
+## Quick Start
 
 ```bash
 npx -y crossfin-mcp
 ```
 
-### Claude Desktop config
+That's it. Your agent now has 16 tools -- 14 free, 2 paid. No API key needed for free tools.
+
+For paid tools ($0.01--$0.10 per call), set `EVM_PRIVATE_KEY` to a Base wallet with USDC.
+
+---
+
+## Client Configuration
+
+### Claude Desktop
+
+`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
 
 ```json
 {
@@ -24,55 +41,197 @@ npx -y crossfin-mcp
 }
 ```
 
-> **No EVM key?** Free tools work without one. Paid tools ($0.01–$0.10 per call) require a Base wallet with USDC.
+### Cursor
 
-## What your agent can do
+`.cursor/mcp.json` in your project root:
 
-- **"빗썸에서 바이낸스로 500만원 USDC 만들려면?"** → `find_optimal_route` evaluates 11 bridge coins, returns cheapest path
-- **"한국-글로벌 스프레드 얼마야?"** → `get_kimchi_premium` returns real-time spread across 11 pairs
-- **"거래소별 XRP 가격 비교해줘"** → `compare_exchange_prices` checks 4 Korean exchanges
-- **"한국 시장 브리핑해줘"** → `call_paid_service` calls Morning Brief bundle
+```json
+{
+  "mcpServers": {
+    "crossfin": {
+      "command": "npx",
+      "args": ["-y", "crossfin-mcp"],
+      "env": {
+        "EVM_PRIVATE_KEY": "0x..."
+      }
+    }
+  }
+}
+```
 
-## Tools
+### VS Code
 
-| Tool | Free/Paid | Description |
-|------|-----------|-------------|
-| `find_optimal_route` | $0.10 | Optimal crypto transfer path across 9 exchanges (11 bridge coins) |
-| `list_exchange_fees` | Free | Trading + withdrawal fee comparison |
-| `compare_exchange_prices` | Free | Live price comparison across Korean exchanges |
-| `get_kimchi_premium` | Free | Korean vs. global price spread preview |
-| `call_paid_service` | Varies | Call any of 35 paid APIs with automatic x402 payment |
-| `search_services` | Free | Search registered services |
-| `list_services` | Free | Browse service catalog |
-| `get_service` | Free | Service details |
-| `list_categories` | Free | Service categories |
-| `get_guide` | Free | Full agent guide |
-| `get_analytics` | Free | Gateway usage stats |
-| `create_wallet` | Free | Local ledger wallet |
-| `get_balance` | Free | Check wallet balance |
-| `transfer` | Free | Transfer between wallets |
-| `list_transactions` | Free | Transaction history |
-| `set_budget` | Free | Daily spend limit |
+`.vscode/mcp.json` in your project root (or user-level in settings):
 
-## Supported exchanges
+```json
+{
+  "inputs": [
+    {
+      "type": "promptString",
+      "id": "evm-key",
+      "description": "Base wallet private key for x402 payments (optional)",
+      "password": true
+    }
+  ],
+  "servers": {
+    "crossfin": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "crossfin-mcp"],
+      "env": {
+        "EVM_PRIVATE_KEY": "${input:evm-key}"
+      }
+    }
+  }
+}
+```
 
-Bithumb, Upbit, Coinone, GoPax (Korea) + bitFlyer, WazirX (Regional Fiat) + Binance, OKX, Bybit (Global)
+### Windsurf
 
-## Bridge coins
+`~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "crossfin": {
+      "command": "npx",
+      "args": ["-y", "crossfin-mcp"],
+      "env": {
+        "EVM_PRIVATE_KEY": "0x..."
+      }
+    }
+  }
+}
+```
+
+### npx (standalone)
+
+```bash
+EVM_PRIVATE_KEY=0x... npx -y crossfin-mcp
+```
+
+> **No EVM key?** Omit `EVM_PRIVATE_KEY` entirely. Free tools work without one.
+
+---
+
+## All 16 Tools
+
+### Routing Engine
+
+| Tool | Price | Description |
+|------|-------|-------------|
+| `find_optimal_route` | $0.10 | Optimal crypto transfer path across 9 exchanges with 11 bridge coins |
+| `list_exchange_fees` | Free | Trading + withdrawal fee comparison for all exchanges |
+| `compare_exchange_prices` | Free | Live Bithumb KRW vs Binance USD price comparison |
+| `get_kimchi_premium` | Free | Korean vs. global route spread preview (top 3 pairs) |
+
+### Paid API Gateway
+
+| Tool | Price | Description |
+|------|-------|-------------|
+| `call_paid_service` | Varies | Call any of 35+ paid APIs with automatic x402 USDC payment |
+
+### Service Registry
+
+| Tool | Price | Description |
+|------|-------|-------------|
+| `search_services` | Free | Search registered services by keyword |
+| `list_services` | Free | Browse the service catalog with category filter |
+| `get_service` | Free | Get details for a specific service |
+| `list_categories` | Free | List all service categories with counts |
+| `get_guide` | Free | Full CrossFin agent guide (services, pricing, x402 flow) |
+| `get_analytics` | Free | Gateway usage stats (total calls, top services) |
+
+### Local Ledger
+
+| Tool | Price | Description |
+|------|-------|-------------|
+| `create_wallet` | Free | Create a wallet in the local CrossFin ledger |
+| `get_balance` | Free | Check wallet balance (KRW) |
+| `transfer` | Free | Transfer funds between wallets |
+| `list_transactions` | Free | Transaction history (optionally filtered by wallet) |
+| `set_budget` | Free | Set a daily spend limit (KRW) |
+
+---
+
+## Sample Prompts
+
+**Korean**
+
+> 빗썸에서 바이낸스로 500만원 USDC 만들려면 가장 싼 방법이 뭐야?
+
+> 지금 한국-글로벌 스프레드 얼마야?
+
+> 거래소별 XRP 가격 비교해줘
+
+> 오늘 한국 시장 브리핑해줘
+
+**English**
+
+> What's the cheapest way to move 5M KRW from Bithumb to Binance as USDC?
+
+> Show me the current Korea-global crypto spread.
+
+> Compare XRP prices across exchanges.
+
+> Give me this morning's Korean market brief.
+
+---
+
+## Supported Exchanges
+
+**Korea:** Bithumb, Upbit, Coinone, GoPax
+**Regional Fiat:** bitFlyer, WazirX
+**Global:** Binance, OKX, Bybit
+
+### Bridge Coins
 
 BTC, ETH, XRP, SOL, DOGE, ADA, DOT, LINK, AVAX, TRX, KAIA
 
-## Environment variables
+---
+
+## Environment Variables
 
 | Variable | Required | Description |
 |----------|----------|-------------|
 | `EVM_PRIVATE_KEY` | For paid tools | Base wallet private key for x402 USDC payments |
 | `CROSSFIN_API_URL` | No | API base URL (default: `https://crossfin.dev`) |
-| `CROSSFIN_LEDGER_PATH` | No | Local ledger path (default: `~/.crossfin/ledger.json`) |
+| `CROSSFIN_LEDGER_PATH` | No | Local ledger file path (default: `~/.crossfin/ledger.json`) |
+
+---
+
+## x402 Payments
+
+Paid tools use the [x402 protocol](https://x402.org) for automatic micropayments. When your agent calls a paid endpoint:
+
+1. The API responds with `402 Payment Required` and a price header
+2. The MCP server signs a USDC payment on **Base** (L2) using your `EVM_PRIVATE_KEY`
+3. The payment is submitted and the API returns the data along with a transaction receipt
+
+Payments settle on-chain. Each response includes `txHash` and a Basescan link for verification. Prices range from $0.01 to $0.20 per call.
+
+To get started, fund a Base wallet with USDC and set `EVM_PRIVATE_KEY`. No account registration or API keys required.
+
+---
+
+## Agent Discovery
+
+CrossFin exposes standard discovery endpoints so agent frameworks can auto-detect capabilities:
+
+| Endpoint | Description |
+|----------|-------------|
+| [`/.well-known/ai-plugin.json`](https://crossfin.dev/.well-known/ai-plugin.json) | OpenAI plugin manifest |
+| [`/.well-known/agent.json`](https://crossfin.dev/.well-known/agent.json) | A2A Agent Card (Google Agent-to-Agent protocol) |
+| [`/.well-known/x402.json`](https://crossfin.dev/.well-known/x402.json) | x402 payment discovery (network, token, payTo) |
+| [`/.well-known/crossfin.json`](https://crossfin.dev/.well-known/crossfin.json) | CrossFin metadata (MCP, API, registry links) |
+| [`/llms.txt`](https://crossfin.dev/llms.txt) | LLM-friendly service description |
+
+---
 
 ## Links
 
-- [crossfin.dev](https://crossfin.dev) — Dashboard
-- [live.crossfin.dev](https://live.crossfin.dev) — Live routing demo
-- [GitHub](https://github.com/bubilife1202/crossfin) — Source code
-- [npm](https://www.npmjs.com/package/crossfin-mcp) — Package
+- [crossfin.dev](https://crossfin.dev) -- Dashboard & API
+- [live.crossfin.dev](https://live.crossfin.dev) -- Live routing demo
+- [docs.crossfin.dev](https://docs.crossfin.dev) -- Documentation
+- [GitHub](https://github.com/bubilife1202/crossfin) -- Source code
+- [npm](https://www.npmjs.com/package/crossfin-mcp) -- Package

package/dist/index.js

@@ -152,6 +152,17 @@ export default function createServer({ config }) {
                 },
             };
         }
+        if (!('tx' in result)) {
+            return {
+                content: [{ type: 'text', text: result.error }],
+                structuredContent: {
+                    transactionId: '',
+                    fromBalanceKrw: -1,
+                    toBalanceKrw: -1,
+                },
+                isError: true,
+            };
+        }
         const out = {
             transactionId: result.tx.id,
             fromBalanceKrw: result.fromBalanceKrw,
@@ -240,7 +251,7 @@ export default function createServer({ config }) {
         title: 'Get service',
         description: 'Get detailed information about a specific service by ID',
         inputSchema: z.object({
-            serviceId: z.string().describe('Service ID (e.g. "svc_kimchi_premium")'),
+            serviceId: z.string().describe('Service ID (e.g. "crossfin_kimchi_premium")'),
         }),
     }, async ({ serviceId }) => {
         try {

package/dist/ledgerStore.js

@@ -67,6 +67,16 @@ export async function transfer(filePath, input) {
         return null;
     if (from.balanceKrw < amount)
         return null;
+    // Budget enforcement: check daily spend limit before executing
+    if (db.budget.dailyLimitKrw !== null) {
+        const todaySpent = getDailySpent(db, input.fromWalletId);
+        if (todaySpent + amount > db.budget.dailyLimitKrw) {
+            const remaining = Math.max(0, db.budget.dailyLimitKrw - todaySpent);
+            return {
+                error: `Daily budget exceeded. Limit: ${db.budget.dailyLimitKrw} KRW, spent today: ${todaySpent} KRW, remaining: ${remaining} KRW, requested: ${amount} KRW`,
+            };
+        }
+    }
     from.balanceKrw -= amount;
     to.balanceKrw += amount;
     const tx = {
@@ -82,6 +92,19 @@ export async function transfer(filePath, input) {
     await writeDb(filePath, db);
     return { tx, fromBalanceKrw: from.balanceKrw, toBalanceKrw: to.balanceKrw };
 }
+/** Sum all outgoing transfers from a wallet for today (UTC). */
+function getDailySpent(db, walletId) {
+    const todayPrefix = new Date().toISOString().slice(0, 10); // "YYYY-MM-DD"
+    let total = 0;
+    for (const tx of db.transactions) {
+        if (!tx.at.startsWith(todayPrefix))
+            continue;
+        if (tx.fromWalletId === walletId) {
+            total += tx.amountKrw;
+        }
+    }
+    return total;
+}
 export async function listTransactions(filePath, input) {
     const db = await readDb(filePath);
     const limit = Math.max(1, Math.min(200, Math.round(input.limit)));

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "crossfin-mcp",
   "private": false,
-  "version": "1.8.8",
+  "version": "1.12.0",
   "mcpName": "io.github.bubilife1202/crossfin",
   "description": "CrossFin MCP server for service discovery and paid x402 API execution",
   "bin": {