A governance API is an evidence layer. It should preserve raw chain events and signed records while making them usable for interfaces, alerts, archives, and analytics. The central design challenge is normalization without erasing the rules that make each governance framework different.
Canonical entities
| Entity | Essential data |
|---|---|
| Organization | Chains, governors, tokens, timelocks, tracks, metadata roots, and versions. |
| Proposal | Proposer, snapshot, timing, choices, quorum, approval, native state, and source text. |
| Action | Target, value, call data, decoded arguments, ordering, simulation, and execution receipt. |
| Vote | Voter, choice, historical weight, reason, source, transaction or signature, and block. |
| Delegation | Delegator, delegate, effective block, amount context, previous state, and transaction. |
Historical voting power
Do not calculate old eligibility from current balances. Store proposal snapshot blocks, checkpoint references, strategy inputs, and enough provenance to reproduce a weight. Delegation should be a time-series graph rather than a single current field.
Reliable ingestion
Handle chain reorganizations with block hashes, idempotent event identifiers, rollback, and replay. Label provisional data until the configured finality depth. Separate raw ingestion from derived calculations so a bug in one metric does not corrupt the source record.
Client interfaces
REST is effective for stable resources and webhooks; GraphQL helps clients select nested proposal, action, and delegate fields. Use cursor pagination, deterministic ordering, scoped filters, signed webhook payloads, and explicit calculation versions.
Provenance before convenience
Expose source contracts, transaction hashes, log indexes, content hashes, decoding versions, and finality state. An API may become critical infrastructure even without signing authority, so publish operational status, lag, and incident history.
Read the complete implementation guide, Building a Governance API, and the companion article on governance analytics.