X Enterprises
fastify-xplaid

investments.getTransactions(accessToken, startDate, endDate, options?)

Get investment transaction history by date range for a Plaid Item.

investments.getTransactions(accessToken, startDate, endDate, options?)

Returns investment transaction history — buys, sells, dividends, fees, and transfers — within a date range. Paginate using count and offset against totalInvestmentTransactions. Requires the investments product to have been enabled in the Link token.

Signature

fastify.xplaid.investments.getTransactions(
  accessToken: string,
  startDate: string,
  endDate: string,
  options?: {
    accountIds?: string[]
    count?: number    // max 500
    offset?: number
  }
): Promise<{
  accounts: PlaidAccount[]
  investmentTransactions: InvestmentTransaction[]
  securities: Security[]
  totalInvestmentTransactions: number
  item: PlaidItem
  requestId: string
}>

Params

NameTypeRequiredDescription
accessTokenstringYesThe Item's permanent access token.
startDatestringYesStart date in YYYY-MM-DD format (inclusive).
endDatestringYesEnd date in YYYY-MM-DD format (inclusive).
options.accountIdsstring[]NoRestrict to specific account IDs.
options.countnumberNoMax results per page (max 500).
options.offsetnumberNoPagination offset for subsequent pages.

Returns

Promise<{ accounts, investmentTransactions, securities, totalInvestmentTransactions, item, requestId }>

FieldDescription
investmentTransactionsInvestment activity — each includes type, subtype, amount, date, quantity, price, and security_id.
securitiesSecurity metadata for all referenced security IDs.
totalInvestmentTransactionsTotal transaction count across all pages — use with offset to paginate.

Throws

  • [xPlaid] accessToken is required and must be a non-empty string
  • [xPlaid] startDate is required and must be a non-empty string
  • [xPlaid] endDate is required and must be a non-empty string
  • Plaid API errors — shape: { message, statusCode, plaidError }.
  • PRODUCTS_NOT_SUPPORTED Plaid error if investments was not enabled.

Examples

Basic — last 30 days of investment activity

const end = new Date().toISOString().slice(0, 10);
const start = new Date(Date.now() - 30 * 86400000).toISOString().slice(0, 10);

const { investmentTransactions, securities } =
  await fastify.xplaid.investments.getTransactions(accessToken, start, end);

Realistic — paginated investment history route

fastify.get("/investments/transactions", async (request, reply) => {
  const { startDate, endDate, page = 0 } = request.query;
  const item = await db.plaidItems.findFirst({ where: { userId: request.user.id } });
  if (!item) return reply.status(404).send({ error: "No linked account" });

  try {
    const { investmentTransactions, securities, totalInvestmentTransactions } =
      await fastify.xplaid.investments.getTransactions(
        decrypt(item.accessToken),
        startDate,
        endDate,
        { count: 100, offset: page * 100 }
      );

    const securityMap = Object.fromEntries(securities.map((s) => [s.security_id, s]));

    return {
      total: totalInvestmentTransactions,
      transactions: investmentTransactions.map((t) => ({
        date: t.date,
        type: t.type,
        subtype: t.subtype,
        amount: t.amount,
        quantity: t.quantity,
        price: t.price,
        ticker: securityMap[t.security_id]?.ticker_symbol,
        name: securityMap[t.security_id]?.name,
      })),
    };
  } catch (error) {
    if (error.plaidError) {
      request.log.error({ code: error.plaidError.error_code }, "Investment transactions failed");
      return reply.status(error.statusCode ?? 500).send({ error: error.message });
    }
    throw error;
  }
});

Full paginated fetch

async function fetchAllInvestmentTransactions(accessToken, startDate, endDate) {
  const PAGE = 500;
  let offset = 0;
  let all = [];

  while (true) {
    const { investmentTransactions, totalInvestmentTransactions } =
      await fastify.xplaid.investments.getTransactions(accessToken, startDate, endDate, {
        count: PAGE,
        offset,
      });
    all = all.concat(investmentTransactions);
    offset += investmentTransactions.length;
    if (offset >= totalInvestmentTransactions) break;
  }
  return all;
}

See also

AI Context

package: "@xenterprises/fastify-xplaid"
method: fastify.xplaid.investments.getTransactions(accessToken, startDate, endDate, options?)
use-when: Get investment transaction history (buys, sells, dividends, fees) by date range — requires "investments" product
params: accessToken, startDate (YYYY-MM-DD), endDate (YYYY-MM-DD), options (accountIds, count, offset)
returns: { investmentTransactions, securities, totalInvestmentTransactions, accounts, item, requestId }

investments.getHoldings(accessToken, options?)

Get current investment holdings and security metadata for a Plaid Item.

xplaid.items.get

Get the current status and configuration of a Plaid Item, including webhook URL, available products, and consent expiration.

Copyright © 2026