Developers

The same engine. Your stack.

Versioned API v1 for catalogs and score history, x402 for agent pay-per-call, plus enterprise workspace endpoints — one deterministic monthly engine underneath.

Programmatic access to the live Global Financial System readout is keyed.

API v1 reference →x402 →Run a brief →

Live - this month's run

Global Financial System readout from the monthly engine - same scores as the homepage instrument.

{
  "entity_name": "Global Financial System",
  "slug": "global-financial-system",
  "nii_score": 1.870559149295314,
  "phase": "Stable",
  "regime": "Stable — Stable",
  "fai": 1.870559149295314,
  "fai_regime": "Green",
  "trend": null,
  "cascade_active": false,
  "confidence": null,
  "run_date": "2026-07-01",
  "field_notes": {
    "phase": "Unified regime from classifyPhaseWithThresholds (engine 0–5 NII → client 0–100): Stable <40, Elevated <60, Severe <80, Crisis <90, Collapse ≥90. Same vocabulary as public badges. Legacy thermodynamic names (Pre-Crisis, Plateau) may appear only on historical rows — always reclassify from NII when present.",
    "regime": "Display score band from classifyRegime on NII × 20 (0–100): Stable <40, Elevated 40–60, Severe 60–80, Crisis 80–90, Collapse 90+. Identical ladder to phase when both derive from NII."
  }
}
run_date Jul 1, 2026fetched_at Aug 10, 2026, 6:12 AM UTC

Slug: global-financial-system

nii

Net Insecurity Index · engine 0–5 on score runs; client display ×20 → 0–100

phase

Thermodynamic phase label on the run

field_notes

Explains phase vs regime semantics on score payloads

run_date

Monthly engine run timestamp (ISO 8601)

cascade_active

Cross-domain propagation flag

domain_scores

Six-domain breakdown per run

entity

Full catalog row with slug and entity_type

Auth

API v1: x-api-key or institutional session. x402: payment header on X Layer.

Rate limits

API v1: 300 requests per minute per key or session.

Errors

JSON body with a single error string, e.g. {"error":"Unauthorized"}.

{
  "error": "Unauthorized"
}

Versioning

v1 is stable. Breaking changes ship as v2 - never in place on a versioned path.

API v1

x-api-key or session

Full catalog, history, and domain breakdown.

  • Filterable entity catalog
  • Paginated monthly score history
  • Six-domain scores per run
  • Latest run bundled on entity detail
  • Entropy source registry and observation series

x402

Pay-per-call · X Layer

Machine-metered Index snapshot — settle on-chain, get a ledgered receipt.

  • GET /api/v1/pulse — live daily stress band
  • HTTP 402 unpaid probe with payment instructions
  • Exact scheme on eip155:196 (USDG)
  • Idempotent pulse_calls ledger on settle
  • No API key or seat required for agents

Enterprise workspace

Institutional agreement

Portal, watchlists, and deliverables on top of the same engine.

  • Org-scoped watchlists
  • Weekly signals and flagship reports
  • Briefing generation and PDF export
  • API key issuance and rotation

01 · Monthly engine

Deterministic scoring

Six domains, one formula, source-traced inputs. Same readout as the public benchmark.

B
M
I
P
A
C

Output

NII

Regime · domains · FAI · cascade

02 · REST API

Programmatic layer

Versioned JSON over HTTPS. Auth via x-api-key or institutional session.

  • GET/api/v1/entities

    Entity catalog - filter by entity_type and priority flag.

  • GET/api/v1/entities/{id}

    Entity metadata plus latest_score_run (nii, phase, cascade, run_date).

  • GET/api/v1/entities/{id}/scores

    Paginated score history - page and page_size up to 100.

  • GET/api/v1/entities/{id}/domain-scores

    Six domain scores for the latest run on that entity.

  • GET/api/v1/entropy-sources

    Ingested entropy source registry — cadence, last_updated, and staleness status.

  • GET/api/v1/entropy-sources/{source_id}/series

    Read-only indicator_observations for a source — optional from/to (YYYY-MM-DD).

Entity reads and catalog access require x-api-key or an institutional session.

03 · Your desk

Your infrastructure

Embed regime structure where decisions are made - without rip-and-replace.

  • Risk and limits

    Regime bands in your stack

  • Routing and OMS

    Entity-level phase inputs

  • Watchlists

    Scoped entities, monthly refresh

  • Research desk

    Domain history and signals

No demo tier. The API returns the same scores published on the public benchmark.

One engine · one API contract · your stack

Entity types in production

Global systems · Nation-states · Transit corridors · Sectors · Organizations

API v1 response shape

Entity detail returns the latest monthly run - NII, phase, cascade, and full metadata for downstream systems.

{
  "entity": {
    "slug": "global-financial-system",
    "name": "Global Financial System",
    "entity_type": "global"
  },
  "latest_score_run": {
    "nii": 3.41,
    "phase": "Collapse",
    "cascade_active": true,
    "run_date": "2026-06-01T00:00:00.000Z",
    "model_version": "mvl-governed"
  },
  "field_notes": {
    "phase": "Unified regime from classifyPhaseWithThresholds (engine 0–5 NII → client 0–100): Stable <40, Elevated <60, Severe <80, Crisis <90, Collapse ≥90. Same vocabulary as public badges. Legacy thermodynamic names (Pre-Crisis, Plateau) may appear only on historical rows — always reclassify from NII when present.",
    "regime": "Display score band from classifyRegime on NII × 20 (0–100): Stable <40, Elevated 40–60, Severe 60–80, Crisis 80–90, Collapse 90+. Identical ladder to phase when both derive from NII."
  }
}

API v1

Authenticated catalog and history. Include x-api-key or an institutional session cookie. Keys issued under enterprise agreements.

  • GET/api/v1/entitiesEntity catalog - filter by entity_type and priority flag.
  • GET/api/v1/entities/{id}Entity metadata plus latest_score_run (nii, phase, cascade, run_date).
  • GET/api/v1/entities/{id}/scoresPaginated score history - page and page_size up to 100.
  • GET/api/v1/entities/{id}/domain-scoresSix domain scores for the latest run on that entity.
  • GET/api/v1/entropy-sourcesIngested entropy source registry — cadence, last_updated, and staleness status.
  • GET/api/v1/entropy-sources/{source_id}/seriesRead-only indicator_observations for a source — optional from/to (YYYY-MM-DD).
{
  "error": "Unauthorized"
}

x402

Live · X Layer

Live structural stress snapshot from the Index — agents settle per call on X Layer, with a ledgered receipt of what the instrument said and when.

x402 is pay-per-call on X Layer; entity catalog and score history use x-api-key or an institutional session - two auth models on API v1.

Production route. Unpaid calls return 402 with settlement instructions; paid calls settle synchronously and write a ledger receipt.

Agents settle per call. Offices license the Index.

  • GET/api/v1/pulseMetered · settled on X Layer. Settlement amount is configured per environment (currently 0.50 USDG atomic units on eip155:196) — a metering unit for agents, not a retail product price.

Probe unpaid (expect 402)

No API key. An unpaid GET returns payment instructions — the agent-commerce handshake.

curl -sS -i "https://www.entropyindex.com/api/v1/pulse"

Auth and payment flow

  1. Unpaid probe: GET /api/v1/pulse with no payment header. Server returns 402 Payment Required with a JSON body (x402Version, resource, accepts[]) and a PAYMENT-REQUIRED header (base64url-encoded copy of the same instructions).
  2. Sign payment: Build an x402 v2 exact payment on network eip155:196 for 0.50 USDG (500000 atomic units, 6 decimals) to the payTo address in accepts[0]. Asset contract: 0x4ae46a509f6b1d9056937ba4500cb143933d2dc8.
  3. Paid request: Retry GET /api/v1/pulse with the signed payload in a payment header. Accepted names: Payment, payment, payment-signature, or x-payment (base64url PaymentPayload). OKX facilitator verifies and settles synchronously; on success the handler returns 200 JSON and may attach a PAYMENT-RESPONSE settlement receipt header. Paid traffic is upserted into pulse_calls by payment id.

Example 200 response

pulse is a daily stress band (easing, stable, elevated, critical) - not the thermodynamic phase label on entity score runs. nii_anchor is read from the latest monthly_scores row (example below: July 2026 canonical nii_score 3.37); level is the global monthly NII scalar (engine 0–5; display ×20 → 0–100), distinct from per-entity phase on keyed entity reads (see field_notes). Driver buckets in this example are illustrative; nii_anchor matches the live ledger month.

{
  "as_of": "2026-07-07T12:00:00.000Z",
  "data_through": "2026-07-06",
  "pulse": "elevated",
  "drift": 12.5,
  "drivers": [
    "event_pressure",
    "attention"
  ],
  "domain_detail": {
    "event_pressure": 60,
    "cyber_activity": 60,
    "macro_spillover": 50,
    "attention": 60
  },
  "nii_anchor": {
    "level": 3.37,
    "as_of": "2026-07-01",
    "next_update": "2026-08-01T08:00:00.000Z"
  },
  "stale_sources": [],
  "note": "Risk context, not trade signals."
}

Error responses

402 Payment Required - no valid payment header, or payment verification failed. Body carries x402 payment instructions (retry after signing).

{
  "x402Version": 2,
  "resource": {
    "url": "https://www.entropyindex.com/api/v1/pulse",
    "description": "Entropy Index Risk Pulse snapshot",
    "mimeType": "application/json"
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:196",
      "asset": "0x4ae46a509f6b1d9056937ba4500cb143933d2dc8",
      "amount": "500000",
      "payTo": "0x742d35cc6634c0532925a3b844bc9e4438f44e00",
      "maxTimeoutSeconds": 300,
      "extra": {
        "decimals": 6,
        "name": "USDG",
        "version": "2"
      }
    }
  ]
}

503 Service Unavailable - payment rail misconfigured (missing or malformed pay-to address, facilitator credentials unavailable, or settlement did not complete synchronously).

{
  "error": "Payment service unavailable"
}

Cache: Successful responses are cached for 15 minutes (Cache-Control: public, s-maxage=900, stale-while-revalidate=1800). Agents should not poll faster than the cache window unless payment economics allow it.

Phase terminology - flagged

The public API returns a phase field on entity reads (e.g. "Collapse"). Terminology review is pending framework sign-off. Surfaces that render phase labels publicly:

  • Public API · Keyed entity reads - phase field on score payloads (see field_notes on responses)
  • Benchmark · Homepage instrument / LiveIndexHero (GFS thermodynamic phase)
  • Entity profiles · /country/{slug} public teaser - display regime badge only; institutional full view shows thermodynamic phase
  • Homepage scanner · HeroGlobalScanner lenses (live display regime for countries); GFS lens shows thermodynamic phase
  • Mandate pages · Hero proof panel - MandateHeroProofPanel (GFS thermodynamic phase)
  • Case studies · /cases/* - CaseStudyLayout, FeaturedCaseCard, CaseStudy2008Content
  • Country explorer · /countries - phaseIndicator from display regime (classifyRegime on NII x 20), not score_runs.phase
  • Readout exports · NiiExportScoreBlock, PrimaryReadoutHero (institutional readout - thermodynamic phase)

Enterprise endpoints

Watchlists, org alerts, weekly signal PDFs, and briefing generation live behind institutional workspace auth - same scores, delivered through portal routes after agreement. Request access for the full integration map.

API v1 reference →← Home