moralis-data-api

关键：实施前先阅读规则文件

导致错误的首要原因，是编写代码前没有阅读端点规则文件。

对于每个端点：

1. 阅读 rules/{EndpointName}.md
2. 找到“Example Response”部分
3. 原样复制 JSON 结构
4. 记下字段名称（snake_case）、数据类型、HTTP 方法、路径和包装结构

阅读顺序：

1. 本 SKILL.md（核心模式）
2. rules/ 中的端点规则文件
3. 当用户询问 CU 成本、高级端点或套餐要求时，阅读 references/PricingAndPremium.md
4. references/ 中的模式参考（仅用于处理边缘情况）

---

设置

API 密钥

绝不要要求用户在聊天中粘贴 API 密钥。 而应：

1. 检查环境中是否已设置 MORALIS_API_KEY（尝试运行 [ -n "$MORALIS_API_KEY" ] && echo "API key is set" || echo "API key is NOT set"）。
2. 如果未设置，提出创建带有空占位值的 .env 文件：MORALIS_API_KEY=
3. 告诉用户打开 .env 文件并自行粘贴密钥。
4. 告知用户：没有密钥，你就无法代表他们测试或调用 Moralis API。

如果他们还没有密钥，请引导他们前往 admin.moralis.com/register。Free 套餐已于 2026 年 9 月 1 日取消；现在需要付费套餐。Starter、Pro 和 Business 的月费价格请参阅 套餐定价，并核对实时定价页面。

环境变量发现

.env 文件的位置取决于技能的安装方式：

在项目根目录（即用户运行 Claude Code 的目录）中创建 .env 文件。确保 .env 已列入 .gitignore。

验证密钥

curl "https://deep-index.moralis.io/api/v2.2/YOUR_EVM_ADDRESS/balance?chain=0x1" \
  -H "X-API-Key: $MORALIS_API_KEY"

---

基础 URL

API	基础 URL
EVM	https://deep-index.moralis.io/api/v2.2
Solana	https://solana-gateway.moralis.io
Universal / Bitcoin	https://api.moralis.com

身份验证

所有请求都需要：X-API-Key: $MORALIS_API_KEY

---

快速参考：最常见模式

数据类型规则

字段	实际格式	不是
block_number	十进制 12386788	十六进制 0xf2b5a4
timestamp	ISO 格式 "2021-05-07T11:08:35.000Z"	Unix 时间戳 1620394115
balance	字符串 "1000000000000000000"	数字
decimals	字符串或数字	始终是数字

区块号（始终为十进制）

block_number: 12386788; // number - use directly
block_number: "12386788"; // string - parseInt(block_number, 10)

时间戳（通常为 ISO 字符串）

"2021-05-07T11:08:35.000Z"; // → new Date(timestamp).getTime()

余额（除属性名为 "formatted"（例如 balanceFormatted）或 BigInt 外，始终为字符串）

balance: "1000000000000000000";
// → (Number(BigInt(balance)) / 1e18).toFixed(6)

响应模式

模式	端点示例
直接数组 [...]	getWalletTokenBalancesPrice、getTokenMetadata
包装对象 { result: [] }	getWalletNFTs、getWalletTransactions
分页对象 { page, cursor, result }	getWalletHistory、getNFTTransfers

// Safe extraction
const data = Array.isArray(response) ? response : response.result || [];

常见字段映射

token_address → tokenAddress
from_address_label → fromAddressLabel
block_number → blockNumber
receipt_status: "1" → success, "0" → failed
possible_spam: "true"/"false" → boolean check

---

常见问题（前 5 项）

1. 区块号是十进制，不是十六进制 - 使用 parseInt(x, 10)，不要使用 parseInt(x, 16)
2. 时间戳是 ISO 字符串 - 使用 new Date(timestamp).getTime()
3. 余额是字符串 - 计算时使用 BigInt(balance)
4. 响应可能有包装层 - 调用 .map() 前先检查 .result
5. 路径不一致 - 有些使用 /wallets/{address}/...，另一些使用 /{address}/...

完整参考请参阅 references/CommonPitfalls.md。

---

分页

许多端点使用基于游标的分页：

# First request
curl "...?limit=100" -H "X-API-Key: $KEY"

# Next page
curl "...?limit=100&cursor=<cursor_from_response>" -H "X-API-Key: $KEY"

详情请参阅 references/Pagination.md。

---

测试端点

ADDRESS="YOUR_EVM_ADDRESS"
CHAIN="0x1"

# Wallet Balance
curl "https://deep-index.moralis.io/api/v2.2/${ADDRESS}/balance?chain=${CHAIN}" \
  -H "X-API-Key: $MORALIS_API_KEY"

# Token Price
curl "https://deep-index.moralis.io/api/v2.2/erc20/YOUR_EVM_ADDRESS/price?chain=${CHAIN}" \
  -H "X-API-Key: $MORALIS_API_KEY"

# Wallet Transactions (note result wrapper)
curl "https://deep-index.moralis.io/api/v2.2/${ADDRESS}?chain=${CHAIN}&limit=5" \
  -H "X-API-Key: $MORALIS_API_KEY" | jq '.result'

---

快速故障排查

问题	原因	解决方案
"Property does not exist"	字段名称不匹配	检查规则文件中的 snake_case
"Cannot read undefined"	缺少可选字段	使用 ?. 可选链
"blockNumber is NaN"	将十进制解析为十六进制	使用基数 10：parseInt(x, 10)
"Wrong timestamp"	将 ISO 格式解析为数字	使用 new Date(timestamp).getTime()
"404 Not Found"	端点路径错误或已移除	查看规则目录和 DeprecatedEndpoints.md

---

性能与超时

在正常情况下，大多数端点都能快速响应。响应时间可能会因钱包活动量、链和查询复杂度而有所不同。

建议的客户端超时时间：

• 简单查询（余额、价格、元数据）：10s
• 复杂查询（钱包历史记录、DeFi 持仓）：30s

交易历史记录较多的大型钱包可能需要更长时间；请使用分页，并设置合理的 limit 值。

请参阅 references/PerformanceAndLatency.md，了解优化技巧。

定价与方案要求

Data API 端点有明确的计算单元（CU）成本，部分端点需要 Starter 或 Pro 方案。在回答成本、配额、高级端点或方案访问限制相关问题前，请先查阅 references/PricingAndPremium.md。

---

默认链行为

EVM 地址（0x...）： 除非另有说明，默认使用 Ethereum（chain=0x1）。

Solana 地址（base58）： 自动检测并路由至 Solana API。

---

支持的链

EVM： 使用端点规则中的当前别名和十六进制 ID。Fantom 和若干测试网已移除。Moonbeam、Moonriver 和 Lisk 计划于 2026 年 9 月 25 日移除。

Solana： 仅主网

完整列表请参阅 references/SupportedApisAndChains.md。

---

端点目录

按类别整理的全部 116 个端点（79 个 EVM + 18 个 Solana + 19 个通用 / Bitcoin）列表。

钱包

余额、代币、NFT、交易历史、盈利能力和净资产数据。

端点	描述
getNativeBalance	获取钱包的原生余额
getNativeBalancesForAddresses	获取一组钱包的原生余额
getWalletActiveChains	获取钱包地址活跃的链
getWalletApprovals	获取钱包的 ERC20 授权
getWalletHistory	获取钱包完整的解码后交易历史
getWalletInsight	获取钱包洞察指标
getWalletNetWorth	获取钱包净资产
getWalletNFTCollections	获取钱包地址的 NFT 集合
getWalletNFTs	获取钱包地址的 NFT
getWalletNFTTransfers	获取钱包地址的 NFT 转账
getWalletProfitability	获取钱包地址的详细盈亏数据
getWalletProfitabilitySummary	获取钱包地址的盈亏摘要
getWalletStats	获取钱包地址的汇总统计数据
getWalletTokenBalances	获取钱包的 ERC20 代币余额
getWalletTokenBalancesPrice	获取钱包地址的代币余额及价格
getWalletTokenTransfers	获取钱包地址的 ERC20 代币转账
getWalletTransactions	获取钱包的原生交易
getWalletTransactionsVerbose	获取钱包的解码后交易

代币

代币价格、元数据、交易对、DEX 兑换、分析数据、安全评分和持有者信息。

端点	描述
getHistoricalTokenScore	根据代币地址获取历史代币评分
getMultipleTokenAnalytics	获取代币地址列表对应的代币分析数据
getPairStats	根据交易对地址获取统计数据
getSwapsByPairAddress	根据交易对地址获取兑换交易
getSwapsByTokenAddress	根据代币地址获取兑换交易
getSwapsByWalletAddress	根据钱包地址获取兑换交易
getTimeSeriesTokenAnalytics	根据代币地址获取时间序列交易统计数据
getTokenAnalytics	根据代币地址获取代币分析数据
getTokenCategories	获取 ERC20 代币类别
getTokenHolders	根据代币地址获取持有者摘要
getTokenMetadata	根据合约获取 ERC20 代币元数据
getTokenOwners	根据合约获取 ERC20 代币所有者
getTokenPairs	根据地址获取代币交易对
getTokenScore	根据代币地址获取代币评分
getTokenTransfers	根据合约地址获取 ERC20 代币转账

NFT

NFT 元数据、转移、特征、稀有度、地板价和交易。

Endpoint	描述
getContractNFTs	按合约地址获取 NFT
getMultipleNFTs	获取 NFT 元数据
getNFTBulkContractMetadata	获取多个 NFT 合约的元数据
getNFTByContractTraits	按特征获取 NFT
getNFTCollectionStats	获取 NFT 收藏集的汇总统计数据
getNFTContractMetadata	获取 NFT 收藏集元数据
getNFTContractSalePrices	按收藏集获取 NFT 售价
getNFTContractTransfers	按合约地址获取 NFT 转移记录
getNFTFloorPriceByContract	按合约获取 NFT 地板价
getNFTFloorPriceByToken	按代币获取 NFT 地板价
getNFTHistoricalFloorPriceByContract	按合约获取 NFT 历史地板价
getNFTMetadata	获取 NFT 元数据
getNFTOwners	按合约地址获取 NFT 持有者
getNFTSalePrices	按代币获取 NFT 售价
getNFTTokenIdOwners	按代币 ID 获取 NFT 持有者
getNFTTrades	按收藏集获取 NFT 交易
getNFTTradesByToken	按代币获取 NFT 交易
getNFTTradesByWallet	按钱包地址获取 NFT 交易
getNFTTraitsByCollection	按收藏集获取 NFT 特征
getNFTTraitsByCollectionPaginate	分页获取收藏集的 NFT 特征
getNFTTransfers	按代币 ID 获取 NFT 转移记录
resyncNFTRarity	重新同步 NFT 特征

DeFi

DeFi 协议头寸、流动性和敞口数据。

Endpoint	描述
getDefiPositionsByProtocol	按协议获取钱包的详细 DeFi 头寸
getDefiPositionsSummary	获取钱包的 DeFi 头寸
getDefiSummary	获取钱包的 DeFi 汇总信息

Entity

带标签的地址，包括交易所、基金、协议和巨鲸。

Endpoint	描述
getEntity	按 ID 获取实体详情
getEntityCategories	获取实体类别

Price

代币和 NFT 价格、OHLCV 蜡烛图数据。

Endpoint	描述
getMultipleTokenPrices	获取多个 ERC20 代币价格
getPairCandlesticks	按交易对地址获取 OHLCV 数据
getTokenPrice	获取 ERC20 代币价格

Blockchain

区块、交易、日期到区块的转换以及合约函数。

Endpoint	描述
getBlock	按哈希获取区块
getDateToBlock	按日期获取区块
getLatestBlockNumber	获取最新区块编号
getTransaction	按哈希获取交易
getTransactionVerbose	按哈希获取解码后的交易

发现

热门代币和顶级交易者发现。

Endpoint	描述
getTopProfitableWalletPerToken	获取指定 ERC20 代币的顶级交易者
getTrendingTokensV2	获取热门代币

其他

地址解析、实体搜索和支持性实用工具。

Endpoint	描述
getEntitiesByCategory	按类别获取实体
getUniqueOwnersByCollection	获取持有某合约 NFT 的唯一钱包地址。
resolveAddress	按地址查询 ENS
resolveAddressToDomain	将地址解析为 Unstoppable 域名
resolveDomain	解析 Unstoppable 域名
resolveENSDomain	按域名查询 ENS
reSyncMetadata	重新同步 NFT 元数据
searchEntities	搜索实体、组织或钱包
searchTokens	根据合约地址、交易对地址、代币名称或代币符号搜索代币。

Solana 端点

Solana 专用端点（16 个原生端点 + 2 个支持 Solana 链的 EVM 变体 = 共 18 个）。

Endpoint	描述
balance	获取指定地址持有的原生余额
getAggregatedTokenPairStats	按地址获取汇总的代币交易对统计数据
getCandleSticks	获取交易对地址的蜡烛图数据
getMultipleTokenMetadata	获取多个代币的元数据
getMultipleTokenPrices	获取代币价格
getNFTMetadata	获取指定合约的全局元数据
getNFTs	获取指定地址持有的 NFT
getPairStats	获取交易对地址的统计数据
getPortfolio	获取指定地址的投资组合
getSPL	获取指定地址持有的代币余额
getSwapsByPairAddress	获取所有与兑换相关的交易（买入、卖出、添加流动性和移除流动性）
getSwapsByTokenAddress	获取所有与兑换相关的交易（买入、卖出）
getSwapsByWalletAddress	获取指定钱包地址的所有与兑换相关的交易（买入、卖出）。
getTokenMetadata	获取代币元数据
getTokenPairs	按地址获取代币交易对
getTokenPrice	获取代币价格
getTokenAnalytics	**Solana 变体：**按代币地址获取代币分析数据
getTrendingTokensV2	**Solana 变体：**获取热门代币

通用 / Bitcoin 端点

Bitcoin Data API 和跨链 Universal API 页面使用的 Universal v1 端点。

端点	描述
getAddressesByXpub	根据 Bitcoin 扩展公钥（xpub）获取派生地址。
getBlockByNumberOrHash	根据链和区块编号或哈希获取区块
getCandleSticks	根据交易对地址获取 OHLCV 蜡烛图数据
getDefiPositions	获取钱包在多个链上的 DeFi 仓位
getDefiProtocolPositions	获取指定协议的 DeFi 仓位
getDefiProtocols	获取所有受支持的 DeFi 协议
getDefiSummary	获取钱包在多个链上的 DeFi 仓位摘要
getSwapsByPairAddress	获取所有与兑换相关的交易（买入、卖出、添加流动性和移除流动性）
getSwapsByTokenAddress	获取所有与兑换相关的交易（买入、卖出）
getTokenBalances	获取指定钱包地址在多个链上的代币余额。
getTokenPrice	根据代币地址获取代币价格
getTokenPriceSparkline	获取代币价格迷你走势图数据
getTokenPriceTimeSeries	获取代币历史价格时间序列
getTopTradersByToken	获取单条链上某代币的顶级交易者。
getTransactionByHash	根据链和交易哈希获取交易
getWalletHistory	获取钱包在多个链上的交易历史。
getWalletInsight	获取钱包在多个链上的洞察指标。
getWalletProfitability	获取钱包在多个链上各代币的盈利能力。
getWalletProfitabilitySummary	获取钱包在多个链上的整体盈利能力摘要。

参考文档

• references/CommonPitfalls.md - 完整的常见问题参考
• references/DataTransformations.md - 类型转换参考
• references/DataFeatureGuidance.md - 数据增强、安全、定价和发现功能行为
• references/DeprecatedEndpoints.md - 已移除的路由、替代方案及明确没有替代方案的情况
• references/ApiResponseCodes.md - 常见状态码和响应字段约定
• references/PerformanceAndLatency.md - 响应时间指南、超时建议和缓存
• references/ResponsePatterns.md - 分页模式
• references/SpamDetection.md - 垃圾信息检测行为和筛选指南
• references/SupportedApisAndChains.md - 链和 API
• references/UniversalAndBitcoin.md - Universal v1 和 Bitcoin Data API 请求模式

---

另请参阅

• 端点规则：rules/*.md 文件
• Streams API：@moralis-streams-api，用于实时事件