NANO MCP SERVER

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](docs/JSONSCHEMAAIAGENTGUIDE.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,  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 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:**
```json
{"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: ``
• 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 "AMOUNTWRONGUNIT" 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)

getTestWall

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: dhyabi2
• Source: dhyabi2/NANOMCP_SERVER
• License: MIT

Install and usage instructions live in the source repository linked above.