Add financial insights to your agent

Retrieve transactions, balances, and account details from customers' connected bank accounts and credit cards.

Financial insights lets your agent answer questions about customer spending, track trends, and provide personalized analysis using data from their connected bank accounts and credit cards. The data is powered by Financial Connections, which lets customers securely share their financial data with your business.

Before you begin

Before you begin, make sure that:

• You’ve set up OAuth .
• You’ve installed Link CLI: npm install -g @stripe/link-cli

Register for Financial Connections

Because your agent accesses financial account data on behalf of customers, you must register as a data recipient with Financial Connections to read data from external accounts.

1. Go to the Financial Connections settings in the Dashboard.
2. Complete the registration form with your business details.
3. Accept the Financial Connections terms of service.

Use the same Stripe account whose publishable key you use to initiate the OAuth flow. Registration happens in the Stripe Dashboard, but your agent retrieves the resulting financial data from the Link API at api.link.com, not from the Stripe API.

If you don’t register for Financial Connections, your agent can request only the read_link_transactions source action. Reading balances, account details, or transactions from external bank accounts and credit cards requires registration.

Request financial data scopes

Financial insights requires the authorization_details parameter in your OAuth authorization URL. This parameter specifies which data types your agent can access, and takes a JSON array. Use the source type with the actions your agent needs:

authorization_details

[
 {
 "type": "source",
 "actions": [
 "read_link_transactions",
 "read_external_transactions",
 "read_balances",
 "read_source_details"
 ]
 }
]

URL-encode that JSON, then add it to the authorization URL from Set up OAuth. If your agent both makes purchases and reads financial data, request the payments scope alongside authorization_details:

Financial insights and payments

https://login.link.com/auth?key=pk_live_YOUR_PUBLISHABLE_KEY&client_id=YOUR_CLIENT_ID&redirect_uri=https://yourapp.com/callback&response_type=code&scope=payment_methods.agentic%20userinfo:read&state=RANDOM_STATE_VALUE&code_challenge=YOUR_PKCE_CODE_CHALLENGE&code_challenge_method=S256&authorization_details=ENCODED_AUTHORIZATION_DETAILS

If your agent only reads financial data, omit payment_methods.agentic:

Financial insights only

https://login.link.com/auth?key=pk_live_YOUR_PUBLISHABLE_KEY&client_id=YOUR_CLIENT_ID&redirect_uri=https://yourapp.com/callback&response_type=code&scope=userinfo:read&state=RANDOM_STATE_VALUE&code_challenge=YOUR_PKCE_CODE_CHALLENGE&code_challenge_method=S256&authorization_details=ENCODED_AUTHORIZATION_DETAILS

Source actions

During the OAuth flow, customers choose which accounts to share. They can also opt in to automatically share accounts they add to Link in the future. Request all available actions upfront to avoid requiring customers to re-authorize later.

List connected accounts

Retrieve the customer’s connected financial accounts:

List sources

link-cli sources list --format json

The response includes the customer’s connected financial accounts:

Sources response

{
 "data": [
 {
 "id": "csmrpd_abc123",
 "name": "BANK SAVINGS",
 "type": "bank_account",
 "capabilities": {
 "balances": { "status": "eligible" },
 "transactions": { "status": "eligible" }
 },
 "external_connection": { "status": "active" },
 "bank_account": { "last4": "5115" },
 "granted_actions": [
 "read_balances",
 "read_external_transactions",
 "read_source_details",
 "read_link_transactions"
 ]
 }
 ],
 "has_more": false
}

Each source includes:

• capabilities : Indicates whether balances and transactions are available. A capability with status eligible can be queried; pending means the data isn’t ready yet.
• granted _ actions : Confirms which data types the customer authorized.
• external _ connection. status : Shows whether the connection to the financial institution is active.
• card or bank _ account : Account details, depending on type . Sources use card and bank _ account . The similarly named card _ details and bank _ account _ details fields belong to payment methods, which are a different object.

Retrieve transactions

Agents can specify the data requested so they only retrieve transactions needed to answer the customer’s prompt. Fetch transaction history from connected accounts:

List transactions

link-cli transactions list --limit 50 --start-date 2026-06-01 --end-date 2026-06-30 --format json

The response includes the customer’s transaction history:

Transactions response

{
 "data": [
 {
 "id": "lbctxn_abc123",
 "source_id": "csmrpd_abc123",
 "amount": 4999,
 "currency": "usd",
 "created_date": "2026-06-15",
 "description": "ACME Coffee Shop",
 "status": "succeeded",
 "category": null,
 "origin": "external_connection"
 }
 ],
 "has_more": true
}

Filters

Use the following flags to filter transactions:

Paginate through results

When has_more is true, fetch the next page using the last transaction’s ID:

Pagination

link-cli transactions list --limit 100 --start-date 2026-06-01 --starting-after lbctxn_abc123 --format json

Continue fetching pages until has_more is false.

Transaction fields

The response includes the transaction details:

The status field isn’t a closed enum, and new values can appear without notice. Observed values include succeeded. Handle unrecognized values gracefully instead of branching on an exhaustive list.

Retrieve balances

Fetch current balances on connected accounts:

List balances

link-cli balances list --format json

The response includes the customer’s current balances:

Balances response

{
 "data": [
 {
 "source_id": "csmrpd_abc123",
 "type": "cash",
 "current": 31005,
 "currency": "usd",
 "as_of": "2026-07-15T00:00:00Z",
 "cash": {
 "available": { "usd": 31005 }
 }
 }
 ],
 "has_more": false
}

Balance types

Use the following types to filter balances:

Amounts are in the smallest currency unit (cents for USD). Divide by 100 for display.

Handle pending data retrieval

When a customer connects a new account, transaction and balance data might not be immediately available. If the data is still loading, the CLI returns a 202 status with:

Pending response

{
 "code": "external_data_retrieval_pending",
 "description": "We are still retrieving external financial data. Please try again in a few seconds."
}

Retry after a few seconds. Data typically becomes available within 30 seconds of the customer connecting an account.

Configure your agent's skill file

A skill file tells your agent when and how to use financial insights. You can either point your agent to the canonical skill file, or host a customized version in your agent’s configuration.

To install the bundled skills:

Install skills

npx skills add stripe/link-cli

This registers the bundled skills with compatible agents (Claude, OpenClaw, and other skill-aware platforms).

Test your integration

1. Complete the OAuth flow with the authorization _ details parameter.
2. Connect at least one bank account or credit card during the authorization flow.
3. Run link-cli sources list --format json and verify your connected accounts appear. Capabilities might show pending for a short time after connecting, then become eligible .
4. Run link-cli transactions list --limit 5 --format json and confirm transaction data returns.
5. Run link-cli balances list --format json and verify balance data.
6. Ask your agent a question about spending (for example, “What did I spend on dining this month?”) to verify end-to-end behavior.

No sandbox environment

Financial insights currently doesn’t support a sandbox environment. Test with live bank accounts using the production OAuth flow.

Data access and customer controls

When a customer connects an account, your agent can access balances and transaction history for that account when requested by the customer. Customers control access at the account level and can revoke access at any time through the Link app. If a customer revokes access, subsequent CLI calls for that source return an authorization error. Prompt the customer to reconnect if they want to restore access, instead of retrying the CLI call.

See also

• Financial Connections
• Set up OAuth