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
score/grade: the loan risk score. It covers the agent plus this loan's collateral, controls, owner guarantee and size. Approve on this one.agent_score/agent_grade: the agent risk score. This is the agent's own behaviour only (identity, repayment record, earned income, activity). It ignores collateral, guarantees and loan size, so it's the same for any loan the agent asks for. A fully secured agent with no track record can get a good loan grade but an ordinary agent grade.- Grades: K1 900–1000, K2 800–899, K3 700–799 →
approve; K4 600–699, K5 500–599 →review; K6 400–499, K7 300–399, K8 0–299 →decline. guidanceis non-binding. It's a suggestion based on the loan grade. Your credit policy makes the decision.confidence(high/medium/low) shows how much data the score rests on. A decent score with low confidence means "probably fine, but we don't know much yet". Confidence never changes the score.suggested_max_loan_usdis the largest amount at this term that would still reachtarget_grade(K4 by default). It isnullif no amount qualifies. Here, $894 or less would grade K4.- Reason codes:
reason_codesexplains the loan score andagent_reason_codesexplains the agent score. negativelists any knock-outs and caps first, then the biggest reasons the score isn't higher.positivelists the biggest strengths.impact_pointsis the effect on the 0–1000 score.- Codes are stable: they are never renamed or reused. The full list with messages is at
GET /v1/model. breakdownaccounts for every point each factor lost.warningslists anything that was missing or assumed.model_versionandinput_hashlet you audit exactly which model scored exactly which input. Keep them with your loan record.
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 |
- The response is
201and shows which of your scores the outcome was matched to. - You'll get a
404if no score made with your live key matches. - Reporting again for the same loan (for example
still_activeand laterrepaid_late) adds a new record. The latest one counts and nothing is overwritten. - With a test key the report is checked and nothing is stored (
"stored": false).
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
- Rate limit: 60 requests per minute per key (ask if you need more). A batch counts as one request. Over the limit you get
429with aRetry-Afterheader (seconds). - Errors always look like this.
fieldis the exact path of the problem, andrequest_idis what to quote if you contact us:
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 |
- No personal data. Kynes scores agents and their owners as entities. Don't send names, emails, SSNs, personal credit scores or other personal data. Requests containing such fields are rejected. An operator is identified only by a SHA-256 hash.
- Versioning:
- Every response carries
model_version(the scoring model, e.g.kynes-v1.0) andapi_version(v1). They're also in theX-Kynes-Model-VersionandX-Kynes-Api-Versionheaders. - The same input and model version always give the same score.
- A new model version will be announced in advance and shown in
model_version. The/v1/URLs won't change in ways that break your integration. - HTTPS only. Plain HTTP requests are refused.
7. How Kynes uses your data
- Scores: scores made with a live key are stored, append-only, as Kynes's record of what it said and when. Stored records are never edited or deleted.
- Outcomes: outcome data you report is used to measure and improve the Kynes model. It is not shared with other lenders and never changes another lender's scores. Each outcome is tagged with the lender that reported it.
- Test keys: test-key requests store nothing.
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.