# DBIS Data API — implementation notes

OpenAPI contract: [openapi.yaml](./openapi.yaml).

## Lineage

| Value | Meaning |
|-------|---------|
| `on_chain` | Derived from Chain 138 indexer, RPC, or token-aggregation inputs |
| `policy` | Published by policy officers; not implied as ledger truth |
| `modelled` | Simulation or internal model |

## Suggested PostgreSQL / Timescale layout

**Relational (PostgreSQL)**

- `api_clients` — id, name, key_hash, rate_limit_tier, created_at  
- `datasets` — id, slug, title, description, lineage_default  
- `dataset_versions` — dataset_id, version, published_at, document_url  

**Hypertables (TimescaleDB)**

- `metric_gru_supply` — time TIMESTAMPTZ, value NUMERIC, metadata JSONB  
- `metric_settlement_volume` — time, window, chain_id, value, tx_count  
- `metric_reserve_snapshot` — time, asset, amount, source  

Ingest jobs read from existing token-aggregation and explorer-compatible sources; separate ETL for policy-published series.

## Frontend (DBIS portal)

Set `NEXT_PUBLIC_DATA_API_BASE` in the Gov Web Portals DBIS app (see `DBIS/.env.example`) so the homepage and `/dashboard` monetary panels call this API. When the service is down, the UI shows placeholders and an “unreachable” status.

## Deployment path

1. Provision CT/VM or service user on LAN.  
2. NPMplus proxy host `data.d-bis.org` → upstream.  
3. Enable API keys (optional) for high-volume consumers; public tier remains read-only GET.  
4. Add host to [E2E_ENDPOINTS_LIST.md](../../docs/04-configuration/E2E_ENDPOINTS_LIST.md) when live.