| name | moralis-data-api |
| description | Query Web3 blockchain data from Moralis API. Use when user asks about wallet data (balances, tokens, NFTs, transaction history, profitability, net worth), token data (prices, metadata, DEX pairs, analytics, security scores), NFT data (metadata, transfers, traits, rarity, floor prices), DeFi positions, entity/label data for exchanges and funds, or block and transaction data. Supports EVM chains (Ethereum, Polygon, BSC, Arbitrum, Base, Optimism, Avalanche, etc.) and Solana. NOT for real-time streaming - use moralis-streams-api instead. |
| version | 1.4.0 |
| license | MIT |
| compatibility | Requires curl for API calls. Requires MORALIS_API_KEY env var for authentication. |
| metadata | {"author":"MoralisWeb3","homepage":"https://docs.moralis.com","repository":"https://github.com/MoralisWeb3/onchain-skills","openclaw":{"requires":{"env":["MORALIS_API_KEY"],"bins":["curl"]},"primaryEnv":"MORALIS_API_KEY"}} |
| allowed-tools | Bash Read Grep Glob |
CRITICAL: Read Rule Files Before Implementing
The #1 cause of bugs is not reading the endpoint rule file before writing code.
For EVERY endpoint:
- Read
rules/{EndpointName}.md
- Find "Example Response" section
- Copy the EXACT JSON structure
- Note field names (snake_case), data types, HTTP method, path, wrapper structure
Reading Order:
- This SKILL.md (core patterns)
- Endpoint rule file in
rules/
- 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:
- 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: MORALIS_API_KEY=
- 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
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 |
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;
block_number: "12386788";
Timestamps (usually ISO strings)
"2021-05-07T11:08:35.000Z";
Balances (always strings unless its a property named "formatted" eg. balanceFormatted, BigInt)
balance: "1000000000000000000";
Response Patterns
| Pattern | Example Endpoints |
|---|
Direct array [...] | getWalletTokenBalancesPrice, getTokenMetadata |
Wrapped { result: [] } | getWalletNFTs, getWalletTransactions |
Paginated { page, cursor, result } | getWalletHistory, getNFTTransfers |
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)
- Block numbers are decimal, not hex - Use
parseInt(x, 10), not parseInt(x, 16)
- Timestamps are ISO strings - Use
new Date(timestamp).getTime()
- Balances are strings - Use
BigInt(balance) for math
- Response may be wrapped - Check for
.result before .map()
- Path inconsistencies - Some use
/wallets/{address}/..., others /{address}/...
See references/CommonPitfalls.md for complete reference.
Pagination
Many endpoints use cursor-based pagination:
curl "...?limit=100" -H "X-API-Key: $KEY"
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"
curl "https://deep-index.moralis.io/api/v2.2/${ADDRESS}/balance?chain=${CHAIN}" \
-H "X-API-Key: $MORALIS_API_KEY"
curl "https://deep-index.moralis.io/api/v2.2/erc20/YOUR_EVM_ADDRESS/price?chain=${CHAIN}" \
-H "X-API-Key: $MORALIS_API_KEY"
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 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.
Token
Token prices, metadata, pairs, DEX swaps, analytics, security scores, and sniper detection.
NFT
NFT metadata, transfers, traits, rarity, floor prices, and trades.
DeFi
DeFi protocol positions, liquidity, and exposure data.
Entity
Labeled addresses including exchanges, funds, protocols, and whales.
Price
Token and NFT prices, OHLCV candlestick data.
Blockchain
Blocks, transactions, date-to-block conversion, and contract functions.
Discovery
Trending tokens, blue chips, market movers, and token discovery.
Other
Utility endpoints including API version, endpoint weights, and address resolution.
Solana Endpoints
Solana-specific endpoints (24 native + 10 EVM variants that support Solana chain = 34 total).
Reference Documentation
See Also
