API Reference

SDK Methods

Complete reference for all InvestecAI methods.

Configuration

All options accepted by the InvestecAI constructor.

new InvestecAI({
  clientId:     string;   // Investec OAuth client ID
  clientSecret: string;   // Investec OAuth client secret
  apiKey:       string;   // Investec x-api-key header value
  openaiApiKey: string;   // OpenAI API key
  environment?: 'sandbox' | 'production';  // default: 'sandbox'
  timeout?:     number;   // request timeout in ms, default: 30000
})

Accounts & Balances

getAccounts()Promise<Account[]>

Returns all accounts linked to the authenticated Investec profile.

const accounts = await sdk.getAccounts();
// Account[]
// {
//   accountId:     string
//   accountNumber: string
//   accountName:   string
//   referenceName: string
//   productName:   string
// }

getBalance(accountId)Promise<Balance>

Returns the current and available balance for a single account.

const balance = await sdk.getBalance('acc_123');
// {
//   currentBalance:   number  // e.g. 12450.00
//   availableBalance: number
//   currency:         string  // 'ZAR'
// }

Transactions

getTransactions(accountId, options?)Promise<Transaction[]>

Returns transactions for an account. Optionally filter by date range or limit results.

const transactions = await sdk.getTransactions('acc_123', {
  from:  '2025-01-01',  // YYYY-MM-DD
  to:    '2025-01-31',
  limit: 50,
});
// Transaction[]
// {
//   uuid:            string
//   description:     string
//   amount:          number
//   type:            'DEBIT' | 'CREDIT'
//   transactionDate: string
//   transactionType: string
//   status:          string
// }

Spending Analysis

analyzeSpending(accountId, options?)Promise<SpendingAnalysis>

Fetches transactions for the given period, categorises them with GPT-4o-mini, and returns insights and predictions. Only debit transactions are included.

const analysis = await sdk.analyzeSpending('acc_123', {
  period: '30d',  // '7d' | '30d' | '90d' | '1y'  default: '30d'
});
// {
//   categories:  Record<string, number>  // { "Groceries": 2400, ... }
//   insights:    string[]                // ["You spent 20% more on food..."]
//   predictions: { next30Days: number }  // predicted spend
//   totalSpent:  number
//   period:      string
// }

Fraud Detection

detectFraud(transaction)Promise<FraudAlert>

Risk-scores a single transaction using GPT-4o. Returns a score from 0–100, reasons, and whether the transaction requires confirmation.

const alert = await sdk.detectFraud(transaction);
// {
//   transactionId:        string
//   riskScore:            number   // 0 (safe) – 100 (high risk)
//   reasons:              string[]
//   requiresConfirmation: boolean
// }

Receipt Scanning

scanReceipt(imageBase64)Promise<ReceiptScan>

Sends a base64-encoded image to GPT-4o Vision and extracts merchant, amount, date, and line items.

const receipt = await sdk.scanReceipt(imageBase64);
// {
//   merchant: string
//   amount:   number
//   date:     string  // YYYY-MM-DD
//   items:    Array<{ name: string; price: number; quantity: number }>
//   matchedTransactionId?: string
// }

Voice Transcription

transcribeAudio(audioBlob, filename?)Promise<string>

Transcribes an audio Blob using OpenAI Whisper. Designed to work with the browser MediaRecorder API.

// audioBlob from browser MediaRecorder
const transcript = await sdk.transcribeAudio(audioBlob, 'audio.webm');
// "What's my current balance?"

AI Chat Handler

createChatHandler(sdk, options?)(req: Request) => Promise<Response>

Creates a framework-agnostic streaming chat handler. Compatible with Next.js App Router, Hono, and any runtime that handles standard Request/Response objects.

import { createChatHandler } from 'investec-ai';

createChatHandler(sdk, {
  // AI model — defaults to GPT-4o. Accepts any Vercel AI SDK-compatible model.
  model?: LanguageModel;

  // Max sequential tool-call steps. Default: 5
  maxSteps?: number;

  // System prompt override
  // string: replaces the default prompt entirely
  // function: receives the default prompt so you can extend it
  system?: string | ((defaultPrompt: string) => string);

  // Default account ID passed to tools when none is in the request body
  defaultAccountId?: string;
})

The handler reads { messages, accountId } from the request body and returns a data stream response compatible with the Vercel AI SDK useChat hook.

Available tools (injected automatically):

get_accounts

get_balance

get_transactions

analyze_spending