# 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](https://docs.stripe.com/financial-connections.md), 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](https://docs.stripe.com/agentic-commerce/link-cli/oauth.md).
- 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](https://dashboard.stripe.com/settings/financial-connections) in the Dashboard.
2. Complete the [registration form](https://dashboard.stripe.com/financial-connections/application) 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:

```json
[
  {
    "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](https://docs.stripe.com/agentic-commerce/link-cli/oauth.md). If your agent both makes purchases and reads financial data, request the payments scope alongside `authorization_details`:

```url
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`:

```url
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.

| Action | Requires Financial Connections registration | Description |
| --- | --- | --- |
| `read_link_transactions` | No | Read transactions made through Link. |
| `read_external_transactions` | Yes | Read transactions from connected external accounts (bank accounts, credit cards). |
| `read_balances` | Yes | Read current and available balances on connected accounts. |
| `read_source_details` | Yes | Read account metadata such as institution name, account type, and last four digits. |

## List connected accounts

Retrieve the customer’s connected financial accounts:

```bash
link-cli sources list --format json
```

The response includes the customer’s connected financial accounts:

```json
{
  "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:

```bash
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:

```json
{
  "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:

| Flag | Description |
| --- | --- |
| `--limit <n>` | Transactions per request, from 1 to 100. |
| `--start-date <YYYY-MM-DD>` | Transactions on or after this date. |
| `--end-date <YYYY-MM-DD>` | Transactions on or before this date. |
| `--origin <origin>` | Filter by `link` (Link purchases) or `external_connection` (bank or card transactions). |
| `--source <id>` | Filter by source ID. Repeatable for multiple sources. |
| `--starting-after <id>` | Transaction ID for forward pagination. |
| `--ending-before <id>` | Transaction ID for backward pagination. |

### Paginate through results

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

```bash
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:

| Field | Description |
| --- | --- |
| `amount` | Amount in the smallest currency unit (cents for USD). Divide by 100 for display. |
| `origin` | `link` for Link purchases, `external_connection` for transactions from connected banks and cards. |
| `status` | Settlement state of the transaction. Treat this as an open set of values. See the following note. |
| `category` | Spending category, when available. Can be `null`. |
| `created_date` | Transaction date in `YYYY-MM-DD` format. |

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:

```bash
link-cli balances list --format json
```

The response includes the customer’s current balances:

```json
{
  "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:

| Type | Fields | Description |
| --- | --- | --- |
| `cash` | `current` or `cash.available` | Bank accounts. `current` is the posted balance, while `available` excludes pending transactions. |
| `credit` | `current` or `credit.used` | Credit cards. `current` is the posted balance, while `used` includes pending charges. |

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:

```json
{
  "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](https://github.com/stripe/link-cli/blob/main/skills/financial-insights/SKILL.md), or host a customized version in your agent’s configuration.

To install the bundled skills:

```bash
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](https://docs.stripe.com/financial-connections.md)
- [Set up OAuth](https://docs.stripe.com/agentic-commerce/link-cli/oauth.md)