financial-insights

金融インサイト

このスキルを使用すると、Link に接続されたユーザーの金融データに関する次のような質問に回答できます。

• 最近の取引
• 支出傾向
• 口座残高
• リンク済みウォレットの情報源
• ユーザーの金融データから作成した基本的な要約
• 購買傾向や好みに関する、利用可能な事前計算済みインサイト

すべてのコマンドは読み取り専用です。資金の移動、支払いの開始、口座の変更、支払い認証情報の公開は行いません。

安全性とプライバシー

必要なソースアクションでユーザーが認証されるまで、金融データを取得しないでください。

ユーザーのリクエストに回答するために必要なデータだけを取得してください。デフォルトですべての一覧コマンドを実行しないでください。

機密性の高い識別子、アクセストークン、認証情報、支払い手段の詳細を公開しないでください。ユーザーの質問に回答するために必要な範囲で、金融情報を要約してください。

資金を移動する操作をユーザーが求めた場合は、skills/create-payment-credential/SKILL.md を参照してください。

認証

金融データを取得する前に、ユーザーが認証済みかどうか、また現在のセッションに必要なソースアクションがあるかどうかを確認してください。

link-cli auth status --format json

応答に authorization_details が含まれている場合は、その中から type: "source" で必要なアクションを含むエントリーを確認してください。トークンエンドポイントから認可の詳細が返されなかった場合、または認証に LINK_ACCESS_TOKEN が使用されている場合、このフィールドはないことがあります。その場合は、必要最小限のデータコマンドのみを実行し、以下の説明に従って権限エラーに対処してください。

ユーザーが未認証の場合は、リクエストされたデータに必要なソースアクションのみを求めるログインを開始してください。ユーザーがすでに認証済みでも、必要なソースアクションが不足している場合は、auth login ではなく auth upgrade を使用してください。auth upgrade は、ユーザーが追加アクセスを承認している間、現在のセッションを維持し、承認が成功した場合にのみセッションを置き換えます。

insights コマンドは、特定のインサイトを一覧から取得するためのアクセストークンの権限が不足している場合、その旨を示します。追加のアクセスが必要なときは、必要なスコープを示す authorization_remediation と authorization_details が返されます。LINK_ACCESS_TOKEN が設定されている場合は、不足しているアクセスについて説明しますが、CLI からアクセス権をアップグレードしようとしないでください。それ以外の場合は、必要なアクセス権を得るためにアップグレードするか、insights の使用を見送ってください。

必要最小限のソースアクションを使用してください。

• Link を通じて処理された取引：read_link_transactions
• 銀行口座接続からインポートされた取引：read_external_transactions
• 口座残高：read_balances
• データソースの詳細と説明：read_source_details。たとえば、取引や残高を特定の口座名に関連付ける必要がある場合など、幅広い用途で役立つアクションです。
• 事前計算済みの集計：上記すべて

ユーザーの質問に複数のデータ種別が必要な場合は、関連するすべてのアクションをまとめてリクエストしてください。

このスキルが購入に対応していて、加盟店が指定されていない場合は、ログイン前に必要な Link の機能を特定してください。購買傾向のインサイトが役立つ可能性が高い場合は、支払いスコープとともに取引へのアクセスを1回のログインでリクエストしてください。現在のトップブランドインサイトは、read_link_transactions または read_external_transactions のいずれかを許可するソースを使用できます。両方をリクエストすると、どちらの種類のソースにも対応できます。すでに認証済みの場合は、insights list-available-types を確認し、そこで報告された不足分のアクセスのみをリクエストしてください。

すべての金融データ種別が必要な、新規ログインの例：

link-cli auth login \
  --client-name "<your-agent-name>" \
  --source-actions read_link_transactions \
  --source-actions read_balances \
  --source-actions read_external_transactions \
  --source-actions read_source_details \
  --format json

既存のセッションに残高へのアクセスを追加する例：

link-cli auth upgrade \
  --client-name "<your-agent-name>" \
  --source-actions read_balances \
  --format json

<your-agent-name> は、エージェントまたはアプリケーションのわかりやすい名前に置き換えてください。返された verification_url をユーザーに提示し、応答の _next の指示に従うか、次のコマンドでポーリングしてください。

link-cli auth status --interval 5 --max-attempts 60 --format json

認証またはアクセス権のアップグレードが成功するまでは、先に進まないでください。承認の期限が切れた場合、拒否された場合、またはタイムアウトした場合は、その結果を報告し、新しい認可フローを繰り返し開始しないでください。

適切なコマンドの選択

ユーザーの質問に答えるために必要な、最小限のコマンドセットを使用してください。

ユーザーの質問	コマンド
利用可能な購入パターンのインサイトと、そのアクセス要件	link-cli insights list-available-types
特定の利用可能なインサイト、または観察された買い物の傾向	link-cli insights list
最近の購入、加盟店、支出、取引履歴、収入、入金、サブスクリプション	link-cli transactions list
現在の利用可能残高、口座残高、現金残高	link-cli balances list
接続済みの口座、カード、銀行、ウォレットの情報源、情報源のメタデータ	link-cli sources list

例：

• 「よく買い物をするブランドはどれですか？」→ 利用可能なインサイトの種類を確認し、該当するインサイトを取得します。
• 「いつもの店で小麦粉を買ってください。」→ 関連する利用可能なインサイトを参考に加盟店を選びます。ただし、結果は手がかりとして扱い、確実な好みだと見なさないでください。
• 「先月、レストランにいくら使いましたか？」→ 取引のみを使用します。
• 「現在の当座預金口座の残高はいくらですか？」→ 残高のみを使用します。
• 「どの口座が接続されていますか？」→ 情報源のみを使用します。
• 「現金残高と最近の支出をまとめてください。」→ 残高と取引を使用します。

出力形式

エージェントが読み取れる構造化出力には JSON を使用してください。

link-cli insights list-available-types --format json
link-cli insights list --insight <insight_id> --format json
link-cli transactions list --format json
link-cli balances list --format json
link-cli sources list --format json

デフォルトの toon 形式は人間向けです。結果の解析、フィルタリング、集計、要約を行う場合は、--format json を優先してください。

すべてのエンドポイントにおいて、金額は通貨の最小単位の整数です（例：152340 = $1,523.40 USD）。通貨の ISO 4217 の補助通貨単位の桁数を考慮するフォーマッターで金額を表示してください。すべての通貨で小数点以下が 2 桁である、または常に 100 で割ればよいと想定しないでください。

符号の解釈はフィールドごとに区別してください。マイナスは口座から出ていく金額、プラスは口座に入ってくる金額を表すのは transactions.amount のみです。残高フィールドには取引の符号の解釈を適用しないでください。current、cash.available、credit.used は、それぞれの残高の種類に応じて解釈してください。

インサイト

説明がユーザーの質問に合致する場合は、事前計算済みのインサイトを使用してください。すべてのインサイトを計算する前に、まず ID とアクセス要件を確認してください。

link-cli insights list-available-types --format json

応答には、id、description、および任意の authorization_remediation を含む data エントリと、has_more が含まれます。has_more が true の場合は、--starting-after <last_id> を指定して続行してください。現在のセッションにデータ取得に必要なアクセス権がなくても、インサイトが一覧に表示されることがあります。インサイトが必要な場合は、CLI 管理のセッションでは報告された対処方法を auth upgrade とともに使用してください。LINK_ACCESS_TOKEN については、上記の環境トークンのルールに従ってください。不足している scope の値は、スペース区切りの 1 つの --scope 引数として渡してください。ソースの authorization_details エントリについては、一覧にある各アクションを個別の --source-actions フラグとして渡してください。インサイト ID を推測したり、一覧にあるすべてのインサイトにこのユーザーのデータがあると想定したりしないでください。

関連する ID のみを取得します（複数の場合は --insight を繰り返します）。または、ユーザーが利用可能なすべてのインサイトを必要とする場合は、フィルターを省略してください。

link-cli insights list --insight <insight_id> --format json

どちらのコマンドも、ページネーション用の --limit（1〜100）と --starting-after に対応しています。各ページには data と has_more が含まれます。最後の項目の id を次のカーソルとして使用し、フィルターは変更しないでください。has_more が true でも使用可能なカーソルが返されない場合は、そこで終了してください。

取得した各インサイトには status があります。

• ready：その data エントリを使用し、回答を提示する際に as_of（Unix 秒）に言及してください。number_of_items 値には、number_of_items.label と number_of_items.count が含まれます。
• pending：計算がまだ完了していません。後で確認するよう提案してください。
• no_data：error_code、error_message、および authorization_remediation を確認してください。missing_permissions の場合は、上記の認証に関するガイダンスに従ってください。それ以外の場合は、データを利用できないことを伝えてください。購入フローでは、アクセスできない場合、またはユーザーがデータの共有を望まない場合は、インサイトなしで続行してください。

今後の応答では、ほかの値の型やステータスが現れる場合があります。意味を独自に作り出さず、JSON をそのまま保持してください。購入パターンの結果は、観測された履歴として扱い、ユーザーの好みを断定するものではありません。利用可能なインサイトで質問に答えられず、取引単位の詳細が必要な場合に限り、生の取引データを使用してください。

ソース（概念）

ソースとは、ユーザーの Link ウォレットに接続された金融口座（銀行口座、クレジットカード、普通預金口座など）です。各ソースには一意の id（例：csmrpd_abc123）があり、ほかのエンドポイントでは source_id として公開されることがあります。

• transactions list では、source_id によって取引がどの口座に属するかを示します。
• balances list では、各残高エントリに口座を識別する source_id が含まれます。
• sources list では、ソースの完全なメタデータ（名前、金融機関、種類、ステータス）が返されます。

source_id を使用してコマンド間のデータを関連付けてください。たとえば、特定の口座の取引を検索したり、残高とソースの種類を照合したりできます。source_id が null の取引を、説明から推測してソースに割り当てないでください。

取引

支出、収入、加盟店、カテゴリ、定期支払い、入金、または口座のアクティビティに関する質問に答えるには、取引を使用してください。

link-cli transactions list --format json

一般的なオプション：

link-cli transactions list --format json --start-date 2025-01-01 --end-date 2025-01-31
link-cli transactions list --format json --category groceries
link-cli transactions list --format json --origin external_connection
link-cli transactions list --format json --source <source_id> --source <source_id>

フラグ	説明
--start-date	この日付以降（当日を含む）の取引のみを対象にします（YYYY-MM-DD）。
--end-date	この日付以前（当日を含む）の取引のみを対象にします（YYYY-MM-DD）。
--category	カテゴリでフィルターします。
--origin	取得元でフィルターします：link または external_connection。
--source	ソース ID でフィルターします（複数回指定可能）。

共通のリスト制御については、ページネーションを参照してください。

レスポンスフィールド

フィールド	備考
amount	負の値 = 口座から出ていくお金 (デビット/購入)、正の値 = 入ってくるお金 (クレジット/入金)。
origin	external_connection (連携された銀行/カードから) または link (Link ネイティブのトランザクション)。
category	未分類の場合は null になることがあります。
status	API が提供するステータス文字列。値の集合が閉じていると仮定しないでください。観測される値には succeeded が含まれます。ステータスの意味が判明している場合にのみ、そのステータスを解釈またはフィルタリングしてください。

トランザクションの集計について:

• 合計を計算する前に、符号を一貫して正規化してください。
• 可能な場合はデビットとクレジットを区別してください。
• 関連がある場合にのみ、加盟店、カテゴリ、口座、通貨、または期間でグループ化してください。
• 回答が限られた取得ウィンドウに基づいている場合は、その旨を記載してください。

残高

残高は、現在の口座残高や利用可能資金に関する質問に回答するために使用します。

link-cli balances list --format json
link-cli balances list --format json --source <source_id>

フラグ	説明
--source	ソース ID でフィルタリングします (繰り返し指定可能)。

共通のリスト制御についてはページネーションを参照してください。

レスポンスフィールド

フィールド	備考
type	cash (銀行/貯蓄) または credit (クレジットカード/信用枠)。どちらのサブオブジェクトが存在するかを決定します。
current	保留中のトランザクション前の残高。利用可能資金とは同じではありません。
cash.available	通貨コードを利用可能資金 (current から出金保留分を引き、入金保留分を足したもの) にマッピングするオブジェクト。type が cash の場合にのみ存在します。
credit.used	通貨コードを使用済みクレジットにマッピングするオブジェクト。type が credit の場合にのみ存在します。
as_of	残高が最後に更新された時刻 — 数時間または数日前の古い情報である可能性があります。

残高を集計する際:

• 通貨を保持してください。
• ユーザーが明示的に要求し、為替レートデータが利用可能でない限り、異なる通貨間で残高を合算しないでください。
• ユーザーの質問で保留中のトランザクションを考慮する必要がない限り、残高のデフォルトの定義として current フィールドを使用してください。
• 複数のソースが返された場合は、口座/ソースごとに集計してください。

ソース

ソースは、連携されたウォレットソース、リンクされた口座、または利用可能な金融データソースに関する質問に回答するために使用します。共通のリスト制御についてはページネーションを参照してください。

link-cli sources list --format json

レスポンスフィールド

フィールド	説明
id	一意のソース識別子 (他のエンドポイントの source_id と同じ)。
name	ソースの表示名。
type	ソースの種類 (例: card、bank_account)。
capabilities	どのようなデータが利用可能かを示すオブジェクト。各キー (例: balances、transactions) は status フィールド (例: eligible) を持つオブジェクトにマッピングされます。
external_connection.status	外部機関への接続ステータス。
granted_actions	ユーザーがこのソースに対して許可したアクションのリスト。

ソースを集計する際:

• 回答に必要な機密性の低いメタデータのみを含めてください。
• 完全な口座番号、認証情報、トークン、または支払い手段の詳細を開示しないでください。
• 利用可能な場合は、金融機関、口座種別、ソースステータス、最終更新時刻などのラベルを優先してください。

ページネーション

3 つのリストコマンドは、すべて同じページネーションフラグに対応しています。

フラグ	説明
--limit	1 ページあたりの最大結果数（1～100）です。複数ページが必要になる可能性がある場合は、100 を指定してください。
--starting-after	カーソル値の次のページを取得します。
--ending-before	カーソル値より前のページを取得します。通常の前方向への取得ではなく、逆方向への移動に使用してください。

JSON レスポンスには data 配列が含まれ、has_more が含まれる場合があります。次のカーソル専用のフィールドはありません。has_more が true の場合、data の最後の項目から次のカーソルを取得してください。

コマンド	次のカーソル
transactions list	最後の取引の id。
balances list	最後の残高の source_id。
sources list	最後のソースの id。

たとえば：

link-cli transactions list --format json --limit 100 --starting-after <last_transaction_id>

すべてのページでフィルターを同一に保ち、--starting-after だけを変更してください。has_more が false または存在しない場合、あるいは網羅的でない検索に十分なデータを取得した場合は、取得を終了してください。has_more が true でも data が空の場合、または必要なカーソルが null か存在しない場合は、ページネーションを続行できなかったことを報告して終了してください。

指定された期間の合計など、完全かつ範囲が限定された結果をユーザーが求めている場合を除き、すべてのページを網羅的に取得しないでください。

ユーザーの質問への回答

回答する際は：

• まず、質問への直接的な回答を述べてください。
• 該当する期間とデータソースに言及してください。
• ページネーションが一部のみであること、カテゴリが欠落していること、取引が保留中であること、未対応の通貨があることなど、制限事項を明記してください。
• ユーザーから求められない限り、生のレコードやオブジェクト ID をそのまま列挙しないでください。
• 簡潔な要約、合計、注目すべき傾向を優先してください。

回答の例：

You spent $342.18 on restaurants across 12 transactions in July. The largest restaurant transaction was $86.40 at Example Bistro on July 18. This is based on the transactions returned for your connected Link sources.

エラー処理

認証に失敗した場合は、ユーザーに再認証を依頼してください。

コマンドがデータを返さない場合は、指定された範囲に該当する Link の財務データがなかったと伝えてください。

CLI が権限不足またはソースアクション不足を示すエラーを返した場合は、不足している特定のアクションのみを依頼してください。セッションがすでに認証済みの場合は auth upgrade を、認証されていない場合は auth login を使用し、承認されるまで待ってからデータコマンドを一度だけ再試行してください。

データが不完全またはページネーションされている場合は、これまでに取得したデータに基づく回答であることを明確に伝えてください。

ガードレール

次のことはしないでください：

• 資金を移動する。
• 支払いを開始する。
• 財務ソースを変更する。
• 無関係な財務データを取得する。
• 必要以上に広範なソースアクションを要求する。
• 認証情報、トークン、または支払いの詳細全体を公開する。
• 確実でない推論結果を断定的な事実として提示する。

次のことを行ってください：

• 読み取り専用コマンドを使用する。
• 取得前に認証する。
• 必要最小限のソースアクションを要求する。
• 解析には --format json を使用する。
• 必要なデータのみを取得する。
• 明確に要約し、制限事項を明記する。