Migrate from v1 to v2
v2 is the current contract for new integrations. v1 remains available as a frozen compatibility surface without a published shutdown date.
Before switching
- Inventory the v1 routes, response fields, pagination, and authentication scopes your integration uses.
- Confirm the partner token includes the required v2 paid scopes, or prepare an x402-capable wallet.
- Add data-status and coverage handling.
- Run v1 and v2 in parallel against representative DAOs before changing production traffic.
Main changes
| Concern | v1 | v2 |
|---|---|---|
| Lists | Legacy shapes | Rows in data.items, page in meta.page |
| Time windows | Epoch-millisecond parameters | RFC 3339 from and to |
| Resource identity | Provider kind and external ID | Opaque proposalKey and topicKey |
| Activity | Mixed activity resources | Explicit events or curated signals |
| Data state | Freshness fields | Publication readiness plus resource coverage |
| Exact values | Mixed number handling | Decimal strings for governance analytics |
Route mapping
| v1 workflow | v2 workflow |
|---|---|
| DAO list/detail | /v2/daos, /v2/daos/:daoId |
| Freshness | /v2/meta/data-status |
| Activity/events/signals | /v2/events or /v2/signals |
| Proposal lookup | /v2/proposals/resolve, then proposal detail |
| DAO brief | Compose DAO detail, proposal list, and events as needed |
| Evidence | /v2/proposals/:proposalKey/evidence |
Cutover and rollback
- Compare key business outputs, not raw JSON equality.
- Verify pagination to completion and restart behavior for stale cursors.
- Confirm partial/backfilling states are disclosed rather than hidden.
- Switch a small traffic segment, monitor errors and cost, then expand.
- Keep the v1 path deployable until v2 behavior is verified; rollback routes traffic to v1 without changing stored v2 keys into guessed legacy identifiers.