CRITICAL: Read Rule Files Before Implementing
The #1 cause of bugs is not reading the endpoint rule file before writing code.
For EVERY endpoint:
- 1. Read INLINECODE0
- Find "Example Response" section
- Copy the EXACT JSON structure
- Note field names (snake_case), data types, HTTP method, path, wrapper structure
Reading Order:
- 1. This SKILL.md (core patterns)
- Endpoint rule file in INLINECODE1
- Pattern references in
references/ (for edge cases only)
Setup
API Key (optional)
Never ask the user to paste their API key into the chat. Instead:
- 1. Check if
MORALIS_API_KEY is set in the environment (try running [ -n "$MORALIS_API_KEY" ] && echo "API key is set" || echo "API key is NOT set"). - If not set, offer to create the
.env file with an empty placeholder: INLINECODE6 - Tell the user to open the
.env file and paste their key there themselves. - Let them know: without the key, you won't be able to test or call the Moralis API on their behalf.
If they don't have a key yet, point them to admin.moralis.com/register (free, no credit card).
Environment Variable Discovery
The .env file location depends on how skills are installed:
Create the .env file in the project root (same directory the user runs Claude Code from). Make sure .env is in .gitignore.
Verify Your Key
CODEBLOCK0
Base URLs
| API | Base URL |
|---|
| EVM | INLINECODE12 |
| Solana |
https://solana-gateway.moralis.io |
Authentication
All requests require: X-API-Key: $MORALIS_API_KEY
Quick Reference: Most Common Patterns
Data Type Rules
| Field | Reality | NOT |
|---|
| INLINECODE15 | Decimal INLINECODE16 | Hex INLINECODE17 |
| INLINECODE18 |
ISO
"2021-05-07T11:08:35.000Z" | Unix
1620394115 |
|
balance | String
"1000000000000000000" | Number |
|
decimals | String or number | Always number |
Block Numbers (always decimal)
CODEBLOCK1
Timestamps (usually ISO strings)
CODEBLOCK2
Balances (always strings unless its a property named "formatted" eg. balanceFormatted, BigInt)
CODEBLOCK3
Response Patterns
| Pattern | Example Endpoints |
|---|
| Direct array INLINECODE24 | getWalletTokenBalancesPrice, getTokenMetadata |
| Wrapped INLINECODE25 |
getWalletNFTs, getWalletTransactions |
| Paginated
{ page, cursor, result } | getWalletHistory, getNFTTransfers |
CODEBLOCK4
Common Field Mappings
CODEBLOCK5
Common Pitfalls (Top 5)
- 1. Block numbers are decimal, not hex - Use
parseInt(x, 10), not INLINECODE28 - Timestamps are ISO strings - Use INLINECODE29
- Balances are strings - Use
BigInt(balance) for math - Response may be wrapped - Check for
.result before INLINECODE32 - Path inconsistencies - Some use
/wallets/{address}/..., others INLINECODE34
See references/CommonPitfalls.md for complete reference.
Pagination
Many endpoints use cursor-based pagination:
CODEBLOCK6
See references/Pagination.md for details.
Testing Endpoints
CODEBLOCK7
Quick Troubleshooting
| Issue | Cause | Solution |
|---|
| "Property does not exist" | Field name mismatch | Check snake_case in rule file |
| "Cannot read undefined" |
Missing optional field | Use
?. optional chaining |
| "blockNumber is NaN" | Parsing decimal as hex | Use radix 10:
parseInt(x, 10) |
| "Wrong timestamp" | Parsing ISO as number | Use
new Date(timestamp).getTime() |
| "404 Not Found" | Wrong endpoint path | Verify path in rule file |
Performance & Timeouts
Most endpoints respond quickly under normal conditions. Response times can vary based on wallet activity volume, chain, and query complexity.
Recommended client timeouts:
- - Simple queries (balance, price, metadata): 10s
- Complex queries (wallet history, DeFi positions): 30s
Large wallets with extensive transaction histories may take longer — use pagination with reasonable limit values.
See references/PerformanceAndLatency.md for optimization tips.
Default Chain Behavior
EVM addresses (0x...): Default to Ethereum (chain=0x1) unless specified.
Solana addresses (base58): Auto-detected and routed to Solana API.
Supported Chains
EVM (40+ chains): Ethereum (0x1), Polygon (0x89), BSC (0x38), Arbitrum (0xa4b1), Optimism (0xa), Base (0x2105), Avalanche (0xa86a), and more.
Solana: Mainnet, Devnet
See references/SupportedApisAndChains.md for full list.
Endpoint Catalog
Complete list of all 136 endpoints (102 EVM + 34 Solana) organized by category.
Wallet
Balances, tokens, NFTs, transaction history, profitability, and net worth data.
Get native balance for a set of wallets |
|
getWalletActiveChains | Get active chains by wallet address |
|
getWalletApprovals | Get ERC20 approvals by wallet |
|
getWalletHistory | Get the complete decoded transaction history of a wallet |
|
getWalletInsight | Get wallet insight metrics |
|
getWalletNetWorth | Get wallet net worth |
|
getWalletNFTCollections | Get NFT collections by wallet address |
|
getWalletNFTs | Get NFTs by wallet address |
|
getWalletNFTTransfers | Get NFT Transfers by wallet address |
|
getWalletProfitability | Get detailed profit and loss by wallet address |
|
getWalletProfitabilitySummary | Get profit and loss summary by wallet address |
|
getWalletStats | Get summary stats by wallet address |
|
getWalletTokenBalancesPrice | Get token balances with prices by wallet address |
|
getWalletTokenTransfers | Get ERC20 token transfers by wallet address |
|
getWalletTransactions | Get native transactions by wallet |
|
getWalletTransactionsVerbose | Get decoded transactions by wallet |
Token
Token prices, metadata, pairs, DEX swaps, analytics, security scores, and sniper detection.
Get historical token score by token address |
|
getMultipleTokenAnalytics | Get token analytics for a list of token addresses |
|
getPairAddress | Get DEX token pair address |
|
getPairReserves | Get DEX token pair reserves |
|
getPairStats | Get stats by pair address |
|
getSnipersByPairAddress | Get snipers by pair address |
|
getSwapsByPairAddress | Get swap transactions by pair address |
|
getSwapsByTokenAddress | Get swap transactions by token address |
|
getSwapsByWalletAddress | Get swap transactions by wallet address |
|
getTimeSeriesTokenAnalytics | Retrieve timeseries trading stats by token addresses |
|
getTokenAnalytics | Get token analytics by token address |
|
getTokenBondingStatus | Get the token bonding status |
|
getTokenCategories | Get ERC20 token categories |
|
getTokenHolders | Get a holders summary by token address |
|
getTokenMetadata | Get ERC20 token metadata by contract |
|
getTokenMetadataBySymbol | Get ERC20 token metadata by symbols |
|
getTokenOwners | Get ERC20 token owners by contract |
|
getTokenPairs | Get token pairs by address |
|
getTokenScore | Get token score by token address |
|
getTokenStats | Get ERC20 token stats |
|
getTokenTransfers | Get ERC20 token transfers by contract address |
NFT
NFT metadata, transfers, traits, rarity, floor prices, and trades.
Get Metadata for NFTs |
|
getNFTBulkContractMetadata | Get metadata for multiple NFT contracts |
|
getNFTByContractTraits | Get NFTs by traits |
|
getNFTCollectionStats | Get summary stats by NFT collection |
|
getNFTContractMetadata | Get NFT collection metadata |
|
getNFTContractSalePrices | Get NFT sale prices by collection |
|
getNFTContractTransfers | Get NFT transfers by contract address |
|
getNFTFloorPriceByContract | Get NFT floor price by contract |
|
getNFTFloorPriceByToken | Get NFT floor price by token |
|
getNFTHistoricalFloorPriceByContract | Get historical NFT floor price by contract |
|
getNFTMetadata | Get NFT metadata |
|
getNFTOwners | Get NFT owners by contract address |
|
getNFTSalePrices | Get NFT sale prices by token |
|
getNFTTokenIdOwners | Get NFT owners by token ID |
|
getNFTTrades | Get NFT trades by collection |
|
getNFTTradesByToken | Get NFT trades by token |
|
getNFTTradesByWallet | Get NFT trades by wallet address |
|
getNFTTraitsByCollection | Get NFT traits by collection |
|
getNFTTraitsByCollectionPaginate | Get NFT traits by collection paginate |
|
getNFTTransfers | Get NFT transfers by token ID |
|
getTopNFTCollectionsByMarketCap | Get top NFT collections by market cap |
DeFi
DeFi protocol positions, liquidity, and exposure data.
Get DeFi positions of a wallet |
|
getDefiSummary | Get the DeFi summary of a wallet |
Entity
Labeled addresses including exchanges, funds, protocols, and whales.
Get Entity Categories |
Price
Token and NFT prices, OHLCV candlestick data.
Get OHLCV by pair address |
|
getPairPrice | Get DEX token pair price |
|
getTokenPrice | Get ERC20 token price |
Blockchain
Blocks, transactions, date-to-block conversion, and contract functions.
Get block by date |
|
getLatestBlockNumber | Get latest block number |
|
getTransaction | Get transaction by hash |
|
getTransactionVerbose | Get decoded transaction by hash |
Discovery
Trending tokens, blue chips, market movers, and token discovery.
Retrieve timeseries trading stats by chain |
|
getTimeSeriesVolumeByCategory | Retrieve timeseries trading stats by category |
|
getTopCryptoCurrenciesByMarketCap | Get top crypto currencies by market cap |
|
getTopCryptoCurrenciesByTradingVolume | Get top crypto currencies by trading volume |
|
getTopERC20TokensByMarketCap | Get top ERC20 tokens by market cap |
|
getTopERC20TokensByPriceMovers | Get top ERC20 tokens by price movements (winners and losers) |
|
getTopGainersTokens | Get tokens with top gainers |
|
getTopLosersTokens | Get tokens with top losers |
|
getTopProfitableWalletPerToken | Get top traders for a given ERC20 token |
|
getTrendingTokens | Get trending tokens |
|
getVolumeStatsByCategory | Get trading stats by categories |
|
getVolumeStatsByChain | Get trading stats by chain |
Other
Utility endpoints including API version, endpoint weights, and address resolution.
Get Entities By Category |
|
getFilteredTokens | Returns a list of tokens that match the specified filters and criteria |
|
getGraduatedTokensByExchange | Get graduated tokens by exchange |
|
getHistoricalTokenHolders | Get timeseries holders data |
|
getNewTokensByExchange | Get new tokens by exchange |
|
getUniqueOwnersByCollection | Get unique wallet addresses owning NFTs from a contract. |
|
resolveAddress | ENS lookup by address |
|
resolveAddressToDomain | Resolve Address to Unstoppable domain |
|
resolveDomain | Resolve Unstoppable domain |
|
resolveENSDomain | ENS lookup by domain |
|
reSyncMetadata | Resync NFT metadata |
|
searchEntities | Search Entities, Organizations or Wallets |
|
searchTokens | Search for tokens based on contract address, pair address, token name or token symbol. |
Solana Endpoints
Solana-specific endpoints (24 native + 10 EVM variants that support Solana chain = 34 total).
Get aggregated token pair statistics by address |
|
getBondingTokensByExchange | Get bonding tokens by exchange |
|
getCandleSticks | Get candlesticks for a pair address |
|
getGraduatedTokensByExchange | Get graduated tokens by exchange |
|
getHistoricalTokenHolders | Get token holders overtime for a given tokens |
|
getMultipleTokenMetadata | Get multiple token metadata |
|
getMultipleTokenPrices | Get token price |
|
getNFTMetadata | Get the global metadata for a given contract |
|
getNFTs | Gets NFTs owned by the given address |
|
getNewTokensByExchange | Get new tokens by exchange |
|
getPairStats | Get stats for a pair address |
|
getPortfolio | Gets the portfolio of the given address |
|
getSPL | Gets token balances owned by the given address |
|
getSnipersByPairAddress | Get snipers by pair address. |
|
getSwapsByPairAddress | Get all swap related transactions (buy, sell, add liquidity & remove liquidity) |
|
getSwapsByTokenAddress | Get all swap related transactions (buy, sell) |
|
getSwapsByWalletAddress | Get all swap related transactions (buy, sell) for a specific wallet address. |
|
getTokenBondingStatus | Get Token Bonding Status |
|
getTokenHolders | Get the summary of holders for a given token token. |
|
getTokenMetadata | Get Token metadata |
|
getTokenPairs | Get token pairs by address |
|
getTokenPrice | Get token price |
|
getTopHolders | Get paginated top holders for a given token. |
|
getDiscoveryToken |
Solana variant: Get token details |
|
getHistoricalTokenScore |
Solana variant: Get historical token score by token address |
|
getTimeSeriesVolume |
Solana variant: Retrieve timeseries trading stats by chain |
|
getTimeSeriesVolumeByCategory |
Solana variant: Retrieve timeseries trading stats by category |
|
getTokenAnalytics |
Solana variant: Get token analytics by token address |
|
getTokenScore |
Solana variant: Get token score by token address |
|
getTopGainersTokens |
Solana variant: Get tokens with top gainers |
|
getTopLosersTokens |
Solana variant: Get tokens with top losers |
|
getTrendingTokens |
Solana variant: Get trending tokens |
|
getVolumeStatsByCategory |
Solana variant: Get trading stats by categories |
Reference Documentation
See Also
- - Endpoint rules:
rules/*.md files - Streams API: @moralis-streams-api for real-time events
关键：在实施前阅读规则文件
导致错误的头号原因是在编写代码前没有阅读端点规则文件。
对于每个端点：
- 1. 读取 rules/{EndpointName}.md
- 找到示例响应部分
- 复制确切的 JSON 结构
- 注意字段名称（snake_case）、数据类型、HTTP 方法、路径、包装结构
阅读顺序：
- 1. 本 SKILL.md（核心模式）
- rules/ 中的端点规则文件
- references/ 中的模式参考（仅用于边缘情况）
设置
API 密钥（可选）
切勿要求用户将 API 密钥粘贴到聊天中。 而是：
- 1. 检查环境中是否设置了 MORALISAPIKEY（尝试运行 [ -n $MORALISAPIKEY ] && echo API key is set || echo API key is NOT set）。
- 如果未设置，主动创建包含空占位符的 .env 文件：MORALISAPIKEY=
- 告诉用户打开 .env 文件并自行粘贴密钥。
- 告知用户：没有密钥，你将无法代表他们测试或调用 Moralis API。
如果他们还没有密钥，请引导他们访问 admin.moralis.com/register（免费，无需信用卡）。
环境变量发现
.env 文件的位置取决于技能的安装方式：
在项目根目录（用户运行 Claude Code 的同一目录）中创建 .env 文件。确保 .env 在 .gitignore 中。
验证你的密钥
bash
curl https://deep-index.moralis.io/api/v2.2/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balance?chain=0x1 \
-H X-API-Key: $MORALISAPIKEY
基础 URL
| API | 基础 URL |
|---|
| EVM | https://deep-index.moralis.io/api/v2.2 |
| Solana |
https://solana-gateway.moralis.io |
身份验证
所有请求都需要：X-API-Key: $MORALISAPIKEY
快速参考：最常见模式
数据类型规则
| 字段 | 实际情况 | 不是 |
|---|
| block_number | 十进制 12386788 | 十六进制 0xf2b5a4 |
| timestamp |
ISO 2021-05-07T11:08:35.000Z | Unix 1620394115 |
| balance | 字符串 1000000000000000000 | 数字 |
| decimals | 字符串或数字 | 始终为数字 |
区块编号（始终为十进制）
typescript
block_number: 12386788; // number - 直接使用
blocknumber: 12386788; // string - parseInt(blocknumber, 10)
时间戳（通常为 ISO 字符串）
typescript
2021-05-07T11:08:35.000Z; // → new Date(timestamp).getTime()
余额（始终为字符串，除非属性名为 formatted，例如 balanceFormatted，BigInt）
typescript
balance: 1000000000000000000;
// → (Number(BigInt(balance)) / 1e18).toFixed(6)
响应模式
| 模式 | 示例端点 |
|---|
| 直接数组 [...] | getWalletTokenBalancesPrice, getTokenMetadata |
| 包装 { result: [] } |
getWalletNFTs, getWalletTransactions |
| 分页 { page, cursor, result } | getWalletHistory, getNFTTransfers |
typescript
// 安全提取
const data = Array.isArray(response) ? response : response.result || [];
常见字段映射
typescript
token_address → tokenAddress
fromaddresslabel → fromAddressLabel
block_number → blockNumber
receipt_status: 1 → success, 0 → failed
possible_spam: true/false → boolean check
常见陷阱（前 5 个）
- 1. 区块编号是十进制，不是十六进制 - 使用 parseInt(x, 10)，而不是 parseInt(x, 16)
- 时间戳是 ISO 字符串 - 使用 new Date(timestamp).getTime()
- 余额是字符串 - 使用 BigInt(balance) 进行数学运算
- 响应可能被包装 - 在 .map() 之前检查 .result
- 路径不一致 - 有些使用 /wallets/{address}/...，其他使用 /{address}/...
请参阅 references/CommonPitfalls.md 获取完整参考。
分页
许多端点使用基于游标的分页：
bash
第一个请求
curl ...?limit=100 -H X-API-Key: $KEY
下一页
curl ...?limit=100&cursor=
fromresponse> -H X-API-Key: $KEY
详情请参阅 references/Pagination.md。
测试端点
bash
ADDRESS=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
CHAIN=0x1
钱包余额
curl https://deep-index.moralis.io/api/v2.2/${ADDRESS}/balance?chain=${CHAIN} \
-H X-API-Key: $MORALISAPIKEY
代币价格
curl https://deep-index.moralis.io/api/v2.2/erc20/0x6B175474E89094C44Da98b954EedeAC495271d0F/price?chain=${CHAIN} \
-H X-API-Key: $MORALISAPIKEY
钱包交易（注意结果包装）
curl https://deep-index.moralis.io/api/v2.2/${ADDRESS}?chain=${CHAIN}&limit=5 \
-H X-API-Key: $MORALISAPIKEY | jq .result
快速故障排除
| 问题 | 原因 | 解决方案 |
|---|
| 属性不存在 | 字段名称不匹配 | 检查规则文件中的 snake_case |
| 无法读取未定义 |
缺少可选字段 | 使用 ?. 可选链 |
| blockNumber 是 NaN | 将十进制解析为十六进制 | 使用基数 10：parseInt(x, 10) |
| 时间戳错误 | 将 ISO 解析为数字 | 使用 new Date(timestamp).getTime() |
| 404 未找到 | 端点路径错误 | 验证规则文件中的路径 |
性能与超时
大多数端点在正常情况下响应迅速。响应时间可能因钱包活动量、链和查询复杂性而异。
推荐的客户端超时：
- - 简单查询（余额、价格、元数据）：10 秒
- 复杂查询（钱包历史、DeFi 头寸）：30 秒
具有大量交易历史的大钱包可能需要更长时间——使用合理的 limit 值进行分页。
优化技巧请参阅 references/PerformanceAndLatency.md。
默认链行为
EVM 地址（0x...）： 除非指定，否则默认为以太坊（chain=0x1）。
Solana 地址（base58）： 自动检测并路由到 Solana API。
支持的链
EVM（40+ 条链）： 以太坊（0x1）、Polygon（0x89）、BSC（0x38）、Arbitrum（0xa4b1）、Optimism（0xa）、Base（0x2105）、Avalanche（0xa86a）等。
Solana： 主网、开发网
完整列表请参阅 references/SupportedApisAndChains.md。
端点目录
按类别组织的所有 136 个端点（102 个 EVM + 34 个 Solana）的完整列表。
钱包
余额、代币、NFT、交易历史、盈利能力和净资产数据。
按