Reads a user's Link financial data — transactions, balances, and wallet sources — so agents can answer questions about spending and available source capabilities. Use when the user says "check my balance", "how much did I spend", "show my transactions", "what accounts are connected", "summarize my s

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. 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. If the user is not authenticated, start a login that requests only the source actions needed for the requested data. If the user is already authenticated but one or more required source actions are missing, use auth upgrade instead of auth login . auth upgrade preserves the current session while the user approves the additional access and replaces it only after approval succeeds. 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 . Use the minimum required source actions: 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. If the user asks a question that requires multiple data types, request all relevant actions together. If this skill supports a purchase and the merchant is unspecified, identify the needed Link capabilities before login. Request transaction access with the payment scopes in one login when a purchase pattern insight is likely to help. The current top brand insight can use a source granting either read link transactions or read external transactions ; requesting both covers both kinds of source. If already authenticated, consult insights list available types and request only the missing access it reports. Example for a new login that needs all financial data types: Example for adding balance access to an existing session: Replace <your agent name 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: 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.” → Use a relevant available insight to inform merchant selection; treat the result as a clue, not a guaranteed preference. “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. 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: The response contains data entries with id , description , and optionally authorization remediation , plus has more . Continue with starting after <last id while has more is true. An insight may be listed even when the current session lacks the access needed to retrieve its data. If the insight is needed, use the 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. 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: 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 : 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. Use raw transactions only if the available insights cannot answer the question and transaction level detail is needed. 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. Common options: 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]( 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. Flag Description source Filter by source ID (repeatable). See [Pagination]( 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]( pagination) for shared list controls. 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 ). externa

financial-insights