moralis-data-api

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

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

对于每个端点：

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

阅读顺序：

1. 本 SKILL.md（核心模式）
2. rules/ 中的端点规则文件
3. 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（免费，无需信用卡）。

环境变量查找

.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

身份验证

所有请求都需要：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"	端点路径错误	在规则文件中核对路径

---

性能与超时

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

建议的客户端超时时间：

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

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

请参阅 references/PerformanceAndLatency.md 了解优化建议。

---

默认链行为

EVM 地址（0x...）： 除非另有指定，否则默认为 Ethereum（chain=0x1）。

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

---

支持的链

EVM（40 多条链）： Ethereum（0x1）、Polygon（0x89）、BSC（0x38）、Arbitrum（0xa4b1）、Optimism（0xa）、Base（0x2105）、Avalanche（0xa86a）等。

Solana： Mainnet、Devnet

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

---

端点目录

按类别整理的全部 136 个端点（102 个 EVM + 34 个 Solana）的完整列表。

钱包

余额、代币、NFT、交易历史记录、盈利能力和净值数据。

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

代币

代币价格、元数据、交易对、DEX 兑换、分析、安全评分和狙击者检测。

端点	描述
getAggregatedTokenPairStats	根据地址获取汇总的代币交易对统计信息
getHistoricalTokenScore	根据代币地址获取历史代币评分
getMultipleTokenAnalytics	获取代币地址列表对应的代币分析数据
getPairAddress	获取 DEX 代币交易对地址
getPairReserves	获取 DEX 代币交易对储备量
getPairStats	根据交易对地址获取统计信息
getSnipersByPairAddress	根据交易对地址获取狙击者
getSwapsByPairAddress	根据交易对地址获取兑换交易
getSwapsByTokenAddress	根据代币地址获取兑换交易
getSwapsByWalletAddress	根据钱包地址获取兑换交易
getTimeSeriesTokenAnalytics	根据代币地址获取时间序列交易统计信息
getTokenAnalytics	根据代币地址获取代币分析数据
getTokenBondingStatus	获取代币绑定状态
getTokenCategories	获取 ERC20 代币类别
getTokenHolders	根据代币地址获取持有者摘要
getTokenMetadata	根据合约获取 ERC20 代币元数据
getTokenMetadataBySymbol	根据代币符号获取 ERC20 代币元数据
getTokenOwners	根据合约获取 ERC20 代币所有者
getTokenPairs	根据地址获取代币交易对
getTokenScore	根据代币地址获取代币评分
getTokenStats	获取 ERC20 代币统计信息
getTokenTransfers	根据合约地址获取 ERC20 代币转账记录

NFT

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

Endpoint	Description
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 转账记录
getTopNFTCollectionsByMarketCap	获取市值最高的 NFT 系列

DeFi

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

Endpoint	Description
getDefiPositionsByProtocol	获取钱包在各协议中的 DeFi 头寸详情
getDefiPositionsSummary	获取钱包的 DeFi 头寸
getDefiSummary	获取钱包的 DeFi 摘要

Entity

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

Endpoint	Description
getEntity	根据 ID 获取实体详情
getEntityCategories	获取实体类别

Price

代币和 NFT 价格、OHLCV K 线数据。

Endpoint	Description
getMultipleTokenPrices	获取多个 ERC20 代币价格
getPairCandlesticks	根据交易对地址获取 OHLCV 数据
getPairPrice	获取 DEX 代币交易对价格
getTokenPrice	获取 ERC20 代币价格

Blockchain

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

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

发现

热门代币、蓝筹代币、市场异动代币和代币发现。

Endpoint	Description
getDiscoveryToken	获取代币详情
getTimeSeriesVolume	按链获取时间序列交易统计数据
getTimeSeriesVolumeByCategory	按类别获取时间序列交易统计数据
getTopCryptoCurrenciesByMarketCap	获取市值最高的加密货币
getTopCryptoCurrenciesByTradingVolume	获取交易量最高的加密货币
getTopERC20TokensByMarketCap	获取市值最高的 ERC20 代币
getTopERC20TokensByPriceMovers	获取价格变动幅度最大的 ERC20 代币（涨幅最大和跌幅最大）
getTopGainersTokens	获取涨幅最大的代币
getTopLosersTokens	获取跌幅最大的代币
getTopProfitableWalletPerToken	获取指定 ERC20 代币的顶级交易者
getTrendingTokens	获取热门代币
getVolumeStatsByCategory	按类别获取交易统计数据
getVolumeStatsByChain	按链获取交易统计数据

其他

实用端点，包括 API 版本、端点权重和地址解析。

Endpoint	Description
getBondingTokensByExchange	按交易所获取绑定代币
getEntitiesByCategory	按类别获取实体
getFilteredTokens	返回符合指定筛选条件和标准的代币列表
getGraduatedTokensByExchange	按交易所获取已毕业的代币
getHistoricalTokenHolders	获取持有者时间序列数据
getNewTokensByExchange	按交易所获取新代币
getUniqueOwnersByCollection	获取拥有某合约 NFT 的唯一钱包地址。
resolveAddress	根据地址查询 ENS
resolveAddressToDomain	将地址解析为 Unstoppable 域名
resolveDomain	解析 Unstoppable 域名
resolveENSDomain	根据域名查询 ENS
reSyncMetadata	重新同步 NFT 元数据
searchEntities	搜索实体、组织或钱包
searchTokens	根据合约地址、交易对地址、代币名称或代币符号搜索代币。

Solana 端点

Solana 专用端点（24 个原生端点 + 10 个支持 Solana 链的 EVM 变体，共 34 个）。

端点	描述
balance	获取给定地址持有的原生代币余额
getAggregatedTokenPairStats	按地址获取汇总的代币对统计信息
getBondingTokensByExchange	按交易所获取绑定中的代币
getCandleSticks	获取交易对地址的 K 线
getGraduatedTokensByExchange	按交易所获取已完成绑定的代币
getHistoricalTokenHolders	获取给定代币的持有者历史变化
getMultipleTokenMetadata	获取多个代币的元数据
getMultipleTokenPrices	获取代币价格
getNFTMetadata	获取给定合约的全局元数据
getNFTs	获取给定地址持有的 NFT
getNewTokensByExchange	按交易所获取新代币
getPairStats	获取交易对地址的统计信息
getPortfolio	获取给定地址的投资组合
getSPL	获取给定地址持有的代币余额
getSnipersByPairAddress	按交易对地址获取狙击者。
getSwapsByPairAddress	获取所有与兑换相关的交易（买入、卖出、添加流动性和移除流动性）
getSwapsByTokenAddress	获取所有与兑换相关的交易（买入、卖出）
getSwapsByWalletAddress	获取特定钱包地址所有与兑换相关的交易（买入、卖出）。
getTokenBondingStatus	获取代币绑定状态
getTokenHolders	获取给定代币的持有者摘要。
getTokenMetadata	获取代币元数据
getTokenPairs	按地址获取代币对
getTokenPrice	获取代币价格
getTopHolders	分页获取给定代币的顶级持有者。
getDiscoveryToken	**Solana 变体：**获取代币详情
getHistoricalTokenScore	**Solana 变体：**按代币地址获取历史代币评分
getTimeSeriesVolume	**Solana 变体：**按链获取时间序列交易统计数据
getTimeSeriesVolumeByCategory	**Solana 变体：**按类别获取时间序列交易统计数据
getTokenAnalytics	**Solana 变体：**按代币地址获取代币分析数据
getTokenScore	**Solana 变体：**按代币地址获取代币评分
getTopGainersTokens	**Solana 变体：**获取涨幅最大的代币
getTopLosersTokens	**Solana 变体：**获取跌幅最大的代币
getTrendingTokens	**Solana 变体：**获取热门代币
getVolumeStatsByCategory	**Solana 变体：**按类别获取交易统计数据

参考文档

• references/CommonPitfalls.md - 完整的常见问题参考
• references/DataTransformations.md - 类型转换参考
• references/FilteredTokens.md - 代币发现指标、时间范围、筛选条件和示例
• references/ApiResponseCodes.md - 常见状态码和响应字段约定
• references/PerformanceAndLatency.md - 响应时间指南、超时建议、缓存
• references/ResponsePatterns.md - 分页模式
• references/SpamDetection.md - 垃圾信息检测行为和筛选指南
• references/SupportedApisAndChains.md - 区块链和 API

---

另请参阅

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