Getting Started with FinRouter

Prerequisites

• Node.js 18 or higher
• TypeScript 5.x (FinRouter ships types)
• At least one provider key (OpenAI, Anthropic, Google, or any OpenRouter-supported model)

Installation

npm install FinRouter

1. Register an encrypted key (BYOK)

Keys are encrypted at rest with AES-256-GCM and zeroed from memory after each request.

import { FinRouter } from "FinRouter";

const router = new FinRouter({
  masterKey: process.env.FR_MASTER_KEY, // used to derive the at-rest cipher
});

await router.keys.add({ provider: "openai", apiKey: process.env.OPENAI_API_KEY });

2. Define a budget hierarchy

Budgets cascade global → org → department → team → user. A request is rejected before it leaves your process if any scope is exhausted.

await router.budgets.set({ scope: "org:acme", monthlyUsd: 5000 });
await router.budgets.set({ scope: "team:platform", monthlyUsd: 800 });
await router.budgets.set({ scope: "user:alice", monthlyUsd: 100 });

3. Route a request

const res = await router.chat({
  scope: "user:alice",
  model: "gpt-4o",
  messages: [{ role: "user", content: "Summarize this contract." }],
});
console.log(res.content, res.spendUsd);

4. Enable the injection guard

The guard runs 14+ pattern checks plus NFKD Unicode normalization on every input.

const router = new FinRouter({
  masterKey: process.env.FR_MASTER_KEY,
  guard: { promptInjection: true, normalizeUnicode: true },
});

5. (Optional) Live pricing & batch downgrade

FinRouter pulls live rates from LiteLLM and OpenRouter and can auto-downgrade batch requests to cheaper models, no restart required.

const router = new FinRouter({
  pricing: { source: "litellm", refreshMinutes: 30 },
  batch: { autoDowngrade: true },
});