# NANO MCP SERVER

> AI-agent-optimized MCP server for NANO cryptocurrency with comprehensive error handling, smart auto-correction, and zero external documentation needed. Integrates in 2-3 minutes with 28 specific error codes and step-by-step recovery guidance.

- **Type:** MCP server
- **Install:** `agentstack add mcp-dhyabi2-nano-mcp-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [dhyabi2](https://agentstack.voostack.com/s/dhyabi2)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [dhyabi2](https://github.com/dhyabi2)
- **Source:** https://github.com/dhyabi2/NANO_MCP_SERVER

## Install

```sh
agentstack add mcp-dhyabi2-nano-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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:**
```bash
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
```json
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:

```bash
# 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**
```bash
# 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**
```typescript
// 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/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:
```bash
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:**

```javascript
// 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**
```json
POST https://nano-mcp.replit.app
{
    "jsonrpc": "2.0",
    "method": "setupTestWallets",
    "params": {},
    "id": 1
}
```

**Response (Save These Addresses!):**
```json
{
    "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
```bash
# Clone or download
cd NANO_MCP_SERVER

# Install dependencies
npm install

# Run server
npm start
```

### Environment Variables (Optional)
```bash
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
```bash
# 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
```json
{"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`
```json
{"jsonrpc": "2.0", "method": "generateWallet", "params": {}, "id": 1}
```

### getBalance
**Purpose:** Check account balance
**Parameters:** `address`
**Returns:** `balance` (raw), `pending` (raw)
```json
{"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.
```json
{"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
```json
{"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.
```json
{"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
```json
{"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
```json
{"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:**
```json
{
    "jsonrpc": "2.0",
    "method": "generateQrCode",
    "params": {
        "address": "nano_3h3m6kfckrxpc4t33jn36eu8smfpukwuq1zq4hy35dh4a7drs6ormhwhkncn",
        "amount": "0.1"
    },
    "id": 1
}
```

**Example Response:**
```json
{
    "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`
```json
{"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`
```json
{"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:**
```json
{"jsonrpc": "2.0", "method": "nanoConverterHelp", "params": {}, "id": 1}
```

**Example Response (truncated):**
```json
{
  "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
```json
{"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](https://github.com/dhyabi2)
- **Source:** [dhyabi2/NANO_MCP_SERVER](https://github.com/dhyabi2/NANO_MCP_SERVER)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-dhyabi2-nano-mcp-server
- Seller: https://agentstack.voostack.com/s/dhyabi2
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.