API Reference – Version 1.1

1. Présentation générale

Cette page fournit la référence technique complète de l’API GHI v1.1. Toutes les structures, paramètres, réponses et exemples sont documentés dans un format homogène destiné aux environnements institutionnels.

Les données proviennent du Sandbox Engine. Les mêmes structures seront utilisées dans les éditions premium (versions institutionnelles enrichies).

2. Liste des endpoints

Endpoint	Méthode	Usage
`/v1/ghi/snapshot`	GET	Coûts min/avg/max par région + données globales
`/v1/ghi/history`	GET	Séries temporelles synthétiques
`/v1/ghi/regions`	GET	Liste des régions GHI disponibles
`/v1/ghi/metadata`	GET	Métadonnées globales (API + moteur)
`/v1/ghi/network`	GET	Métriques réseau synthétiques (exp. : hashrate)
`/v1/ghi/forecast`	GET	Prévision synthétique du coût moyen

3. Métadonnées communes (toutes réponses)

{
  "version": "1.1",
  "timestamp_utc": "2025-12-09T12:00:00Z",
  "engine_sandbox_version": "0.4.0-sandbox"
}

Ces champs sont présents dans toutes les réponses. Ils permettent de tracer les requêtes, monitorer la stabilité des versions, et auditer les pipelines de données.

4. Endpoint : /v1/ghi/snapshot

Fournit les coûts actuels de production du Bitcoin par région, avec les statistiques globales :

Structure de réponse

{
  "version": "1.1",
  "timestamp_utc": "...",
  "engine_sandbox_version": "0.4.0-sandbox",
  "region_count": 3,
  "regions": [
    {
      "region_id": "us",
      "currency": "USD",
      "min_cost_usd": 38000.0,
      "avg_cost_usd": 42000.0,
      "max_cost_usd": 50000.0
    }
  ],
  "global_min_cost_usd": 35000.0,
  "global_avg_cost_usd": 42000.0,
  "global_max_cost_usd": 52000.0
}

Notes institutionnelles

Format strictement stable entre toutes les versions mineures (1.x).
Les régions sont garanties nominalement stables.

5. Endpoint : /v1/ghi/history

Paramètres

Paramètre	Type	Description
`region_id`	string	ID de région (ex : "us") ou "global"

Structure de réponse

{
  "region_id": "global",
  "points": [
    {
      "date": "2025-12-01",
      "min_cost_usd": 41000.0,
      "avg_cost_usd": 45000.0,
      "max_cost_usd": 49500.0
    }
  ]
}

6. Endpoint : /v1/ghi/regions

{
  "version": "1.1",
  "timestamp_utc": "...",
  "regions": [
    {"id": "us", "name": "United States"},
    {"id": "eu", "name": "Europe"},
    {"id": "cn", "name": "China"}
  ],
  "region_count": 3
}

7. Endpoint : /v1/ghi/metadata

{
  "version": "1.1",
  "timestamp_utc": "...",
  "engine_sandbox_version": "0.4.0-sandbox",
  "available_endpoints": [
    "/v1/ghi/snapshot",
    "/v1/ghi/history",
    "/v1/ghi/regions",
    "/v1/ghi/metadata",
    "/v1/ghi/network",
    "/v1/ghi/forecast"
  ]
}

8. Endpoint : /v1/ghi/network

{
  "hashrate_eh": 554.0,
  "difficulty": 8.9e13,
  "avg_fee_usd": 4.2
}

9. Endpoint : /v1/ghi/forecast

Paramètres

Nom	Type	Description
`forecast_days`	int	Fenêtre de prévision (défaut : 7 jours)

Exemple

{
  "forecast_days": 7,
  "predicted_avg_cost_usd": 62300.0
}

API Reference – Version 1.1

1. Overview

This page provides the complete technical reference for the GHI API v1.1. All response structures, parameters, and examples are documented in a uniform, institutional-grade format.

2. Endpoint list

Endpoint	Method	Description
`/v1/ghi/snapshot`	GET	Min/avg/max production costs per region + globals
`/v1/ghi/history`	GET	Synthetic historical time series
`/v1/ghi/regions`	GET	Available GHI regions
`/v1/ghi/metadata`	GET	API + engine metadata
`/v1/ghi/network`	GET	Synthetic network metrics
`/v1/ghi/forecast`	GET	Synthetic cost forecast

3. Common metadata

{
  "version": "1.1",
  "timestamp_utc": "...",
  "engine_sandbox_version": "0.4.0-sandbox"
}

4. Endpoint: /v1/ghi/snapshot

Current production-cost metrics per region, including global statistics.

{
  "region_count": 3,
  "regions": [
    {
      "region_id": "us",
      "min_cost_usd": 38000.0,
      "avg_cost_usd": 42000.0,
      "max_cost_usd": 50000.0
    }
  ]
}

5. Endpoint: /v1/ghi/history

{
  "region_id": "global",
  "points": [
    {
      "date": "2025-12-01",
      "min_cost_usd": 41000.0,
      "avg_cost_usd": 45000.0,
      "max_cost_usd": 49500.0
    }
  ]
}

6. Endpoint: /v1/ghi/regions

{
  "regions": [
    {"id": "us", "name": "United States"},
    {"id": "eu", "name": "Europe"},
    {"id": "cn", "name": "China"}
  ]
}

7. Endpoint: /v1/ghi/metadata

{
  "available_endpoints": [
    "/v1/ghi/snapshot",
    "/v1/ghi/history",
    "/v1/ghi/regions",
    "/v1/ghi/metadata",
    "/v1/ghi/network",
    "/v1/ghi/forecast"
  ]
}

8. Endpoint: /v1/ghi/network

{
  "hashrate_eh": 554.0,
  "difficulty": 8.9e13,
  "avg_fee_usd": 4.2
}

9. Endpoint: /v1/ghi/forecast

{
  "forecast_days": 7,
  "predicted_avg_cost_usd": 62300.0
}