使用说明

钱包余额MCP服务器

概述

钱包余额MCP服务器为AI代理提供了在30多个区块链网络上查询加密货币钱包余额的能力。此MCP服务器与AgentLedger AI代理平台无缝集成，使代理能够获取以太坊、比特币、Polygon、Sui、Arweave、Filecoin和许多其他区块链网络的实时钱包余额。

主要特点：

🌐 30+区块链网络 -对主要和新兴连锁店的支持
🔑 灵活的身份验证 -API密钥和公共端点的混合
⚡ 高速查询 -直接区块链API集成
🎯 精确的平衡 -每个链的原生精度（ETH为18位小数，SUI为9位小数等）
🔄 多链查询 -同时跨多个链获取余额
✅ 地址验证 -所有支持链的内置格式验证

身份验证模式

图案类型： API密钥（模式3）

此服务使用 API密钥身份验证模式 使用特殊的多键JSON格式支持多个区块链浏览器API。

令牌格式

accessToken: '{"etherscan":"YOUR_ETHERSCAN_KEY","bscscan":"YOUR_BSCSCAN_KEY","polygonscan":"YOUR_POLYGONSCAN_KEY",...}'

这 accessToken 是一个 JSON字符串 包含不同区块链资源管理器服务的多个API密钥。并不是所有的键都是必需的，只需要查询需要API键的链。

按链划分的必需API密钥

需要API密钥的链：

ethereum → etherscan 钥匙
polygon → polygonscan 钥匙
bsc → bscscan 钥匙
arbitrum → arbiscan 钥匙
optimism → optimistic_etherscan 钥匙
cardano → blockfrost_cardano 钥匙
base → basescan 钥匙

带有公共API的链（无需密钥）：

bitcoin, litecoin, sui, arweave, filecoin, stellar, near, solana, cosmos, avalanche, fantom，以及更多

令牌配置示例

最小（仅限公共链）：

{}

单链：

{"etherscan": "ABC123XYZ789"}

多条链：

{
  "etherscan": "ABC123",
  "polygonscan": "DEF456",
  "bscscan": "GHI789",
  "arbiscan": "JKL012"
}

可用工具

1. `get_wallet_balance`

在任何支持的区块链网络上获取钱包地址的加密货币余额。

参数：

accessToken （字符串，可选）：JSON字符串，包含区块链探索者的API密钥。仅对于需要API密钥的链是必需的。
chain （string，必填）：区块链网络名称（例如。， ethereum, bitcoin, sui, polygon)
address （字符串，必填）：用于检查余额的钱包地址。格式因链而异。

例子：

{
  accessToken: '{"etherscan":"YOUR_KEY"}',
  chain: "ethereum",
  address: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
}

答复：

{
  "success": true,
  "data": {
    "ticker": "ETH",
    "amount": "1.234567890123456789",
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "chain": "Ethereum",
    "timestamp": 1697040000,
    "raw": "1234567890123456789"
  }
}

2. `get_multiple_balances`

同时跨多个区块链网络获取单个钱包地址的加密货币余额。

参数：

accessToken （字符串，可选）：包含API密钥的JSON字符串
chains （array，必填）：要查询的区块链网络名称数组
address （字符串，必填）：钱包地址（必须对指定的链有效）

例子：

{
  accessToken: '{"etherscan":"KEY1","polygonscan":"KEY2"}',
  chains: ["ethereum", "polygon", "sui", "arweave"],
  address: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
}

答复：

{
  "success": true,
  "data": {
    "balances": [
      {
        "ticker": "ETH",
        "amount": "1.234567890123456789",
        "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
        "chain": "Ethereum",
        "timestamp": 1697040000
      },
      {
        "ticker": "MATIC",
        "amount": "50.123456789012345678",
        "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
        "chain": "Polygon",
        "timestamp": 1697040000
      }
    ],
    "totalChains": 4,
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "timestamp": 1697040000
  }
}

3. `list_supported_chains`

列出所有支持的区块链网络以及可选的API关键需求信息。

参数：

accessToken （string，可选）：此操作不需要
includeApiKeyRequirements （布尔型，可选）：如果为true，则包括哪些链需要API键。默认值：false

例子：

{
  includeApiKeyRequirements: true
}

答复：

{
  "success": true,
  "data": {
    "chains": [
      {
        "id": "ethereum",
        "name": "Ethereum",
        "ticker": "ETH",
        "decimals": 18,
        "requiresApiKey": true,
        "apiKeyName": "etherscan"
      },
      {
        "id": "sui",
        "name": "Sui",
        "ticker": "SUI",
        "decimals": 9,
        "requiresApiKey": false
      }
    ],
    "total": 30,
    "chainsRequiringApiKeys": 7,
    "chainsWithPublicApis": 23
  }
}

4. `validate_address`

验证钱包地址是否具有特定区块链网络的正确格式。

参数：

accessToken （string，可选）：此操作不需要
chain （字符串，必填）：用于验证地址的区块链网络
address （字符串，必填）：要验证的地址

例子：

{
  chain: "ethereum",
  address: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
}

答复：

{
  "success": true,
  "data": {
    "valid": true,
    "chain": "Ethereum",
    "chainId": "ethereum",
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "expectedFormat": "0x followed by 40 hexadecimal characters"
  }
}

5. `get_chain_info`

获取有关特定区块链网络的详细信息，包括股票代码、小数、API要求和端点。

参数：

accessToken （string，可选）：此操作不需要
chain （string，必填）：区块链网络获取有关信息

例子：

{
  chain: "sui"
}

答复：

{
  "success": true,
  "data": {
    "id": "sui",
    "name": "Sui",
    "ticker": "SUI",
    "decimals": 9,
    "requiresApiKey": false,
    "rpcEndpoint": "https://fullnode.mainnet.sui.io:443"
  }
}

6. `health_check`

检查MCP服务器是否正在运行并响应。

参数：

accessToken （string，可选）：此操作不需要

例子：

{}

答复：

{
  "success": true,
  "data": {
    "status": "healthy",
    "server": "wallet-balance",
    "version": "1.0.0",
    "timestamp": 1697040000,
    "supportedChains": 30
  }
}

支持的区块链

Chain	Ticker	Decimals	需要API密钥	API密钥名称
以太坊	ETH	18	✅	以太扫描
比特币	BTC	8	❌	-
多边形	MATIC	18	✅	多边形扫描
BSC	BNB	18	✅	bscscan
Arbitrum	ETH	18	✅	阿比斯卡
乐观	ETH	18	✅	乐观主义者
隋	Sui	9	❌	-
Arweave	AR	12	❌	-
Filecoin	FIL	18	❌	-
恒星	XLM	7	❌	-
卡尔达诺	ADA	6	✅	blockfrost_cardano
雪崩	AVAX	18	❌	-
近	近	24	❌	-
索拉纳	索尔	9	❌	-
宇宙	原子	6	❌	-
莱特币	LTC	8	❌	-
芬托姆	FTM	18	❌	-
基础	以太坊	18	✅	基线扫描

还有更多。..

安装

# Clone the repository
git clone https://github.com/oregpt/AgentLedger_MCP_WalletBalanceService.git
cd AgentLedger_MCP_WalletBalanceService

# Install dependencies
npm install

# Build the project
npm run build

测试

# Run tests
npm test

手动测试

import { WalletBalanceMCPServer } from './dist/index.js';

const server = new WalletBalanceMCPServer();
await server.initialize();

// Test listing chains
const chains = await server.executeTool('list_supported_chains', {
  includeApiKeyRequirements: true
});
console.log(chains);

// Test balance query (public chain)
const suiBalance = await server.executeTool('get_wallet_balance', {
  chain: 'sui',
  address: '0x...'
});
console.log(suiBalance);

// Test balance query (requires API key)
const ethBalance = await server.executeTool('get_wallet_balance', {
  accessToken: '{"etherscan":"YOUR_KEY"}',
  chain: 'ethereum',
  address: '0x...'
});
console.log(ethBalance);

await server.shutdown();

平台集成说明

🔑 多密钥身份验证

此服务实现了 独特的多密钥身份验证模式 标准AgentLedger指南模式中未涵盖。它不使用单个API键，而是使用包含多个API键的JSON对象。

平台集成要求：

令牌存储格式
- 存储为JSON字符串： {"etherscan":"key1","bscscan":"key2",...}
- 平台应提供UI供用户配置多个密钥
- 密钥应安全存储并一起检索
UI建议
- 显示链及其API关键要求的列表
- 允许用户有选择地添加密钥（仅适用于他们需要的链）
- 提供链接以获取每个服务的API密钥：
  - 以太网扫描：https://etherscan.io/apis
  - 多边形扫描：https://polygonscan.com/apis
  - BSC扫描：https://bscscan.com/apis
  - Arbiscan：https://arbiscan.io/apis
  - Blockfrost（卡尔达诺）：https://blockfrost.io/

令牌格式示例

// Platform should construct this JSON and pass as accessToken
{
  "etherscan": "user_entered_key_1",
  "polygonscan": "user_entered_key_2",
  "bscscan": "user_entered_key_3"
}

错误处理
- 如果链需要API密钥，但未提供该密钥，则该工具将返回：
```
{
  "success": false,
  "error": "API key required for Ethereum. Please provide 'etherscan' in accessToken."
}
```
- 平台应提示用户添加所需的API密钥
可选密钥
- 用户不需要提供所有密钥
- 只需要他们想要查询的链的密钥
- 公共链（比特币、Sui、Arweave等）在没有任何密钥的情况下工作

🎯 链发现

平台应利用 list_supported_chains 工具用于：

向用户显示哪些链可用
指明哪些链需要API密钥
帮助用户了解他们的用例需要什么密钥

⚡ 性能注意事项

大多数区块链API都有速率限制
考虑将平衡结果缓存30-60秒，以减少API调用
这 get_multiple_balances 该工具发出并发请求，但遵守速率限制
建议用户获得付费的API密钥以进行高容量使用

🔒 安全说明

所有API密钥都应加密存储在平台中
永远不要在响应中记录或公开API密钥
MCP服务器本身不存储任何凭据
每个请求都会从平台接收新的凭据

错误处理

常见错误

地址格式无效：

{
  "success": false,
  "error": "Invalid Ethereum address format. Expected address starting with '0x' and 40 hex characters."
}

缺少API密钥：

{
  "success": false,
  "error": "API key required for Ethereum. Please provide 'etherscan' in accessToken."
}

不支持链：

{
  "success": false,
  "error": "Chain 'unknown-chain' is not yet implemented. Use 'list_supported_chains' to see available chains."
}

API费率限制：

{
  "success": false,
  "error": "Rate limit exceeded for Etherscan API. Please try again in 60 seconds."
}

网络错误：

{
  "success": false,
  "error": "Failed to fetch Bitcoin balance: Network timeout"
}

发展

项目结构

wallet-balance-mcp/
├── src/
│   ├── index.ts              # Main MCP server implementation
│   ├── types.ts              # TypeScript type definitions
│   ├── schemas.ts            # Zod validation schemas
│   └── chains/
│       └── chainHandlers.ts  # Blockchain-specific implementations
├── dist/                     # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
├── README.md
└── .gitignore

添加新链

要添加对新区块链的支持：

将链配置添加到 CHAIN_CONFIG 在 src/chains/chainHandlers.ts
实现余额提取功能（例如。， getNewChainBalance)
将链添加到 SupportedChain 输入 src/types.ts
将链添加到 SupportedChainEnum 在 src/schemas.ts
在中添加路由逻辑 src/index.ts fetchBalance() 方法
在中添加地址验证逻辑 validateAddressFormat() 方法
更新文档

依赖项

@模型上下文协议/sdk -MCP协议实现
轴 -区块链API请求的HTTP客户端
黄道带 -模式验证和类型安全

技术规格

Node.js版本: >= 18.0.0
TypeScript版本: ^5.0.0
模块系统：ES模块（ESM）
速率限制：尊重区块链API费率限制
并发请求：支持多链查询
超时：每个区块链API请求30秒

许可证

麻省理工学院

支持

对于问题、疑问或贡献：

GitHub问题：https://github.com/oregpt/AgentLedger_MCP_WalletBalanceService/issues
原始服务：https://github.com/orephillips/walletbalanceservice

鸣谢

根据MCP服务器构建模式指南为AgentLedger AI代理平台构建。

@orephillips原创区块链API服务

使用说明

钱包余额MCP服务器

概述

身份验证模式

令牌格式

按链划分的必需API密钥

令牌配置示例

可用工具

1. get_wallet_balance

2. get_multiple_balances

3. list_supported_chains

4. validate_address

5. get_chain_info

6. health_check

支持的区块链

安装

测试

手动测试

平台集成说明

🔑 多密钥身份验证

🎯 链发现

⚡ 性能注意事项

🔒 安全说明

错误处理

常见错误

发展

项目结构

添加新链

依赖项

技术规格

许可证

支持

鸣谢

相关 MCP

加密货币交易所集成服务

实时金融新闻分析服务

金融数据服务

加密货币查询服务

加密货币情绪指数服务

AI代理金融工具包

1. `get_wallet_balance`

2. `get_multiple_balances`

3. `list_supported_chains`

4. `validate_address`

5. `get_chain_info`

6. `health_check`