# Moralis Data API

> Query Web3 blockchain data from Moralis API. Use when user asks about wallet data, token data, NFTs, DeFi positions, entity labels, blocks, transactions, Universal multi-chain data, or Bitcoin address/xpub data. Supports EVM, Solana, Universal, and Bitcoin paths. NOT for real-time streaming - use moralis-streams-api instead.

- Skill: `novnski/moralis-data-api` (Agent Skill, multi-file: 135 files)
- Install (CLI): `npx skillmds@latest add novnski/moralis-data-api`
- Raw SKILL.md: https://api.skillmd.com/api/skills/novnski/moralis-data-api/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- License: MIT
- Author: novnski (https://skillmd.com/u/novnski)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/novnski/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](https://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](../learn-moralis/references/FAQ.md#what-are-the-current-plan-prices) and verify the [live pricing page](https://moralis.com/pricing/).

### 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

```bash
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)

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

### Timestamps (usually ISO strings)

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

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

```typescript
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             |

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

### Common Field Mappings

```typescript
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](references/CommonPitfalls.md) for complete reference.

---

## Pagination

Many endpoints use cursor-based pagination:

```bash
# 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](references/Pagination.md) for details.

---

## Testing Endpoints

```bash
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](references/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](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](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](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](rules/getNativeBalance.md) | Get native balance by wallet |
| [getNativeBalancesForAddresses](rules/getNativeBalancesForAddresses.md) | Get native balance for a set of wallets |
| [getWalletActiveChains](rules/getWalletActiveChains.md) | Get active chains by wallet address |
| [getWalletApprovals](rules/getWalletApprovals.md) | Get ERC20 approvals by wallet |
| [getWalletHistory](rules/getWalletHistory.md) | Get the complete decoded transaction history of a wallet |
| [getWalletInsight](rules/getWalletInsight.md) | Get wallet insight metrics |
| [getWalletNetWorth](rules/getWalletNetWorth.md) | Get wallet net worth |
| [getWalletNFTCollections](rules/getWalletNFTCollections.md) | Get NFT collections by wallet address |
| [getWalletNFTs](rules/getWalletNFTs.md) | Get NFTs by wallet address |
| [getWalletNFTTransfers](rules/getWalletNFTTransfers.md) | Get NFT Transfers by wallet address |
| [getWalletProfitability](rules/getWalletProfitability.md) | Get detailed profit and loss by wallet address |
| [getWalletProfitabilitySummary](rules/getWalletProfitabilitySummary.md) | Get profit and loss summary by wallet address |
| [getWalletStats](rules/getWalletStats.md) | Get summary stats by wallet address |
| [getWalletTokenBalances](rules/getWalletTokenBalances.md) | Get ERC20 token balances by wallet |
| [getWalletTokenBalancesPrice](rules/getWalletTokenBalancesPrice.md) | Get token balances with prices by wallet address |
| [getWalletTokenTransfers](rules/getWalletTokenTransfers.md) | Get ERC20 token transfers by wallet address |
| [getWalletTransactions](rules/getWalletTransactions.md) | Get native transactions by wallet |
| [getWalletTransactionsVerbose](rules/getWalletTransactionsVerbose.md) | Get decoded transactions by wallet |

### Token

Token prices, metadata, pairs, DEX swaps, analytics, security scores, and holders.

| Endpoint | Description |
|----------|-------------|
| [getHistoricalTokenScore](rules/getHistoricalTokenScore.md) | Get historical token score by token address |
| [getMultipleTokenAnalytics](rules/getMultipleTokenAnalytics.md) | Get token analytics for a list of token addresses |
| [getPairStats](rules/getPairStats__evm.md) | Get stats by pair address |
| [getSwapsByPairAddress](rules/getSwapsByPairAddress__evm.md) | Get swap transactions by pair address |
| [getSwapsByTokenAddress](rules/getSwapsByTokenAddress__evm.md) | Get swap transactions by token address |
| [getSwapsByWalletAddress](rules/getSwapsByWalletAddress__evm.md) | Get swap transactions by wallet address |
| [getTimeSeriesTokenAnalytics](rules/getTimeSeriesTokenAnalytics.md) | Retrieve timeseries trading stats by token addresses |
| [getTokenAnalytics](rules/getTokenAnalytics.md) | Get token analytics by token address |
| [getTokenCategories](rules/getTokenCategories.md) | Get ERC20 token categories |
| [getTokenHolders](rules/getTokenHolders.md) | Get a holders summary by token address |
| [getTokenMetadata](rules/getTokenMetadata__evm.md) | Get ERC20 token metadata by contract |
| [getTokenOwners](rules/getTokenOwners.md) | Get ERC20 token owners by contract |
| [getTokenPairs](rules/getTokenPairs__evm.md) | Get token pairs by address |
| [getTokenScore](rules/getTokenScore.md) | Get token score by token address |
| [getTokenTransfers](rules/getTokenTransfers.md) | Get ERC20 token transfers by contract address |

### NFT

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

| Endpoint | Description |
|----------|-------------|
| [getContractNFTs](rules/getContractNFTs.md) | Get NFTs by contract address |
| [getMultipleNFTs](rules/getMultipleNFTs.md) | Get Metadata for NFTs |
| [getNFTBulkContractMetadata](rules/getNFTBulkContractMetadata.md) | Get metadata for multiple NFT contracts |
| [getNFTByContractTraits](rules/getNFTByContractTraits.md) | Get NFTs by traits |
| [getNFTCollectionStats](rules/getNFTCollectionStats.md) | Get summary stats by NFT collection |
| [getNFTContractMetadata](rules/getNFTContractMetadata.md) | Get NFT collection metadata |
| [getNFTContractSalePrices](rules/getNFTContractSalePrices.md) | Get NFT sale prices by collection |
| [getNFTContractTransfers](rules/getNFTContractTransfers.md) | Get NFT transfers by contract address |
| [getNFTFloorPriceByContract](rules/getNFTFloorPriceByContract.md) | Get NFT floor price by contract |
| [getNFTFloorPriceByToken](rules/getNFTFloorPriceByToken.md) | Get NFT floor price by token |
| [getNFTHistoricalFloorPriceByContract](rules/getNFTHistoricalFloorPriceByContract.md) | Get historical NFT floor price by contract |
| [getNFTMetadata](rules/getNFTMetadata__evm.md) | Get NFT metadata |
| [getNFTOwners](rules/getNFTOwners.md) | Get NFT owners by contract address |
| [getNFTSalePrices](rules/getNFTSalePrices.md) | Get NFT sale prices by token |
| [getNFTTokenIdOwners](rules/getNFTTokenIdOwners.md) | Get NFT owners by token ID |
| [getNFTTrades](rules/getNFTTrades.md) | Get NFT trades by collection |
| [getNFTTradesByToken](rules/getNFTTradesByToken.md) | Get NFT trades by token |
| [getNFTTradesByWallet](rules/getNFTTradesByWallet.md) | Get NFT trades by wallet address |
| [getNFTTraitsByCollection](rules/getNFTTraitsByCollection.md) | Get NFT traits by collection |
| [getNFTTraitsByCollectionPaginate](rules/getNFTTraitsByCollectionPaginate.md) | Get NFT traits by collection paginate |
| [getNFTTransfers](rules/getNFTTransfers.md) | Get NFT transfers by token ID |
| [resyncNFTRarity](rules/resyncNFTRarity.md) | Resync NFT Trait |

### DeFi

DeFi protocol positions, liquidity, and exposure data.

| Endpoint | Description |
|----------|-------------|
| [getDefiPositionsByProtocol](rules/getDefiPositionsByProtocol.md) | Get detailed DeFi positions by protocol for a wallet |
| [getDefiPositionsSummary](rules/getDefiPositionsSummary.md) | Get DeFi positions of a wallet |
| [getDefiSummary](rules/getDefiSummary.md) | Get the DeFi summary of a wallet |

### Entity

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

| Endpoint | Description |
|----------|-------------|
| [getEntity](rules/getEntity.md) | Get Entity Details By Id |
| [getEntityCategories](rules/getEntityCategories.md) | Get Entity Categories |

### Price

Token and NFT prices, OHLCV candlestick data.

| Endpoint | Description |
|----------|-------------|
| [getMultipleTokenPrices](rules/getMultipleTokenPrices__evm.md) | Get Multiple ERC20 token prices |
| [getPairCandlesticks](rules/getPairCandlesticks.md) | Get OHLCV by pair address |
| [getTokenPrice](rules/getTokenPrice__evm.md) | Get ERC20 token price |

### Blockchain

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

| Endpoint | Description |
|----------|-------------|
| [getBlock](rules/getBlock.md) | Get block by hash |
| [getDateToBlock](rules/getDateToBlock.md) | Get block by date |
| [getLatestBlockNumber](rules/getLatestBlockNumber.md) | Get latest block number |
| [getTransaction](rules/getTransaction.md) | Get transaction by hash |
| [getTransactionVerbose](rules/getTransactionVerbose.md) | Get decoded transaction by hash |

### Discovery

Trending tokens and top-trader discovery.

| Endpoint | Description |
|----------|-------------|
| [getTopProfitableWalletPerToken](rules/getTopProfitableWalletPerToken.md) | Get top traders for a given ERC20 token |
| [getTrendingTokensV2](rules/getTrendingTokensV2.md) | Get trending tokens |

### Other

Address resolution, entity search, and supporting utilities.

| Endpoint | Description |
|----------|-------------|
| [getEntitiesByCategory](rules/getEntitiesByCategory.md) | Get Entities By Category |
| [getUniqueOwnersByCollection](rules/getUniqueOwnersByCollection.md) | Get unique wallet addresses owning NFTs from a contract. |
| [resolveAddress](rules/resolveAddress.md) | ENS lookup by address |
| [resolveAddressToDomain](rules/resolveAddressToDomain.md) | Resolve Address to Unstoppable domain |
| [resolveDomain](rules/resolveDomain.md) | Resolve Unstoppable domain |
| [resolveENSDomain](rules/resolveENSDomain.md) | ENS lookup by domain |
| [reSyncMetadata](rules/reSyncMetadata.md) | Resync NFT metadata |
| [searchEntities](rules/searchEntities.md) | Search Entities, Organizations or Wallets |
| [searchTokens](rules/searchTokens.md) | 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](rules/balance__solana.md) | Gets native balance owned by the given address |
| [getAggregatedTokenPairStats](rules/getAggregatedTokenPairStats__solana.md) | Get aggregated token pair statistics by address |
| [getCandleSticks](rules/getCandleSticks__solana.md) | Get candlesticks for a pair address |
| [getMultipleTokenMetadata](rules/getMultipleTokenMetadata__solana.md) | Get multiple token metadata |
| [getMultipleTokenPrices](rules/getMultipleTokenPrices__solana.md) | Get token price |
| [getNFTMetadata](rules/getNFTMetadata__solana.md) | Get the global metadata for a given contract |
| [getNFTs](rules/getNFTs__solana.md) | Gets NFTs owned by the given address |
| [getPairStats](rules/getPairStats__solana.md) | Get stats for a pair address |
| [getPortfolio](rules/getPortfolio__solana.md) | Gets the portfolio of the given address |
| [getSPL](rules/getSPL__solana.md) | Gets token balances owned by the given address |
| [getSwapsByPairAddress](rules/getSwapsByPairAddress__solana.md) | Get all swap related transactions (buy, sell, add liquidity & remove liquidity) |
| [getSwapsByTokenAddress](rules/getSwapsByTokenAddress__solana.md) | Get all swap related transactions (buy, sell) |
| [getSwapsByWalletAddress](rules/getSwapsByWalletAddress__solana.md) | Get all swap related transactions (buy, sell) for a specific wallet address. |
| [getTokenMetadata](rules/getTokenMetadata__solana.md) | Get Token metadata |
| [getTokenPairs](rules/getTokenPairs__solana.md) | Get token pairs by address |
| [getTokenPrice](rules/getTokenPrice__solana.md) | Get token price |
| [getTokenAnalytics](rules/getTokenAnalytics__solana.md) | **Solana variant:** Get token analytics by token address |
| [getTrendingTokensV2](rules/getTrendingTokensV2__solana.md) | **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](rules/getAddressesByXpub__universal.md) | Get derived addresses from a Bitcoin extended public key (xpub). |
| [getBlockByNumberOrHash](rules/getBlockByNumberOrHash__universal.md) | Get a block by chain and block number or hash |
| [getCandleSticks](rules/getCandleSticks__universal.md) | Get the OHLCV candle stick by using pair address |
| [getDefiPositions](rules/getDefiPositions__universal.md) | Get DeFi positions for a wallet across multiple chains |
| [getDefiProtocolPositions](rules/getDefiProtocolPositions__universal.md) | Get DeFi positions for a specific protocol |
| [getDefiProtocols](rules/getDefiProtocols__universal.md) | Get all supported DeFi protocols |
| [getDefiSummary](rules/getDefiSummary__universal.md) | Get DeFi positions summary for a wallet across multiple chains |
| [getSwapsByPairAddress](rules/getSwapsByPairAddress__universal.md) | Get all swap related transactions (buy, sell, add liquidity & remove liquidity) |
| [getSwapsByTokenAddress](rules/getSwapsByTokenAddress__universal.md) | Get all swap related transactions (buy, sell) |
| [getTokenBalances](rules/getTokenBalances__universal.md) | Get token balances from multiple chains for a specific wallet address. |
| [getTokenPrice](rules/getTokenPrice__universal.md) | Get the price of a token by its address |
| [getTokenPriceSparkline](rules/getTokenPriceSparkline__universal.md) | Get sparkline price data for a token |
| [getTokenPriceTimeSeries](rules/getTokenPriceTimeSeries__universal.md) | Get historical price time-series for a token |
| [getTopTradersByToken](rules/getTopTradersByToken__universal.md) | Get the top traders for a token on a single chain. |
| [getTransactionByHash](rules/getTransactionByHash__universal.md) | Get a transaction by chain and transaction hash |
| [getWalletHistory](rules/getWalletHistory__universal.md) | Get wallet transaction history across multiple chains. |
| [getWalletInsight](rules/getWalletInsight__universal.md) | Get wallet insight metrics across multiple chains. |
| [getWalletProfitability](rules/getWalletProfitability__universal.md) | Get per-token profitability for a wallet across multiple chains. |
| [getWalletProfitabilitySummary](rules/getWalletProfitabilitySummary__universal.md) | Get the wallet-level profitability summary across multiple chains. |

## Reference Documentation

- [references/CommonPitfalls.md](references/CommonPitfalls.md) - Complete pitfalls reference
- [references/DataTransformations.md](references/DataTransformations.md) - Type conversion reference
- [references/DataFeatureGuidance.md](references/DataFeatureGuidance.md) - Enrichment, safety, pricing, and discovery feature behavior
- [references/DeprecatedEndpoints.md](references/DeprecatedEndpoints.md) - Removed routes, replacements, and explicit no-replacement cases
- [references/ApiResponseCodes.md](references/ApiResponseCodes.md) - Common status codes and response field conventions
- [references/PerformanceAndLatency.md](references/PerformanceAndLatency.md) - Response time guidance, timeout recommendations, caching
- [references/ResponsePatterns.md](references/ResponsePatterns.md) - Pagination patterns
- [references/SpamDetection.md](references/SpamDetection.md) - Spam detection behavior and filtering guidance
- [references/SupportedApisAndChains.md](references/SupportedApisAndChains.md) - Chains and APIs
- [references/UniversalAndBitcoin.md](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