Skip to content

Proposed Agent API v2 — not yet available

This guide describes the proposed v2 contract. The v2 endpoints are not live yet and everything below is subject to change. See Agent API overview.

Quickstart

This guide takes you from zero to a proposal detail page in five minutes. You do not need a wallet or a partner token for the first two steps.

1. Check the service and data status (free)

curl https://agent-api.degov.ai/v2/meta/data-status

{
  "data": {
    "scope": "global",
    "counts": { "daos": 120, "proposals": 48000 },
    "coverageStatus": "complete"
  },
  "meta": {
    "requestId": "req-01J...",
    "generatedAt": "2026-08-05T07:30:00.000Z",
    "dataAsOf": "2026-08-05T07:29:30.000Z",
    "readiness": { "status": "ready" }
  }
}

If readiness.status is ready, the dataset is consistent and safe to query. If it is backfilling or stale, results may be partial — see Readiness & Coverage.

2. Pick a DAO (free)

curl "https://agent-api.degov.ai/v2/daos?hasVoteData=true&limit=5"

From the response, choose a daoId — for example ens-dao.

3. Choose your access path

Paid (standard and plus tier) endpoints require one of:

  • x402 payment — pay per request in USDC on Base. No subscription, no API key. See Authentication.
  • Partner token — an API key issued for partner integrations, sent as x-degov-api-token.

4. Find an active proposal (standard)

curl -H "x-degov-api-token: <token>" \
  "https://agent-api.degov.ai/v2/proposals?daoId=ens-dao&lifecycleStatus=active&sort=endingSoon&limit=20"

The list response does not include bodies or votes. It returns enough to choose, plus the key you need next:

{
  "data": [
    {
      "proposalKey": "p1_eyJkYW9JZCI6ImVucy1kYW8iLCJwcm92aWRlciI6InNuYXBzaG90IiwiZXh0ZXJuYWxJZCI6ImFiYzEyMyJ9",
      "identity": { "daoId": "ens-dao", "provider": "snapshot", "externalId": "abc123" },
      "title": "Increase Protocol Budget",
      "lifecycleStatus": "active",
      "outcome": "unknown",
      "endAt": "2026-08-07T12:00:00.000Z"
    }
  ],
  "meta": { "page": { "limit": 20, "hasMore": false } }
}

proposalKey is an opaque identifier generated by the API. Copy it as-is; never construct it yourself. See Proposal & Topic Keys.

5. Read the proposal detail (plus)

curl -H "x-degov-api-token: <token>" \
  "https://agent-api.degov.ai/v2/proposals/p1_eyJkYW9JZCI6ImVucy1kYW8iLCJwcm92aWRlciI6InNuYXBzaG90IiwiZXh0ZXJuYWxJZCI6ImFiYzEyMyJ9"

You get the normalized body, choices, quorum raw value, source and discussion URLs, lifecycle status, and voting window — exactly what an agent needs to explain the proposal.

6. Next steps

  • Want the result of the vote? Call GET /v2/proposals/:proposalKey/votes/summary — see Inspect Proposal Votes.
  • Want per-voter breakdowns? Call GET /v2/proposals/:proposalKey/votes.
  • Want citable provenance and data limitations? Call GET /v2/proposals/:proposalKey/evidence — see Build a Cited Research Brief.
  • Need to resolve a Snapshot/Tally URL or a title you were given outside the API? See Resolve an External Proposal.
Last update: August 5, 2026
Created: August 5, 2026