Skip to main content
The Agora API provides programmatic access to DAO governance data including proposals, delegates, votes, and analytics. The API is built on Next.js and uses PostgreSQL for data storage with Prisma ORM.

​
Base URL

All API requests should be made to: 
https://vote.{dao-domain}/api/v1
For example:
  • ENS: https://vote.ens.domains/api/v1
  • Optimism: https://vote.optimism.io/api/v1
  • Uniswap: https://vote.uniswap.org/api/v1

​
Authentication

All API endpoints require authentication using either:
  • API Key (recommended for server-to-server)
  • JWT Token (for wallet-based authentication)
See the Authentication page for details.

​
Response Format

All API responses follow a consistent JSON format:

​
Success Response

{
  "meta": {
    "has_next": true,
    "next_offset": 10,
    "total_returned": 10,
    "total_count": 245
  },
  "data": [...]
}

​
Error Response

{
  "error": "Error description",
  "status": 400
}

​
Pagination

Most list endpoints support pagination using query parameters:
​
limit
number
default:"10"
Number of items to return (max: 50-1000 depending on endpoint)
​
offset
number
default:"0"
Number of items to skip

​
Example

GET /api/v1/proposals?limit=20&offset=40

​
Rate Limiting

API rate limits are enforced per API key:
  • Rate limits are configured per tenant and API user
  • Monitor your usage through provider dashboards
  • Contact support if you need higher limits

​
Error Handling

The API uses standard HTTP status codes:
Status CodeDescription
200Success
400Bad Request - Invalid parameters
401Unauthorized - Missing or invalid authentication
404Not Found - Resource doesn’t exist
500Internal Server Error

​
Common Error Responses

Invalid Query Parameters 
{
  "error": "Invalid query parameters: limit must be between 1 and 50",
  "status": 400
}
Authentication Required 
{
  "error": "Missing or invalid bearer token",
  "status": 401
}
Internal Server Error 
{
  "error": "Internal server error: [error details]",
  "status": 500
}

​
Data Sources

The API aggregates data from multiple sources:
  1. PostgreSQL Database - Primary data store with views and materialized views
  2. DAO Node Service - External service for delegate and proposal data
  3. Snapshot - Off-chain voting data
  4. Blockchain RPC - On-chain data via Alchemy

​
Environment Configuration

The API behavior varies based on the tenant configuration:
  • NEXT_PUBLIC_AGORA_INSTANCE_NAME - Determines DAO configuration
  • NEXT_PUBLIC_AGORA_ENV - Controls prod vs dev environment
  • Database URLs are environment-specific (prod vs dev)
See the README for full environment variable documentation.

​
Getting Started

  1. Generate an API key
  2. Make your first request to /api/v1/proposals
  3. Explore other endpoints for delegates, votes, and analytics

​
SDK and Libraries

Currently, there are no official SDKs. You can use any HTTP client: 
# cURL
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://vote.ens.domains/api/v1/proposals

// JavaScript/Node.js
const response = await fetch('https://vote.ens.domains/api/v1/proposals', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});
const data = await response.json();

# Python
import requests

response = requests.get(
    'https://vote.ens.domains/api/v1/proposals',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)
data = response.json()

​
Support

For API support:
  • Review the endpoint documentation
  • Check error messages for guidance
  • Contact the Agora team via Discord

Build docs developers (and LLMs) love

Get started for freeTalk to us