NANO MCP Server

Name: NANO MCP Server
Author: dhyabi2

本地服务

github.com/dhyabi2金融数据343 周前更新

代码仓库

关于 NANO MCP Server

NANO MCP Server 通过 JSON-RPC 2.0 提供 NANO 加密货币操作接口，面向 AI Agent 和开发者。它包含钱包、交易及测试钱包功能，并以带有恢复指引的错误响应和可发现的 JSON Schema 为特点；标签注明项目已被取代且不再维护，托管实例已关闭。

主要功能

01生成钱包并查询账户状态
02发送 NANO 并接收待处理区块
03转换余额单位并生成支付二维码
04管理开发用测试钱包
05提供 Schema、类型定义和错误恢复指引

适用场景

01为 Agent 集成 NANO 钱包和转账操作
02检查账户余额及待处理交易
03为开发测试准备和管理测试钱包

MCP 相关

作为 MCP 服务，它通过 JSON-RPC 2.0 向客户端提供钱包、账户、交易、单位转换和测试钱包工具。README 还说明可获取工具的 JSON Schema、TypeScript 定义及 OpenAPI 规范。

#nano-mcp #crypto-server #nano-network

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "NANO_MCP_SERVER": {
      "command": "npx",
      "args": [
        "-y",
        "nano-mcp"
      ],
      "env": {
        "MCP_PORT": "<MCP_PORT>",
        "NANO_RPC_URL": "<NANO_RPC_URL>",
        "NANO_RPC_KEY": "<NANO_RPC_KEY>",
        "NANO_REPRESENTATIVE": "<NANO_REPRESENTATIVE>"
      }
    }
  }
}

启动命令npx -y nano-mcp

需要配置的环境变量

MCP_PORT

NANO_RPC_URL

NANO_RPC_KEY密钥

NANO_REPRESENTATIVE

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npmnano-mcpstdio

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

NANO MCP Server - AI Agent 集成指南

面向 AI Agent：此服务专为自主 Agent 设计。所有错误都会提供自我说明和分步指引。无需查阅外部文档。

🌐 生产服务 URL

使用此 URL： https://nano-mcp.replit.app

所有请求均发送至： https://nano-mcp.replit.app（使用 JSON-RPC 2.0 格式的 POST 请求）

快速示例：

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

🤖 AI Agent 快速入门

生产服务（推荐）

服务 URL： https://nano-mcp.replit.app

无需安装！ 服务已在运行。直接开始发送请求即可。

第 1 步：测试连接

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

第 2 步：准备就绪！

服务会返回所有可用方法。立即开始使用即可。

🔍 JSON Schema 自动发现（全新！）

AI Agent 零样本集成

🎯 无需阅读文档！ 获取完整的 JSON Schema 并自动生成客户端代码：

# 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 功能

✅ 输入/输出 Schema - 包含验证模式的完整 JSON Schema
✅ 即用示例 - 每个工具都提供可复制粘贴的示例
✅ 类型定义 - 提供 TypeScript .d.ts，构建类型安全的客户端
✅ 参数验证 - 用于地址、密钥和金额的正则表达式模式
✅ 错误 Schema - 全部 29 个错误代码及处理指南
✅ 性能说明 - 预期耗时和超时建议
✅ 前置条件 - 每项操作的依赖信息

快速使用 Schema

# 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

代码生成示例

// 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!

📖 完整指南： 有关详细的 Schema 集成模式，请参阅 docs/JSON_SCHEMA_AI_AGENT_GUIDE.md。

**⏱️ 预计集成时间：**5 分钟（而不是花数小时阅读文档）

本地开发（可选）

如需在本地运行以进行开发：

cd NANO_MCP_SERVER
npm install
npm start

本地服务运行地址：http://localhost:8080

⚡ 最快集成路径（AI Agent：从这里开始）

5-6 次调用即可完成整个工作流，耗时 30-60 秒：

// 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)

⏱️ 预期响应时间

函数	预期耗时	建议超时
setupTestWallets	< 1s	5s
getAccountStatus	1-3s	10s
initializeAccount	8-60s（不定）	60s
sendTransaction	10-60s（不定）	60s
receiveAllPending	每个区块 5-60s	60s
convertBalance	< 500ms	5s
generateQrCode	< 2s	10s

⚠️ 关键：工作量生成性能

工作量证明（PoW）的生成时间因系统而有很大差异：

高性能系统：10-15 秒
较慢的系统：30-60 秒
对交易函数（initializeAccount、sendTransaction、receiveAllPending）务必至少设置 60 秒超时

如果遇到超时：

将超时时间增加到 90-120 秒
检查系统 CPU 是否可用
不要立即重试——工作量可能仍在处理中
超时后检查账户状态——交易可能已经完成

❌ 不要这样做（浪费时间）

1. 不要先调用 getBalance 再调用 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. 不要反复调用 checkTestWalletsFunding

// ❌ 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. 不要为交易设置过短的超时时间

// ❌ 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. 独立的函数不要按顺序逐个测试

// ❌ 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

💡 给 AI Agent 的专业建议

所有情况都使用 getAccountStatus - 它可以替代 getBalance、getAccountInfo 和 getPendingBlocks
遵循 needsAction 数组 - 无需反复试错即可自动恢复
批量调用彼此独立的请求 - 使用 Promise.all 或批量请求
设置宽裕的超时时间 - 交易至少设置 60 秒（系统性能各不相同）
保存 setupTestWallets 的响应 - 除非要获取测试钱包，否则不要调用 getTestWallets
超时后不要重试 - 先检查账户状态，交易可能已经完成
预期工作量生成时间会有变化 - 根据系统负载，耗时为 10-60 秒

📊 优化效果

指标	未优化	优化后	改进幅度
总调用次数	10-12	5-6	40-50% ↓
总 Token 数	10,000-15,000	5,000-7,000	50% ↓
总耗时	60-90s	30-60s	40% ↓
决策点	5-6	1-2	70% ↓

结果： 集成更快、成本更低、错误更少。

🎯 此服务的功能

NANO MCP 服务为 NANO 加密货币操作提供 JSON-RPC 2.0 API，包含：

✅ 自带说明的错误 - 每条错误都会明确告诉你接下来该怎么做
✅ 辅助函数 - 自动转换单位、检查账户状态
✅ 测试钱包系统 - 为开发生成和管理测试钱包
✅ 无需外部文档 - 所有信息都包含在 API 响应中

NANO 加密货币特性：

即时交易（< 1 秒）
零手续费
环保（能耗极低）
非常适合自动化 AI 系统

📋 可用的 MCP 函数（共 17 个）

初始化（1 个）

initialize - 获取服务功能和所有可用函数

核心函数（8 个）

generateWallet - 创建新的 NANO 钱包
getBalance - 检查账户余额
getAccountInfo - 获取详细账户数据
getPendingBlocks - 列出待处理交易
initializeAccount - 开通／激活新账户
sendTransaction - 发送 NANO（含增强的错误处理）
receiveAllPending - 接收所有待处理区块
generateQrCode - 创建包含 base64 PNG 的支付二维码

辅助函数（3 个）- 供自主 Agent 使用

convertBalance - 转换 NANO ↔ raw 单位
getAccountStatus - 一次调用即可查看：余额、待处理款项、功能，以及需要执行的操作
nanoConverterHelp - 全新！ Nano（XNO）转换、格式和数字处理的综合指南（对于不熟悉 Nano 的客户端至关重要）

测试钱包函数（5 个）- 用于开发

setupTestWallets - 生成两个测试钱包（需要人工注资）
getTestWallets - 获取测试钱包信息
updateTestWalletBalance - 更新钱包余额记录
checkTestWalletsFunding - 检查钱包是否已准备就绪
resetTestWallets - 删除并重新开始

🚀 AI Agent 完整工作流

工作流：发送 NANO 交易

// 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)

⚡ 快速参考：常见任务

任务 1：生成新钱包

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

返回：address、privateKey、publicKey、seed

任务 2：检查余额

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

返回：balance（raw）、pending（raw）

任务 3：转换单位

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

返回：包含公式的 converted 值

任务 4：检查账户是否就绪

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

返回：完整状态和接下来要执行的操作

🧠 面向 AI Agent 的全面错误处理

✨ 特别之处

NANO MCP 服务拥有最全面、最适合 AI Agent 的错误处理机制：

20 多种专用错误代码，便于程序处理
全面的输入验证 - 检查地址、私钥、金额和所有参数
自动检测常见错误（例如，误用 NANO 而不是 raw）
建议修正方案 - 服务会为你计算正确的值
逐步恢复指引 - 遇到错误也不会束手无策
无需外部文档 - 错误响应中包含所有信息

错误响应结构

所有错误均包含：

errorCode - 机器可读的代码（例如，"INSUFFICIENT_BALANCE"）
error - 人类可读的消息
details - 具体背景信息（错误原因、预期格式等）
nextSteps - 逐步修复说明（数组）
relatedFunctions - 有助于解决问题的函数
exampleRequest - 可直接复制粘贴的正确请求
suggestedCorrection - 自动修正后的值（如适用）

📋 完整错误代码列表

验证错误：

MISSING_PARAMETER - 未提供必需参数
METHOD_NOT_FOUND - MCP 方法名称无效
INVALID_ADDRESS_FORMAT - 地址缺失或类型错误
INVALID_ADDRESS_PREFIX - 地址未以 'nano_' 或 'xrb_' 开头
INVALID_ADDRESS_LENGTH - 地址长度错误
INVALID_ADDRESS_CHARACTERS - 地址包含无效字符
INVALID_PRIVATE_KEY_FORMAT - 私钥缺失或类型错误
INVALID_PRIVATE_KEY_LENGTH - 私钥不是 64 个字符
INVALID_PRIVATE_KEY_CHARACTERS - 私钥不是十六进制格式
INVALID_AMOUNT_FORMAT - 金额缺失或类型错误
AMOUNT_WRONG_UNIT - 智能检测：你使用了 NANO，而不是 raw
INVALID_AMOUNT_CHARACTERS - 金额包含无效字符
INVALID_AMOUNT_ZERO_OR_NEGATIVE - 金额必须为正数
INVALID_AMOUNT_OVERFLOW - 金额过大
INVALID_CONVERSION_UNITS - 'from' 或 'to' 单位无效
SAME_CONVERSION_UNITS - 无法转换相同单位
INVALID_QR_AMOUNT_FORMAT - QR 码金额格式无效

区块链错误：

INSUFFICIENT_BALANCE - 没有足够的 NANO 可发送
INSUFFICIENT_WORK - [严重] 工作量未达到难度阈值（已修复 - 只需重试）
ACCOUNT_NOT_INITIALIZED - 账户需要先接收第一笔交易
ACCOUNT_NOT_INITIALIZED_NO_PENDING - 账户没有待处理区块
PENDING_BLOCKS_NOT_RECEIVED - 应先接收待处理区块
BLOCKCHAIN_INVALID_BLOCK - 区块链拒绝了区块
BLOCKCHAIN_INSUFFICIENT_BALANCE - 区块链余额检查失败
BLOCKCHAIN_ERROR - 一般区块链操作错误
CONVERSION_ERROR - 余额转换失败

示例：余额不足错误

请求：

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

错误响应：

{
    "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
}

🎯 智能自动更正示例

你发的是 NANO，而不是 raw？服务端会自动为你更正！

错误请求（使用 NANO，而不是 raw）：

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

智能错误响应：

{
    "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 操作：

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

错误代码速查表

错误代码	含义	是否可自动修复	操作
`INSUFFICIENT_BALANCE`	NANO 不足	部分（显示短缺金额）	减少金额或充值
`INSUFFICIENT_WORK`	PoW 低于阈值	是（自动重试）	只需重试请求
`ACCOUNT_NOT_INITIALIZED`	账户尚未开通	是（2 种解决方案）	调用 initializeAccount
`AMOUNT_WRONG_UNIT`	使用了 NANO，而不是 raw	是（自动转换）	使用 suggestedCorrection
`INVALID_ADDRESS_*`	地址格式错误	是（显示格式）	修正地址格式
`INVALID_PRIVATE_KEY_*`	密钥格式错误	是（显示格式）	修正私钥
`MISSING_PARAMETER`	缺少参数	是（显示示例）	添加缺失参数
`METHOD_NOT_FOUND`	方法无效	是（列出所有方法）	使用正确的方法

📚 完整文档

详细的错误处理指南： 请参阅 docs/AI_AGENT_ERROR_HANDLING.md

涵盖主题：

说明全部 29 个错误代码（包括 INSUFFICIENT_WORK）
智能自动更正示例
错误恢复决策树
AI Agent 最佳实践
安全注意事项
100% 验证覆盖率详情

错误处理决策树

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

🧪 测试钱包系统（用于开发）

快速设置

步骤 1：生成测试钱包

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

响应（请保存这些地址！）：

{
    "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
}

⚠️ 重要 — 需要执行操作： 必须由人工为这些钱包充值！

复制钱包 1 地址： nano_3h3m6kfckrxpc4t33jn36eu8smfpukwuq1zq4hy35dh4a7drs6ormhwhkncn
复制钱包 2 地址： nano_39isqp67xsse8cj5igtonuiwicqy8p6txa57mbjd8bcyip7ggrai4bby1x1w
向两个地址都发送测试 NANO（建议每个钱包发送 0.1 NANO）
使用 NANO 水龙头或你自己的钱包发送测试资金
等待确认（通常少于 5 秒）

步骤 2：检查充值状态

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

步骤 3：两个钱包都充值后，开始测试！ 准备就绪后，响应将显示 "bothFunded": true。

测试钱包工作流

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

💡 决策树：完整交易流程

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

📊 单位换算（重要！）

NANO 使用两种单位：

NANO（十进制，例如 "0.1"）— 便于人类阅读
raw（整数字符串）— 区块链使用此单位

换算：

1 NANO = 10³⁰ raw
amountRaw 参数始终使用 raw

快速参考：

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

使用 convertBalance 函数：

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

🔧 设置和配置

安装

# Clone or download
cd NANO_MCP_SERVER

# Install dependencies
npm install

# Run server
npm start

环境变量（可选）

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)

测试

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

📚 完整函数参考

initialize

用途： 初始化 MCP 服务并获取所有可用功能/函数列表 参数： 无 返回： 服务信息以及所有可用 MCP 工具的列表及其说明

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

响应包含：

protocolVersion — MCP 协议版本
serverInfo — 服务名称和版本
capabilities — 服务功能
tools — 所有可用 MCP 函数的完整列表，包括说明和参数架构

使用场景： 首次调用，用于了解服务能做什么以及有哪些可用函数

generateWallet

用途： 创建新的 NANO 钱包 参数： 无 返回： address、privateKey、publicKey、seed

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

getBalance

用途： 检查账户余额 参数： address 返回： balance（raw）、pending（raw）

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

getAccountInfo

用途： 获取详细的账户信息 参数： address 返回： frontier、balance、representative、block_count 等

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

getPendingBlocks

用途： 列出待处理（尚未接收）的交易 参数： address 返回： 包含待处理区块和金额的对象

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

initializeAccount

用途： 开启/激活新账户（首次接收） 参数： address、privateKey 返回： initialized、blockHash、balance 等

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

sendTransaction

用途： 向另一个地址发送 NANO 参数： fromAddress、toAddress、amountRaw、privateKey 返回： success、hash 或增强错误信息

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

receiveAllPending

用途： 接收所有待处理交易 参数： address、privateKey 返回： 已接收区块的数组

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

generateQrCode

用途： 生成用于接收 NANO 的支付二维码 参数：

address（字符串，必填）- 用于接收付款的 NANO 地址
amount（字符串，可选）- NANO 金额（十进制格式，例如“0.1”）

返回：

qrCode（字符串）- Base64 编码的 PNG 图像
paymentString（字符串）- 用于支付的 NANO URI（nano:address?amount=...）
address（字符串）- NANO 地址
amount（字符串）- NANO 金额（如果已提供）

请求示例：

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

响应示例：

{
    "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
}

使用场景：

在 Web/移动应用中显示二维码以收款
为开票生成支付链接
创建可分享的付款请求
qrCode 可直接嵌入 HTML：<img src="data:image/png;base64,..." />
paymentString 可用作 NANO 钱包的可点击链接或深层链接

convertBalance（辅助工具）

用途： 在 NANO 和 raw 单位之间转换 参数： amount、from（"nano"/"raw"）、to（"nano"/"raw"） 返回： converted、formula

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

getAccountStatus（辅助工具）

用途： 全面检查账户是否已准备就绪 参数： address 返回： initialized、balance、pending、capabilities、needsAction、recommendations

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

nanoConverterHelp（辅助工具）- 全新！

用途： 获取 Nano（XNO）转换工具和数字格式的全面帮助 参数： 无 返回： 转换公式、示例、常见错误、最佳实践以及实用函数文档

⚠️ 重要：不熟悉 Nano 的客户端必备！

此工具存在的原因： 大多数加密货币客户端都预期使用类似 Bitcoin 或 Ethereum 的简单十进制数字。然而，Nano 使用 30 位小数（10^30 个 raw 单位 = 1 XNO），因此需要特殊处理以避免精度错误。

请求示例：

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

响应示例（已截断）：

{
  "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
}

使用场景：

首次集成：在实现任何 Nano 交易之前调用此方法，以了解数字格式
转换错误排查：如果遇到“AMOUNT_WRONG_UNIT”错误，此工具会说明正确的格式
客户端教育：使用返回的信息向终端用户介绍 Nano 的精度
参考文档：将此响应作为实现时的参考

setupTestWallets（测试钱包）

用途： 生成两个包含所有凭据的测试钱包 参数： 无 返回： wallet1、wallet2（包含地址、私钥、公钥、种子）、fundingInstructions ⚠️ 需要执行操作： 人工必须向两个钱包地址充值测试 NANO

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

响应包含：

两组完整的钱包凭据（地址、私钥、公钥、种子）
充值说明，包含需要充值的确切地址
状态指示“awaiting_funding”
建议的测试金额（每个钱包 0.1 NANO）

getTestWallets（测试钱包）

用途： 获取当前测试钱包信息 参数： 无 返回： wallet1、wallet2（包含地址、余额、充值状态）

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

使用场景： 生成钱包后获取钱包凭据，或检查当前状态

updateTestWalletBalance（测试钱包）

用途： 更新测试钱包的跟踪余额 参数： walletName（"wallet1" 或 "wallet2"）、balance（raw）、funded（布尔值） 返回： 更新后的钱包信息

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

使用场景： 手动跟踪余额变化，或将钱包标记为已充值

checkTestWalletsFunding（测试钱包）

用途： 检查两个测试钱包是否都已充值（余额 > 0） 参数： 无 返回： wallet1（余额、已充值状态）、wallet2（余额、已充值状态）、bothFunded、status

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

使用场景： 人工充值后，确认钱包已准备好进行测试

resetTestWallets（测试钱包）

用途： 删除测试钱包并重新开始 参数： 无 返回： 确认消息

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

使用场景： 清理并生成新的测试钱包

🎓 AI Agent 最佳实践

✅ 应做：

始终先检查账户状态，使用 getAccountStatus
在交易前转换金额，使用 convertBalance
解析 errorCode 以进行程序化错误处理
遵循错误响应中的 nextSteps 数组
发送交易前接收待处理区块

❌ 不应做：

跳过账户状态检查
在 amountRaw 中直接使用 NANO 值（必须使用原始单位）
忽略错误中的 nextSteps——它们会指导恢复操作
假设账户已就绪——务必验证
解析错误消息字符串（应使用 errorCode）

🔒 安全说明

私钥：切勿记录或泄露私钥
测试与生产环境：开发时使用测试钱包
RPC 节点：提供默认公共节点（有速率限制）
验证：服务器会验证所有输入

📖 更多文档

位于 NANO_MCP_SERVER/：

AUTONOMOUS_AGENT_INTEGRATION_GUIDE.md - 完整集成指南
TEST_WALLET_INTEGRATION.md - 测试钱包文档
AUTONOMOUS_AGENT_ERROR_ENHANCEMENT.md - 错误处理详情
examples/test-wallet-usage.json - 请求示例

🎉 为什么这个服务器对 AI Agent 友好

✅ 自我说明 - 每条错误都会解释自身 ✅ 辅助函数 - 内置转换和状态检查功能 ✅ 结构化响应 - JSON 易于解析 ✅ 机器可读代码 - 错误代码可用于程序化处理 ✅ 可执行的指导 - 每条错误都包含 nextSteps ✅ 无需外部文档 - 所有信息都在响应中 ✅ 快速集成 - 5-10 分钟即可完成首次交易

🚀 集成速度

任务	所需时间
安装并运行	2 分钟
首次交易	5-10 分钟
完成集成	< 30 分钟

相比传统 NANO 集成：至少需要 1-2 小时

⚡ 快速测试（复制粘贴）

生产服务器（无需设置）：

# 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

本地开发（可选）：

# 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}'