Guides

Framework Guides

Step-by-step integration guides for common frameworks and use cases.

Next.js App Router

The recommended way to use the SDK. The chat handler exports directly as a Next.js route handler.

1. Create the SDK instance

lib/sdk.ts

import { InvestecAI } from 'investec-ai';

export 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!,
});

2. Create the chat route

app/api/chat/route.ts

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

export const POST = createChatHandler(sdk);

3. Add the chat UI

app/chat/page.tsx

'use client';

import { useChat } from 'ai/react';

export default function ChatPage() {
  const { messages, input, handleInputChange, handleSubmit } = useChat({
    api: '/api/chat',
  });

  return (
    <div>
      {messages.map(m => (
        <div key={m.id}>
          <strong>{m.role}:</strong> {m.content}
        </div>
      ))}
      <form onSubmit={handleSubmit}>
        <input value={input} onChange={handleInputChange} placeholder="Ask anything..." />
        <button type="submit">Send</button>
      </form>
    </div>
  );
}

4. Fetch account data server-side

app/dashboard/page.tsx

import { sdk } from '@/lib/sdk';

export default async function DashboardPage() {
  const accounts = await sdk.getAccounts();
  const primary = accounts[0];
  const balance = await sdk.getBalance(primary.accountId);

  return (
    <div>
      <h1>{primary.accountName}</h1>
      <p>Balance: R{balance.currentBalance.toFixed(2)}</p>
    </div>
  );
}

Hono

The chat handler works with Hono since it uses standard Request/Response objects.

import { Hono } from 'hono';
import { InvestecAI, createChatHandler } 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!,
});

const chatHandler = createChatHandler(sdk);

const app = new Hono();

app.post('/api/chat', c => chatHandler(c.req.raw));
app.get('/api/accounts', async c => {
  const accounts = await sdk.getAccounts();
  return c.json(accounts);
});

export default app;

Using a custom AI model

The SDK defaults to GPT-4o but accepts any model from the Vercel AI SDK provider list.

Using Claude

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

export const POST = createChatHandler(sdk, {
  model: anthropic('claude-opus-4-5'),
  maxSteps: 10,
});

Extending the system prompt

export const POST = createChatHandler(sdk, {
  // Receives the default prompt — append to it instead of replacing
  system: (defaultPrompt) => `${defaultPrompt}

Additional instructions:
- Always greet the user by first name
- Format amounts with the full currency name (South African Rand)
- Highlight any unusual spending patterns first`,
});

Setting a default account

export const POST = createChatHandler(sdk, {
  // Tools use this account when none is provided in the request body
  defaultAccountId: process.env.DEFAULT_ACCOUNT_ID,
});

Going to production

Switch from the Investec sandbox to production data with a single config change.

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!,
  environment:  'production',  // ← switch here
});

💡 Make sure you have production credentials from the Investec Developer Portal — sandbox and production credentials are different.