API Reference

Complete documentation for KaelAi Agent (wallet trust scoring) and KaelAi Shield (DeFi threat detection).

Mode Comparison

mode=agent (default) mode=shield
Purpose Wallet trust scoring for agentic commerce DeFi security threat detection
Output Wallet Trust Score 0-100, grade, reasoning Five-tier action + threat classification
Weight system Equal (20% each dimension) TL 30%, BC 25%, CQ 20%, WA 15%, VS 10%
Billing Base query rate Base + $0.05 Shield PAYG
Registry check No Yes - exploit + trusted registry
Risk flags No 6 Phase 1 flags
Use case x402, Bittensor, agent wallets DeFi protocols, front-ends, security teams
KaelAi Agent

Wallet Trust Scoring

Authentication

All API requests require a Bearer token in the Authorization header. Generate your API key at kaelai.io/signup. The free tier includes 100 queries with no credit card required.

Header 
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
API keys are prefixed with kat_ for identification. Never commit keys to version control. Use environment variables.

POST /api/v1/score

Score a wallet address. Without a mode parameter, defaults to Agent mode - returning a KAT Trust Score, grade, and behavioral breakdown.

Request Body

Field Type Required Description
wallet_address string Yes The wallet address to score
chain string Yes Chain code (eth, sol, btc, tao, base, polygon, bsc, arbitrum, avax, hype)
tx_limit integer No Number of transactions to analyze. Default: 50. Range: 10-100.
force_refresh boolean No Bypass the 24hr cache and re-score. Default: false.

Example Request

curl - Agent Mode 
curl -X POST https://api.kaelai.io/api/v1/score \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_address": "0xYourWalletAddress",
    "chain": "eth"
  }'

Agent Response Schema

Field Type Description
wallet_address string The queried wallet address
chain string The queried chain
scoring_mode string "agent"
overall_score integer KAT Trust Score 0-100 (equal-weight average of all 5 dimensions)
grade string Bond-style grade: AAA, AA, A, BBB, BB, B, CCC
grade_label string Plain-English description of the grade
dimensions object Individual scores for each of the 5 behavioral dimensions
dimensions.transaction_longevity integer TL score 0-100 - wallet age and transaction history depth
dimensions.behavioral_consistency integer BC score 0-100 - pattern stability over time
dimensions.counterparty_quality integer CQ score 0-100 - trustworthiness of interaction network
dimensions.wallet_activity integer WA score 0-100 - depth and breadth of protocol engagement
dimensions.value_stability integer VS score 0-100 - transaction value variance and patterns
recommendation string Plain-English commerce recommendation
cached boolean Whether this result was served from the 24hr cache
scored_at string ISO 8601 timestamp of when this score was computed

Supported Chains

Chain Code Network
EthereumethMainnet
SolanasolMainnet
BitcoinbtcMainnet
BittensortaoMainnet
BasebaseMainnet
PolygonpolygonMainnet
BNB Smart ChainbscMainnet
ArbitrumarbitrumOne
AvalancheavaxC-Chain
HyperliquidhypeMainnet

Score History & Trends

Retrieve historical scores and trend data for a wallet address using the history endpoint.

GET /api/v1/score/history

curl - Score History 
curl -G https://api.kaelai.io/api/v1/score/history \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "wallet_address=0xYourWalletAddress" \
  --data-urlencode "chain=eth" \
  --data-urlencode "limit=10"

Returns an array of historical score records, each containing overall_score, grade, dimensions, and scored_at. Useful for tracking behavioral drift or establishing trust over time.

KaelAi Shield

DeFi Threat Detection

POST /api/v1/score (Shield Mode)

Same endpoint as Agent mode. Add "mode": "shield" to activate threat detection. Shield mode applies threat-optimized dimension weighting, runs exploit registry checks, evaluates 6 behavioral flags, and returns a five-tier action recommendation.

Shield queries are billed at your base tier rate plus a $0.05 Shield PAYG charge per query. This covers exploit registry lookups and enhanced analysis.

Shield Request Parameters

Field Type Required Description
wallet_address string Yes The wallet address to score
chain string Yes Chain code (see supported chains)
mode string Required for Shield Set to "shield" to activate threat detection mode
tx_limit integer No Transactions to analyze. Default: 50. Range: 10-100.
force_refresh boolean No Bypass 24hr cache. Default: false. Recommended for live security decisions.

Example Request

curl - Shield Mode 
curl -X POST https://api.kaelai.io/api/v1/score \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_address": "0xSuspiciousWalletAddress",
    "chain": "eth",
    "mode": "shield",
    "force_refresh": true
  }'

Shield Response Schema

Field Type Description
scoring_mode string "shield"
overall_score integer Shield-weighted score 0-100 (TL 30%, BC 25%, CQ 20%, WA 15%, VS 10%)
grade string Bond grade: AAA, AA, A, BBB, BB, B, CCC
threat_classification string confirmed_exploit_wallet / mixer_funded / draining_address / suspicious_pattern / low_protocol_engagement / clean / verified_good_actor
threat_confidence float 0.0-1.0 confidence in the threat classification. Registry matches always 0.99.
shield_flags array List of triggered Phase 1 behavioral flags (empty array if none)
registry_checked boolean Always true in shield mode
registry_match object / null Registry data if matched. Includes registry_type (threat/trusted), incident_name, role, amount_usd. Null if no match.
recommended_action string block / flag / review / monitor / allow
recommended_action_label string Plain-English explanation of the recommended action and reasoning
alert_severity string critical / high / medium / low / none
billing.shield_query_charge float $0.05 per shield query, billed in addition to base tier rate

Shield Response Example

JSON - Registry Match (BLOCK) 
{
  "scoring_mode":          "shield",
  "overall_score":         22,
  "grade":                 "CCC",
  "threat_classification": "confirmed_exploit_wallet",
  "threat_confidence":     0.99,
  "shield_flags": [
    "receive_only_pattern",
    "zero_known_protocol_ratio"
  ],
  "registry_checked": true,
  "registry_match": {
    "matched":       true,
    "registry_type": "threat",
    "incident_name": "Drift Protocol Exploit",
    "incident_date": "2026-04-01",
    "role":          "attacker",
    "amount_usd":    285000000
  },
  "recommended_action":       "block",
  "recommended_action_label": "REGISTRY MATCH — confirmed attacker wallet from Drift Protocol Exploit ($285M). Block immediately.",
  "alert_severity":           "critical",
  "billing": {
    "shield_query_charge": 0.05
  }
}

Phase 1 Threat Flags

Flag Trigger Condition Severity
receive_only_pattern 0% outbound transactions in sampled history Critical
zero_known_protocol_ratio Zero interaction with verified DeFi protocols despite contract activity Critical
tornado_cash_funded Direct or indirect funding from Tornado Cash or confirmed mixer addresses High
value_spike_anomaly Max/mean transaction value ratio exceeds 50× High
counterparty_concentration Single counterparty accounts for ≥70% of total transaction volume Medium
failed_tx_anomaly ≥15% of sampled transactions failed (error state) Low

Five-Tier Action Reference

Tier recommended_action Score Range alert_severity What to do
BLOCK block 0-14 or registry match critical Reject interaction immediately
FLAG flag 15-24 high Manual review before any interaction
REVIEW review 25-49 medium Human review recommended
MONITOR monitor 50-69 low Allow with monitoring
ALLOW allow 70-100 or trusted registry none Proceed normally
Registry matches override score thresholds. A wallet in the threat registry always returns block regardless of behavioral score. A wallet in the trusted registry always returns allow.