moralis-data-api

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 rules/{EndpointName}.md
2. Find "Example Response" section
3. Copy the EXACT JSON structure
4. Note field names (snake_case), data types, HTTP method, path, wrapper structure

Reading Order:

1. This SKILL.md (core patterns)
2. Endpoint rule file in rules/
3. references/PricingAndPremium.md when the user asks about CU costs, premium endpoints, or plan requirements
4. Pattern references in references/ (for edge cases only)

---

Setup

API Key

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").
2. If not set, offer to create the .env file with an empty placeholder: MORALIS_API_KEY=
3. Tell the user to open the .env file and paste their key there themselves.
4. 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. The Free plan was removed on September 1, 2026; a paid plan is required. For Starter, Pro, and Business monthly prices, see plan pricing and verify the live pricing page.

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

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

---

Base URLs

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

Authentication

All requests require: X-API-Key: $MORALIS_API_KEY

---

Quick Reference: Most Common Patterns

Data Type Rules

Field	Reality	NOT
block_number	Decimal 12386788	Hex 0xf2b5a4
timestamp	ISO "2021-05-07T11:08:35.000Z"	Unix 1620394115
balance	String "1000000000000000000"	Number
decimals	String or number	Always number

Block Numbers (always decimal)

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

Timestamps (usually ISO strings)

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

Balances (always strings unless its a property named "formatted" eg. balanceFormatted, BigInt)

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

Response Patterns

Pattern	Example Endpoints
Direct array [...]	getWalletTokenBalancesPrice, getTokenMetadata
Wrapped { result: [] }	getWalletNFTs, getWalletTransactions
Paginated { page, cursor, result }	getWalletHistory, getNFTTransfers

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

Common Field Mappings

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

---

Common Pitfalls (Top 5)

1. Block numbers are decimal, not hex - Use parseInt(x, 10), not parseInt(x, 16)
2. Timestamps are ISO strings - Use new Date(timestamp).getTime()
3. Balances are strings - Use BigInt(balance) for math
4. Response may be wrapped - Check for .result before .map()
5. Path inconsistencies - Some use /wallets/{address}/..., others /{address}/...

See references/CommonPitfalls.md for complete reference.

---

Pagination

Many endpoints use cursor-based pagination:

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

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

See references/Pagination.md for details.

---

Testing Endpoints

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'

---

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 or removed endpoint path	Verify the rule catalog and DeprecatedEndpoints.md

---

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.

Pricing and Plan Requirements

Data API endpoints have explicit Compute Unit (CU) costs, and some endpoints require Starter or Pro plans. Use references/PricingAndPremium.md before answering cost, quota, premium endpoint, or plan-gating questions.

---

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: Use the current aliases and hex IDs from the endpoint rule. Fantom and several testnets have been removed. Moonbeam, Moonriver, and Lisk are scheduled for removal on September 25, 2026.

Solana: Mainnet only

See references/SupportedApisAndChains.md for full list.

---

Endpoint Catalog

Complete list of all 116 endpoints (79 EVM + 18 Solana + 19 Universal / Bitcoin) organized by category.

Wallet

Balances, tokens, NFTs, transaction history, profitability, and net worth data.

Endpoint	Description
getNativeBalance	Get native balance by wallet
getNativeBalancesForAddresses	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
getWalletTokenBalances	Get ERC20 token balances by wallet
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 holders.

Endpoint	Description
getHistoricalTokenScore	Get historical token score by token address
getMultipleTokenAnalytics	Get token analytics for a list of token addresses
getPairStats	Get stats 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
getTokenCategories	Get ERC20 token categories
getTokenHolders	Get a holders summary by token address
getTokenMetadata	Get ERC20 token metadata by contract
getTokenOwners	Get ERC20 token owners by contract
getTokenPairs	Get token pairs by address
getTokenScore	Get token score by token address
getTokenTransfers	Get ERC20 token transfers by contract address

NFT

NFT metadata, transfers, traits, rarity, floor prices, and trades.

Endpoint	Description
getContractNFTs	Get NFTs by contract address
getMultipleNFTs	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
resyncNFTRarity	Resync NFT Trait

DeFi

DeFi protocol positions, liquidity, and exposure data.

Endpoint	Description
getDefiPositionsByProtocol	Get detailed DeFi positions by protocol for a wallet
getDefiPositionsSummary	Get DeFi positions of a wallet
getDefiSummary	Get the DeFi summary of a wallet

Entity

Labeled addresses including exchanges, funds, protocols, and whales.

Endpoint	Description
getEntity	Get Entity Details By Id
getEntityCategories	Get Entity Categories

Price

Token and NFT prices, OHLCV candlestick data.

Endpoint	Description
getMultipleTokenPrices	Get Multiple ERC20 token prices
getPairCandlesticks	Get OHLCV by pair address
getTokenPrice	Get ERC20 token price

Blockchain

Blocks, transactions, date-to-block conversion, and contract functions.

Endpoint	Description
getBlock	Get block by hash
getDateToBlock	Get block by date
getLatestBlockNumber	Get latest block number
getTransaction	Get transaction by hash
getTransactionVerbose	Get decoded transaction by hash

Discovery

Trending tokens and top-trader discovery.

Endpoint	Description
getTopProfitableWalletPerToken	Get top traders for a given ERC20 token
getTrendingTokensV2	Get trending tokens

Other

Address resolution, entity search, and supporting utilities.

Endpoint	Description
getEntitiesByCategory	Get Entities By Category
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 (16 native + 2 EVM variants that support Solana chain = 18 total).

Endpoint	Description
balance	Gets native balance owned by the given address
getAggregatedTokenPairStats	Get aggregated token pair statistics by address
getCandleSticks	Get candlesticks for a pair address
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
getPairStats	Get stats for a pair address
getPortfolio	Gets the portfolio of the given address
getSPL	Gets token balances owned by the given 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.
getTokenMetadata	Get Token metadata
getTokenPairs	Get token pairs by address
getTokenPrice	Get token price
getTokenAnalytics	Solana variant: Get token analytics by token address
getTrendingTokensV2	Solana variant: Get trending tokens

Universal / Bitcoin Endpoints

Universal v1 endpoints used by the Bitcoin Data API and cross-chain Universal API pages.

Endpoint	Description
getAddressesByXpub	Get derived addresses from a Bitcoin extended public key (xpub).
getBlockByNumberOrHash	Get a block by chain and block number or hash
getCandleSticks	Get the OHLCV candle stick by using pair address
getDefiPositions	Get DeFi positions for a wallet across multiple chains
getDefiProtocolPositions	Get DeFi positions for a specific protocol
getDefiProtocols	Get all supported DeFi protocols
getDefiSummary	Get DeFi positions summary for a wallet across multiple chains
getSwapsByPairAddress	Get all swap related transactions (buy, sell, add liquidity & remove liquidity)
getSwapsByTokenAddress	Get all swap related transactions (buy, sell)
getTokenBalances	Get token balances from multiple chains for a specific wallet address.
getTokenPrice	Get the price of a token by its address
getTokenPriceSparkline	Get sparkline price data for a token
getTokenPriceTimeSeries	Get historical price time-series for a token
getTopTradersByToken	Get the top traders for a token on a single chain.
getTransactionByHash	Get a transaction by chain and transaction hash
getWalletHistory	Get wallet transaction history across multiple chains.
getWalletInsight	Get wallet insight metrics across multiple chains.
getWalletProfitability	Get per-token profitability for a wallet across multiple chains.
getWalletProfitabilitySummary	Get the wallet-level profitability summary across multiple chains.

Reference Documentation

• references/CommonPitfalls.md - Complete pitfalls reference
• references/DataTransformations.md - Type conversion reference
• references/DataFeatureGuidance.md - Enrichment, safety, pricing, and discovery feature behavior
• references/DeprecatedEndpoints.md - Removed routes, replacements, and explicit no-replacement cases
• references/ApiResponseCodes.md - Common status codes and response field conventions
• references/PerformanceAndLatency.md - Response time guidance, timeout recommendations, caching
• references/ResponsePatterns.md - Pagination patterns
• references/SpamDetection.md - Spam detection behavior and filtering guidance
• references/SupportedApisAndChains.md - Chains and APIs
• references/UniversalAndBitcoin.md - Universal v1 and Bitcoin Data API request patterns

---

See Also

• Endpoint rules: rules/*.md files
• Streams API: @moralis-streams-api for real-time events