Delegates API

The Delegates API provides access to governance delegates, their voting power, delegators, and participation statistics.

List Delegates

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://vote.ens.domains/api/v1/delegates?limit=20&sort=voting_power"

Location in code: src/app/api/common/delegates/getDelegates.ts:59

Query Parameters

limit

number

default:"500"

Number of delegates to return (max: 500)

offset

number

default:"0"

Number of delegates to skip for pagination

sort

string

default:"voting_power"

Sort order:

voting_power - Highest voting power first (default)
least_voting_power - Lowest voting power first
most_delegators - Most delegators first
weighted_random - Weighted random order (requires seed)
most_recent_delegation - Most recently delegated to
oldest_delegation - Oldest delegation first
latest_voting_block - Most recent vote first
vp_change_7d - Largest VP increase (7 days)
vp_change_7d_desc - Largest VP decrease (7 days)

seed

number

Random seed for weighted_random sort (must be between 0 and 1)

delegator

string

Filter to delegates that a specific address has delegated to (Ethereum address)

issues

string

Comma-separated list of issues to filter by (from delegate statements)

stakeholders

string

Filter by stakeholder type in delegate statements

endorsed

boolean

Filter to only endorsed delegates

hasStatement

boolean

Filter to delegates with a statement (minimum 10 characters)

showParticipation

boolean

Include participation rate in response

Response

Example Response

{
  "meta": {
    "has_next": true,
    "next_offset": 20,
    "total_returned": 20,
    "total_count": 1542
  },
  "data": [
    {
      "address": "0x1234567890abcdef1234567890abcdef12345678",
      "votingPower": {
        "total": "5000000000000000000000",
        "direct": "4500000000000000000000",
        "advanced": "500000000000000000000"
      },
      "numOfDelegators": "142",
      "statement": {
        "signature": "0xabc...123",
        "payload": {
          "delegateStatement": "I am committed to governance...",
          "topIssues": [
            {"type": "security", "value": "Smart contract security"},
            {"type": "growth", "value": "Protocol growth"}
          ],
          "topStakeholders": [
            {"type": "developers"}
          ]
        },
        "twitter": "@delegate_handle",
        "discord": "delegate#1234",
        "warpcast": null,
        "endorsed": true
      },
      "participation": 87.5,
      "mostRecentDelegationBlock": "18500000",
      "lastVoteBlock": "18525000",
      "vpChange7d": "100000000000000000000"
    }
  ]
}

Get Single Delegate

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://vote.ens.domains/api/v1/delegates/0x1234...5678"

Location in code: src/app/api/common/delegates/getDelegates.ts:647

Path Parameters

address

string

required

Ethereum address or ENS name of the delegate

Response

address

string

Delegate’s Ethereum address

votingPower

object

Voting power breakdown (total, direct, advanced)

votingPowerRelativeToVotableSupply

number

Voting power as percentage of votable supply

votingPowerRelativeToQuorum

number

Voting power as percentage of quorum

proposalsCreated

string

Number of proposals created by this delegate

proposalsVotedOn

string

Number of proposals voted on

votedFor

string

Total FOR votes cast

votedAgainst

string

Total AGAINST votes cast

votedAbstain

string

Total ABSTAIN votes cast

votingParticipation

number

Participation rate (0-1)

lastTenProps

string

Votes on last 10 proposals

numOfDelegators

string

Number of delegators

totalProposals

number

Total proposals in DAO

statement

object

Delegate statement (if exists)

Example Response

{
  "address": "0x1234567890abcdef1234567890abcdef12345678",
  "votingPower": {
    "total": "5000000000000000000000",
    "direct": "4500000000000000000000",
    "advanced": "500000000000000000000"
  },
  "votingPowerRelativeToVotableSupply": 0.025,
  "votingPowerRelativeToQuorum": 1.25,
  "proposalsCreated": "3",
  "proposalsVotedOn": "87",
  "votedFor": "3500000000000000000000",
  "votedAgainst": "1200000000000000000000",
  "votedAbstain": "300000000000000000000",
  "votingParticipation": 0.875,
  "lastTenProps": "8",
  "numOfDelegators": "142",
  "totalProposals": 100,
  "statement": {
    "signature": "0xabc...123",
    "payload": {
      "delegateStatement": "I am committed to responsible governance...",
      "topIssues": [...],
      "topStakeholders": [...]
    },
    "twitter": "@delegate_handle",
    "endorsed": true
  }
}

Delegate Voting Power

Voting power is composed of:

Direct Delegations: Standard ERC-20/ERC-721 delegations
Advanced Delegations: Partial delegations via Alligator (liquid delegation)

votingPower = {
  total: direct + advanced,
  direct: sum of direct delegations,
  advanced: sum of partial delegations
}

Data Sources

Delegate data is fetched from:

DAO Node Service - Primary source with 30s cache
PostgreSQL Views - Fallback and additional metadata
- {namespace}.delegates - Voting power and delegator counts
- {namespace}.voter_stats - Participation metrics
- agora.delegate_statements - Statements and social profiles

Location in code: src/app/api/common/delegates/getDelegates.ts:32

Filtering Examples

Filter by Delegator

Get all delegates that a specific address has delegated to:

GET /api/v1/delegates?delegator=0xYourAddress

Filter by Issues

Find delegates focused on specific issues:

GET /api/v1/delegates?issues=security,growth

Filter by Statement

Only delegates with a statement:

GET /api/v1/delegates?hasStatement=true

Endorsed Delegates Only

GET /api/v1/delegates?endorsed=true

Combined Filters

GET /api/v1/delegates?endorsed=true&hasStatement=true&issues=security&sort=voting_power

Sorting Examples

By Voting Power (Default)

GET /api/v1/delegates?sort=voting_power

By Number of Delegators

GET /api/v1/delegates?sort=most_delegators

By Recent Activity

GET /api/v1/delegates?sort=latest_voting_block

Weighted Random (for fair sampling)

GET /api/v1/delegates?sort=weighted_random&seed=0.42

By VP Change

# Biggest gainers
GET /api/v1/delegates?sort=vp_change_7d

# Biggest losers
GET /api/v1/delegates?sort=vp_change_7d_desc

Delegate Statements

Delegates can publish statements that include:

Delegate Statement: Text description of governance philosophy
Top Issues: Issues they care about (e.g., security, growth, community)
Top Stakeholders: Who they represent (e.g., developers, users, protocols)
Social Profiles: Twitter, Discord, Warpcast handles
Endorsed Status: Whether endorsed by the DAO

Statement Structure

statement: {
  signature: string;           // EIP-712 signature
  payload: {
    delegateStatement: string; // Main statement text
    topIssues: Array<{
      type: string;            // Issue category
      value: string;           // Specific issue
    }>;
    topStakeholders: Array<{
      type: string;            // Stakeholder category
    }>;
  };
  twitter: string | null;      // Twitter handle
  discord: string | null;      // Discord username
  warpcast: string | null;     // Warpcast username
  endorsed: boolean;           // Endorsement status
  created_at: Date;
  updated_at: Date;
}

Delegation Models

The API supports different delegation models:

Direct Delegation (ERC-20)

// Standard token delegation
token.delegate(delegateAddress);

Direct Delegation (ERC-721)

// NFT-based delegation
nft.delegate(delegateAddress);

Partial Delegation (Alligator)

// Delegate a portion of voting power
alligator.subDelegate(toAddress, amount, rules);

Advanced Use Cases

Get Top Delegates

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://vote.ens.domains/api/v1/delegates?limit=10&sort=voting_power"

Get Active Delegates

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://vote.ens.domains/api/v1/delegates?sort=latest_voting_block&limit=50"

Get Delegates with High Participation

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://vote.ens.domains/api/v1/delegates?showParticipation=true&sort=voting_power&limit=100"

Find Delegates for Specific Issues

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://vote.ens.domains/api/v1/delegates?issues=security,privacy&endorsed=true"

Error Responses

Invalid Address Format

{
  "error": "Invalid address format",
  "status": 400
}

Delegate Not Found

{
  "error": "Delegate not found",
  "status": 404
}

Invalid Sort Parameter

{
  "error": "Invalid sort parameter",
  "status": 400
}

Overview

Endpoints

​List Delegates

​Query Parameters

​Response

​Example Response

​Get Single Delegate

​Path Parameters

​Response

​Example Response

​Delegate Voting Power

​Data Sources

​Filtering Examples

​Filter by Delegator

​Filter by Issues

​Filter by Statement

​Endorsed Delegates Only

​Combined Filters

​Sorting Examples

​By Voting Power (Default)

​By Number of Delegators

​By Recent Activity

​Weighted Random (for fair sampling)

​By VP Change

​Delegate Statements

​Statement Structure

​Delegation Models

​Direct Delegation (ERC-20)

​Direct Delegation (ERC-721)

​Partial Delegation (Alligator)

​Advanced Use Cases

​Get Top Delegates

​Get Active Delegates

​Get Delegates with High Participation

​Find Delegates for Specific Issues

​Error Responses

​Invalid Address Format

​Delegate Not Found

​Invalid Sort Parameter

Build docs developers (and LLMs) love

List Delegates

Query Parameters

Response

Example Response

Get Single Delegate

Path Parameters

Response

Example Response

Delegate Voting Power

Data Sources

Filtering Examples

Filter by Delegator

Filter by Issues

Filter by Statement

Endorsed Delegates Only

Combined Filters

Sorting Examples

By Voting Power (Default)

By Number of Delegators

By Recent Activity

Weighted Random (for fair sampling)

By VP Change

Delegate Statements

Statement Structure

Delegation Models

Direct Delegation (ERC-20)

Direct Delegation (ERC-721)

Partial Delegation (Alligator)

Advanced Use Cases

Get Top Delegates

Get Active Delegates

Get Delegates with High Participation

Find Delegates for Specific Issues

Error Responses

Invalid Address Format

Delegate Not Found

Invalid Sort Parameter