Get an allow / caution / block decision for a wallet
The core pre-transaction check: returns a verdict (allow, caution,
block) for the wallet under a use case, with a recommended USDC limit,
reason codes, advisory warnings, the evidence used and missing, freshness
metadata and data-coverage notes. The read is deterministic and
side-effect-free: it never triggers indexing or provider scans.
A valid wallet that Kyro has not indexed yet still answers 200 with a
conservative baseline verdict; freshness.cacheStatus is
indexing_required and the verdict must not be treated as evidence about
the counterparty. Only freshness.cacheStatus of cached means the
verdict rests on a committed score snapshot. Costs 1 rate unit.
Authorization
bearerApiKey Optional Kyro API key: Authorization: Bearer kyro_live_.... Anonymous
access (no header) works on every endpoint with a lower rate limit
(20 units/minute per IP vs 120 units/minute per key). Keys are validated
only when the header is present; a malformed, unknown or revoked key is
rejected with 401 INVALID_KEY.
In: header
Path Parameters
EVM wallet address. 0x + 40 hex characters (case-insensitive).
^0x[a-fA-F0-9]{40}$Query Parameters
What the caller is about to do with this counterparty. Defaults to payment.
"payment"Value in
- "payment"
- "escrow"
- "lending"
- "marketplace"
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/api/v1/decision/0xd8da6bf26964af9d7eed9e03e53415d37aa96045"{ "ok": true, "version": "v1", "data": { "wallet": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045", "username": null, "useCase": "payment", "decision": "caution", "riskLevel": "Trusted", "recommendedLimit": { "amountUsdc": 50, "currency": "USDC", "basis": "Caution band for payment (v0 conservative limits)." }, "reasons": [ { "code": "KYRO_TRUST_GRAPH_MISSING", "message": "This wallet has no Kyro-native relationship evidence yet. No verified peers or attestations on Kyro." }, { "code": "DATA_LIMITED", "message": "Wallet intelligence coverage is limited, partial or not indexed yet." } ], "warnings": [ { "code": "DATA_PROVIDER_TRANSIENT", "message": "Chain scans hit temporary provider failures on Base during the last refresh." }, { "code": "DATA_HISTORY_CAPPED", "message": "Provider history on Ethereum Mainnet, Arbitrum, Polygon is capped to the oldest rows." } ], "score": 79, "evidence": { "used": [ "score", "riskLevel", "riskPenalty", "scoreModelVersion", "globalWalletAgeDays", "cacheStatus", "intelligenceStatus", "refreshInProgress", "refreshRecommended", "lastIndexedAt" ], "missing": [ "trustGraph", "trustGraph.trustConfidence" ] }, "freshness": { "cacheStatus": "cached", "lastIndexedAt": "2026-08-11T13:36:05.979Z", "refreshInProgress": false, "refreshRecommended": false }, "coverage": { "chains": [ { "chain": "Ethereum Mainnet", "status": "indexed", "transient": false, "standing": false, "historyCapped": true, "recencyReliable": false }, { "chain": "Base", "status": "error", "transient": true, "standing": false, "historyCapped": null, "recencyReliable": null }, { "chain": "BNB Chain", "status": "limited", "transient": false, "standing": true, "historyCapped": null, "recencyReliable": null }, { "chain": "Arc Testnet", "status": "indexed", "transient": false, "standing": false, "historyCapped": null, "recencyReliable": null } ], "historyCapped": true, "hasTransientIssues": true, "hasStandingLimitations": true }, "scoreModelVersion": "identity_score_v1", "decisionModelVersion": "decision_v0.4.1" }}