Kapix Documentation

# Node.js
npm install @kapix/sdk

# Python
pip install kapix-sdk

# Go
go get github.com/kapix/kapix-go

import Kapix from "@kapix/sdk";

const client = new Kapix({
  apiKey: process.env.KAPIX_API_KEY,
  region: "af-west-1", // or "eu-west-1", "us-east-1"
});

const result = await client.credit.score({
  entity_id:   "ent_01HXYZ4A3B",
  entity_type: "individual",
  data_sources: ["bureau", "mobile_money", "transaction_history"],
});

console.log(result.score);        // 0.847
console.log(result.decision);     // "approve"
console.log(result.latency_ms);   // 11

Authorization: Bearer kpx_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

const score = await client.credit.score({
  entity_id:   "ent_01HXYZ4A3B",
  entity_type: "individual",
  data_sources: ["bureau", "mobile_money"],
  context: {
    loan_amount:  500000,   // in minor currency units
    loan_purpose: "working_capital",
    tenure_days:  90,
  },
  explain: true,
});

{
  "score":        0.847,
  "decision":     "approve",
  "confidence":   0.94,
  "risk_band":    "A2",
  "latency_ms":   11,
  "request_id":   "req_01JXYZ9QWE",
  "explanation": {
    "top_features": [
      { "feature": "repayment_consistency", "weight": 0.31, "direction": "positive" },
      { "feature": "mobile_money_velocity", "weight": 0.24, "direction": "positive" },
      { "feature": "bureau_derogatory",     "weight": 0.18, "direction": "negative" }
    ]
  },
  "audit_id": "aud_01JXYZ9QWF"
}

const result = await client.fraud.evaluate({
  transaction_id: "txn_01HABC1234",
  amount:         45000,          // minor currency units
  currency:       "NGN",
  sender_id:      "ent_01HXYZ4A3B",
  receiver_id:    "ent_01HABC5678",
  channel:        "mobile_app",
  metadata: {
    device_fingerprint: "fp_xxxx",
    ip_address:         "102.89.x.x",
    session_age_s:      120,
  },
});

// result.fraud_score  — 0.0 (clean) to 1.0 (definite fraud)
// result.action       — "allow" | "challenge" | "block"
// result.signals      — array of triggered signal names

{
  "fraud_score": 0.07,
  "action":      "allow",
  "confidence":  0.96,
  "signals":     [],
  "latency_ms":  9,
  "request_id":  "req_01JXYZABCD"
}

// Assess a single exposure
const assessment = await client.risk.assess({
  exposure_id:   "exp_01HXYZ0001",
  exposure_type: "loan",
  counterparty:  "ent_01HABC5678",
  amount:        10_000_000,
  currency:      "NGN",
  tenor_days:    180,
});

// result.risk_score     — 0.0 (minimal) to 1.0 (critical)
// result.risk_category  — "low" | "medium" | "high" | "critical"
// result.var_95         — value at risk at 95% confidence
// result.expected_loss  — expected monetary loss

const decision = await client.decisions.run({
  policy_id: "pol_loan_origination_v3",
  inputs: {
    credit_score_id: score.request_id,
    fraud_eval_id:   result.request_id,
    applicant_id:    "ent_01HXYZ4A3B",
    requested_amount: 500000,
  },
  override_window_s: 300, // allow manual override for 5 minutes
});

// decision.outcome   — "approve" | "decline" | "refer"
// decision.reason    — human-readable explanation
// decision.audit_id  — immutable audit record ID

import { createHmac, timingSafeEqual } from "crypto";

function verifyWebhook(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expected = createHmac("sha256", secret)
    .update(payload)
    .digest("hex");

  return timingSafeEqual(
    Buffer.from(signature, "hex"),
    Buffer.from(expected,  "hex")
  );
}

// In your Express/Next.js route:
const sig = req.headers["kapix-signature"] as string;
if (!verifyWebhook(rawBody, sig, process.env.KAPIX_WEBHOOK_SECRET!)) {
  return res.status(401).json({ error: "Invalid signature" });
}

X-RateLimit-Limit:     600
X-RateLimit-Remaining: 594
X-RateLimit-Reset:     1714492800
Retry-After:           12          # only present on 429 responses

{
  "error": {
    "code":    "ENTITY_NOT_FOUND",
    "message": "No entity found with id ent_01HXYZ4A3B",
    "docs":    "https://usekapix.com/docs/errors#ENTITY_NOT_FOUND",
    "request_id": "req_01JXYZ9QWE"
  }
}