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 supported wallet address.

import requests

# Before transacting with an unknown agent
response = requests.post(
    'https://kaelai.io/api/v1/score',
    headers={'Authorization': 'Bearer kael_live_your_key'},
    json={'wallet_address': '0x742d...', 'chain': 'eth'}
)

score = response.json()

if score['overall_score'] >= 60:
    proceed_with_transaction()
elif score['overall_score'] >= 35:
    proceed_with_reduced_limits()
else:
    flag_for_review()

// Before transacting with an unknown agent
const response = await fetch('https://kaelai.io/api/v1/score', {
    method:  'POST',
    headers: {
        'Authorization': 'Bearer kael_live_your_key',
        'Content-Type':  'application/json'
    },
    body: JSON.stringify({
        wallet_address: '0x742d...',
        chain:          'eth'
    })
});

const score = await response.json();

if (score.overall_score >= 60) {
    proceedWithTransaction();
} else if (score.overall_score >= 35) {
    proceedWithReducedLimits();
} else {
    flagForReview();
}

# Score a wallet before transacting
curl -X POST https://kaelai.io/api/v1/score \
  -H 'Authorization: Bearer kael_live_your_key' \
  -H 'Content-Type: application/json' \
  -d '{"wallet_address": "0x742d...", "chain": "eth"}'

# Returns immediately — use the score in your logic
# overall_score >= 60  → proceed
# overall_score 35–59  → proceed with caution
# overall_score < 35   → flag for review

Response:

{
  "wallet_address":      "0x1a2b3c4d5e6f...",
  "overall_score":       78,
  "grade":               "A",
  "confidence":          0.91,
  "wallet_type":         "autonomous_agent",
  "risk_flag":           "low_agent_fit",
  "risk_flag_label":     "No suspicious activity detected...",
  "recommended_action":  "proceed",
  "recommended_action_label": "No suspicious activity detected. Safe to proceed based on your own risk tolerance.",
  "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]. Get a key instantly at kaelai.io — self-serve, no waitlist.

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 us to request higher limits for your use case.

Supported Chains

Pricing

Simple, transparent pricing. Start free — pay only for what you use.

Free to Start

Pay As You Go — $0.010 per query

Pricing is in USD. Pay As You Go usage invoiced monthly via Stripe. No subscriptions currently active.

How billing works

Kael is designed to be frictionless to start and easy to scale. Here's how the transition from free to paid works.

Free tier

Every new account includes 100 free KAT Score queries. No credit card required. Queries never expire — use them at your own pace during evaluation and integration.

Running low

When you reach 20 queries remaining you will receive an email notification with a direct link to add a payment method. No action required to keep using your free allocation.

Grace period

When your free queries are exhausted your account enters a 7-day grace period with 50 additional queries included. This gives you time to add a payment method without interrupting an active integration — no code changes required.

Pay As You Go activation

Add a payment method at kaelai.io/billing before your grace period ends. Your account reactivates immediately. Queries are billed at $0.010 each, invoiced monthly via Stripe. No subscription, no minimum spend, no commitment.

If the grace period expires

If no payment method is added before the grace period ends your API key is paused and all requests return HTTP 402. Add a payment method at kaelai.io/billing at any time to reactivate instantly — no support ticket required.

Changelog