Agent Guide

Observing many signals. Resolving one truth.

How to consume the Demos Network Oracle as a machine agent.

Purpose

The Oracle provides current network state for the Demos blockchain testnet. It is strictly watch-only: it observes, interprets, and publishes. It does not advise, predict, or issue instructions.

Your agent reads the state and decides what to do with it. The Oracle never tells you.

Endpoint

GET /organism

Returns 12 flat JSON fields. No nested objects. No fleet data. Every field is always present, never null. Refreshes every 20 seconds.

{
  "status": "stable",
  "trend": "stable",
  "risk": "elevated",
  "data_quality": "sufficient",
  "confidence": "clear",
  "agreement": "strong",
  "active_incidents": 0,
  "max_incident_severity": "none",
  "summary": "Network stable; 3/5 public nodes currently synced",
  "staleness_seconds": 4,
  "last_updated": "2026-04-16T22:00:00.000Z",
  "api_version": "1.0"
}

Field Meanings

status — network operability. stable degraded unstable unknown

risk — resilience / safety margin. low elevated high

confidence — certainty of assessment. clear uncertain

data_quality — observability. sufficient insufficient

agreement — validator consensus. strong moderate weak unknown

trend — direction of change. improving stable worsening unknown

active_incidents — count of current unresolved issues.

max_incident_severity — worst active incident: none info warning critical

staleness_seconds — seconds since last observation. Use for freshness judgment.

The Minimal Triple

The simplest consumption pattern reads three fields:

status + risk + confidence

These give you the complete picture in three values. Add data_quality for trust calibration and active_incidents for problem awareness.

Trust Calibration

Before relying on the assessment, check:

data_quality — if insufficient, treat all values with skepticism.

staleness_seconds — if high, data may not reflect current reality.

confidence — if uncertain, signals conflict. Consume with caution.

Polling Guidance

Recommended interval: 10–30 seconds. The Oracle updates every 20 seconds.

Respect the Cache-Control: public, max-age=5 header. Do not poll faster than every 5 seconds.

For less time-sensitive consumers, polling every 60 seconds is sufficient.

Consumption Examples

curl

curl -s https://demos-oracle.com/organism | jq '{status, risk, confidence}'

JavaScript

const res = await fetch('https://demos-oracle.com/organism');
const state = await res.json();
if (state.status === 'unstable' || state.risk === 'high') {
  // handle degraded network
}

Python

import requests
state = requests.get('https://demos-oracle.com/organism').json()
if state['data_quality'] == 'insufficient':
    pass  # data unreliable, act cautiously

Other Endpoints

/health — full diagnostic with agreement details, public nodes, signals, reference data.

/incidents — incident log. Default scope: public. Use ?scope=all for fleet.

/methodology — how the Oracle makes assessments.

Design Principle