Investec AI SDK

An AI-powered banking developer platform built on top of the Investec Open API. Add conversational banking, spending analysis, fraud detection, voice banking, and receipt scanning to any app in minutes.

Live demo: https://investec-ai-sdk.vercel.app
npm: https://www.npmjs.com/package/investec-ai

What's inside

| Package | Description | |---|---| | packages/sdk | The investec-ai npm package | | packages/react | Headless React components and hooks | | packages/shared | Shared TypeScript types | | apps/web | Next.js demo app (deployed to Vercel) | | apps/docs | Documentation site |

Quickstart

1. Install

npm install investec-ai

2. Initialise the client

import { InvestecAI } from 'investec-ai';

const sdk = new InvestecAI({
  clientId:     process.env.INVESTEC_CLIENT_ID!,
  clientSecret: process.env.INVESTEC_CLIENT_SECRET!,
  apiKey:       process.env.INVESTEC_API_KEY!,
  openaiApiKey: process.env.OPENAI_API_KEY!,
});

3. Add AI chat to any route (Next.js example)

// app/api/chat/route.ts
import { InvestecAI, createChatHandler } from 'investec-ai';

const sdk = new InvestecAI({ ... });

export const POST = createChatHandler(sdk);

That's it. Your app now has a fully functional AI banking assistant backed by real Investec data.

SDK reference

Accounts

// List all accounts
const accounts = await sdk.getAccounts();

// Get live balance
const { currentBalance, availableBalance } = await sdk.getBalance(accountId);

Transactions

const transactions = await sdk.getTransactions(accountId, {
  from: '2025-01-01',
  to:   '2025-01-31',
  limit: 50,
});

AI spending analysis

const analysis = await sdk.analyzeSpending(accountId, { period: '30d' });

console.log(analysis.categories);         // { "Groceries": 2400, "Transport": 850, ... }
console.log(analysis.insights);           // ["You spent 20% more on food...", ...]
console.log(analysis.predictions.next30Days); // 6200

Fraud detection

const alert = await sdk.detectFraud(transaction);

console.log(alert.riskScore);        // 0–100
console.log(alert.reasons);          // ["Unusual merchant location", ...]
console.log(alert.requiresConfirmation); // true | false

Receipt scanning

const receipt = await sdk.scanReceipt(imageBase64);

console.log(receipt.merchant); // "Woolworths Food"
console.log(receipt.amount);   // 342.50
console.log(receipt.items);    // [{ name: "Milk", price: 28, quantity: 2 }, ...]

Voice transcription

// audioBlob from browser MediaRecorder
const transcript = await sdk.transcribeAudio(audioBlob);

AI chat handler

import { createChatHandler } from 'investec-ai';
import { anthropic } from '@ai-sdk/anthropic';

export const POST = createChatHandler(sdk, {
  model: anthropic('claude-opus-4-5'),  // any Vercel AI SDK model
  maxSteps: 10,
  system: (defaultPrompt) => `${defaultPrompt}\n\nAlways respond in Zulu.`,
});

The handler is framework-agnostic — works with Next.js App Router, Hono, or any runtime that handles standard Request/Response objects.

Environment variables

| Variable | Description | |---|---| | INVESTEC_CLIENT_ID | Investec OAuth client ID | | INVESTEC_CLIENT_SECRET | Investec OAuth client secret | | INVESTEC_API_KEY | Investec x-api-key header value | | OPENAI_API_KEY | OpenAI API key (for chat, analysis, fraud detection, receipt scanning, transcription) |

Get your Investec credentials from the Investec Developer Portal. The SDK defaults to the sandbox environment. Pass environment: 'production' to use live data.

Running the demo app locally

# 1. Clone the repo
git clone https://github.com/HappyDevs1/investec-ai.git
cd investec-ai

# 2. Install dependencies
pnpm install

# 3. Add environment variables
cp apps/web/.env.local.example apps/web/.env.local
# Fill in your credentials

# 4. Start the dev server
pnpm --filter @investec-ai/web dev

Then open http://localhost:3000.

Demo features

| Page | Feature | |---|---| | /dashboard | Account overview, live balance, spending chart, AI insights | | /dashboard/chat | Conversational banking — ask anything about your finances | | /dashboard/transactions | Full transaction list with per-transaction AI fraud detection | | /dashboard/voice | Voice banking — speak a question, Whisper transcribes, GPT-4o responds | | /dashboard/receipt | Receipt scanner — upload a photo, GPT-4o Vision extracts the data | | /dashboard/goals | Savings goals with progress tracking | | /dashboard/budgets | Category budgets with over-limit alerts |

Architecture

The SDK calls Investec and OpenAI directly using the developer's own credentials — no hosted infrastructure in the trust chain.

Your app
  └── investec-ai SDK
        ├── InvestecClient  →  Investec Open API (your credentials)
        ├── AIFeatures      →  OpenAI API (your key)
        └── createChatHandler → Vercel AI SDK (streaming)

Tech stack

• SDK: TypeScript, Vercel AI SDK, OpenAI SDK
• Demo app: Next.js 16, Tailwind CSS, TanStack Query, Recharts, Shiki
• Monorepo: Turborepo + pnpm workspaces
• Deployment: Vercel (demo app) · npm (SDK)

License

MIT © Happy Mahlangu