CLARAI API — v1

Yield intelligence
for AI agents

Risk-adjusted DeFi stablecoin yield, scored and served as a live JSON API. Built for autonomous agents and the developers building them. No keys. No custody. No execution. Just intelligence.

Live · Base + Ethereum · updated every 10 minutes from DeFiLlama

What this is: a read-only intelligence layer. CLARAI scores every tracked stablecoin pool on audit status, TVL, protocol age, and yield sustainability — then serves that scored data to any agent or app that needs to reason about where risk-adjusted yield actually is. CLARAI never holds, moves, or routes funds. Your agent decides and acts; CLARAI informs.

Base URL

GET https://clarai.xyz/.netlify/functions/yields

All endpoints are GET requests returning JSON. No authentication required for the public tier. Responses are cached for 10 minutes.

Endpoints

All scored pools

GET /yields

Returns every tracked pool, scored, sorted by YieldScore descending.

Top N by YieldScore

GET /yields?view=top&n=10

The highest risk-adjusted opportunities. Use when an agent wants "the best options" without parsing the full set.

Single pool with full breakdown

GET /yields?id=<poolId>

One pool, including the complete transparent score breakdown.

Query parameters

Parameter	Example	Description
`view`	top	Set to `top` with `n` for highest-scored pools only.
`n`	10	Number of results when `view=top`.
`chain`	Base	Filter by chain: `Base` or `Ethereum`.
`asset`	USDC	Filter by stablecoin symbol.
`minScore`	70	Only pools with YieldScore ≥ this value.
`minApy`	5	Only pools with APY ≥ this value.
`maxApy`	20	Only pools with APY ≤ this value.
`tier`	conservative	`conservative`, `balanced`, or `aggressive`.
`id`	<poolId>	Return a single pool by its id.

Example request

# Safest USDC yields on Base, score 70+
curl "https://clarai.xyz/.netlify/functions/yields?chain=Base&asset=USDC&minScore=70"

Example response

{
  "source": "CLARAI YieldScore",
  "updated": "2026-10-02T14:05:00.000Z",
  "count": 2,
  "pools": [
    {
      "id": "aave-v3-usdc-base",
      "protocol": "aave-v3",
      "chain": "Base",
      "asset": "USDC",
      "apy": 4.2,
      "tvlUsd": 612000000,
      "yieldScore": 96,
      "rating": "A+",
      "scoreBreakdown": {
        "audit": 25,
        "tvl": 25,
        "age": 16,
        "apySustainability": 20,
        "apyStability": 10
      },
      "audited": true,
      "tier": "conservative"
    }
  ],
  "disclaimer": "...research only, not financial advice..."
}

The YieldScore

Every pool is scored 0–100. Higher means safer, more sustainable yield. The score is fully transparent — every response includes the scoreBreakdown so your agent can see exactly how it was derived, never a black box.

Factor	Max	Basis
Audit status	25	Whether the protocol is audited / established.
TVL	25	Total value locked — deeper liquidity scores higher.
Protocol age	20	How long the protocol has operated.
APY sustainability	20	Very high APY scores lower — unsustainable yield is penalised.
APY stability	10	Deviation from 30-day mean APY. Stable scores higher.

Not financial advice. CLARAI provides risk-adjusted yield intelligence for research and informational purposes only. Scores are derived from public data, may be incomplete or delayed, and are not a recommendation to deposit, buy, or allocate funds. Yields and risks change constantly. Any agent or person consuming this API is solely responsible for their own decisions.

MCP Server

CLARAI speaks the Model Context Protocol, so MCP-capable agents and assistants can use CLARAI as a native tool rather than calling the REST API by hand. The server is live and exposes three tools: get_top_yields, find_opportunities, and explain_score.

POST https://clarai.xyz/.netlify/functions/mcp

Speaks JSON-RPC 2.0 over HTTP — the standard MCP methods (initialize, tools/list, tools/call). A GET on the same URL returns a self-describing descriptor listing the available tools, for registry probes and discovery.

On transport: remote MCP is still stabilising across clients. CLARAI implements the stable JSON-RPC core; depending on your MCP client you may connect directly or via a thin local bridge. The REST API above is always available as a fallback for any agent framework.

Roadmap

Next: historical score tracking to build a measurable track record (how pools CLARAI rated highly actually performed over time), listing in emerging MCP/agent tool registries for discovery, and additional intelligence primitives beyond yield — protocol risk, stablecoin quality, and eventually tokenised real-world assets as that market matures on Base.

Yield intelligencefor AI agents