Kael API Docs

Score any autonomous AI agent wallet with a single HTTP request. The Known Agent Trust (KAT) Score API returns a structured trust profile — 0 to 100, bond-style grade, five dimension scores, and plain-English reasoning — in milliseconds.

Quick Start

Everything you need in one request. Swap in your API key and any EVM wallet address.

curl -X POST https://kaelai.io/api/v1/score \
  -H 'Authorization: Bearer kael_live_your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{"wallet_address": "0x1a2b3c4d5e6f..."}'

Response:

{
  "wallet_address":      "0x1a2b3c4d5e6f...",
  "overall_score":       78,
  "grade":               "A",
  "confidence":          0.91,
  "dimension_scores": {
    "behavioral_consistency":  17,
    "transaction_legitimacy":  15,
    "wallet_age_and_history":   18,
    "counterparty_quality":     13,
    "volume_stability":         15
  },
  "reasoning":  "Established wallet with 2+ years of consistent on-chain activity.
               Regular interaction patterns with reputable protocols.
               Counterparty quality slightly reduced by two unverified
               contract interactions in Q3. Overall profile is consistent
               with a legitimate autonomous agent.",
  "chain":               "eth",
  "transactions_analysed": 50,
  "cache_hit":           false,
  "timestamp":           "2026-03-26T01:00:00.000000+00:00"
}

Authentication

API keys are passed as Bearer tokens in the Authorization header. Keys follow the format kael_live_[32 chars]. Request a key at hello@kaelai.io with your name and intended use case. Keys are provisioned manually during beta.

Authorization: Bearer kael_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Endpoint Reference

Compute or retrieve a KAT Score for any EVM wallet. Required: wallet_address. Optional: chain (default eth), force_refresh (default false). Results are cached for 24 hours — cache hits return in single-digit milliseconds.

Returns an array of all KAT Score objects for the given wallet address, newest first. Every query — cached or fresh — is permanently logged, making history useful for tracking counterparty interest over time.

Returns trend direction (improving, declining, or stable), the score delta between oldest and newest in the window, and number of data points used.

Returns API status. Use this to verify connectivity before making scoring requests.

{ "status": "ok", "service": "kael" }

Request Parameters

Applies to POST /api/v1/score. Send as a JSON body.

Response Schema

Every successful score response returns the following fields.

Grade Scale

KAT Scores map to a simplified bond-style grade. Use the grade as a quick programmatic trust signal.

Error Responses

All errors return JSON with a detail field describing what went wrong.

{ "detail": "Invalid API key." }

Rate Limits

During beta, rate limits are applied per API key. The default limit is 100 requests per hour. Contact hello@kaelai.io to request higher limits for your use case.

Supported Chains

More chains coming. Contact hello@kaelai.io to request priority support for a specific chain.

Changelog