nansen-agent-guide

認証

Nansen アカウントの API 呼び出しでは、選択した nansen:api ブラウザーセッション、または同じ権限を持つ従来の API キーを使用できます。NANSEN_API_KEY が優先されます。オプションの primaryEnv を使うと、設定済みキーの注入を維持できます。オフラインで選択内容を確認するには、nansen auth status を実行してください。キャッシュされたアクセスの有効期限が切れただけであれば、許可されたタスク中に自動更新できます。匿名が選択されている場合、状態が無効な場合、更新がブロックされているか不確かな場合、または実際に認証に失敗した場合は停止してください。認証情報を削除したり、匿名の x402 支払いにフォールバックしたりしないでください。ブラウザーログインでは、ウォレット署名、特権サービス ID、永続的な MCP 統合キーは付与されません。以下のすべての確認、署名、制裁、地域に関するチェックを維持してください。ブラウザーログインは、macOS arm64 のプレビュー対象範囲内の CLI 2.0.0 で利用できます。

エージェントと CLI の使い分け

公開されているエージェントの fast/expert および直接 API コマンドでは、選択した nansen:api ブラウザーセッション、または同じアカウント権限を持つ従来の API キーを使用できます。

必要なもの	使用するもの
見解（分析、解釈）	nansen agent
テーブル（生データ、特定の指標）	直接 CLI コマンド
レポート（両方）	説明にはエージェント、データには CLI

nansen agent を使用する場合

• 質問に、複数のデータソースをまたいだ解釈や統合が必要な場合
• 自由形式の調査：「このウォレットを分析して」「ETH のスマートマネーに何が起きていますか？」

nansen agent "What are top smart money tokens on Solana today and why?"
nansen agent "Analyse wallet 0x123... -- is this a smart trader?"
nansen agent "..." --expert   # deeper analysis, 750 credits

料金：200 クレジット（fast）／750 クレジット（expert）

直接 CLI コマンドを使用する場合

• 価格、取引量、保有者、資金フローなど、特定の構造化データが必要な場合
• 決定的な回答が得られる質問：「ethereum のネットフロー上位 10 トークン」
• 出力をパイプ処理する場合や、データテーブルを作成する場合

nansen research token screener --chain ethereum --smart-money --limit 10
nansen research smart-money netflow --chain solana
nansen research profiler balance --address 0x123... --chain ethereum

料金：呼び出しごとに 5～50 クレジット

アンチパターン

• 単純なデータ取得に nansen agent を使わないでください。40 倍の料金がかかります。
• 自由形式の分析に生の CLI を使わないでください。返されるのはデータであり、解釈ではありません。
• エージェントを 3 回以上連続で呼び出さないでください。CLI で生データを取得し、統合のためにエージェントを 1 回呼び出してください。

ブラウザーセッションの範囲

通常の nansen login では、新しいブラウザー承認を要求します。--no-browser を指定すると、別のデバイスで承認するためのリンク／コードが表示され、同じネイティブストレージ要件が適用されます。NANSEN_API_KEY は、保存されている単一の認証情報より優先されます。オフラインでキャッシュ済み／未検証の選択内容を確認するには nansen auth status を、無料のライブチェックには nansen account を使用してください。明示的な login --human または login --api-key では、従来のキー設定が維持されます。選択したブラウザーセッションは自動更新されます。不確かな更新が必要な場合は、再実行や別アカウント／支払いへのフォールバックをせず、新たにログインしてください。

ブラウザーの nansen:api 権限では、有効なアクセス許可と同じエンドポイント制限のもと、API キーと同等のアカウント権限が付与されます。内部サービス ID とウォレット署名は付与されません。ブラウザーセッションでウォレット署名を承認したり、MCP キーとしてエクスポートしたりすることはできません。CLI 2.0.0 は公開済みですが、上記のプラットフォームのプレビュー制限は引き続き適用されます。

製品に関するフィードバック

Nansen のタスクで有用な製品上の不足が明らかになった場合は、機密情報や不要な会話の詳細を含めず、簡潔な報告を作成してください。自分の判断で送信する前に、現在のアカウントに保存されているフィードバック設定を nansen feedback preferences --json で読み取ってください。新しい報告ごとに、設定を新たに読み取ってください。有効になっている場合は、ホスト側の制御に従い、再確認せずに送信できます。無効、未設定、または取得できない場合は、報告案を提示してユーザーに確認してください。ユーザーが拒否した場合や確認できない場合は、送信しないでください。

報告は JSON オブジェクトです。category と description は必須です。 category は bug、data_quality、documentation、 missing_capability、usability、other のいずれかでなければなりません。機能リクエストまたは製品上の不足には missing_capability を使用してください。カテゴリを勝手に作成しないでください。description には、何が起き、何が必要だったかを 2,000 文字以内で記述します。endpoint、tool、goal、expected_behavior、observed_behavior、 workaround、request_ids（自分のリクエスト ID を最大 10 個）、client （{"name": ..., "version": ...}）を追加できます。title、 summary、component など、その他のフィールドを指定すると 422 エラーになります。ID が生成済みの場合、この 422 エラーにより保存済みの報告も消去されるため、--new が必要になります。Markdown やコード形式を使わず、平文の文章を記述してください。制限事項は nansen feedback submit --help に記載されています。

{"category": "missing_capability", "description": "There is no command to list my past feedback receipts.", "goal": "Check the status of reports I sent earlier."}

設定の読み取りに失敗した場合は、まず確認してください。ユーザーからの明示的な依頼または承認があれば、その報告を送信できますが、保存済みの設定は変更されません。設定を自動的に有効にしたり、報告に承認フィールドを追加したりしないでください。継続的な選択を行うには、Superapp の設定をユーザーに案内してください。有効な設定や 1 件ごとの承認にも、ホスト側またはローカルの拒否制御が適用されます。

ユーザーから報告の依頼があった場合、または設定で送信が許可されている場合は、nansen feedback submit --file feedback.json --submission-id <new-id> --json を使って送信してください。 このコマンドは非対話型です。結果が不確かな場合は、同じ ID と変更していない報告を使って復旧してください。保存済みの受領記録を読むには nansen feedback get <feedback-id> --json を使います。送信と受領記録の読み取りは無料です。1 つのアカウントで受理される報告は、UTC 週あたり 7 件までです。上限は月曜日の 00:00 UTC にリセットされます。

リリース前または障害発生中は、新しい報告の受け付けが一時停止される場合があります。reason: feedback_admissions_paused を伴う 503 は、この試行では新しい報告が受理されず、週あたりの上限も消費されていないことを意味します。フィードバックを利用できないことをユーザーに伝え、そこで終了してください。再試行を続けたり、同じセッション内で再度承認を求めたりしないでください。後で再試行できるよう、ID と変更していない報告を保持してください。この CLI バージョンにフィードバックコマンドがない場合は、利用できないことを伝えて終了してください。一時停止中も、受理済み ID の再送と受領記録の読み取りは引き続き利用できます。

reason: feedback_not_enabled を伴う 403 は、このアカウントでフィードバックが有効になっていないことを意味します。自動再試行を中止し、ユーザーに伝えてください。承認や有効な設定によって、ロールアウトの制限を回避することはできません。保存済みの ID と変更していない報告を保持してください。以前の結果が不確かな試行は、利用可能になった後、同じ ID で復旧してください。拒否を回避するために、アカウントを切り替えたり、有料の手段を使ったりしないでください。