Which integrations are available for this server?

Provides tools for interacting with the NANO cryptocurrency network, including wallet generation, balance checks, sending transactions, receiving pending blocks, and account initialization.

How do I use NANO MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@NANO MCP Server create a new NANO wallet" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

NANO MCP Server

by dhyabi2

Overview Schema Related Servers Score Discussions

JavaScript

Hybrid

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:

Increase timeout to 90-120 seconds
Check system CPU availability
Don't retry immediately - work might still be processing
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

Use getAccountStatus for everything - It replaces getBalance, getAccountInfo, getPendingBlocks
Follow needsAction array - Auto-recovery without trial-and-error
Batch independent calls - Use Promise.all or batch requests
Set generous timeouts - 60s minimum for transactions (system performance varies)
Save setupTestWallets response - Don't call getTestWallets unless retrieving
Don't retry on timeout - Check account status first, transaction may have completed
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)

initialize - Get server capabilities and all available functions

Core Functions (8)

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

Helper Functions (3) - For Autonomous Agents

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

Test Wallet Functions (5) - For Development

setupTestWallets - Generate two test wallets (requires human funding)
getTestWallets - Retrieve test wallet info
updateTestWalletBalance - Update wallet balance tracking
checkTestWalletsFunding - Check if wallets are ready
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!

Copy Wallet 1 Address: nano_3h3m6kfckrxpc4t33jn36eu8smfpukwuq1zq4hy35dh4a7drs6ormhwhkncn
Copy Wallet 2 Address: nano_39isqp67xsse8cj5igtonuiwicqy8p6txa57mbjd8bcyip7ggrai4bby1x1w
Send test NANO to BOTH addresses (0.1 NANO recommended per wallet)
Use a NANO faucet or your own wallet to send test funds
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:

First-time Integration: Call this method before implementing any Nano transactions to understand the number format
Debugging Conversion Errors: If you get "AMOUNT_WRONG_UNIT" errors, this explains the correct format
Client Education: Use the returned information to educate end-users about Nano's precision
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:

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

❌ DON'T:

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

🔒 Security Notes

Private Keys: Never log or expose private keys
Test vs Production: Use test wallets for development
RPC Node: Default public node provided (rate limited)
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! 🚀

This server cannot be installed

license - permissive license

quality - not tested

maintenance

How are these scores calculated?

Resources

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

Lightport: Open-Sourcing Glama's AI Gateway
By punkpeye on April 27, 2026.
open source
OpenAI
Tool Definition Quality Score (TDQS)
By punkpeye on April 3, 2026.
mcp
The Hackers Who Tracked My Sleep Cycle
By punkpeye on March 26, 2026.
security

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/dhyabi2/NANO_MCP_SERVER'

If you have feedback or need assistance with the MCP directory API, please join our Discord server