# Investment Holdings
URL: https://www.quiltt.dev/api/holdings
Description: Learn how to work with investment holdings through Quiltt's GraphQL API.
Navigation: api → holdings
Tags: API, Core Resources
Content Length: 6k characters

A **Holding** in Quiltt represents an investment position such as a stock, bond,
ETF, or mutual fund held in an investment account.

## Schemas & Types

Profile GraphQL Note:

## GraphQL Queries

Quiltt provides holdings at two levels:

1. **Profile level** - Aggregated positions across all investment accounts via
   the `holdings` query.
2. **Account level** - Individual positions for a specific account via
   `account.holdings`.

| Aspect          | Profile Level (Holding)   | Account Level (AccountHolding) |
| --------------- | ------------------------- | ------------------------------ |
| **Access**      | Root `holdings` field     | `Account.holdings` field       |
| **Scope**       | All investment accounts   | Single account                 |
| **Data source** | System-calculated roll-up | Provider remote data           |
| **Remote data** | Not available             | Available                      |

### When to Use Each

Use the `holdings` query when you want:

- Consolidated portfolio view across all accounts
- Total exposure to a specific security
- Overall investment performance
- Aggregate portfolio analytics

Use account-level holdings (`account.holdings`) when you want:

- Positions broken down by account
- Access to provider-specific remote data
- Account-specific cost basis for reconciliation

### Profile-Level Holdings

Use the `holdings` query to fetch aggregated positions across all investment
accounts belonging to the Profile. This provides a consolidated portfolio view.

GraphQLRequest:

Query:
```graphql
query GetHoldings {
  holdings {
    nodes {
      id
      quantity
      position
      price
      value
      costBasis
      at
      security [name
        tickerSymbol]
    }
  }
}
```

  

Response:
```json
{
  "data": {
    "holdings": {
      "nodes": [
        {
          "id": "hld_12xBsJKrI455PNcaCkqpGk",
          "quantity": 250.75,
          "position": "LONG",
          "price": 178.32,
          "value": 44713.74,
          "costBasis": 38542.50,
          "at": "2024-06-09T12:34:56Z",
          "security": ["name": "Apple Inc.",
            "tickerSymbol": "AAPL"]
        }
      ]
    }
  }
}
```

Profile-level holdings are calculated after each sync completes and the
`profile.ready` event is fired. When you own the same investment across
multiple accounts, positions are combined:

- **Quantity**: Total shares across all accounts
- **Value**: Total market value across all accounts
- **Cost Basis**: Your average cost per share across all accounts

### Account-Level Holdings

Account-level holdings are available through Accounts. Use `account.holdings`
when you need positions for a specific investment account, including access to
provider-specific remote data.

GraphQLRequest:

Query:
```graphql
query GetAccountHoldings {
  account(id: "acct_12tgD1YP33AwEvbdmSrcRY") {
    id
    name
    holdings {
      nodes {
        id
        quantity
        position
        price
        value
        costBasis
        at
        security [name
          tickerSymbol]
      }
    }
  }
}
```

  

Response:
```json
{
  "data": {
    "account": {
      "id": "acct_12tgD1YP33AwEvbdmSrcRY",
      "name": "Individual Brokerage",
      "holdings": {
        "nodes": [
          {
            "id": "achld_12xBsJKrI455PNcaCkqpGh",
            "quantity": 150.5,
            "position": "LONG",
            "price": 178.32,
            "value": 26837.16,
            "costBasis": 22542.00,
            "at": "2024-06-09T12:34:56Z",
            "security": ["name": "Apple Inc.",
              "tickerSymbol": "AAPL"]
          }
        ]
      }
    }
  }
}
```

### Accessing Remote Data

Account-level holdings include raw provider data via the `remoteData` field:

```graphql
query AccountHoldingRemoteData {
  account(id: "acct_12tgD1YP33AwEvbdmSrcRY") {
    holdings {
      nodes {
        id
        remoteData {
          finicity {
            holding {
              response [securityId
                marketValue]
            }
          }
        }
      }
    }
  }
}
```

[RemoteDataCallout]

## Long and short positions

Every holding includes a `position` field that indicates whether the lot is a
long or short position. The field is available on both profile-level holdings
and account-level holdings.

| Value   | Meaning                                                                |
| ------- | --------------------------------------------------------------------- |
| `LONG`  | A standard owned position. This is the default for most holdings.     |
| `SHORT` | A short position, where the security was sold short rather than owned. |

Quiltt reports short positions with a negative `quantity`, reflecting the
borrowed shares owed back to the broker. Read the `position` field when you need
to separate long exposure from short exposure in portfolio calculations rather
than inferring direction from the sign of `quantity` alone.

## Data freshness

Holdings and their balances update when Quiltt syncs the underlying connection,
not in real time. Each holding's `at` field records when Quiltt last observed
that position, and profile-level holdings are recalculated after every sync
completes and the `profile.ready` event fires.

Investment accounts refresh differently from depository and credit accounts.
Because Plaid doesn't send webhooks for investment account balance or position
changes, Quiltt automatically syncs Plaid connections that hold investment
accounts more frequently than other connections. This scheduled polling captures
balance and position changes without a real-time push, so investment holdings
stay reasonably current even though no webhook signals the update.

Info:
Read the `at` timestamp when you need to know how current a holding is, and
subscribe to `connection.synced.successful` on the
[Connections API](/api/connections) to react as soon as new holdings data lands.

## Testing

Info:
Holdings data is only available for accounts that contain investment positions
(e.g., brokerage, IRA, 401k). Holdings are not available for depository or credit accounts.

### Finicity Test Logins

Use the logins below to test investments data using a Finicity-enabled Connector. Your Connector must have the **Investments** product enabled.

These logins are only available in **Sandbox** and **Test** environments. See the [Connections guide](/api/connections) for details on creating test connections.

To connect, select the **Finicity Test Bank** institution and choose **FinBank Profiles A** or **FinBank Profiles B** portal.

| Username | Password |
| -------- | -------- |
| `sue_wealthy` | `profile_700` |
| `joe_investor` | `profile_03` |

For a full list of test profiles including additional bank account profiles
with specific investment account types (IRAs, 401ks, brokerage, etc.), refer to
the [Mastercard Test APIs documentation](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/).