wallet-analysis

Zerion API を使ったウォレット分析

Zerion の正規化されたウォレット API を使って、Solana を優先したウォレット分析機能を構築します。ユーザーが Solana アドレスのポートフォリオ表示、トークン残高、解釈済みトランザクション、チャート、またはウォレット単位の損益を必要としている場合にこのスキルを使います。同時に、Zerion が対応する幅広いマルチチェーン環境でも同じワークフローをサポートします。

概要

Zerion は、特に次のような場合に役立ちます。

• 独自のインデクサーを構築せずに、Solana ウォレットのポートフォリオ概要を取得する
• 正規化されたスキーマで Solana トークンの保有状況やウォレットのアクティビティを把握する
• ポートフォリオアプリやエージェント向けに、ウォレットの損益や過去のチャート表示を実現する
• API を中心とした実装ガイダンスを利用する。エージェントネイティブな環境では MCP も利用可能です

認証

次の順序で認証方式を優先してください。

1. アプリ連携向け API キー

ユーザーがプロダクト連携を構築している場合は、Zerion API を直接使用します。

export ZERION_API_KEY="zk_dev_..."

curl -u "$ZERION_API_KEY:" \
  "https://api.zerion.io/v1/wallets/8BH9pjtgyZDC4iAQH5ZiYDZ1MDWC98xki2V8NzqqKW3K/portfolio"

ヘッダーを明示する場合は、base64("${ZERION_API_KEY}:") を使った HTTP Basic 認証を使用します。

2. Solana を含む、API キー不要のエージェントワークフロー向け x402

ユーザーが API キーの発行を望まない場合、Zerion は AI ワークフロー向けの従量課金方式として x402 を案内しています。Zerion の公式エージェントリポジトリでは Solana ベースの x402 も案内されているため、実行環境が x402 の支払いハンドシェイクに対応していれば、API キーの代わりに Solana ウォレットを使用できます。

export SOLANA_PRIVATE_KEY="5C1y..."
export ZERION_X402_PREFER_SOLANA=true

次の場合は x402 を使用します。

• ユーザーが API キーを使わないことを明示的に希望している
• 環境がすでに x402 に対応している
• ワークフローがエージェント型で、Solana で資金を用意している

3. エージェントネイティブな環境向けのホスト型 MCP

ユーザーが Claude Code、Cursor、または別の MCP ネイティブなクライアントを使用している場合、Zerion API はホスト型 MCP エンドポイントを提供しています。

https://developers.zerion.io/mcp

MCP は別のプロダクトではなく、代替インターフェースとして扱ってください。同じウォレット分析機能を利用でき、Zerion の公式 AI ドキュメントやリポジトリでは、AI ワークフロー向けの API キーおよび x402 認証方式が説明されています。ユーザーがアプリのコードを求めている場合は、REST API を直接使った例を優先してください。

ルーティング

ユーザーが別のチェーンを指定しない限り、Solana から始めます。Zerion のウォレット分析エンドポイントは Solana アドレスに対応しており、API のほかの部分と同じ正規化オブジェクトモデルを使用します。

ユーザーの目的	エンドポイント／ツール
Solana ウォレットの概要	GET /v1/wallets/{address}/portfolio または MCP wallet-portfolio
Solana トークン残高	GET /v1/wallets/{address}/positions/ または MCP wallet-positions
Solana の最近のアクティビティ	GET /v1/wallets/{address}/transactions/ または MCP wallet-transactions
Solana ウォレットの損益	GET /v1/wallets/{address}/pnl または MCP wallet-pnl
Solana ポートフォリオチャート	GET /v1/wallets/{address}/charts/{period}
対応チェーン	GET /v1/chains/ または MCP chains-list

Solana を優先するワークフロー

1. ユーザーが Solana 向けに構築している場合は、ウォレットアドレスが Solana のものか確認します。
2. まず portfolio を取得して、合計価値と大まかな内訳を把握します。
3. 次に positions を取得して、トークン単位の内訳を確認します。
4. 解釈済みのウォレットアクティビティを取得するには、transactions を取得します。
5. ユーザーがパフォーマンス、実現損益、または純投資額を必要としている場合は、pnl を取得します。
6. UI でポートフォリオの過去の価値を表示する必要がある場合は、charts を追加します。
7. ユーザーのリクエストで実際に必要な場合に限り、EVM やマルチチェーンのフィルターに範囲を広げます。

API パターン

ポートフォリオ

curl -u "$ZERION_API_KEY:" \
  "https://api.zerion.io/v1/wallets/${ADDRESS}/portfolio?currency=usd"

Solana ウォレットのダッシュボード、ウォッチリスト、概要カードでは、これを最初に使用します。

ポジション

curl -u "$ZERION_API_KEY:" \
  "https://api.zerion.io/v1/wallets/${ADDRESS}/positions/?filter[positions]=no_filter"

ユーザーがトークン残高のみを求めている場合は、filter[positions]=only_simple を使用します。

トランザクション

curl -u "$ZERION_API_KEY:" \
  "https://api.zerion.io/v1/wallets/${ADDRESS}/transactions/?page[size]=10&currency=usd"

スワップ、送金、承認など、解釈済みの Solana アクティビティを取得するには、これを使用します。

損益

curl -u "$ZERION_API_KEY:" \
  "https://api.zerion.io/v1/wallets/${ADDRESS}/pnl?currency=usd"

ユーザーが実現益、未実現益、純投資額、または取得原価を尋ねている場合は、これを使用します。

チャート

curl -u "$ZERION_API_KEY:" \
  "https://api.zerion.io/v1/wallets/${ADDRESS}/charts/month?currency=usd"

ポートフォリオの推移を示すチャートやタイムラインの可視化には、これを使用します。

ガイドライン

• アプリのコードでの実装例には、Zerion API を優先して使用してください。
• 可能な限り、プロンプト、コード、説明では Solana ウォレットの例を使用してください。
• ユーザーが Claude Code、Cursor、または VS Code でエージェントネイティブなクエリを求めている場合は、Zerion MCP を使用してください。
• 特にユーザーが Solana で資金を用意した API キー不要のセットアップを求めている場合は、x402 を第一級のフォールバックとして扱ってください。
• Basic 認証の例は正確に記述してください。API キーをユーザー名として指定し、パスワードは空にします。
• Zerion が Solana ウォレットデータをすでに正規化している場合、チェーン固有のパーサーを作成するようユーザーに案内しないでください。
• x402 のヘッダーや決済フローをでっち上げないでください。ランタイムが x402 に対応している場合は、Zerion のドキュメントに記載された方法を使用してください。

よくあるエラー

401 Unauthorized

原因：Basic 認証の API キーが存在しないか、無効です。 対処方法：curl -u "$ZERION_API_KEY:" ... を使用するか、ZERION_API_KEY: を Authorization: Basic ... ヘッダーにエンコードしてください。

402 Payment Required

原因：x402 の方法が選択されていますが、ランタイムで決済ハンドシェイクが完了していません。 対処方法：x402 に対応したクライアント／ランタイムを使用し、必要な残高を Solana ウォレットに用意してください。

初回リクエスト時に Solana のポジションが空になる

原因：Zerion のドキュメントによると、一部の Solana 資産では短い初期化期間が必要になる場合があります。 対処方法：ウォレットが空だと決めつけず、回数に上限を設けたポーリングで再試行してください。

Solana のプロトコルポジションが見つからない

原因：Zerion の現在のドキュメントでは、ウォレットポジションのエンドポイントにおける Solana のプロトコルポジション対応は、暫定的な制限として引き続き記載されています。 対処方法：トークン残高は取得できますが、現時点では Solana の DeFi プロトコルポジションの対応範囲が不完全な場合があることを明確に伝えてください。

参考資料

• Zerion API の概要
• AI で構築する
• ホスト型 MCP
• ウォレットのポートフォリオを取得
• ウォレットのポジションを取得
• ウォレットのトランザクションを取得
• ウォレットの損益を取得