NANO MCP

NANO MCP Server - AI Agent Integration Guide

For AI Agents: This server is designed specifically for autonomous agents. All errors are self-documenting with step-by-step guidance. No external documentation needed.

---

🌐 Production Server URL

USE THIS URL: https://nano-mcp.replit.app

All requests go to: https://nano-mcp.replit.app (POST requests with JSON-RPC 2.0 format)

Quick Example:

curl -X POST https://nano-mcp.replit.app \

-H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}'

---

🤖 Quick Start for AI Agents

Production Server (RECOMMENDED)

Server URL: https://nano-mcp.replit.app

No installation needed! The server is already running. Just start making requests.

Step 1: Test Connection

POST https://nano-mcp.replit.app

{ "jsonrpc": "2.0", "method": "initialize", "params": {}, "id": 1 }

Step 2: You're Ready!

The server responds with all available methods. Start using them immediately.

---

🔍 JSON Schema Auto-Discovery (NEW!)

Zero-Shot Integration for AI Agents

🎯 No documentation reading required! Fetch the complete JSON Schema and auto-generate your client code:

# Get complete JSON Schema with all 16 tools

GET https://nano-mcp.replit.app/schema

Get TypeScript definitions

GET https://nano-mcp.replit.app/schema/typescript

Get OpenAPI 3.0 spec (Swagger compatible)

GET https://nano-mcp.replit.app/openapi.json

Schema Features

• ✅ Input/Output Schemas - Full JSON Schema with validation patterns
• ✅ Ready-to-Use Examples - Copy-paste examples for every tool
• ✅ Type Definitions - TypeScript .d.ts for type-safe clients
• ✅ Parameter Validation - Regex patterns for addresses, keys, amounts
• ✅ Error Schemas - All 29 error codes with handling guidance
• ✅ Performance Notes - Expected durations and timeout recommendations
• ✅ Prerequisites - Dependency information for each operation

Quick Schema Usage

# Get schema for specific tool

GET https://nano-mcp.replit.app/schema/tools/sendTransaction

Get examples for a tool

GET https://nano-mcp.replit.app/schema/examples/generateWallet

Validate parameters before sending

POST https://nano-mcp.replit.app/schema/validate/sendTransaction { "fromAddress": "...", "toAddress": "...", "amountRaw": "...", "privateKey": "..." }

Get tools by category (query, transaction, utility, etc.)

GET https://nano-mcp.replit.app/schema/category/transaction

Get all error codes

GET https://nano-mcp.replit.app/schema/errors

Code Generation Example

// 1. Download TypeScript definitions

// curl https://nano-mcp.replit.app/schema/typescript > nano-mcp.d.ts

// 2. Import types import type { SendTransactionParams, SendTransactionResult } from './nano-mcp';

// 3. Use with full type safety const params: SendTransactionParams = { fromAddress: "nano_...", toAddress: "nano_...", amountRaw: "1000000000000000000000000000", privateKey: "..." }; // TypeScript validates all fields!

📖 Complete Guide: See docs/JSON_SCHEMA_AI_AGENT_GUIDE.md for detailed schema integration patterns.

⏱️ Estimated Integration Time: 5 minutes (vs. hours of documentation reading)

---

Local Development (Optional)

If you need to run locally for development:

cd NANO_MCP_SERVER

npm install npm start

Local server runs on: `http://localhost:8080`

---

⚡ Fastest Integration Path (AI Agents: START HERE)

Complete workflow in 5-6 calls, 30-60 seconds:

// STEP 1: Setup test wallets (1 call, < 1s)

POST https://nano-mcp.replit.app {"jsonrpc":"2.0","method":"setupTestWallets","params":{},"id":1} → Returns: wallet addresses + private keys

// STEP 2: Human funds both addresses (30-60s wait) // → Send 0.1+ NANO to each address

// STEP 3: Check BOTH wallets in parallel (2 calls, 4-6s) POST https://nano-mcp.replit.app {"jsonrpc":"2.0","method":"getAccountStatus","params":{"address":"wallet1_address"},"id":1} {"jsonrpc":"2.0","method":"getAccountStatus","params":{"address":"wallet2_address"},"id":2} → Returns: balance, pending blocks, needsAction

// STEP 4: Follow needsAction automatically (2 calls, 16-24s) POST https://nano-mcp.replit.app {"jsonrpc":"2.0","method":"initializeAccount","params":{"address":"wallet1","privateKey":"key1"},"id":1} {"jsonrpc":"2.0","method":"initializeAccount","params":{"address":"wallet2","privateKey":"key2"},"id":2} → Returns: initialized confirmation

// STEP 5: Send transaction (1 call, 10-15s) POST https://nano-mcp.replit.app {"jsonrpc":"2.0","method":"sendTransaction","params":{ "fromAddress":"wallet1", "toAddress":"wallet2", "amountRaw":"50000000000000000000000000", "privateKey":"key1" },"id":1} → Returns: transaction hash

// DONE! ✅ Total: 6 calls, ~60 seconds (including human wait)

⏱️ Expected Response Times

⚠️ CRITICAL: Work Generation Performance

Proof-of-Work (PoW) generation time varies significantly by system:

• Fast systems: 10-15 seconds
• Slower systems: 30-60 seconds
• ALWAYS set 60-second timeout minimum for transaction functions (initializeAccount, sendTransaction, receiveAllPending)

If experiencing timeouts:

1. Increase timeout to 90-120 seconds
2. Check system CPU availability
3. Don't retry immediately - work might still be processing
4. Check account status after timeout - transaction may have completed

❌ DON'T Do These (Time Wasters)

1. Don't call `getBalance` then `getAccountStatus`

// ❌ INEFFICIENT: 2 calls, 4-6s

await call('getBalance', {address}) // Returns: balance, pending await call('getAccountStatus', {address}) // Returns: balance, pending + more

// ✅ EFFICIENT: 1 call, 2-3s await call('getAccountStatus', {address}) // Returns: everything you need

2. Don't call `checkTestWalletsFunding` repeatedly

// ❌ INEFFICIENT: Shows 0 until manually updated

await call('checkTestWalletsFunding') // Returns: bothFunded: false await call('checkTestWalletsFunding') // Still false (not auto-updating)

// ✅ EFFICIENT: Check blockchain directly await call('getAccountStatus', {address}) // Shows pending blocks immediately

3. Don't set short timeouts on transactions

// ❌ FAILS: Work generation takes 10-15 seconds

await call('sendTransaction', {...}, {timeout: 5000}) // Times out!

// ✅ WORKS: Proper timeout await call('sendTransaction', {...}, {timeout: 30000}) // Completes successfully

4. Don't test functions sequentially when independent

// ❌ SLOW: 6 seconds total

await call('getAccountStatus', {address: wallet1}) // 3s await call('getAccountStatus', {address: wallet2}) // 3s

// ✅ FAST: 3 seconds total await Promise.all([ call('getAccountStatus', {address: wallet1}), call('getAccountStatus', {address: wallet2}) ]) // Both in 3s

💡 Pro Tips for AI Agents

1. Use `getAccountStatus` for everything - It replaces getBalance, getAccountInfo, getPendingBlocks
2. Follow `needsAction` array - Auto-recovery without trial-and-error
3. Batch independent calls - Use Promise.all or batch requests
4. Set generous timeouts - 60s minimum for transactions (system performance varies)
5. Save setupTestWallets response - Don't call getTestWallets unless retrieving
6. Don't retry on timeout - Check account status first, transaction may have completed
7. Expect work generation variability - 10-60s depending on system load

📊 Optimization Impact

Result: Faster integration, lower costs, fewer errors.

---

🎯 What This Server Does

NANO MCP Server provides JSON-RPC 2.0 API for NANO cryptocurrency operations with:

• ✅ Self-documenting errors - Every error tells you exactly what to do next
• ✅ Helper functions - Convert units, check account status automatically
• ✅ Test wallet system - Generate and manage test wallets for development
• ✅ No external docs needed - All information in API responses

NANO Cryptocurrency Features:

• Instant transactions (< 1 second)
• Zero fees
• Eco-friendly (minimal energy)
• Perfect for automated AI systems

---

📋 Available MCP Functions (17 Total)

Initialization (1)

1. initialize - Get server capabilities and all available functions

Core Functions (8)

1. generateWallet - Create new NANO wallet
2. getBalance - Check account balance
3. getAccountInfo - Get detailed account data
4. getPendingBlocks - List pending transactions
5. initializeAccount - Open/activate new account
6. sendTransaction - Send NANO (with enhanced errors)
7. receiveAllPending - Receive all pending blocks
8. generateQrCode - Create payment QR code with base64 PNG

Helper Functions (3) - For Autonomous Agents

1. `convertBalance` - Convert NANO ↔ raw units
2. `getAccountStatus` - One call shows: balance, pending, capabilities, what actions needed
3. `nanoConverterHelp` - NEW! Comprehensive guide for Nano (XNO) conversions, formats, and number handling (essential for clients unfamiliar with Nano)

Test Wallet Functions (5) - For Development

1. setupTestWallets - Generate two test wallets (requires human funding)
2. getTestWallets - Retrieve test wallet info
3. updateTestWalletBalance - Update wallet balance tracking
4. checkTestWalletsFunding - Check if wallets are ready
5. resetTestWallets - Delete and start fresh

---

🚀 Complete Workflow for AI Agents

Workflow: Send NANO Transaction

// Step 1: Check account status first (ALWAYS DO THIS)

POST https://nano-mcp.replit.app { "jsonrpc": "2.0", "method": "getAccountStatus", "params": { "address": "nano_your_address" }, "id": 1 }

// Response shows: // - initialized: true/false // - balance: {raw, nano} // - pending: {count, amount} // - needsAction: [array of required actions] // - readyForTesting: true/false

// Step 2: Handle any required actions // If needsAction includes "initializeAccount": { "jsonrpc": "2.0", "method": "initializeAccount", "params": { "address": "nano_your_address", "privateKey": "your_private_key" }, "id": 2 }

// If needsAction includes "receiveAllPending": { "jsonrpc": "2.0", "method": "receiveAllPending", "params": { "address": "nano_your_address", "privateKey": "your_private_key" }, "id": 3 }

// Step 3: Convert amount to raw units { "jsonrpc": "2.0", "method": "convertBalance", "params": { "amount": "0.1", "from": "nano", "to": "raw" }, "id": 4 } // Returns: {"converted": "100000000000000000000000000000"}

// Step 4: Send transaction { "jsonrpc": "2.0", "method": "sendTransaction", "params": { "fromAddress": "nano_sender", "toAddress": "nano_recipient", "amountRaw": "100000000000000000000000000", "privateKey": "sender_private_key" }, "id": 5 }

// Success: {"success": true, "hash": "..."} // Error: Detailed error with nextSteps (see Error Handling section)

---

⚡ Quick Reference: Common Tasks

Task 1: Generate New