API v1.1 — Référence (Sandbox)

Cette page documente l’API Sandbox GHI v1.1. Le mode Sandbox est conçu pour offrir une structure stable aux intégrateurs. Les réponses peuvent contenir des valeurs de démonstration.

Statut : Sandbox • URL de base : https://<votre-domaine>/v1/ghi (ou http://127.0.0.1:8000/v1/ghi en local)

Format : JSON • Authentification : aucune (sandbox) • Limite de débit : best-effort

Démarrage rapide

Objectif	Commande
Récupérer le snapshot	`curl -s http://127.0.0.1:8000/v1/ghi/snapshot \| jq`
Liste des régions	`curl -s http://127.0.0.1:8000/v1/ghi/regions \| jq`
Détail d’une région	`curl -s http://127.0.0.1:8000/v1/ghi/regions/us \| jq`
Historique global	`curl -s "http://127.0.0.1:8000/v1/ghi/history?region_id=global" \| jq`

Endpoints

`GET /v1/ghi/snapshot`

Retourne le dernier snapshot global (coût min / moyen / max + métadonnées).

{
  "timestamp_utc": "2025-12-11T19:56:27.777989Z",
  "engine_sandbox_version": "0.4.3-sandbox",
  "version": "1.1",
  "global_min_cost_usd": 36000.0,
  "global_avg_cost_usd": 43000.0,
  "global_max_cost_usd": 53000.0
}

`GET /v1/ghi/regions`

Retourne le registre des régions exposées par le Sandbox.

{
  "version": "1.1",
  "timestamp_utc": "2025-12-11T19:56:27.777989Z",
  "region_count": 3,
  "regions": [
    { "id": "us", "name": "United States" },
    { "id": "eu", "name": "Europe" },
    { "id": "cn", "name": "China" }
  ]
}

`GET /v1/ghi/regions/{id}`

Retourne les détails d’une région. La structure est conçue pour rester stable pour les intégrations dashboard.

{
  "version": "1.1",
  "timestamp_utc": "2025-12-11T19:56:27.777989Z",
  "region_id": "us",
  "name": "United States",
  "min_cost_usd": 38000.0,
  "avg_cost_usd": 45000.0,
  "max_cost_usd": 56000.0,
  "hashrate_share_pct": 32.0
}

`GET /v1/ghi/history?region_id=global`

Retourne une série temporelle. Le Sandbox garantit un ordre chronologique strict dans points[].

{
  "version": "1.1",
  "timestamp_utc": "2025-12-11T19:56:27.781785Z",
  "engine_sandbox_version": "0.4.3-sandbox",
  "region_id": "global",
  "points": [
    { "date": "2025-12-01", "min_cost_usd": 35000.0, "avg_cost_usd": 41200.0, "max_cost_usd": 49500.0, "currency": "USD" },
    { "date": "2025-12-02", "min_cost_usd": 35200.0, "avg_cost_usd": 41500.0, "max_cost_usd": 49800.0, "currency": "USD" }
  ]
}

Notes pour les intégrateurs

Tous les timestamps sont en UTC et ISO-8601.
Les champs numériques sont des flottants ; un arrondi côté client est recommandé.
Les valeurs peuvent être synthétiques ; la stabilité de la structure prime sur la précision.

API v1.1 — Reference (Sandbox)

This page documents the GHI Sandbox API v1.1. The sandbox is designed to be stable for integrators. Responses may contain demo values.

Status: Sandbox • Base URL: https://<your-domain>/v1/ghi (or http://127.0.0.1:8000/v1/ghi locally)

Format: JSON • Auth: none (sandbox) • Rate limit: best-effort

Quickstart

Goal	Command
Fetch snapshot	`curl -s http://127.0.0.1:8000/v1/ghi/snapshot \| jq`
List regions	`curl -s http://127.0.0.1:8000/v1/ghi/regions \| jq`
Region detail	`curl -s http://127.0.0.1:8000/v1/ghi/regions/us \| jq`
Global history	`curl -s "http://127.0.0.1:8000/v1/ghi/history?region_id=global" \| jq`

Endpoints

`GET /v1/ghi/snapshot`

Returns the latest global snapshot (min / avg / max production cost, plus metadata).

{
  "timestamp_utc": "2025-12-11T19:56:27.777989Z",
  "engine_sandbox_version": "0.4.3-sandbox",
  "version": "1.1",
  "global_min_cost_usd": 36000.0,
  "global_avg_cost_usd": 43000.0,
  "global_max_cost_usd": 53000.0
}

`GET /v1/ghi/regions`

Returns the region registry exposed by the sandbox.

{
  "version": "1.1",
  "timestamp_utc": "2025-12-11T19:56:27.777989Z",
  "region_count": 3,
  "regions": [
    { "id": "us", "name": "United States" },
    { "id": "eu", "name": "Europe" },
    { "id": "cn", "name": "China" }
  ]
}

`GET /v1/ghi/regions/{id}`

Returns details for one region. The payload is intended to be stable for dashboard integrations.

{
  "version": "1.1",
  "timestamp_utc": "2025-12-11T19:56:27.777989Z",
  "region_id": "us",
  "name": "United States",
  "min_cost_usd": 38000.0,
  "avg_cost_usd": 45000.0,
  "max_cost_usd": 56000.0,
  "hashrate_share_pct": 32.0
}

`GET /v1/ghi/history?region_id=global`

Returns time-series points for the requested region. The sandbox guarantees increasing dates in points[].

{
  "version": "1.1",
  "timestamp_utc": "2025-12-11T19:56:27.781785Z",
  "engine_sandbox_version": "0.4.3-sandbox",
  "region_id": "global",
  "points": [
    { "date": "2025-12-01", "min_cost_usd": 35000.0, "avg_cost_usd": 41200.0, "max_cost_usd": 49500.0, "currency": "USD" },
    { "date": "2025-12-02", "min_cost_usd": 35200.0, "avg_cost_usd": 41500.0, "max_cost_usd": 49800.0, "currency": "USD" }
  ]
}

Notes for integrators

All timestamps are UTC and ISO-8601.
Numeric fields are floats; clients should round for display.
Sandbox may return demo values; structural stability matters more than accuracy here.