API reference

Checkpoint advice

Advice on whether to checkpoint now, from the event, time and anomaly budgets you report. It never writes a block.

GET /v1/chain/checkpoint/recommend

`GET` `/v1/chain/checkpoint/recommend`

Should this chain checkpoint now

Evaluates the checkpoint policy against budgets you report and says which trigger, if any, is firing.

Auth: session cookie or API key
Capability: governance
Success: HTTP 200

The stats come from you. The server has no anomaly classifier, so it does not invent one; an omitted anomalies_since scores zero and anomalies_source says not_reported.

Parameters

anomalies_since query, integer or null: Anomalous events since the last checkpoint as classified by the caller (out-of-order arrivals, verification failures, chain repairs). Omitting it scores the drift trigger at zero and the response says so.
events_since query, integer required: Events accumulated since this chain's last checkpoint.
seconds_since query, number required: Wall-clock seconds since this chain's last checkpoint.
total_events query, integer or null: Optional context: total events on the chain.

Request body

None.

Example request

curl

curl -sS -X GET "https://api.afaprotocol.com/v1/chain/checkpoint/recommend?events_since=180&seconds_since=5400&anomalies_since=2&total_events=1200" \
  -H "X-API-Key: afa-beta-EXAMPLE-e4qs"

Python

import requests

API = "https://api.afaprotocol.com"
headers = {"X-API-Key": "afa-beta-EXAMPLE-e4qs"}
params = {
    "anomalies_since": "2",
    "events_since": "180",
    "seconds_since": "5400",
    "total_events": "1200"
}

r = requests.get(f"{API}/v1/chain/checkpoint/recommend", headers=headers, params=params, timeout=30)
r.raise_for_status()
print(r.json())

Example response

HTTP 200
{
  "anomalies_source": "caller_reported",
  "config": {
    "drift_threshold": 0.03,
    "max_unattested_events": 500,
    "max_unattested_seconds": 21600.0,
    "min_events_between": 50
  },
  "recommendation": {
    "checkpoint_now": false,
    "evidence": {
      "anomalies_since_checkpoint": 2,
      "anomalies_to_drift_fire": 4,
      "anomaly_fraction": 0.0111,
      "drift_threshold": 0.03,
      "events_since_checkpoint": 180,
      "events_to_event_budget": 320,
      "events_until_floor": 0,
      "max_unattested_events": 500,
      "max_unattested_seconds": 21600.0,
      "min_events_between": 50,
      "seconds_since_checkpoint": 5400.0,
      "seconds_to_time_budget": 16200.0,
      "suppressed_by_floor": [],
      "total_events": 1200,
      "triggers_firing": []
    },
    "reason": "hold",
    "reason_detail": "no trigger firing: 320 more events to the event budget, 16200 more seconds to the time budget, 4 more anomalous arrivals to the drift threshold"
  },
  "stats": {
    "anomalies_since_checkpoint": 2,
    "events_since_checkpoint": 180,
    "seconds_since_checkpoint": 5400.0,
    "total_events": 1200
  }
}

Errors

Status	Code	Meaning
401	missing_token / invalid_or_expired_api_key	No credential, an expired session, or a revoked or expired key.
403	scope_missing	A key limited by scopes lacks governance; the body names it.
422	validation error	A required field is missing or a value has the wrong type.
422	validation	anomalies_since exceeds events_since, or a value is negative.

What would show this is false

Omit anomalies_since: anomalies_source reads not_reported. A reported zero and an omitted value are kept distinguishable.