REST API

Base URL and auth#

export API=https://dapp.cleaton.xyz/api/v1
curl -s "$API/pool/0xbeeff033f34c046626b8d0a041844c5d1a5409dd"

No key, no header, no account. Every read below is free and unauthenticated, and stays that way: a record only its author can audit is not a record. Keys exist, but only for the endpoints that write — see below.

Reading a pool#

{pool} takes a bare address or a full pool key. An address is only unique within a chain — the same contract exists at the same address on several — so a bare address that matches more than one pool returns ambiguous with the keys to choose between, rather than silently picking one.

{
  "pool":       "0xbeeff033f34c046626b8d0a041844c5d1a5409dd",
  "chainId":    4663,
  "poolKey":    "4663:0xbeeff033f34c046626b8d0a041844c5d1a5409dd",
  "symbol":     "steakUSDG/USDG",
  "protocol":   "Morpho",
  "horizon":    90,
  "confidence": "0.65",
  "issuedAt":   1787325423,
  "expiry":     1787411823,
  "expired":    false,
  "outcome":    "pending",
  "signature":  "0xd810beb6...4f201b",
  "attester":   "0xb6486340a930e21b7ee505111188e929120d9eda",
  "signed":     true,
  "sample":     false
}

confidence is a decimal string, not a number. It is part of the canonical payload the signature covers, and a float has no canonical decimal form across languages — so it travels as text and is compared as text.

The liquidity map#

Cleaton measures four things about a pool, and this is the endpoint that returns them at once: depth (how much is there, how much of it is standing on emissions, how much survives the durability discount), durability (the signed horizon, or the incentive share of yield when no horizon stands), movement (what the depth has done across the stored days), and exitability (how much can actually leave, stated only where it is exact). The rollup returns exitability under its own exit key; the per-pool profile reports it inside depth.

Both take ?days= for the history window. An address that names a pool on more than one chain answers 300 with the candidate keys rather than picking one; pass the full {chainId}:{address} key to disambiguate.

Exit capacity, and where the numbers come from#

depth.availableUsd and depth.utilisation answer how much can actually leave right now — and they are null for everything except a lending market. That is the answer, not a gap. For an AMM, exit impact needs reserves and curve maths per protocol; for a vault it is whatever the strategy can unwind. For a lending market it is supplied − borrowed in the loan asset: exact, with no model. One number spanning all three would be a category error.

utilisationis null when nothing is supplied. Zero over zero is not “0% used” — it is a market nobody has lent into.

The public record#

/scoreboard takes ?limit= (1–500). /dtvl takes ?chainId=. /calendar takes ?withinDays=. /analyze takes ?q= — a pool key, a token address, a ticker or an asset class.

Batch#

Score a whole book in one round trip.

curl -s "$API/batch" \
  -H "Content-Type: application/json" \
  -d '{"pools": ["0xbeeff033...5409dd", "0x0000...0001"]}'

{
  "found":        1,
  "missing":      ["0x0000000000000000000000000000000000000001"],
  "invalid":      [],
  "ambiguous":    {},
  "attestations": { "0xbeeff033...5409dd": { /* as above */ } }
}

The four buckets are the point. A position Cleaton has never scored is not an error and is not a pass — it is the one nobody is watching, and it is returned separately so it cannot be mistaken for either.

Writing#

These take Authorization: Bearer clt_…, issued from the dapp. They spend third-party quota or write to the public record, which is what the key is for — it is not a paywall on reading.

Specified, not built#

These appear in whitepaper §11 and in the surface list, and they do not answer yet. They are named here rather than omitted, because a reference that quietly lists only what works cannot be used to tell what is coming.

Metering#