REST API

The endpoints that exist today: point query, batch, survival curve, history and verification.

Argued in full in the whitepaper at §11, Layer 2.

Base URL and auth#

terminal

export API=https://api.cleaton.xyz/v1
curl -s "$API/pool/$POOL" -H "Authorization: Bearer $CLEATON_KEY"

Endpoints#

Method	Path	Returns
GET	`/v1/pool/{address}`	Current signed attestation for one pool
POST	`/v1/batch`	Attestations for a set of pools in one request
GET	`/v1/pool/{address}/curve`	The full survival function, not just the scalar horizon
GET	`/v1/pool/{address}/history`	Every past attestation with its realised outcome
POST	`/v1/verify`	Stateless authenticity and freshness check
GET	`/v1/campaign/{id}/efficiency`	Emission efficiency for an observable campaign
POST	`/v1/counterfactual`	Horizon under a hypothetical schedule, lock or depositor exit

Batch#

Score a whole book in one round trip. Priced per pool, because the work is linear in the number of pools, not in the number of requests.

batch.sh

curl -s "$API/batch" \
  -H "Authorization: Bearer $CLEATON_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chainId": 8453,
    "pools": ["0xA0b8...", "0x4200...", "0x8335..."],
    "include": ["neff"]
  }'

Passing include: ["neff"] also returns the effective number of independent exposures across the set. That is the number worth reading — eleven positions drawing incentives from the same treasury with expiries in a nine-day band are not eleven bets.

Survival curve#

The point query returns a horizon at the reference survival floor of 0.5. If you run your own threshold, take the curve instead and compute your own:

curve.json

{
  "pool": "0xA0b8...",
  "thresholdBps": 7000,
  "curve": [
    { "day": 1,  "survival": 0.99 },
    { "day": 7,  "survival": 0.71 },
    { "day": 14, "survival": 0.38 },
    { "day": 30, "survival": 0.09 }
  ]
}

Metering#

Surface	Metering
On-chain read of a committed attestation	Free — gas is the only cost
Fresh signed attestation	Per request: the computation is the cost
Batch scan	Per pool
Historical / backtest	Per-query tier
Webhook subscription	Per pool-month
Agent (MCP) call	Per call, prepaid or x402