# Kairos: Open-source, real-time fraud and risk decisioning

> Source: <https://github.com/finic-ai/kairos>
> Published: 2026-11-02 06:20:09+00:00

[Kairos](https://kairos.finic.ai) decides every sign-up, login, order, payment and payout as it happens, and keeps each decision with the signals behind it. It is an open-source alternative to Sardine, Sift, Riskified and SEON, with two things they don't have: **your coding agent tunes it**, and **decision models** catch fraud before you have the labels to train on.

- [Real-time decisions](https://github.com/finic-ai/kairos/blob/main/docs/concepts/decisions.md) : one call returns approve, step up, review or block, with a risk score and the reasons, from the subject's history, the devices, cards and addresses it shares with others, and the session.
- [Workflows](https://github.com/finic-ai/kairos/blob/main/docs/platform/workflows.md) : ask a decision model, score with a model, branch, call webhooks, open cases, and decide again later.
- [Queues and cases](https://github.com/finic-ai/kairos/blob/main/docs/case-management/queues.md) : review work for people, whose resolutions become labels.

- [MCP server](https://github.com/finic-ai/kairos/blob/main/docs/reference/mcp.md) : Claude Code, Cursor or Codex read your decisions and build workflows, with every action recorded under its key.
- [Experiments](https://github.com/finic-ai/kairos/blob/main/docs/platform/models.md) : your agent proposes model variants, Kairos trains and tests them on your data, and the agent ships the winner.

- [Grayson](https://finic.ai) : Finic's decision model answers questions about each request in plain language. It works with few labels and reads unstructured data.
- [Models](https://github.com/finic-ai/kairos/blob/main/docs/platform/models.md) : logistic regression and gradient-boosted trees (XGBoost-compatible) on your numbers and Grayson's answers, trained in Kairos or uploaded.

- [SDKs](https://github.com/finic-ai/kairos/blob/main/docs/reference/clients/typescript.md) for TypeScript (`@finic-ai/kairos` ) and Python (`finic-kairos` ), a[CLI](https://github.com/finic-ai/kairos/blob/main/docs/reference/clients/cli.md) , an[HTTP API](https://github.com/finic-ai/kairos/blob/main/docs/reference/api.md) , and[self-hosting](https://github.com/finic-ai/kairos/blob/main/docs/deployment/self-hosting.md) with Docker.

You send Kairos what happens in your product: sign-ups, logins, orders, payouts, chargebacks. It decides each request (approve, step up, review or block) and keeps every decision with the signals behind it.

What makes Kairos different is who tunes it. Connect Claude Code, Cursor, Codex or any agent over **MCP**, and the agent can do the work of a fraud ML engineer:

1. **Build the workflow.** It defines what to decide, which questions to ask a decision model, and which fields to score.
2. **Design experiments.** It proposes variants: a decision model alone, logistic regression on your numbers, gradient-boosted trees, a stack of them, or the decision model's answers combined with your numbers in one model.
3. **Let Kairos run them.** The server trains each variant on your oldest labeled data, chooses on the next, and tests on the newest, then reports ROC-AUC, PR-AUC, the gain over a baseline with its 95% interval, and precision and recall at your thresholds.
4. **Pick the winner and ship it.** The agent explains its choice, applies the variant as the workflow's next version, and comes back when new labels arrive.

```
You:     "Our chargebacks went up. Find a better model for shopify_order and publish it if it wins."
Agent:   designs six variants → create_workflow_experiment → reads the results →
         "Logistic regression on the order's numbers plus Grayson's answers wins: ROC-AUC 0.949 on validation,
          0.930 on test. Publishing it as v6."
```

Kairos is built around [**Grayson**](https://finic.ai), Finic's decision model. You ask it questions in plain language ("Does the shipping address look like a reshipper?", "Is this email throwaway?") and it answers with calibrated probabilities. Decision models are strong where traditional ML is weak:

- **Few labels.** Grayson works on day one, before you have the thousands of chargebacks a model needs to learn from.
- **Unstructured data.** It reads descriptions, emails, names, addresses, notes and item titles, which a gradient-boosted tree can't.
- **Explanations.** Every answer is a question you wrote, so every decision says why.

Traditional models are strong where decision models are weak: they learn your own outcomes precisely, from your own numbers, and they cost nothing per decision. Kairos lets you combine both: Grayson's answers become features next to your fields in a **logistic regression** or **gradient-boosted trees** (XGBoost-compatible, trained in Kairos itself), and experiments tell you which combination wins on your data.

Sign up at [**kairos.finic.ai**](https://kairos.finic.ai). Create a sandbox environment, a secret key, and you're ready to send events.

In the console, open **Settings › MCP**, turn on the tool groups your agent needs, and create a key. Then, in Claude Code:

```
claude mcp add --transport http kairos https://kairos.finic.ai/mcp --header "Authorization: Bearer ksk_…"
```

Cursor, Codex and VS Code work the same way: see [MCP for agents](https://kairos.finic.ai/docs/reference/mcp). Then ask your agent to look at your decisions, build a workflow, or run an experiment.

```
npm install @finic-ai/kairos      # or: pip install finic-kairos
js
import { Kairos } from "@finic-ai/kairos";

const kairos = new Kairos({ apiKey: process.env.KAIROS_API_KEY!, baseUrl: "https://kairos.finic.ai" });

await kairos.defineAction("withdrawal", {
  subject: "user",
  hold: "Should this withdrawal be held because the account shows signs of fraud or takeover?",
});

kairos.track("login", { userId: "user_42", deviceId: "dev_9", ipCountry: "GB" });

const decision = await kairos.decide({ type: "withdrawal", userId: "user_42", usd: 900 });
// { decision: "approve" | "step_up" | "review" | "block", riskScore, reasons, … }
```

You need Node.js 22, pnpm 10 and a Grayson API key from [portal.finic.ai](https://portal.finic.ai/keys). No database to set up: the server starts its own Postgres.

```
pnpm install
cp .env.example .env     # set GRAYSON_API_KEY
pnpm kairos dev          # the API on http://localhost:8787 and the console on http://localhost:5273
```

For your team, `docker compose up --build`. See [Self-hosting](https://github.com/finic-ai/kairos/blob/main/docs/deployment/self-hosting.md) and [Local setup](https://github.com/finic-ai/kairos/blob/main/docs/development/local-setup.md).

## **The CLI**

```
pnpm kairos signup                                                     # the local server, a new account
pnpm kairos login --profile prod --url https://kairos.finic.ai --email you@example.com
pnpm kairos keys create "My server"                                    # a secret key for your code
pnpm kairos actions define withdrawal --data @withdrawal.json
pnpm kairos import events transactions.csv --type transaction --ts created_at --entity user=customer
pnpm kairos decide withdrawal -e user=user_42 -p usd=900
pnpm kairos workflows run review_payout -i user=user_42 --wait
pnpm kairos --help                                                     # every command
```

To have `kairos` on your path, run `pnpm link --global` in `apps/cli`.

- **Shopify:** decide every order, hold risky ones for review, and learn from chargebacks. To get the Kairos app for your store, reach the Finic team on[Discord](https://discord.gg/4zRwRCK6Mx) or at[support@finic.ai](mailto:support@finic.ai) .
- **Inbound webhooks:** take events from providers such as Stripe. See[Inbound webhooks](https://github.com/finic-ai/kairos/blob/main/docs/platform/webhooks/inbound.md) .

The docs are at [kairos.finic.ai/docs](https://kairos.finic.ai/docs), and in [`docs/`](https://github.com/finic-ai/kairos/blob/main/docs/README.md).

| [Overview](https://github.com/finic-ai/kairos/blob/main/docs/getting-started/overview.md) | What Kairos does, how a decision is made, and what it does not do | 
| [Quickstart](https://github.com/finic-ai/kairos/blob/main/docs/getting-started/quickstart.md) | A first decision in a few minutes | 
| [MCP for agents](https://github.com/finic-ai/kairos/blob/main/docs/reference/mcp.md) | Connect Claude Code, Cursor, Codex or VS Code | 
| [Models and experiments](https://github.com/finic-ai/kairos/blob/main/docs/platform/models.md) | Scoring models, and experiments that compare them | 
| [Workflows](https://github.com/finic-ai/kairos/blob/main/docs/platform/workflows.md) | Triggers, steps, expressions and runs | 
| [Concepts](https://github.com/finic-ai/kairos/blob/main/docs/concepts/core-concepts.md) | Entities, events, labels, links, actions, policies, decisions | 
| [Import your history](https://github.com/finic-ai/kairos/blob/main/docs/getting-started/import-history.md) | Load existing events, customers and outcomes from files | 
| [TypeScript SDK](https://github.com/finic-ai/kairos/blob/main/docs/reference/clients/typescript.md) ·[Python SDK](https://github.com/finic-ai/kairos/blob/main/docs/reference/clients/python.md) | The two clients | 
| [API reference](https://github.com/finic-ai/kairos/blob/main/docs/reference/api.md) | Every HTTP endpoint | 
| [Queues and cases](https://github.com/finic-ai/kairos/blob/main/docs/case-management/queues.md) | Review work for people | 
| [Self-hosting](https://github.com/finic-ai/kairos/blob/main/docs/deployment/self-hosting.md) | Docker, Postgres, migrations, configuration, security | 
| [Working on Kairos](https://github.com/finic-ai/kairos/blob/main/docs/development/development.md) | The repository, the server, the tests and the evaluation suite | 

| Path | What it is | 
|---|---|
| `apps/server` | The HTTP API and MCP server. Hono on Node.js, Postgres through Drizzle. | 
| `apps/console` | The web console. React and Vite. | 
| `apps/cli` | `kairos` , the CLI: starts Kairos, connects to a server, and calls its API. | 
| `packages/core` | The decision path, the model scorers and the tree trainer. | 
| `packages/sdk` | `@finic-ai/kairos` , the TypeScript client. | 
| `packages/sdk-python` | `finic-kairos` , the Python client. | 
| `packages/eval` | The evaluation suite and the experiments. | 
| `templates/` | Action definitions and event shapes to copy. | 
| `examples/` | Runnable scenarios, end to end. | 
| `docs/` | The documentation. | 

```
pnpm test         # all tests; no network
pnpm test:python  # the tests of the Python SDK
pnpm typecheck
```

- **Discord:** questions, ideas and show-and-tell, at[discord.gg/4zRwRCK6Mx](https://discord.gg/4zRwRCK6Mx)
- **Email:**[support@finic.ai](mailto:support@finic.ai)
- **Contributing:** issues and pull requests are welcome. Read[Working on Kairos](https://github.com/finic-ai/kairos/blob/main/docs/development/development.md) first.

Kairos is licensed under the [Apache License 2.0](https://github.com/finic-ai/kairos/blob/main/LICENSE).