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	10 進数 12386788	16 進数 0xf2b5a4
timestamp	ISO "2021-05-07T11:08:35.000Z"	Unix 1620394115
balance	文字列 "1000000000000000000"	数値
decimals	文字列または数値	常に数値

ブロック番号（常に 10 進数）

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. ブロック番号は 16 進数ではなく 10 進数です - parseInt(x, 16) ではなく、parseInt(x, 10) を使用します
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進数を16進数として解析	基数に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件のエンドポイント（EVM 102件 + Solana 34件）の一覧です。

ウォレット

残高、トークン、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 のメタデータ、移転、トレイト、希少度、フロア価格、取引。

エンドポイント	説明
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 プロトコルのポジション、流動性、エクスポージャーのデータ。

エンドポイント	説明
getDefiPositionsByProtocol	ウォレットの DeFi プロトコルごとの詳細なポジションを取得
getDefiPositionsSummary	ウォレットの DeFi ポジションを取得
getDefiSummary	ウォレットの DeFi 概要を取得

Entity

取引所、ファンド、プロトコル、クジラなどのラベル付きアドレス。

エンドポイント	説明
getEntity	ID でエンティティの詳細を取得
getEntityCategories	エンティティのカテゴリを取得

Price

トークンと NFT の価格、OHLCV のローソク足データ。

エンドポイント	説明
getMultipleTokenPrices	複数の ERC20 トークン価格を取得
getPairCandlesticks	ペアアドレスで OHLCV を取得
getPairPrice	DEX トークンペアの価格を取得
getTokenPrice	ERC20 トークン価格を取得

Blockchain

ブロック、トランザクション、日付からブロックへの変換、コントラクト関数。

エンドポイント	説明
getBlock	ハッシュでブロックを取得
getDateToBlock	日付でブロックを取得
getLatestBlockNumber	最新のブロック番号を取得
getTransaction	ハッシュでトランザクションを取得
getTransactionVerbose	ハッシュでデコード済みトランザクションを取得

ディスカバリー

トレンドのトークン、優良銘柄、市場で値動きの大きい銘柄、トークンのディスカバリー。

Endpoint	説明
getDiscoveryToken	トークンの詳細を取得
getTimeSeriesVolume	チェーン別の時系列取引統計を取得
getTimeSeriesVolumeByCategory	カテゴリ別の時系列取引統計を取得
getTopCryptoCurrenciesByMarketCap	時価総額上位の暗号資産を取得
getTopCryptoCurrenciesByTradingVolume	取引量上位の暗号資産を取得
getTopERC20TokensByMarketCap	時価総額上位のERC20トークンを取得
getTopERC20TokensByPriceMovers	価格変動が大きいERC20トークンを取得（上昇銘柄と下落銘柄）
getTopGainersTokens	上昇率上位のトークンを取得
getTopLosersTokens	下落率上位のトークンを取得
getTopProfitableWalletPerToken	指定したERC20トークンの上位トレーダーを取得
getTrendingTokens	トレンドのトークンを取得
getVolumeStatsByCategory	カテゴリ別の取引統計を取得
getVolumeStatsByChain	チェーン別の取引統計を取得

その他

APIバージョン、エンドポイントのウェイト、アドレス解決などのユーティリティエンドポイントです。

Endpoint	説明
getBondingTokensByExchange	取引所別のボンディングトークンを取得
getEntitiesByCategory	カテゴリ別のエンティティを取得
getFilteredTokens	指定したフィルターと条件に一致するトークンの一覧を返します
getGraduatedTokensByExchange	取引所別のグラデュエート済みトークンを取得
getHistoricalTokenHolders	保有者の時系列データを取得
getNewTokensByExchange	取引所別の新しいトークンを取得
getUniqueOwnersByCollection	コントラクトのNFTを所有する一意のウォレットアドレスを取得します。
resolveAddress	アドレスからENSを検索
resolveAddressToDomain	アドレスをUnstoppableドメインに解決
resolveDomain	Unstoppableドメインを解決
resolveENSDomain	ドメインからENSを検索
reSyncMetadata	NFTメタデータを再同期
searchEntities	エンティティ、組織、またはウォレットを検索
searchTokens	コントラクトアドレス、ペアアドレス、トークン名、またはトークンシンボルに基づいてトークンを検索します。

Solana エンドポイント

Solana 固有のエンドポイント（ネイティブ 24 個 + Solana チェーンに対応する EVM バリアント 10 個 = 合計 34 個）。

エンドポイント	説明
balance	指定したアドレスが保有するネイティブ残高を取得します
getAggregatedTokenPairStats	アドレスでトークンペアの集計統計を取得します
getBondingTokensByExchange	取引所別にボンディングトークンを取得します
getCandleSticks	ペアアドレスのローソク足を取得します
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 を参照してください