Integrate any AI agent with Kakunin in under 15 minutes. Cryptographic identity, behavioral monitoring, and compliance-ready audit trails.

AI Agent Quickstart

Kakunin gives your AI agent a cryptographic identity, behavioral risk score, and immutable audit trail — everything regulators require under MiCA and EU AI Act.

Integration takes 3 steps: register → certify → log events. Under 15 minutes from zero to a monitored agent.

Prompt Handover

Copy this prompt into any AI coding agent (Claude Code, Cursor, Copilot) to build the integration from scratch:

You are integrating an AI agent with Kakunin — a KYC compliance platform for AI agents.

Base URL: https://kakunin.ai/api/v1
Auth: Bearer token — set KAKUNIN_API_KEY env var
Docs: https://kakunin.ai/docs/api-reference

Complete these 3 steps:

1. Register the agent:
POST /agents
Body: { name, model_hash, model, version, permitted_actions[] }
Save the returned agent.id

2. Issue X.509 certificate:
POST /agents/{id}/certify
Returns: { certificate_pem, serial_number, expires_at }
Store cert_pem for mTLS — it expires in 365 days

3. Log behavioral events (call after every significant action):
POST /events
Body: { agent_id, action_type, metadata }
action_type options: data_access | trade_execution | authentication | report_generation | user_interaction | api_call | model_inference | data_mutation

Test against sandbox first:
- Base URL: https://kakunin-git-staging-immortalpilot365-5309s-projects.vercel.app/api/v1
- Generate sandbox key: POST /api-keys/sandbox (returns kkn_sandbox_* key)
- Sandbox data auto-deletes after 7 days, no billing

MCP alternative (Node.js only):
npx @kakunin/mcp with env: KAKUNIN_API_KEY + KAKUNIN_AGENT_ID
Tools: verify_agent_scope, check_risk_score, audit_log_append

Pick Your Path

Node.js / TypeScript — SDK

npm install @kakunin/sdk

import { Kakunin } from '@kakunin/sdk';

const kkn = new Kakunin({ apiKey: process.env.KAKUNIN_API_KEY! });

// 1. Register
const agent = await kkn.agents.create({
  name: 'My Trading Bot v1.0',
  model_hash: await Kakunin.computeModelHash('gpt-4o-2024-08'),
  model: 'gpt-4o',
  version: 'v1.0.0',
  permitted_actions: ['trade_execution', 'data_access'],
});

// 2. Certify
const cert = await kkn.agents.certify(agent.id);
console.log(cert.serial_number);

// 3. Log events
await kkn.events.ingest({
  agent_id: agent.id,
  action_type: 'trade_execution',
  metadata: { symbol: 'BTC/USDT', side: 'buy', amount_usd: 5000 },
});

Python — REST API

import os, hashlib, requests

BASE = "https://kakunin.ai/api/v1"
HEADERS = {
    "Authorization": f"Bearer {os.environ['KAKUNIN_API_KEY']}",
    "Content-Type": "application/json",
}

# 1. Register
agent = requests.post(f"{BASE}/agents", json={
    "name": "My Python Bot v1.0",
    "model": "gpt-4o",
    "version": "v1.0.0",
    "permitted_actions": ["data_access", "report_generation"],
}, headers=HEADERS).json()["data"]

# 2. Certify
cert = requests.post(f"{BASE}/agents/{agent['id']}/certify",
    headers=HEADERS).json()["data"]

# 3. Log event
requests.post(f"{BASE}/events", json={
    "agent_id": agent["id"],
    "action_type": "data_access",
    "metadata": {"resource": "customer_records", "count": 42},
}, headers=HEADERS)

Any Runtime — REST

# 1. Register
curl -X POST https://kakunin.ai/api/v1/agents \
  -H "Authorization: Bearer $KAKUNIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"My Agent","model":"gpt-4o","version":"v1.0.0","permitted_actions":["data_access"]}'

# 2. Certify (use returned agent id)
curl -X POST https://kakunin.ai/api/v1/agents/$AGENT_ID/certify \
  -H "Authorization: Bearer $KAKUNIN_API_KEY"

# 3. Log event
curl -X POST https://kakunin.ai/api/v1/events \
  -H "Authorization: Bearer $KAKUNIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"$AGENT_ID","action_type":"data_access","metadata":{}}'

Action Types

`action_type`	When to use
`data_access`	Agent reads customer records, databases, files
`trade_execution`	Agent places orders, transfers funds
`authentication`	Agent logs in, verifies identity
`report_generation`	Agent produces compliance or analytical output
`user_interaction`	Agent sends message, takes user-facing action
`api_call`	Agent calls external API
`model_inference`	Agent runs a model call
`data_mutation`	Agent creates, updates, or deletes records

Log every significant action. Kakunin computes a rolling 30-day risk score — missing events skew the score.

Risk Scores

After logging events, check risk band:

const { risk_score, risk_band } = await kkn.agents.getRiskScore(agent.id);
// risk_band: 'low' | 'medium' | 'high'
// risk_score: 0.0 – 1.0

Band	Score	Action
low	< 0.3	Continue operating normally
medium	0.3 – 0.75	Review unusual patterns
high	≥ 0.75	Pre-revocation warning sent; address immediately

Score ≥ 0.85 triggers auto-revocation check.

MCP Integration (Node.js)

If your agent uses the Model Context Protocol, skip the SDK and use @kakunin/mcp instead:

npm install @kakunin/mcp
# or: npx @kakunin/mcp (no install needed)

Three tools available: verify_agent_scope, check_risk_score, audit_log_append.

→ See MCP Server docs for full reference.

Test in Sandbox First

Before using production keys:

# 1. Generate sandbox key (via dashboard or API)
curl -X POST https://kakunin-git-staging-immortalpilot365-5309s-projects.vercel.app/api/v1/api-keys/sandbox \
  -H "Authorization: Bearer $KAKUNIN_API_KEY"

# 2. Use kkn_sandbox_* key with staging URL
export KAKUNIN_API_KEY=kkn_sandbox_...
export KAKUNIN_BASE_URL=https://kakunin-git-staging-immortalpilot365-5309s-projects.vercel.app/api/v1

Sandbox data auto-deletes after 7 days. Reset manually: POST /api/internal/sandbox/reset.

→ See Sandbox docs for full reference.

Reference Implementations

Agent	Pattern	Language
HTTP tool-using agent	Full lifecycle test (register → certify → events → risk)	TypeScript
Event harness	100+ events, throughput test	TypeScript
Discord bot	Interactive slash commands	TypeScript
Freqtrade bot	Python trading bot integration	Python

→ Run locally: npm run agent:http-tool · npm run agent:event-harness · npm run agent:discord

→ See Freqtrade integration guide for the Python trading bot pattern.

Checklist Before Going Live

Agent registered with accurate permitted_actions
X.509 certificate issued and stored
Events logged for all action types your agent performs
Risk score checked after each session
Webhook configured for certificate.revoked alerts
Sandbox smoke test passed (all 3 steps green)

Next: API Reference · MCP Server · Sandbox · Freqtrade Guide

AI Agent Quickstart

On this page