Skip to main content

Kixago API Documentation

Real-time DeFi credit scoring and risk analysis API

Get complete portfolio analysis across all major DeFi protocols and chains in a single API call.

What This API Returns​

DataResponse TimeCoverage
DeFi Credit Score (300-850)1-4 secondsAave V2/V3, Compound V2/V3, MakerDAO
Complete lending positionsCached: <100msEthereum, Base, Arbitrum, Polygon
Liquidation scenariosToken-level collateral/debt breakdown
Risk factors + recommendationsReal-time on-chain data (30s cache)

Quick Example​

Request​

curl -H "X-API-Key: your_api_key" \
  "[https://api.kixago.com/v1/risk-profile/0xf0bb20865277aBd641a307eCe5Ee04E79073416C](https://api.kixago.com/v1/risk-profile/0xf0bb20865277aBd641a307eCe5Ee04E79073416C)"

Response (excerpt)​

{
  "wallet_address": "0xf0bb20865277aBd641a307eCe5Ee04E79073416C",
  "total_collateral_usd": 2175957718.47,
  "total_borrowed_usd": 1905081695.88,
  "global_health_factor": 1.067,
  "global_ltv": 89.02,
  "positions_at_risk_count": 2,
  "defi_score": {
    "defi_score": 467,
    "risk_level": "High Risk",
    "risk_category": "HIGH_RISK",
    "risk_factors": [
      {
        "severity": "critical",
        "factor": "Imminent Liquidation Risk",
        "description": "Health factor 1.067 means position will be liquidated if collateral value drops 6.7%"
      }
    ],
    "recommendations": {
      "immediate": [
        "🚨 URGENT: Deposit $387M more collateral OR repay debt to raise health factor above 1.5"
      ]
    },
    "liquidation_simulation": {
      "scenarios": [
        {
          "event": "Collateral drops 10%",
          "new_health_factor": 0.961,
          "status": "LIQUIDATED",
          "estimated_loss": "~$218M in liquidation penalties"
        }
      ]
    }
  },
  "lending_positions": [
    {
      "protocol": "Aave",
      "protocol_version": "V3",
      "chain": "Ethereum",
      "collateral_usd": 2112215608.12,
      "borrowed_usd": 1884925796.26,
      "health_factor": 1.065,
      "ltv_current": 89.24,
      "is_at_risk": true,
      "collateral_details": [
        {
          "token": "weETH",
          "amount": 496800.01,
          "usd_value": 2112215608.12,
          "token_address": "0xCd5fE23C85820F7B72D0926FC9b05b43E359b7ee"
        }
      ],
      "borrowed_details": [
        {
          "token": "WETH",
          "amount": 478632.98,
          "usd_value": 1884925796.26,
          "token_address": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"
        }
      ]
    }
  ]
}

Core Endpoints​

EndpointMethodAuthPurpose
/v1/risk-profile/{wallet}GETRequiredComplete portfolio + credit score
/healthGETNoneAPI status check

View full endpoint documentation →

DeFi Credit Score (300-850)​

FICO-style scoring for DeFi lending positions

Score Ranges​

ScoreRisk LevelDescription
750-850Very Low RiskHealthy positions, low leverage
650-749Low RiskConservative borrowing
550-649Medium RiskModerate leverage
450-549High RiskApproaching danger zone
300-449Very High RiskImminent liquidation risk

Scoring Formula​

The score is calculated from 5 weighted components:

ComponentWeightMeasures
Health Factor40%Proximity to liquidation
Leverage (LTV)30%Debt-to-collateral ratio
Diversification15%Concentration risk (assets + protocols)
Volatility Exposure10%Collateral asset risk
Protocol Risk5%Smart contract maturity
Internal Score  (0−100)=∑(Component Score×Weight)\text{Internal Score} \; (0-100) = \sum (\text{Component Score} \times \text{Weight}) Final Score=(Internal Score×5.5)+300\text{Final Score} = (\text{Internal Score} \times 5.5) + 300

Example calculation for the whale wallet above:​

ComponentCalculationWeighted Score
Health Factor Score20/100×0.4020/100 \times 0.408.08.0
Leverage Score20/100×0.3020/100 \times 0.306.06.0
Diversification Score45/100×0.1545/100 \times 0.156.756.75
Volatility Score50/100×0.1050/100 \times 0.105.05.0
Protocol Risk Score95/100×0.0595/100 \times 0.054.754.75
Total Internal Score30.530.5
$$[Complete scoring methodology →](/docs/api/understand-responses/defi-score-explained) ----- ## Response Structure Every response includes: ### 1\. Portfolio Summary (Top-Level) ```json { "wallet_address": "0x...", "total_collateral_usd": 2175957718.47, "total_borrowed_usd": 1905081695.88, "global_health_factor": 1.067, "global_ltv": 89.02, "positions_at_risk_count": 2, "last_updated": "2025-10-21T04:19:25Z", "aggregation_duration": "1.234s" } ``` ### 2\. Lending Positions (Per Protocol/Chain) ```json { "lending_positions": [ { "protocol": "Aave", "protocol_version": "V3", "chain": "Ethereum", "collateral_usd": 2112215608.12, "borrowed_usd": 1884925796.26, "health_factor": 1.065, "ltv_current": 89.24, "is_at_risk": true, "collateral_details": [ /* token breakdown */ ], "borrowed_details": [ /* token breakdown */ ] } ] } ``` ### 3\. DeFi Credit Score ```json { "defi_score": { "defi_score": 467, "risk_level": "High Risk", "risk_category": "HIGH_RISK", "score_breakdown": { /* 5 components */ }, "risk_factors": [ /* critical issues */ ], "recommendations": { /* immediate/short/long-term */ }, "liquidation_simulation": { /* what-if scenarios */ } } } ``` ### 4\. Partial Failures (Non-Fatal) ```json { "aggregation_errors": { "CompoundV3:Ethereum": "could not get numAssets from Compound V3 market" } } ``` **Important:** Protocol errors don't fail the entire request. You still get data from working protocols. ----- ## Authentication All endpoints (except `/health`) require an API key: ```bash curl -H "X-API-Key: your_api_key" \ "[https://api.kixago.com/v1/risk-profile/0x](https://api.kixago.com/v1/risk-profile/0x)..." ``` [Get your API key: https://kixago.com/dashboard](https://kixago.com/dashboard) *Free tier: 10,000 requests/month* [Authentication details →](/docs/api/authentication) ----- ## Supported Protocols | Protocol | Versions | Chains | | :--- | :--- | :--- | | Aave | V2, V3 | Ethereum, Base, Arbitrum, Polygon | | Compound | V2, V3 | Ethereum, Base, Arbitrum, Polygon | | MakerDAO | Vaults (V1) | Ethereum | *Coming Q2 2025: Morpho, Spark Protocol, Euler V2* ----- ## Response Times Based on actual production data: | Scenario | Duration | Notes | | :--- | :--- | :--- | | **Cache HIT** | `<100ms` | Served from cache (30s TTL) | | **Cache MISS** | 1-4 seconds | Full multi-chain aggregation | | **Single chain** | 1-2 seconds | e.g., Ethereum only | | **Multi-chain** | 2-4 seconds | Concurrent fetching | | **Timeout** | 30s max | Graceful degradation | Check cache status via header: ```http X-Cache-Status: HIT ``` ### Data Freshness * ✅ **Real-time on-chain queries** (not indexed data) * ✅ Own Ethereum/Base nodes (no rate limits) * ✅ **30-second response cache** for performance * ✅ `last_updated` timestamp in every position We query protocols directly, not via The Graph or other indexers. ----- ## Use Cases ### 1\. Credit Underwriting (Banks/Lenders) ```typescript const risk = await kixago.getRiskProfile('0xBorrower...'); if (risk.defi_score >= 700 && risk.global_health_factor > 2.0) { return 'APPROVED'; } else if (risk.defi_score < 550) { return 'DECLINED - High liquidation risk'; } ``` ### 2\. Portfolio Verification (Wealth Advisors) ```typescript const client = await kixago.getRiskProfile('client.eth'); console.log(`Total AUM: $${client.total_collateral_usd.toLocaleString()}`); console.log(`Risk Level: ${client.defi_score.risk_level}`); console.log(`Positions: ${client.lending_positions.length} across ${uniqueChains} chains`); ``` ### 3\. Liquidation Monitoring (Traders) ```typescript const whales = ['0xWhale1...', '0xWhale2...']; for (const whale of whales) { const risk = await kixago.getRiskProfile(whale); if (risk.global_health_factor < 1.15) { alert(`🚨 Liquidation opportunity: ${whale}\nCollateral: $${risk.total_collateral_usd}\nBuffer: ${risk.defi_score.liquidation_simulation.buffer_percentage}%`); } } ``` [More use case examples →](/docs/api/use-cases) ----- ## Error Handling ### Invalid Address ```bash curl -H "X-API-Key: key" "[https://api.kixago.com/v1/risk-profile/invalid](https://api.kixago.com/v1/risk-profile/invalid)" ``` Response (400): ```json { "error": "invalid address format - use hex address or ENS name" } ``` ### Missing API Key ```bash curl "[https://api.kixago.com/v1/risk-profile/0x](https://api.kixago.com/v1/risk-profile/0x)..." ``` Response (401): ```json { "error": "missing or invalid API key" } ``` ### ENS Resolution Failure ```bash curl -H "X-API-Key: key" "[https://api.kixago.com/v1/risk-profile/nonexistent.eth](https://api.kixago.com/v1/risk-profile/nonexistent.eth)" ``` Response (400): ```json { "error": "could not resolve ENS name: nonexistent.eth" } ``` [Full error handling guide →](/docs/api/error-handling) ----- ## Next Steps \<div className="button-group"\> \<a href="(/docs/api/quickstart" className="button button--primary button--lg"\> 🚀 5-Minute Quickstart \</a\> \<a href="(/docs/api/endpoints/risk-profile/risk-profile" className="button button--secondary button--lg"\> 📖 Full API Reference \</a\> \<a href="(/docs/api/understand-responses/defi-score-explained" className="button button--secondary button--lg"\> 🧮 How Scoring Works \</a\> \</div\> ----- ## Rate Limits | Tier | Requests/Month | Rate Limit | | :--- | :--- | :--- | | Developer (Free) | 10,000 | 10 req/sec | | Startup | 100,000 | 50 req/sec | | Institution | 1,000,000 | 200 req/sec | | Enterprise | Unlimited | Custom | Rate limit headers: ```http X-RateLimit-Limit: 10 X-RateLimit-Remaining: 7 X-RateLimit-Reset: 1634567890 ``` ----- ## SDKs (Coming Soon) ### TypeScript/JavaScript: ```typescript import { KixagoClient } from '@kixago/sdk'; const client = new KixagoClient({ apiKey: 'kixakey_...' }); const risk = await client.portfolio.getRiskScore('0x...'); console.log(risk.defiScore.score); // 467 ``` ### Python: ```python from kixago import KixagoClient client = KixagoClient(api_key='kixakey_...') risk = client.portfolio.get_risk_score('0x...') print(risk.defi_score.score) # 467 ``` ----- ## Support * Documentation: You're reading it * OpenAPI Spec: * Email: api@kixago.com * GitHub: github.com/kixago/api-issues