Financial Insights

Financial insights

Use this skill to answer questions about a user’s Link-connected financial data, including:

• Recent transactions
• Spending patterns
• Account balances
• Linked wallet sources
• Basic summaries derived from the user’s financial data
• Available precomputed insights about purchase patterns and preferences

All commands are read-only. They do not move money, initiate payments, modify accounts, or expose payment credentials.

Safety and privacy

Do not retrieve financial data until the user is authenticated with the required source actions.

Only retrieve the data needed to answer the user’s request. Do not run every list command by default.

Do not expose sensitive identifiers, access tokens, credentials, or payment instrument details. Summarize financial information at the level needed to answer the user’s question.

If the user asks for an action that would move money, reference skills/create-payment-credential/SKILL.md instead.

Authentication

Before retrieving financial data, check whether the user is authenticated and whether the current session has the required source actions.

link-cli auth status --format json

When present, inspect authorization_details in the response for entries with type: "source" and the required actions. The field may be absent when the token endpoint did not return authorization details or when authentication comes from LINK_ACCESS_TOKEN; in that case, run only the minimum data command needed and handle a permission error as described below.

For a new connection, auth login requests the userinfo:read and payment_methods.agentic scopes and all four financial-insights source actions by default. The user must approve the connection; this request does not retrieve any financial data. If the user wants payment-only access, use --no-financial-insights. If they do not want the default payment scope, use --no-agentic-payments. If they want a narrower set of financial-data actions, pass only the desired --source-actions flags or --authorization-detail entries; either replaces the default. Do not combine either with an explicit --financial-insights or --no-financial-insights flag. An explicit --scope replaces the default scopes.

If the user is already authenticated but an action needed for their financial-data request is missing, use auth upgrade with only that missing action instead of auth login. auth upgrade preserves the current session while the user approves the additional access and replaces it only after approval succeeds. Do not upgrade access solely for an optional insight during a purchase.

The insights commands will indicate when the access token is insufficient to retrieve a particular insight in the list. It will provide authorization_remediation indicating required scopes and authorization_details when more access is needed. When LINK_ACCESS_TOKEN is set, explain the missing access but do not attempt to upgrade access through the CLI. Otherwise, upgrade to obtain the requisite access or skip using insights.

The financial-insights source actions are:

• Transactions processed through Link: read_link_transactions
• Transactions imported from bank connections: read_external_transactions
• Account balances: read_balances
• Data source details and descriptions: read_source_details. This action is broadly useful, for example if you will ever need to tie a transaction or balance to a particular account name.
• Pre-computed aggregations: all of the above.

When narrowing a new login or upgrading an existing one, request only the actions needed for the user's question.

During a purchase with an ambiguous merchant, use an available top-brand insight as one clue when the current connection already has access. If access is missing, continue without the optional insight; do not start an upgrade just for merchant selection.

Recommended new login:

link-cli auth login --client-name "" --format json

Payment-only opt-out:

link-cli auth login --client-name "" --no-financial-insights --format json

Example for adding balance access to an existing session:

link-cli auth upgrade \
  --client-name "" \
  --source-actions read_balances \
  --format json

Replace ` with a clear name for the agent or application. Present the returned verification_url to the user, then follow the response's _next` instruction or poll with:

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

Do not proceed until authentication or the access upgrade succeeds. If the approval expires, is denied, or times out, report that outcome instead of repeatedly starting new authorization flows.

Choosing the right command

Use the smallest command set that answers the user’s question.

User asks about	Command
Available purchase-pattern insights and their access requirements	link-cli insights list-available-types
A specific available insight or observed shopping preference	link-cli insights list
Recent purchases, merchants, spend, transaction history, income, deposits, subscriptions	link-cli transactions list
Current available balance, account balance, cash position	link-cli balances list
Connected accounts, cards, banks, wallet sources, source metadata	link-cli sources list

Examples:

• Which brands do I tend to shop at? → Discover available insight types, then retrieve the relevant insight.
• Buy flour from my usual store. → If available with the current access, check a relevant top-brand insight once. Treat the result as a clue, not a guaranteed preference; continue without it if unavailable.
• How much did I spend on restaurants last month? → Use transactions only.
• What is my current checking account balance? → Use balances only.
• Which accounts are connected? → Use sources only.
• Summarize my cash position and recent spending. → Use balances and transactions.

Output format

Use JSON for agent-readable structured output.

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

The default toon format is intended for humans. Prefer --format json whenever parsing, filtering, aggregating, or summarizing results.

All monetary amounts across all endpoints are integers in the currency's smallest unit (e.g. 152340 = $1,523.40 USD). Format amounts with a currency-aware formatter that uses the currency's ISO 4217 minor-unit exponent; do not assume every currency has two decimal places or always divide by 100.

Keep sign interpretation field-specific. Only transactions.amount uses negative for money leaving the account and positive for money entering it. Do not apply transaction sign semantics to balance fields; interpret current, cash.available, and credit.used according to the balance type.

Insights

Use precomputed insights when their descriptions match the user's question. First discover IDs and access requirements without computing every insight:

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

The response contains data entries with id, description, and optionally authorization_remediation, plus has_more. Continue with --starting-after while has_more is true. An insight may be listed even when the current session lacks the access needed to retrieve its data. For a direct financial-data request, use reported remediation with auth upgrade for a CLI-managed session; follow the environment-token rule above for LINK_ACCESS_TOKEN. Pass missing scope values as one space-separated --scope argument; for a source authorization_details entry, pass each listed action as a separate --source-actions flag. For an optional purchase clue, skip an insight that needs new access. Do not guess insight IDs or assume that every listed insight has data for this user.

Retrieve only relevant IDs (repeat --insight for more than one), or omit the filter when the user needs all available insights:

link-cli insights list --insight  --format json

Both commands support --limit (1–100) and --starting-after for pagination. Each page has data and has_more; use the last item's id as the next cursor, keeping the filter unchanged. Stop if has_more is true but no usable cursor is returned.

Each retrieved insight has a status:

Command	What it does
ready	use its data entries and mention as_of (Unix seconds) when giving an answer. A number_of_items value contains number_of_items.label and number_of_items.count.
pending	the computation is not ready; suggest checking later.
no_data	inspect error_code, error_message, and authorization_remediation. For missing_permissions, follow the authentication guidance above; otherwise report that data is unavailable. In a purchase flow, continue without the insight when access is unavailable or the user declines to share data.

Other value types or statuses may appear in future responses. Preserve their JSON rather than inventing a meaning. Treat purchase-pattern results as observed history, not a definitive statement of the user's preference. For an ambiguous payment, check only a relevant category and use the result only if ready; an explicit merchant choice always wins. If insight discovery or retrieval fails, is pending, lacks access, or returns no useful data, continue from other task context or ask the user which merchant they want. Do not retry or delay a payment solely for an optional insight. Use raw transactions only if the user needs transaction-level detail to answer their question.

Sources (concept)

A source is a financial account connected to the user's Link wallet — a bank account, credit card, savings account, etc. Each source has a unique id (e.g. csmrpd_abc123) that other endpoints may expose as source_id:

• In transactions list, source_id indicates which account a transaction belongs to.
• In balances list, each balance entry includes a source_id identifying the account.
• In sources list, the full source metadata (name, institution, type, status) is returned.

Use a source_id to correlate data across commands — for example, to find transactions for a specific account or to match a balance to its source type. Do not assign transactions with a null source_id to a source by guessing from their description.

Transactions

Use transactions to answer questions about spending, income, merchants, categories, recurring payments, deposits, or account activity.

link-cli transactions list --format json

Common options:

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

Flag	Description
--start-date	Only transactions on or after this date (YYYY-MM-DD).
--end-date	Only transactions on or before this date (YYYY-MM-DD).
--category	Filter by category.
--origin	Filter by origin: link or external_connection.
--source	Filter by source ID (repeatable).

See Pagination for shared list controls.

Response fields

Field	Note
amount	Negative = money leaving the account (debit/purchase), positive = money entering (credit/deposit).
origin	external_connection (from linked bank/card) or link (Link-native transaction).
category	May be null if unclassified.
status	API-provided status string. Do not assume a closed set of values; observed values include succeeded. Interpret or filter a status only when its meaning is known.

For transaction summaries:

• Normalize signs consistently before calculating totals.
• Distinguish debits from credits when possible.
• Group by merchant, category, account, currency, or time period only when relevant.
• Mention if the answer is based on a limited retrieved window.

Balances

Use balances to answer questions about current account balances or available funds.

link-cli balances list --format json
link-cli balances list --format json --source

Flag	Description
--source	Filter by source ID (repeatable).

See Pagination for shared list controls.

Response fields

Field	Note
type	cash (bank/savings) or credit (credit card/line of credit). Determines which sub-object is present.
current	Balance before pending transactions. Not the same as available funds.
cash.available	Object mapping currency codes to available funds (current minus outbound pending plus inbound pending). Only present when type is cash.
credit.used	Object mapping currency codes to credit used. Only present when type is credit.
as_of	When the balance was last updated — may be stale by hours or days.

When summarizing balances:

• Preserve currencies.
• Do not add balances across different currencies unless the user explicitly asks and exchange-rate data is available.
• Use the current field as the default definition of a balance, unless the user's question requires considering pending transactions.
• If multiple sources are returned, summarize by account/source.

Sources

Use sources to answer questions about connected wallet sources, linked accounts, or available financial data sources. See Pagination for shared list controls.

link-cli sources list --format json

Response fields

Field	Description
id	Unique source identifier (same as source_id in other endpoints).
name	Display name of the source.
type	Source type (e.g. card, bank_account).
capabilities	Object indicating what data is available. Each key (e.g. balances, transactions) maps to an object with a status field (e.g. eligible).
external_connection.status	Connection status to the external institution.
granted_actions	List of actions the user has granted for this source.

When summarizing sources:

• Include only non-sensitive metadata needed for the answer.
• Avoid exposing full account numbers, credentials, tokens, or payment instrument details.
• Prefer labels such as institution, account type, source status, and last updated time when available.

Pagination

All three list commands support the same pagination flags:

Flag	Description
--limit	Maximum results per page (1-100). Prefer 100 when multiple pages may be needed.
--starting-after	Fetch the next page after a cursor value.
--ending-before	Fetch the previous page before a cursor value. Use for reverse navigation, not normal forward collection.

JSON responses contain a data array and may contain has_more. They do not provide a separate next-cursor field. When has_more is true, derive the next cursor from the final item in data:

Command	Next cursor
transactions list	Final transaction's id.
balances list	Final balance's source_id.
sources list	Final source's id.

For example:

link-cli transactions list --format json --limit 100 --starting-after

Keep all filters identical across pages and change only --starting-after. Stop when has_more is false or absent, or when enough data has been retrieved for a non-exhaustive lookup. If has_more is true but data is empty or the required cursor is null or missing, stop and report that pagination could not continue.

Do not exhaustively paginate unless the user’s request requires a complete bounded result, such as a total for a specified time range.

Answering user questions

When answering:

• State the direct answer first.
• Mention the relevant time range and data source.
• Note any limitations, such as partial pagination, missing categories, pending transactions, or unsupported currencies.
• Avoid dumping raw records and object IDs unless the user asks for them.
• Prefer concise summaries, totals, and notable patterns.

Example response style:

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.

Error handling

If login initiation fails specifically because the default source actions are unsupported or unavailable, explain the reduced access and retry once with auth login --no-financial-insights when payment access is still needed. Do not automatically retry after the user declines or abandons approval. For other authentication failures, ask the user to re-authenticate.

If a command returns no data, say that no matching Link financial data was available for the requested scope.

For a direct financial-data request, if the CLI reports missing permissions, request only the specific missing action. Use auth upgrade when a session is already authenticated and auth login when it is not, then wait for approval before retrying the data command once. Skip an optional payment insight instead of escalating access.

If data is incomplete or paginated, clearly state that the answer is based on the data retrieved so far.

Guardrails

Do not:

• Move money.
• Initiate payments.
• Modify financial sources.
• Retrieve unrelated financial data.
• Override the user's opt-out or explicit narrow access choice.
• Expose credentials, tokens, or full payment details.
• Present uncertain derived insights as definitive.

Do:

• Use read-only commands.
• Authenticate before retrieval.
• Use the four-action default for a new login unless the user opts out or chooses narrower access.
• Use --format json for parsing.
• Retrieve only the data needed.
• Summarize clearly and note limitations.