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

Kairos 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: 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: ask a decision model, score with a model, branch, call webhooks, open cases, and decide again later.

Queues and cases: review work for people, whose resolutions become labels.

Agent-first

MCP server: Claude Code, Cursor or Codex read your decisions and build workflows, with every action recorded under its key.

Experiments: your agent proposes model variants, Kairos trains and tests them on your data, and the agent ships the winner.

Decision models and traditional ML

Grayson: Finic's decision model answers questions about each request in plain language. It works with few labels and reads unstructured data.

Models: logistic regression and gradient-boosted trees (XGBoost-compatible) on your numbers and Grayson's answers, trained in Kairos or uploaded.

For developers

SDKs for TypeScript (@finic-ai/kairos) and Python (finic-kairos), a CLI, an HTTP API, and self-hosting with Docker.

An AI fraud ML engineer, always tuning on your data

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:

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."

Decision models and traditional ML, together

Kairos is built around Grayson, 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:

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.

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. 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

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, … }

Self-host

You need Node.js 22, pnpm 10 and a Grayson API key from portal.finic.ai. 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 and Local setup.

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 or at support@finic.ai.

Inbound webhooks: take events from providers such as Stripe. See Inbound webhooks.

Documentation

The docs are at kairos.finic.ai/docs, and in docs/.

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

Community

Discord: questions, ideas and show-and-tell, at discord.gg/4zRwRCK6Mx

Email: support@finic.ai

Contributing: issues and pull requests are welcome. Read Working on Kairos first.

License

Kairos is licensed under the Apache License 2.0.