Kynes Scoring API

Risk scores for AI agents that borrow

Kynes gives lenders an instant, explainable risk score for AI agents that apply for loans. You send what you know about the agent and the loan, and Kynes returns two 0–1000 risk scores with risk grades K1 (lowest risk) to K8 (highest risk), non-binding guidance, a suggested maximum loan, and plain-English reasons. It is a risk score, not a credit rating, and the lending decision is always yours.

POSThttps://kynes-api.onrender.com/v1/score
Example agent: 576 (K5)
K8
K7
K6
K5
K4
K3
K2
K1
0Higher riskLower risk1000
Decline0–499
Review500–699
Approve700–1000
Every score maps to a risk grade and non-binding guidance. The lender always makes the decision.

1. Get an API key

Email samualbrusky@gmail.com to request keys. You'll get two:

Key Looks like What it does
Test kyn_test_... Scores normally, stores nothing. Use it while you build.
Live kyn_live_... Scores and stores the result, so you can report outcomes later.

Send the key on every request as Authorization: Bearer <key>. Keep it on your server; never put it in a browser or mobile app. The API is server-to-server only (no CORS).

2. Your first score

These examples score a real synthetic agent: registry-verified, verified company owner, 60-day-old wallet, about $5,000 a month of income, no loan history, asking for $2,000 for 30 days.

curl

export KYNES_KEY="kyn_test_..."   # your key

curl -s https://kynes-api.onrender.com/v1/score \
  -H "Authorization: Bearer $KYNES_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent":{"agent_id":"solid_new_verified","identity_verification":"registry_verified","owner_type":"company","owner_verified":true,"owner_guarantee_usd":0,"deployment_age_days":60},"onchain":{"wallet_age_days":60,"tx_count_90d":120,"unique_counterparties_90d":40,"self_transfer_ratio_90d":0.05,"monthly_inflow_usd":[4800,5200],"largest_single_inflow_share_90d":0.3,"inflow_last_7d_usd":1200,"defi_liquidations_count":0,"mixer_exposure":false,"sanctions_hit":false,"fraud_flag":false},"credit_history":{"source":"lender_reported","prior_loans":[]},"controls":{"collateral":[],"spending_limit_configured":true,"lender_can_auto_collect":true,"kill_switch_available":true},"loan":{"amount_usd":2000,"term_days":30,"currency":"USDC","application_id":"demo-0001"}}'

Python (pip install requests)

import os, requests

application = {
    "agent": {"agent_id": "solid_new_verified", "identity_verification": "registry_verified",
              "owner_type": "company", "owner_verified": True, "owner_guarantee_usd": 0, "deployment_age_days": 60},
    "onchain": {"wallet_age_days": 60, "tx_count_90d": 120, "unique_counterparties_90d": 40,
                "self_transfer_ratio_90d": 0.05, "monthly_inflow_usd": [4800, 5200],
                "largest_single_inflow_share_90d": 0.3, "inflow_last_7d_usd": 1200, "defi_liquidations_count": 0,
                "mixer_exposure": False, "sanctions_hit": False, "fraud_flag": False},
    "credit_history": {"source": "lender_reported", "prior_loans": []},
    "controls": {"collateral": [], "spending_limit_configured": True, "lender_can_auto_collect": True,
                 "kill_switch_available": True},
    "loan": {"amount_usd": 2000, "term_days": 30, "currency": "USDC", "application_id": "demo-0001"},
}

r = requests.post("https://kynes-api.onrender.com/v1/score", json=application, timeout=10,
                  headers={"Authorization": f"Bearer {os.environ['KYNES_KEY']}"})
r.raise_for_status()
result = r.json()
print(result["score"], result["grade"], result["guidance"], result["agent_grade"])

JavaScript (Node 18+, server-side)

const application = {
  agent: { agent_id: "solid_new_verified", identity_verification: "registry_verified", owner_type: "company",
           owner_verified: true, owner_guarantee_usd: 0, deployment_age_days: 60 },
  onchain: { wallet_age_days: 60, tx_count_90d: 120, unique_counterparties_90d: 40, self_transfer_ratio_90d: 0.05,
             monthly_inflow_usd: [4800, 5200], largest_single_inflow_share_90d: 0.3, inflow_last_7d_usd: 1200,
             defi_liquidations_count: 0, mixer_exposure: false, sanctions_hit: false, fraud_flag: false },
  credit_history: { source: "lender_reported", prior_loans: [] },
  controls: { collateral: [], spending_limit_configured: true, lender_can_auto_collect: true, kill_switch_available: true },
  loan: { amount_usd: 2000, term_days: 30, currency: "USDC", application_id: "demo-0001" },
};

const res = await fetch("https://kynes-api.onrender.com/v1/score", {
  method: "POST",
  headers: { "Authorization": `Bearer ${process.env.KYNES_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify(application),
});
const result = await res.json();
if (!res.ok) throw new Error(`${result.error.code}: ${result.error.message} (${result.error.field})`);
console.log(result.score, result.grade, result.guidance, result.agent_grade);

You should get back (shortened):

{
  "score": 576, "grade": "K5",
  "agent_score": 632, "agent_grade": "K4",
  "guidance": "review",
  "guidance_note": "Non-binding guidance. The lender makes the final lending decision.",
  "confidence": "medium",
  "suggested_max_loan_usd": 894.0, "target_grade": "K4",
  "reason_codes": {
    "negative": [
      {"code": "THIN_HISTORY", "factor": "repayment_history", "impact_points": -132, "applies_to": "both",
       "message": "The agent has little or no record of repaying loans."},
      {"code": "NO_COLLATERAL", "factor": "controls_collateral", "impact_points": -108, "applies_to": "loan",
       "message": "No collateral is posted for this loan."}
    ],
    "positive": [
      {"code": "VERIFIED_IDENTITY", "factor": "identity", "impact_points": 193, "applies_to": "both",
       "message": "The agent's identity is verified by a signed credential or a registry."}
    ]
  },
  "agent_reason_codes": {"negative": ["..."], "positive": ["..."]},
  "breakdown": {"...": "every point lost, by factor and reason code"},
  "warnings": [],
  "model_version": "kynes-v1.0",
  "input_hash": "sha256:771a04f9...",
  "application_id": "demo-0001",
  "request_id": "req_...",
  "api_version": "v1"
}

Only three fields are required: agent.agent_id, loan.amount_usd (> 0) and loan.term_days (> 0). Everything else is optional, and leaving a field out never causes an error: it's scored conservatively. Sending a field incorrectly does cause an error (see section 6), so typos don't silently change a score.

3. How to read the result

4. Report what happened (outcomes)

When a loan you scored with a live key resolves, tell Kynes. Match it with the application_id you sent (preferred) or the input_hash you got back.

curl -s https://kynes-api.onrender.com/v1/outcomes \
  -H "Authorization: Bearer $KYNES_KEY" \
  -H "Content-Type: application/json" \
  -d '{"application_id":"demo-0001","outcome":"repaid_on_time","days_late":0,"resolved_at":"2026-12-16","amount_repaid_usd":2016.40}'
Field Required Values
application_id or input_hash one of them from your score request / response
outcome yes repaid_on_time, repaid_late, defaulted, charged_off, still_active
days_late yes most days late at any point; 0 if never late (must be > 0 for repaid_late)
resolved_at yes, unless still_active ISO date, e.g. 2026-12-16
amount_repaid_usd no total repaid in USD

5. Batch scoring

Send up to 100 applications in one request: POST /v1/score/batch with body {"applications": [ ... ]}. Results come back in the same order. If one item is invalid, its slot holds an error object with the field path (e.g. applications[3].loan.amount_usd) and the rest are still scored.

6. Limits, errors and versioning

json {"error": {"code": "out_of_range", "message": "Value -10 is out of range; it must be at least 0.", "field": "onchain.wallet_age_days", "request_id": "req_..."}}

Status Code(s) Meaning
401 missing_api_key, invalid_api_key No key, or the key is unknown or revoked
404 score_not_found Outcome doesn't match a score you made with a live key
422 missing_field, invalid_value, out_of_range, unknown_field, personal_data_not_accepted, invalid_operator_id, invalid_json, batch_too_large Fix the named field and retry
429 rate_limited Wait Retry-After seconds

7. How Kynes uses your data


v1 is an expert-weighted scorecard. Nobody has repayment data on AI agents yet, so its weights reflect lending judgment, not statistical fitting, and Kynes publishes no default-probability numbers until real outcome data supports them. Methodology: see the published METHODOLOGY in the Kynes repository.