{"name":"CrossFin Agent Guide","version":"1.18.0","overview":{"what":"CrossFin is a service gateway for AI agents. Discover, compare, and call x402/REST services through a single API.","services":"Use GET /api/registry/stats for the current active service counts.","payment":"CrossFin services use x402 protocol — pay per API call with USDC on Base mainnet. No API key, no subscription.","free":"Registry search, categories, stats, and the arbitrage demo are all free."},"quickStart":{"step1":{"title":"Search for services","endpoint":"GET /api/registry/search?q=crypto","description":"Search by keyword. Returns matching services with endpoint, price, and payment metadata.","example":"curl https://crossfin.dev/api/registry/search?q=korea"},"step2":{"title":"Get service details","endpoint":"GET /api/registry/{id}","description":"Get full details for a specific service including endpoint URL, pricing, inputSchema/outputExample, and (for CrossFin services) a guide field.","example":"curl https://crossfin.dev/api/registry/crossfin_kimchi_premium"},"step3":{"title":"Call the service","description":"Call the service endpoint directly. For x402 services, the first request returns HTTP 402 with payment details. Sign the payment and resend.","freeExample":"curl https://crossfin.dev/api/arbitrage/demo","paidExample":"Requires x402 client library — see x402Payment section below."}},"freeEndpoints":[{"path":"/api/health","description":"Health check"},{"path":"/api/registry/search?q=","description":"Search services by keyword"},{"path":"/api/registry","description":"List all services (filterable by category)"},{"path":"/api/registry/categories","description":"List categories with counts"},{"path":"/api/registry/stats","description":"Total service counts"},{"path":"/api/registry/{id}","description":"Service details by ID"},{"path":"/api/arbitrage/demo","description":"Free route spread preview (top 3 pairs)"},{"path":"/api/analytics/overview","description":"Gateway usage analytics"},{"path":"/api/analytics/funnel/overview","description":"Web onboarding conversion funnel analytics"},{"path":"/api/analytics/funnel/events","description":"Track web onboarding events (POST)"},{"path":"/api/stats","description":"Public-safe summary (sensitive counts redacted)"},{"path":"/api/openapi.json","description":"OpenAPI 3.1 specification"},{"path":"/api/docs/guide","description":"This guide"},{"path":"/.well-known/crossfin.json","description":"CrossFin discovery metadata for agents"},{"path":"/.well-known/x402.json","description":"x402 discovery metadata (payment/network/endpoints)"},{"path":"/.well-known/glama.json","description":"Glama.ai ownership verification"},{"path":"/api/route/exchanges","description":"List supported exchanges with trading fees and supported coins"},{"path":"/api/route/fees","description":"Fee comparison table — trading + withdrawal fees for all exchanges"},{"path":"/api/route/fees?coin=KAIA","description":"Fee comparison for a specific coin"},{"path":"/api/route/pairs","description":"All supported trading pairs with live Binance prices"},{"path":"/api/route/status","description":"Exchange API health check (online/offline per exchange)"},{"path":"/api/routing/optimal","description":"Free live routing endpoint for RouteGraph (orderbook/slippage + real fee table)"},{"path":"/api/acp/status","description":"ACP protocol capabilities and supported exchanges"},{"path":"POST /api/acp/quote","description":"Request a free routing quote (ACP-compatible, preview-only)"},{"path":"POST /api/acp/execute","description":"Start tracked execution (step-level orchestration simulation)"},{"path":"GET /api/acp/executions/{execution_id}","description":"Get execution progress and step-by-step state"},{"path":"POST /api/telegram/webhook","description":"Telegram bot webhook endpoint for /route command integration"}],"notes":["Proxy endpoints (/api/proxy/:serviceId) require X-Agent-Key to prevent abuse.","Regional fiat exchanges (KRW: Upbit/Bithumb/Coinone/GoPax, JPY: bitFlyer, INR: WazirX, IDR: Indodax, THB: Bitkub) and global exchanges (Binance/OKX/Bybit) are all supported.","Routing engine supports bidirectional transfers: Korea→Global and Global→Korea."],"crossfinServices":{"_note":"33 cataloged paid endpoints organized by category (+2 utility paid endpoints: /api/premium/report, /api/premium/enterprise). All paid via x402 with USDC on Base mainnet.","crypto_arbitrage":[{"id":"crossfin_kimchi_premium","endpoint":"/api/premium/arbitrage/kimchi","price":"$0.05","description":"Real-time Route Spread Index — price spread between Korean (Bithumb) and global (Binance) exchanges for 13 crypto pairs including KAIA, SUI, APT."},{"id":"crossfin_kimchi_premium_history","endpoint":"/api/premium/arbitrage/kimchi/history","price":"$0.05","description":"Hourly snapshots of route spread data from D1 database, up to 7 days lookback. Query by coin and time range."},{"id":"crossfin_arbitrage_opportunities","endpoint":"/api/premium/arbitrage/opportunities","price":"$0.10","description":"AI-ready market condition indicators: POSITIVE_SPREAD/NEUTRAL/NEGATIVE_SPREAD with slippage, premium trends, transfer time risk, and signal strength scores."},{"id":"crossfin_cross_exchange","endpoint":"/api/premium/market/cross-exchange","price":"$0.08","description":"Compare prices across 4 Korean exchanges with SPREAD_OPPORTUNITY/NEUTRAL_SIGNAL/MONITORING indicators and best buy/sell routing."},{"id":"crossfin_crypto_korea_5exchange","endpoint":"/api/premium/crypto/korea/5exchange?coin=BTC","price":"$0.08","description":"Compare crypto prices across 4 Korean exchanges (Upbit, Bithumb, Coinone, GoPax) for any coin."}],"exchange_data":[{"id":"crossfin_bithumb_orderbook","endpoint":"/api/premium/bithumb/orderbook?pair=BTC","price":"$0.02","description":"Live 30-level orderbook depth from Bithumb for any KRW trading pair."},{"id":"crossfin_bithumb_volume","endpoint":"/api/premium/bithumb/volume-analysis","price":"$0.03","description":"24h volume distribution, concentration, and unusual volume detection across Bithumb."},{"id":"crossfin_upbit_ticker","endpoint":"/api/premium/market/upbit/ticker?market=KRW-BTC","price":"$0.02","description":"Upbit spot ticker data for any KRW market pair."},{"id":"crossfin_upbit_orderbook","endpoint":"/api/premium/market/upbit/orderbook?market=KRW-BTC","price":"$0.02","description":"Upbit orderbook snapshot for any KRW market pair."},{"id":"crossfin_upbit_signals","endpoint":"/api/premium/market/upbit/signals","price":"$0.05","description":"Trading signals for major KRW markets on Upbit — momentum, relative volume, volatility, and combined bullish/bearish/neutral call."},{"id":"crossfin_upbit_candles","endpoint":"/api/premium/crypto/korea/upbit-candles?coin=BTC&type=days","price":"$0.02","description":"Upbit OHLCV candle data (1m, 5m, 15m, 1h, 4h, daily, weekly, monthly). Up to 200 candles."},{"id":"crossfin_coinone_ticker","endpoint":"/api/premium/market/coinone/ticker?currency=BTC","price":"$0.02","description":"Coinone spot ticker data for any KRW pair."},{"id":"crossfin_crypto_korea_exchange_status","endpoint":"/api/premium/crypto/korea/exchange-status","price":"$0.03","description":"Bithumb deposit/withdrawal status for all coins — check before transferring."}],"market_sentiment":[{"id":"crossfin_korea_sentiment","endpoint":"/api/premium/market/korea","price":"$0.03","description":"Korean crypto market sentiment — top gainers, losers, volume leaders, and overall market mood (bullish/bearish/neutral)."},{"id":"crossfin_korea_headlines","endpoint":"/api/premium/news/korea/headlines","price":"$0.03","description":"Korean crypto/finance news headlines via Google News RSS feed."}],"fx_rates":[{"id":"crossfin_usdkrw","endpoint":"/api/premium/market/fx/usdkrw","price":"$0.01","description":"USD/KRW exchange rate for converting Korean exchange prices."},{"id":"crossfin_crypto_korea_fx_rate","endpoint":"/api/premium/crypto/korea/fx-rate","price":"$0.01","description":"Real-time KRW/USD exchange rate from Upbit CRIX with 52-week high/low context."}],"bundle_apis":[{"id":"crossfin_morning_brief","endpoint":"/api/premium/morning/brief","price":"$0.20","description":"Morning Brief — route spread + FX rate + headlines in one call. Best value for daily market overview."},{"id":"crossfin_crypto_snapshot","endpoint":"/api/premium/crypto/snapshot","price":"$0.15","description":"Crypto Snapshot — 4-exchange BTC prices + route spread + Bithumb volume + FX rate in one call."},{"id":"crossfin_kimchi_stats","endpoint":"/api/premium/kimchi/stats","price":"$0.15","description":"Route Spread Stats — current spreads + 24h trend + arbitrage signal + cross-exchange spread in one call."}],"routing_engine":[{"id":"crossfin_route_find","endpoint":"/api/premium/route/find?from=bithumb:KRW&to=binance:USDC&amount=1000000","price":"$0.10","description":"Find optimal crypto transfer route across 14 exchanges (Bithumb, Upbit, Coinone, GoPax, bitFlyer, WazirX, bitbank, Indodax, Bitkub, Binance, OKX, Bybit, KuCoin, Coinbase). Compares 13 bridge coins, estimates fees and slippage. Bidirectional: regional fiat↔global."}]},"routingEngine":{"overview":"CrossFin Routing Engine finds the cheapest, fastest, or balanced crypto transfer route across 14 exchanges. It compares 13 bridge coins, models trading fees, withdrawal fees, slippage, and transfer times.","supportedExchanges":[{"id":"bithumb","country":"South Korea","tradingFee":"0.25%","note":"Lowest withdrawal fee policy"},{"id":"upbit","country":"South Korea","tradingFee":"0.05%","note":"Largest Korean exchange by volume (KRW market)"},{"id":"coinone","country":"South Korea","tradingFee":"0.20%","note":"Supports KAIA"},{"id":"gopax","country":"South Korea","tradingFee":"0.20%","note":"Supports KAIA, no DOT"},{"id":"binance","country":"Global","tradingFee":"0.10%","note":"Global exchange, trades in USDT/USDC"},{"id":"okx","country":"Global","tradingFee":"0.08%","note":"Deep global spot liquidity, strong USDT market depth"},{"id":"bybit","country":"Global","tradingFee":"0.10%","note":"High Asian spot liquidity with stable public API"},{"id":"kucoin","country":"Global","tradingFee":"0.10%","note":"Global exchange, trades in USDC/USDT/USD with deep altcoin liquidity"},{"id":"coinbase","country":"Global","tradingFee":"0.50%","note":"Global exchange, trades in USD/USDC/USDT with reliable fiat on/off ramps"},{"id":"bitflyer","country":"Japan","tradingFee":"0.15%","note":"Largest Japanese exchange, synthetic pricing via global feed × FX"},{"id":"wazirx","country":"India","tradingFee":"0.20%","note":"Indian exchange with INR pairs"}],"bridgeCoins":["XRP","SOL","TRX","KAIA","ETH","BTC","ADA","DOGE","AVAX","DOT","LINK","SUI","APT"],"bridgeCoinNotes":{"fastest":"XRP (~30s), SOL (~1m), TRX (~1m), KAIA (~1m)","cheapest":"XRP, TRX, KAIA (very low withdrawal fees)","KAIA":"Kaia (formerly Klaytn). 1-second blocks with instant PBFT finality. Available on Binance, Bithumb, Coinone, GoPax. NOT on Upbit.","notOnAllExchanges":"DOT not on GoPax. KAIA not on Upbit. Check /api/route/exchanges for per-exchange coin support."},"strategies":[{"id":"cheapest","description":"Minimize total fees (trading + withdrawal + slippage). Default."},{"id":"fastest","description":"Minimize transfer time. Prefers XRP, SOL, TRX, KAIA."},{"id":"balanced","description":"Weighted combination of cost and speed."}],"directions":{"koreaToGlobal":{"example":"from=bithumb:KRW&to=binance:USDC&amount=1000000","description":"Transfer KRW from Korean exchange to USDC on Binance. Common for taking profits from route spread."},"globalToKorea":{"example":"from=binance:USDC&to=bithumb:KRW&amount=1000","description":"Transfer USDC from Binance to KRW on Korean exchange. Profitable when route spread is positive (buy cheap globally, sell expensive in Korea)."}},"responseIncludes":["Optimal route with step-by-step execution plan","Up to 10 alternative routes ranked by strategy","Fee breakdown (trading + withdrawal)","Estimated output amount and net profit/loss %","Transfer time estimate per bridge coin","User-friendly summary with recommendation (GOOD_DEAL/PROCEED/EXPENSIVE/VERY_EXPENSIVE)","Live exchange rates used for calculation"],"freeEndpoints":[{"path":"/api/route/exchanges","description":"List all 14 exchanges with supported coins and fees"},{"path":"/api/route/fees","description":"Full fee comparison table (add ?coin=KAIA to filter)"},{"path":"/api/route/pairs","description":"All trading pairs with live Binance prices"},{"path":"/api/route/status","description":"Exchange API health check"},{"path":"/api/routing/optimal?from=bithumb:KRW&to=binance:USDC&amount=1000000","description":"Live optimal route + alternatives + D1 fee table (free, RouteGraph)"}],"paidEndpoint":{"path":"/api/premium/route/find","price":"$0.10","description":"Full route analysis with step-by-step execution plan"},"examples":{"cheapestKoreaToGlobal":"curl \"https://crossfin.dev/api/premium/route/find?from=bithumb:KRW&to=binance:USDC&amount=1000000&strategy=cheapest\"","fastestGlobalToKorea":"curl \"https://crossfin.dev/api/premium/route/find?from=binance:USDC&to=coinone:KRW&amount=500&strategy=fastest\"","freeExchanges":"curl https://crossfin.dev/api/route/exchanges","freeFees":"curl \"https://crossfin.dev/api/route/fees?coin=KAIA\""}},"acpProtocol":{"overview":"Agentic Commerce Protocol (ACP) — standardized quote/execute flow for agent-to-agent commerce. CrossFin ACP lets agents request routing quotes and run tracked step-level execution orchestration without x402 payment.","endpoints":[{"method":"POST","path":"/api/acp/quote","price":"Free","description":"Request a routing quote. Returns preview of optimal route (no step-by-step details). For full analysis, upgrade to /api/premium/route/find ($0.10)."},{"method":"POST","path":"/api/acp/execute","price":"Free","description":"Start execution orchestration from quote_id. Returns execution_id and real-time step state."},{"method":"GET","path":"/api/acp/executions/{execution_id}","price":"Free","description":"Get execution progress, ETA, and per-step status."},{"method":"GET","path":"/api/acp/status","price":"Free","description":"ACP protocol capabilities, supported exchanges, bridge coins, and execution mode."}],"quoteRequestExample":{"method":"POST","url":"https://crossfin.dev/api/acp/quote","body":{"from_exchange":"bithumb","from_currency":"KRW","to_exchange":"binance","to_currency":"USDC","amount":1000000,"strategy":"cheapest"}},"compatibleWith":["locus","x402","openai-acp"],"executionMode":"tracked_orchestration","liveExecution":"requires_exchange_api_key_integration"},"useCases":[{"name":"Daily Market Brief Agent","description":"Agent that sends a daily summary of Korean markets to a Slack/Discord channel.","flow":"1. Call /api/premium/morning/brief ($0.20) for full market overview. 2. Parse route spread, FX rate, headlines. 3. Format and post to channel.","cost":"$0.20/day"},{"name":"Route Spread Monitor","description":"Agent that monitors route spread and alerts when arbitrage opportunity appears.","flow":"1. Poll /api/premium/arbitrage/opportunities ($0.10) every 15 minutes. 2. When indicator=POSITIVE_SPREAD, call /api/premium/route/find ($0.10) for optimal route. 3. Alert user with route details.","cost":"~$10/day (polling every 15m)"},{"name":"Cross-Exchange Arbitrage Bot","description":"Agent that finds the best exchange to buy/sell crypto across Korean exchanges.","flow":"1. Call /api/premium/crypto/korea/5exchange?coin=BTC ($0.08) to compare prices. 2. If spread > threshold, call /api/premium/route/find ($0.10) for transfer route. 3. Execute trade manually or via API.","cost":"$0.18 per check"}],"x402Payment":{"protocol":"x402 (HTTP 402 Payment Required)","network":"Base mainnet (eip155:8453)","currency":"USDC","facilitator":"Coinbase x402 facilitator","flow":["1. Send GET request to paid endpoint","2. Receive HTTP 402 with PAYMENT-REQUIRED header containing payment details (base64 JSON)","3. Parse payment details (amount, recipient, network)","4. Sign USDC transfer with your wallet","5. Resend request with PAYMENT-SIGNATURE header","6. Receive paid response (HTTP 200)"],"libraries":{"javascript":"@x402/fetch (wrapFetchWithPayment)","python":"x402 (pip install x402)"},"walletRequirement":"You need a wallet with USDC on Base mainnet. Minimum $0.01 for cheapest endpoint.","codeExamples":{"curl":"# Free endpoint (no payment)\ncurl https://crossfin.dev/api/arbitrage/demo\n\n# Inspect PAYMENT-REQUIRED header (paid endpoint)\ncurl -s -D - https://crossfin.dev/api/premium/arbitrage/kimchi -o /dev/null","javascript":"import { x402Client, wrapFetchWithPayment } from '@x402/fetch';\nimport { registerExactEvmScheme } from '@x402/evm/exact/client';\nimport { privateKeyToAccount } from 'viem/accounts';\n\nconst signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY);\nconst client = new x402Client();\nregisterExactEvmScheme(client, { signer });\n\nconst paidFetch = wrapFetchWithPayment(fetch, client);\nconst res = await paidFetch('https://crossfin.dev/api/premium/arbitrage/kimchi', { method: 'GET' });\nconsole.log(await res.json());","python":"import os\nfrom eth_account import Account\nfrom x402 import x402ClientSync\nfrom x402.http.clients import x402_requests\nfrom x402.mechanisms.evm import EthAccountSigner\nfrom x402.mechanisms.evm.exact.register import register_exact_evm_client\n\nclient = x402ClientSync()\naccount = Account.from_key(os.environ['EVM_PRIVATE_KEY'])\nregister_exact_evm_client(client, EthAccountSigner(account))\n\nwith x402_requests(client) as session:\n    r = session.get('https://crossfin.dev/api/premium/arbitrage/kimchi')\n    print(r.json())"}},"mcpServer":{"description":"CrossFin MCP server for any MCP-compatible client.","npmPackage":"crossfin-mcp","install":"npx -y crossfin-mcp","globalInstall":"npm i -g crossfin-mcp && crossfin-mcp","localBuild":"cd apps/mcp-server && npm install && npm run build","notes":["MCP servers are typically launched by the client (e.g. Cursor, Windsurf, or any MCP-compatible app). You usually do not run the stdio server directly in a terminal.","Set EVM_PRIVATE_KEY to enable paid calls; leave it unset if you only want free browsing/search tools."],"tools":[{"name":"search_services","description":"Search the service registry by keyword"},{"name":"list_services","description":"List services with optional category filter"},{"name":"get_service","description":"Get details for a specific service"},{"name":"list_categories","description":"List all categories with counts"},{"name":"get_kimchi_premium","description":"Free route spread preview (top 3 pairs)"},{"name":"get_analytics","description":"Gateway usage analytics"},{"name":"get_guide","description":"Get the full CrossFin agent guide"},{"name":"create_wallet","description":"Create a wallet in local ledger"},{"name":"get_balance","description":"Check wallet balance"},{"name":"transfer","description":"Transfer funds between wallets"},{"name":"list_transactions","description":"List recent transactions"},{"name":"set_budget","description":"Set daily spend limit"},{"name":"call_paid_service","description":"Call a paid API with automatic x402 USDC payment (returns data + txHash + basescan link)"},{"name":"find_optimal_route","description":"Find optimal crypto transfer route across 14 exchanges using 13 bridge coins (routing engine)"},{"name":"list_exchange_fees","description":"List supported exchange fees — trading and withdrawal fees for all exchanges (routing engine)"},{"name":"compare_exchange_prices","description":"Compare live exchange prices for routing across 14 exchanges (routing engine)"}],"mcpClientConfig":{"mcpServers":{"crossfin":{"command":"npx","args":["-y","crossfin-mcp"],"env":{"CROSSFIN_API_URL":"https://crossfin.dev","EVM_PRIVATE_KEY":"0x..."}}}},"mcpClientConfigLocalBuild":{"mcpServers":{"crossfin":{"command":"node","args":["/path/to/crossfin/apps/mcp-server/dist/index.js"],"env":{"CROSSFIN_API_URL":"https://crossfin.dev","EVM_PRIVATE_KEY":"0x..."}}}}},"links":{"website":"https://crossfin.dev","liveDemo":"https://live.crossfin.dev","github":"https://github.com/bubilife1202/crossfin","openapi":"https://crossfin.dev/api/openapi.json"},"_disclaimer":"This data is provided \"AS IS\" for informational purposes only. It does not constitute investment advice. Data accuracy, completeness, and timeliness are not guaranteed. All trading decisions are at the user's sole risk. CrossFin is not liable for any losses arising from the use of this data. | 본 데이터는 정보 제공 목적의 \"있는 그대로\" 제공이며, 투자 자문에 해당하지 않습니다. 데이터의 정확성, 완전성, 시의성은 보증되지 않습니다. 모든 거래 결정은 이용자의 책임이며, CrossFin은 본 데이터 사용으로 인한 어떠한 손해에도 책임을 지지 않습니다.","_legal":{"disclaimer":"This data is provided \"AS IS\" for informational purposes only. It does not constitute investment advice. Data accuracy, completeness, and timeliness are not guaranteed. All trading decisions are at the user's sole risk. CrossFin is not liable for any losses arising from the use of this data. | 본 데이터는 정보 제공 목적의 \"있는 그대로\" 제공이며, 투자 자문에 해당하지 않습니다. 데이터의 정확성, 완전성, 시의성은 보증되지 않습니다. 모든 거래 결정은 이용자의 책임이며, CrossFin은 본 데이터 사용으로 인한 어떠한 손해에도 책임을 지지 않습니다.","disclaimerUrl":"https://crossfin.dev/api/legal/disclaimer","tosUrl":"https://crossfin.dev/api/legal/terms","privacyUrl":"https://crossfin.dev/api/legal/privacy","dataProvision":"AS_IS","notInvestmentAdvice":true}}