使用说明

NANO MCP服务器-AI代理集成指南

对于AI代理：此服务器是专门为自主代理设计的。所有错误都会在逐步指导下自行记录。不需要外部文件。

🌐 生产服务器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代理的快速入门

生产服务器（推荐）

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

无需安装！ 服务器已在运行。请开始提出请求。

步骤1：测试连接

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

第二步：你准备好了！

服务器用所有可用的方法进行响应。立即开始使用它们。

🔍 JSON模式自动发现（新增！）

人工智能代理的零样本集成

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

# 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

架构特性

✅ 输入/输出模式 -带有验证模式的完整JSON模式
✅ 即用型示例 -为每个工具复制粘贴示例
✅ 类型定义 -TypeScript .d.ts 适用于类型安全客户端
✅ 参数验证 -地址、键、金额的正则表达式模式
✅ 错误模式 -所有29个错误代码及处理指南
✅ 业绩说明 -预期持续时间和超时建议
✅ 先决条件 -每个操作的依赖关系信息

快速架构使用

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

📖 完整指南： 看 docs/JSON_SCHEMA_AI_AGENT_GUIDE.md 了解详细的模式集成模式。

⏱️ 预计集成时间： 5分钟 （与阅读文件的小时数相比）

地方发展（可选）

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

cd NANO_MCP_SERVER
npm install
npm start

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

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

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	小于1秒	5秒
获取帐户状态	1-3s	10s
初始化帐户	8-60s（变化）	60年代
sendTransaction	10-60s（变化）	60年代
receiveAll待定	每个区块5-60s	60年代
转换器平衡	<500ms	5s
生成代码	<2S	10s

⚠️ 关键：工作生成绩效

工作量证明（PoW）生成时间 因系统而异:

快速系统：10-15秒
较慢的系统：30-60秒
始终设置60秒的最小超时时间 用于交易功能（initializeAccount、sendTransaction、receiveAllPending）

如果遇到超时：

将超时时间增加到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代理的专业提示

使用 getAccountStatus 为了一切 -它取代了getBalance、getAccountInfo、getPendingBlocks
跟随 needsAction 数组 -无需反复试验即可自动恢复
批量独立呼叫 -使用Promise.all或批处理请求
设置慷慨的超时 - 最小60秒 对于事务（系统性能各不相同）
保存setupTestWallets响应 -除非检索到，否则不要调用getTestWallets
超时后不要重试 -先检查账户状态，交易可能已完成
预期工作生成的可变性 -10-60s，取决于系统负载

📊 优化影响

度量	低效	优化	改进
总通话次数	10-12	5-6	40-50% ↓
代币总数	10000-15000	5000-7000	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）-适用于自主代理

convertBalance -转换NANO↔ 原料装置
getAccountStatus -一个电话显示：平衡、待定、能力、需要采取的行动
nanoConverterHelp - 新 Nano（XNO）转换、格式和数字处理的综合指南（对于不熟悉Nano的客户至关重要）

测试钱包功能（5）-用于开发

setupTestWallets -生成两个测试钱包（需要人力资助）
getTestWallets -检索测试钱包信息
updateTestWalletBalance -更新钱包余额跟踪
checkTestWalletsFunding -检查钱包是否准备就绪
resetTestWallets -删除并重新开始

🚀 AI代理的完整工作流程

工作流程：发送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 （生）， pending （未加工）

任务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代理的全面错误处理

✨ 是什么让这个特别

NANO MCP服务器具有最全面、AI代理友好的错误处理功能：

20+特定错误代码 用于程序化处理
广泛的输入验证 -地址、私钥、金额、所有参数
自动检测常见错误 （例如，使用NANO而不是原始）
建议更正 -服务器为您计算正确的值
逐步恢复 -永远不要陷入错误
无需外部文件 -错误响应中的所有信息

错误响应结构

所有错误包括：

errorCode -机器可读代码（例如“INSUFFICIENT_ALANCE”）
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而不是原始
INVALID_AMOUNT_CHARACTERS -金额包含无效字符
INVALID_AMOUNT_ZERO_OR_NEGATIVE -金额必须为正
INVALID_AMOUNT_OVERFLOW -金额太大
INVALID_CONVERSION_UNITS -“from”或“to”单位无效
SAME_CONVERSION_UNITS -无法转换同一单位
INVALID_QR_AMOUNT_FORMAT -二维码金额格式无效

区块链错误：

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而不是生的？服务器会自动为您更正！

错误请求（NANO而不是原始请求）：

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

// 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个解决方案）	呼叫初始化帐户
`AMOUNT_WRONG_UNIT`	使用过的NANO不是生的	是（自动转换）	使用建议更正
`INVALID_ADDRESS_*`	地址格式错误	是（显示格式）	修复地址格式
`INVALID_PRIVATE_KEY_*`	密钥格式错误	是（显示格式）	修复私钥
`MISSING_PARAMETER`	参数缺失	是（示例显示）	添加缺失的参数
`METHOD_NOT_FOUND`	无效方法	是（列出所有方法）	使用正确的方法

📚 完整的文件

有关详细的错误处理指南： 看 docs/AI_AGENT_ERROR_HANDLING.md

涵盖的主题：

解释了所有29个错误代码（包括INSUFFICIENT_WORK）
智能自动校正示例
用于错误恢复的决策树
AI代理的最佳实践
安全注意事项
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秒）

第二步：检查资金状况

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

第三步：当两者都有资金时，开始测试！ 响应将显示 "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使用两个单位：

纳米（十进制，例如“0.1”）-人类可读
原始（整数字符串）-区块链使用此

转换：

1纳米=10³⁰ raw
始终使用生食 amountRaw 参数

快速参考：

NANO	原始
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

📚 完整功能参考

初始化

目的： 初始化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}

余额

目的： 检查账户余额 参数： address 退货： balance （生）， pending （未加工）

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

获取账户信息

目的： 获取详细的帐户信息 参数： 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}

初始化帐户

目的： 打开/激活新帐户（首次接收） 参数： 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}

receiveAll待定

目的： 接收所有待处理交易 参数： address, privateKey 退货： 接收块数组

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

生成QrCode

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

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

退货：

qrCode （string）-Base64编码的PNG图像
paymentString （string）-支付的NANO URI（NANO:地址？金额=…）
address （string）-NANO地址
amount （string）-以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
}

使用案例：

在网络/移动应用程序中显示二维码以进行收款
生成发票付款链接
创建可共享的付款请求
这 qrCode 可以直接嵌入HTML中： <img src="data:image/png;base64,..." />
这 paymentString 可以用作NANO钱包的可点击链接或深度链接

convertBalance（助手）

目的： 在NANO和原始单位之间转换 参数： amount, from （“纳米”/“原始”）， to （“纳米”/“原始”） 退货： 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的客户来说，这是必不可少的！

为何存在此工具： 大多数加密货币客户期望比特币或以太坊等简单的十进制数字。然而，Nano使用30位小数（10^30原始单位=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}

答复包括：

两个完整的钱包凭据（地址、私钥、公钥、种子）
带有确切资金地址的资金说明
状态显示“唤醒_资金”
建议测试金额（每个钱包0.1 NANO）

getTestWallets（测试钱包）

目的： 检索当前测试钱包信息 参数： 无 退货： wallet1, wallet2 （含地址、余额、资金状况）

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

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

更新测试钱包余额（测试钱包）

目的： 更新测试钱包的跟踪余额 参数： walletName （“墙1”或“墙2”）， balance （生）， funded （布尔值） 退货： 更新钱包信息

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

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

check测试钱包资金（测试钱包）

目的： 检查两个测试钱包是否都已获得资金（余额>0） 参数： 无 退货： wallet1 （余额，已资助）， wallet2 （余额，已资助）， bothFunded, status

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

用例： 验证钱包在人力资助后是否已准备好进行测试

resetTestWallets（测试钱包）

目的： 删除测试钱包并重新开始 参数： 无 退货： 确认消息

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

用例： 清理并生成新的测试钱包

🎓 AI代理的最佳实践

✅ 做：

始终先检查帐户状态 使用 getAccountStatus
转换金额 使用 convertBalance 交易前
解析错误代码 用于程序错误处理
遵循下一步 错误响应中的数组
接收待处理的区块 发送交易之前

❌ 不要：

跳过帐户状态检查
直接在中使用NANO值 amountRaw （必须是原始单位）
忽略错误 nextSteps -他们指导复苏
假设帐户已准备就绪-始终进行验证
解析错误消息字符串（使用 errorCode 相反）

🔒 安全说明

私钥：切勿记录或公开私钥
测试与生产：使用测试钱包进行开发
RPC节点：提供默认公共节点（速率受限）
验证：所有输入均由服务器验证

📖 其他文件

位于 NANO_MCP_SERVER/:

自动命名_代理_集成_指南.md -完整的集成指南
测试_WLLET_INTEGRATION.md -测试钱包文档
AUTONOMOUS_AGENT_ERROR_ENHANCEMENT.md -错误处理详细信息
examples/test-wallet-usage.json -请求示例

🎉 为什么此服务器对AI代理友好

✅ 自我记录 -每个错误都会自行解释 ✅ 帮助函数 -转换，内置状态检查 ✅ 结构化响应 -易于解析JSON ✅ 机器可读代码 -程序化处理的错误代码 ✅ 可操作的指导 -每个错误都包含next步骤 ✅ 无需外部文档 -回复中的所有信息 ✅ 快速集成 -距离首次交易还有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}'

📞 支持

对于AI代理：

所有错误都包括补救步骤
使用 getAccountStatus 诊断问题
检查 errorCode 针对具体问题
跟随 nextSteps 在错误响应中

对于开发者：

GitHub问题：创建问题
文档：请参阅中的文件 NANO_MCP_SERVER/docs/

🎊 准备开始！

你有你需要的一切。服务器会通过自我记录错误来指导您完成每一步。

要运行的第一个命令：

cd NANO_MCP_SERVER && npm start

服务器将在以下时间准备就绪： http://localhost:8080

从以下内容开始： {"jsonrpc":"2.0","method":"initialize","params":{},"id":1}

祝您NANO集成顺利！ 🚀