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

Function	Expected Time	Recommended Timeout
setupTestWallets	< 1s	5s
getAccountStatus	1-3s	10s
initializeAccount	8-60s (varies)	60s
sendTransaction	10-60s (varies)	60s
receiveAllPending	5-60s per block	60s
convertBalance	< 500ms	5s
generateQrCode	< 2s	10s

⚠️ 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

Metric	Inefficient	Optimized	Improvement
Total Calls	10-12	5-6	40-50% ↓
Total Tokens	10,000-15,000	5,000-7,000	50% ↓
Total Time	60-90s	30-60s	40% ↓
Decision Points	5-6	1-2	70% ↓

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)

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

Helper Functions (3) - For Autonomous Agents

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

Test Wallet Functions (5) - For Development

13. setupTestWallets - Generate two test wallets (requires human funding)
14. getTestWallets - Retrieve test wallet info
15. updateTestWalletBalance - Update wallet balance tracking
16. checkTestWalletsFunding - Check if wallets are ready
17. 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 Wallet

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

Returns: address, privateKey, publicKey, seed

Task 2: Check Balance

{"jsonrpc": "2.0", "method": "getBalance", "params": {"address": "nano_xxx"}, "id": 1}

Returns: balance (raw), pending (raw)

Task 3: Convert Units

{"jsonrpc": "2.0", "method": "convertBalance", "params": {"amount": "0.1", "from": "nano", "to": "raw"}, "id": 1}

Returns: converted value with formula

Task 4: Check Account Readiness

{"jsonrpc": "2.0", "method": "getAccountStatus", "params": {"address": "nano_xxx"}, "id": 1}

Returns: Complete status + what to do next

---

🧠 Comprehensive Error Handling for AI Agents

✨ What Makes This Special

The NANO MCP Server has the most comprehensive, AI-agent-friendly error handling:

• 20+ specific error codes for programmatic handling
• Extensive input validation - addresses, private keys, amounts, all parameters
• Auto-detection of common mistakes (e.g., using NANO instead of raw)
• Suggested corrections - server calculates the correct value for you
• Step-by-step recovery - never get stuck on an error
• Zero external documentation needed - all info in the error response

Error Response Structure

All errors include:

• errorCode - Machine-readable code (e.g., "INSUFFICIENT_BALANCE")
• error - Human-readable message
• details - Specific context (what went wrong, expected format, etc.)
• nextSteps - Step-by-step remediation instructions (array)
• relatedFunctions - What functions can help solve this
• exampleRequest - Copy-paste ready correct request
• suggestedCorrection - Auto-corrected values (when applicable)

📋 Complete Error Code List

Validation Errors:

• MISSING_PARAMETER - Required parameter not provided
• METHOD_NOT_FOUND - Invalid MCP method name
• INVALID_ADDRESS_FORMAT - Address missing or wrong type
• INVALID_ADDRESS_PREFIX - Address doesn't start with 'nano_' or 'xrb_'
• INVALID_ADDRESS_LENGTH - Address wrong length
• INVALID_ADDRESS_CHARACTERS - Address has invalid characters
• INVALID_PRIVATE_KEY_FORMAT - Private key missing or wrong type
• INVALID_PRIVATE_KEY_LENGTH - Private key not 64 characters
• INVALID_PRIVATE_KEY_CHARACTERS - Private key not hexadecimal
• INVALID_AMOUNT_FORMAT - Amount missing or wrong type
• AMOUNT_WRONG_UNIT - Smart detection: You used NANO instead of raw
• INVALID_AMOUNT_CHARACTERS - Amount has invalid characters
• INVALID_AMOUNT_ZERO_OR_NEGATIVE - Amount must be positive
• INVALID_AMOUNT_OVERFLOW - Amount too large
• INVALID_CONVERSION_UNITS - Invalid 'from' or 'to' unit
• SAME_CONVERSION_UNITS - Cannot convert same unit
• INVALID_QR_AMOUNT_FORMAT - QR code amount format invalid

Blockchain Errors:

• INSUFFICIENT_BALANCE - Not enough NANO to send
• INSUFFICIENT_WORK - [CRITICAL] Work doesn't meet difficulty threshold (FIXED - just retry)
• ACCOUNT_NOT_INITIALIZED - Account needs to receive first transaction
• ACCOUNT_NOT_INITIALIZED_NO_PENDING - Account has no pending blocks
• PENDING_BLOCKS_NOT_RECEIVED - Should receive pending first
• BLOCKCHAIN_INVALID_BLOCK - Blockchain rejected block
• BLOCKCHAIN_INSUFFICIENT_BALANCE - Blockchain balance check failed
• BLOCKCHAIN_ERROR - General blockchain operation error
• CONVERSION_ERROR - Balance conversion failed

Example: Insufficient Balance Error

Request:

{
    "jsonrpc": "2.0",
    "method": "sendTransaction",
    "params": {
        "fromAddress": "nano_xxx",
        "toAddress": "nano_yyy",
        "amountRaw": "1000000000000000000000000000",
        "privateKey": "key"
    },
    "id": 1
}

Error Response:

{
    "jsonrpc": "2.0",
    "result": {
        "success": false,
        "error": "Insufficient balance",
        "errorCode": "INSUFFICIENT_BALANCE",
        "details": {
            "address": "nano_xxx",
            "currentBalance": "80000000000000000000000000",
            "currentBalanceNano": "0.00016",
            "attemptedAmount": "1000000000000000000000000000",
            "attemptedAmountNano": "0.002",
            "shortfall": "920000000000000000000000000",
            "shortfallNano": "0.00184"
        },
        "nextSteps": [
            "Step 1: Check current balance using getBalance or getAccountInfo",
            "Step 2: Either reduce send amount to maximum 0.00016 NANO or less",
            "Step 3: Or fund account with additional 0.00184 NANO minimum",
            "Step 4: After funding, use receiveAllPending to process pending blocks",
            "Step 5: Retry your send transaction"
        ],
        "relatedFunctions": ["getBalance", "getAccountInfo", "receiveAllPending"],
        "exampleRequest": {
            "jsonrpc": "2.0",
            "method": "getBalance",
            "params": {"address": "nano_xxx"},
            "id": 1
        }
    },
    "id": 1
}

🎯 Smart Auto-Correction Example

You sent NANO instead of raw? The server auto-corrects for you!

Bad Request (NANO instead of raw):

{
    "jsonrpc": "2.0",
    "method": "sendTransaction",
    "params": {
        "fromAddress": "nano_3sender...",
        "toAddress": "nano_3receiver...",
        "amountRaw": "0.1",
        "privateKey": "abc123..."
    },
    "id": 1
}

Smart Error Response:

{
    "success": false,
    "error": "amountRaw appears to be in NANO format, not raw",
    "errorCode": "AMOUNT_WRONG_UNIT",
    "details": {
        "providedValue": "0.1",
        "detectedFormat": "NANO (decimal)",
        "expectedFormat": "raw (integer string)"
    },
    "suggestedCorrection": {
        "originalValue": "0.1",
        "originalUnit": "NANO",
        "correctedValue": "100000000000000000000000000000",
        "correctedUnit": "raw"
    },
    "nextSteps": [
        "Step 1: Use the correctedValue from suggestedCorrection below",
        "Step 2: Retry your request with the raw amount"
    ],
    "exampleConversion": {
        "jsonrpc": "2.0",
        "method": "convertBalance",
        "params": { "amount": "0.1", "from": "nano", "to": "raw" },
        "id": 1
    }
}

AI Agent Action:

// Extract corrected value automatically
if (response.errorCode === "AMOUNT_WRONG_UNIT") {
    const correctedAmount = response.suggestedCorrection.correctedValue;
    // Retry with corrected value: "100000000000000000000000000000"
}

Error Codes Quick Reference

Error Code	What It Means	Auto-Fix Available	Action
INSUFFICIENT_BALANCE	Not enough NANO	Partial (shows shortfall)	Reduce amount or fund
INSUFFICIENT_WORK	PoW below threshold	YES (auto-retry)	Simply retry request
ACCOUNT_NOT_INITIALIZED	Account not opened	Yes (2 solutions)	Call initializeAccount
AMOUNT_WRONG_UNIT	Used NANO not raw	YES (auto-converts)	Use suggestedCorrection
INVALID_ADDRESS_*	Bad address format	Yes (shows format)	Fix address format
INVALID_PRIVATE_KEY_*	Bad key format	Yes (shows format)	Fix private key
MISSING_PARAMETER	Parameter missing	Yes (example shown)	Add missing parameter
METHOD_NOT_FOUND	Invalid method	Yes (lists all methods)	Use correct method

📚 Complete Documentation

For detailed error handling guide: See docs/AI_AGENT_ERROR_HANDLING.md

Topics covered:

• All 29 error codes explained (including INSUFFICIENT_WORK)
• Smart auto-correction examples
• Decision trees for error recovery
• Best practices for AI agents
• Security considerations
• 100% validation coverage details

Decision Tree for Error Handling

Receive Error
  |
  ├─> errorCode == "INSUFFICIENT_BALANCE"
  |     ├─> Check details.shortfall
  |     ├─> Option 1: Reduce amountRaw
  |     └─> Option 2: Fund account
  |
  ├─> errorCode == "ACCOUNT_NOT_INITIALIZED"
  |     ├─> Check details.hasPendingBlocks
  |     ├─> If true: Call initializeAccount
  |     └─> If false: Send NANO to address first
  |
  ├─> errorCode == "PENDING_BLOCKS_NOT_RECEIVED"
  |     └─> Call receiveAllPending
  |
  └─> Other errors
        └─> Follow nextSteps array

---

🧪 Test Wallet System (For Development)

Quick Setup

Step 1: Generate Test Wallets

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

Response (Save These Addresses!):

{
    "jsonrpc": "2.0",
    "result": {
        "wallet1": {
            "address": "nano_3h3m6kfckrxpc4t33jn36eu8smfpukwuq1zq4hy35dh4a7drs6ormhwhkncn",
            "privateKey": "6b84f1b17dd0a6176df2b500b40ce17c0db5bd8042ca8ac04173dd74bac303b8",
            "publicKey": "bc33249aa963b650b410c68123366ccdb6dcb9bb83f713fc11ade241578c92b8",
            "seed": "cbce4f1ec09296e245f4125b8f89930cc490599f30697491bc03e4915041c146",
            "balance": "0",
            "funded": false
        },
        "wallet2": {
            "address": "nano_39isqp67xsse8cj5igtonuiwicqy8p6txa57mbjd8bcyip7ggrai4bby1x1w",
            "privateKey": "9279a138a0000ac09477be901210b58b80e503835744f08c70690d94d57e70b9",
            "publicKey": "9e19bd885ee72c32a2383b55a6e1c82afe3589aea0659a62b3255e858ae76110",
            "seed": "bf69ae134c00c0e24aabb97ac4a0a7e1933fdd28672a1b0caf9b1c7ea193d917",
            "balance": "0",
            "funded": false
        },
        "created": "2025-11-11T15:25:23.161Z",
        "status": "awaiting_funding",
        "fundingInstructions": [
            "Send test NANO to Wallet 1: nano_3h3m6kfckrxpc4t33jn36eu8smfpukwuq1zq4hy35dh4a7drs6ormhwhkncn",
            "Send test NANO to Wallet 2: nano_39isqp67xsse8cj5igtonuiwicqy8p6txa57mbjd8bcyip7ggrai4bby1x1w",
            "After funding, use checkFundingStatus to verify both wallets are funded",
            "Recommended test amount: 0.1 NANO or more per wallet"
        ]
    },
    "id": 1
}

⚠️ IMPORTANT - ACTION REQUIRED: HUMAN MUST FUND THESE WALLETS!

1. Copy Wallet 1 Address: nano_3h3m6kfckrxpc4t33jn36eu8smfpukwuq1zq4hy35dh4a7drs6ormhwhkncn
2. Copy Wallet 2 Address: nano_39isqp67xsse8cj5igtonuiwicqy8p6txa57mbjd8bcyip7ggrai4bby1x1w
3. Send test NANO to BOTH addresses (0.1 NANO recommended per wallet)
4. Use a NANO faucet or your own wallet to send test funds
5. Wait for confirmation (usually < 5 seconds)

Step 2: Check Funding Status

{
    "jsonrpc": "2.0",
    "method": "checkTestWalletsFunding",
    "params": {},
    "id": 2
}

Step 3: When Both Funded, Start Testing! Response will show "bothFunded": true when ready.

Test Wallet Workflow

setupTestWallets
     ↓
Fund addresses (external)
     ↓
initializeAccount (both wallets)
     ↓
updateTestWalletBalance (both wallets)
     ↓
checkTestWalletsFunding
     ↓
Ready for send/receive testing!

---

💡 Decision Tree: Complete Transaction Flow

START
  |
  v
Call: getAccountStatus(address)
  |
  ├─> initialized: false
  |   |
  |   ├─> hasPendingBlocks: true
  |   |   └─> Call: initializeAccount
  |   |
  |   └─> hasPendingBlocks: false
  |       └─> STOP: Fund account first
  |
  └─> initialized: true
      |
      ├─> pendingCount > 0
      |   └─> Call: receiveAllPending
      |
      └─> canSend: true
          |
          v
      Call: convertBalance(amount, "nano", "raw")
          |
          v
      Call: sendTransaction(...)
          |
          ├─> success: true
          |   └─> DONE!
          |
          └─> success: false
              └─> Parse errorCode
                  └─> Follow nextSteps in error response

---

📊 Unit Conversion (Important!)

NANO uses TWO units:

• NANO (decimal, e.g., "0.1") - Human-readable
• raw (integer string) - Blockchain uses this

Conversion:

• 1 NANO = 10³⁰ raw
• Always use raw for amountRaw parameter

Quick Reference:

NANO	Raw
0.000001	1000000000000000000000000
0.001	1000000000000000000000000000
0.01	10000000000000000000000000000
0.1	100000000000000000000000000000
1.0	1000000000000000000000000000000

Use convertBalance function:

{"jsonrpc": "2.0", "method": "convertBalance", "params": {"amount": "0.1", "from": "nano", "to": "raw"}, "id": 1}

---

🔧 Setup and Configuration

Installation

# Clone or download
cd NANO_MCP_SERVER

# Install dependencies
npm install

# Run server
npm start

Environment Variables (Optional)

MCP_PORT=8080                    # Server port (default: 8080)
MCP_TRANSPORT=http               # Transport type (default: http)
NANO_RPC_URL=https://...         # NANO RPC node (has default)
NANO_REPRESENTATIVE=nano_xxx     # Representative (has default)

Testing

# Run tests (21 tests for test wallet system)
npm test

---

📚 Complete Function Reference

initialize

Purpose: Initialize the MCP server and get list of all available capabilities/functions Parameters: None Returns: Server information and list of all available MCP tools with their descriptions

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

Response includes:

• protocolVersion - MCP protocol version
• serverInfo - Server name and version
• capabilities - Server capabilities
• tools - Complete list of all available MCP functions with descriptions and parameter schemas

Use Case: First call to discover what the server can do and what functions are available

generateWallet

Purpose: Create new NANO wallet Parameters: None Returns: address, privateKey, publicKey, seed

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

getBalance

Purpose: Check account balance Parameters: address Returns: balance (raw), pending (raw)

{"jsonrpc": "2.0", "method": "getBalance", "params": {"address": "nano_xxx"}, "id": 1}

getAccountInfo

Purpose: Get detailed account information Parameters: address Returns: frontier, balance, representative, block_count, etc.

{"jsonrpc": "2.0", "method": "getAccountInfo", "params": {"address": "nano_xxx"}, "id": 1}

getPendingBlocks

Purpose: List pending (unreceived) transactions Parameters: address Returns: Object with pending blocks and amounts

{"jsonrpc": "2.0", "method": "getPendingBlocks", "params": {"address": "nano_xxx"}, "id": 1}

initializeAccount

Purpose: Open/activate new account (first receive) Parameters: address, privateKey Returns: initialized, blockHash, balance, etc.

{"jsonrpc": "2.0", "method": "initializeAccount", "params": {"address": "nano_xxx", "privateKey": "key"}, "id": 1}

sendTransaction

Purpose: Send NANO to another address Parameters: fromAddress, toAddress, amountRaw, privateKey Returns: success, hash OR enhanced error

{"jsonrpc": "2.0", "method": "sendTransaction", "params": {"fromAddress": "nano_xxx", "toAddress": "nano_yyy", "amountRaw": "100000000000000000000000000", "privateKey": "key"}, "id": 1}

receiveAllPending

Purpose: Receive all pending transactions Parameters: address, privateKey Returns: Array of received blocks

{"jsonrpc": "2.0", "method": "receiveAllPending", "params": {"address": "nano_xxx", "privateKey": "key"}, "id": 1}

generateQrCode

Purpose: Generate payment QR code for receiving NANO Parameters:

• address (string, required) - NANO address to receive payment
• amount (string, optional) - Amount in NANO (decimal format, e.g., "0.1")

Returns:

• qrCode (string) - Base64 encoded PNG image
• paymentString (string) - NANO URI for payment (nano:address?amount=...)
• address (string) - The NANO address
• amount (string) - The amount in NANO (if provided)

Example Request:

{
    "jsonrpc": "2.0",
    "method": "generateQrCode",
    "params": {
        "address": "nano_3h3m6kfckrxpc4t33jn36eu8smfpukwuq1zq4hy35dh4a7drs6ormhwhkncn",
        "amount": "0.1"
    },
    "id": 1
}

Example Response:

{
    "jsonrpc": "2.0",
    "result": {
        "qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...[long base64 string]",
        "paymentString": "nano:nano_3h3m6kfckrxpc4t33jn36eu8smfpukwuq1zq4hy35dh4a7drs6ormhwhkncn?amount=100000000000000000000000000000",
        "address": "nano_3h3m6kfckrxpc4t33jn36eu8smfpukwuq1zq4hy35dh4a7drs6ormhwhkncn",
        "amount": "0.1"
    },
    "id": 1
}

Use Cases:

• Display QR code in web/mobile apps for payment collection
• Generate payment links for invoicing
• Create shareable payment requests
• The qrCode can be directly embedded in HTML: <img src="data:image/png;base64,..." />
• The paymentString can be used as a clickable link or deep link for NANO wallets

convertBalance (Helper)

Purpose: Convert between NANO and raw units Parameters: amount, from ("nano"/"raw"), to ("nano"/"raw") Returns: converted, formula

{"jsonrpc": "2.0", "method": "convertBalance", "params": {"amount": "0.1", "from": "nano", "to": "raw"}, "id": 1}

getAccountStatus (Helper)

Purpose: Comprehensive account readiness check Parameters: address Returns: initialized, balance, pending, capabilities, needsAction, recommendations

{"jsonrpc": "2.0", "method": "getAccountStatus", "params": {"address": "nano_xxx"}, "id": 1}

nanoConverterHelp (Helper) - NEW!

Purpose: Get comprehensive help for Nano (XNO) conversion utilities and number formats Parameters: None Returns: Conversion formulas, examples, common mistakes, best practices, and utility function documentation

⚠️ IMPORTANT: Essential for clients unfamiliar with Nano!

Why this tool exists: Most cryptocurrency clients expect simple decimal numbers like Bitcoin or Ethereum. However, Nano uses 30 decimal places (10^30 raw units = 1 XNO), which requires special handling to avoid precision errors.

Example Request:

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

Example Response (truncated):

{
  "jsonrpc": "2.0",
  "result": {
    "description": "Nano (XNO) uses raw units for all on-chain operations. 1 XNO = 10^30 raw. This ensures exact precision without floating-point errors.",
    "formula": "raw = XNO × 10^30",
    "reverseFormula": "XNO = raw ÷ 10^30",
    "decimalPlaces": 30,
    "examples": {
      "0.1_XNO": "100000000000000000000000000000",
      "1_XNO": "1000000000000000000000000000000"
    },
    "commonMistakes": [
      "Using XNO value instead of raw in amountRaw parameter",
      "Using floating-point arithmetic which causes rounding errors"
    ],
    "utilityFunctions": {
      "xnoToRaw": {
        "description": "Convert XNO amount to raw units (use this for all transaction amounts)",
        "example": "xnoToRaw(1) => '1000000000000000000000000000000'",
        "usage": "Always use this before sending transactions"
      }
    },
    "exampleWorkflow": [
      "Step 1: Get user input in XNO (e.g., '0.1')",
      "Step 2: Convert to raw using NanoConverter.xnoToRaw('0.1')",
      "Step 3: Validate address using NanoConverter.isValidNanoAddress(address)",
      "Step 4: Use raw amount in sendTransaction"
    ],
    "warning": "IMPORTANT: Most clients don't know Nano uses 30 decimal places. Always educate users that 1 XNO = 10^30 raw units."
  },
  "id": 1
}

Use Cases:

1. First-time Integration: Call this method before implementing any Nano transactions to understand the number format
2. Debugging Conversion Errors: If you get "AMOUNT_WRONG_UNIT" errors, this explains the correct format
3. Client Education: Use the returned information to educate end-users about Nano's precision
4. Reference Documentation: Keep this response as a reference for your implementation

setupTestWallets (Test Wallet)

Purpose: Generate two test wallets with all credentials Parameters: None Returns: wallet1, wallet2 (with address, privateKey, publicKey, seed), fundingInstructions ⚠️ Action Required: Human must fund both wallet addresses with test NANO

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

Response includes:

• Two complete wallet credentials (address, private key, public key, seed)
• Funding instructions with exact addresses to fund
• Status indicating "awaiting_funding"
• Recommended test amount (0.1 NANO per wallet)

getTestWallets (Test Wallet)

Purpose: Retrieve current test wallet information Parameters: None Returns: wallet1, wallet2 (with addresses, balances, funding status)

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

Use Case: Get wallet credentials after generating them, or check current state

updateTestWalletBalance (Test Wallet)

Purpose: Update tracked balance for a test wallet Parameters: walletName ("wallet1" or "wallet2"), balance (raw), funded (boolean) Returns: Updated wallet info

{"jsonrpc": "2.0", "method": "updateTestWalletBalance", "params": {"walletName": "wallet1", "balance": "100000000000000000000000000000", "funded": true}, "id": 1}

Use Case: Manually track balance changes or mark wallet as funded

checkTestWalletsFunding (Test Wallet)

Purpose: Check if both test wallets have been funded (have balance > 0) Parameters: None Returns: wallet1 (balance, funded), wallet2 (balance, funded), bothFunded, status

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

Use Case: Verify wallets are ready for testing after human funding

resetTestWallets (Test Wallet)

Purpose: Delete test wallets and start fresh Parameters: None Returns: Confirmation message

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

Use Case: Clean up and generate new test wallets

---

🎓 Best Practices for AI Agents

✅ DO:

1. Always check account status first using getAccountStatus
2. Convert amounts using convertBalance before transactions
3. Parse errorCode for programmatic error handling
4. Follow nextSteps array in error responses
5. Receive pending blocks before sending transactions

❌ DON'T:

1. Skip account status checks
2. Use NANO values directly in amountRaw (must be raw units)
3. Ignore error nextSteps - they guide recovery
4. Assume account is ready - always verify
5. Parse error message strings (use errorCode instead)

---

🔒 Security Notes

1. Private Keys: Never log or expose private keys
2. Test vs Production: Use test wallets for development
3. RPC Node: Default public node provided (rate limited)
4. Validation: All inputs validated by server

---

📖 Additional Documentation

Located in NANO_MCP_SERVER/:

• AUTONOMOUS_AGENT_INTEGRATION_GUIDE.md - Complete integration guide
• TEST_WALLET_INTEGRATION.md - Test wallet documentation
• AUTONOMOUS_AGENT_ERROR_ENHANCEMENT.md - Error handling details
• examples/test-wallet-usage.json - Request examples

---

🎉 Why This Server is AI Agent-Friendly

✅ Self-documenting - Every error explains itself ✅ Helper functions - Convert, status check built-in ✅ Structured responses - Easy to parse JSON ✅ Machine-readable codes - Error codes for programmatic handling ✅ Actionable guidance - Every error includes nextSteps ✅ No external docs needed - All info in responses ✅ Fast integration - 5-10 minutes to first transaction

---

🚀 Integration Speed

Task	Time Required
Install and run	2 minutes
First transaction	5-10 minutes
Complete integration	< 30 minutes

vs Traditional NANO integration: 1-2 hours minimum

---

⚡ Quick Test (Copy-Paste)

Production Server (No Setup Required):

# Test the production server immediately:
curl -X POST https://nano-mcp.replit.app \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}'

# You should see list of all 16 available methods

Local Development (Optional):

# 1. Start local server
cd NANO_MCP_SERVER && npm start

# 2. In another terminal, test:
curl -X POST http://localhost:8080 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}'

---

📞 Support

For AI Agents:

• All errors include remediation steps
• Use getAccountStatus to diagnose issues
• Check errorCode for specific problems
• Follow nextSteps in error responses

For Developers:

• GitHub Issues: Create issue
• Documentation: See files in NANO_MCP_SERVER/docs/

---

🎊 Ready to Start!

You have everything you need. The server guides you through every step with self-documenting errors.

First command to run:

cd NANO_MCP_SERVER && npm start

Server will be ready on: http://localhost:8080

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

Good luck with your NANO integration! 🚀