DocumentationapiProposals API

Proposals API

Endpoints for managing and querying governance proposals.

List Proposals

Get all proposals with optional filters.

GET /api/proposals

Query Parameters

Filter by state: voting, succeeded, defeated, executed.

Filter by type: standard, expedited, emergency.

Filter by proposer address.

Maximum results.

Pagination offset.

Response

{
  "proposals": [
    {
      "id": "abc123",
      "title": "Treasury Allocation for Development Fund",
      "description": "Allocate 5% of treasury...",
      "type": "standard",
      "state": "voting",
      "proposer": "7xKXtg2C...",
      "forVotes": 150000,
      "againstVotes": 45000,
      "abstainVotes": 5000,
      "quorumRequired": 250000,
      "votingStart": "2024-02-01T00:00:00Z",
      "votingEnd": "2024-02-08T00:00:00Z",
      "timeLockExpiry": "2024-02-10T00:00:00Z"
    }
  ],
  "total": 45,
  "limit": 20,
  "offset": 0
}

Get Proposal

Get a single proposal by ID.

GET /api/proposals/:id

Response

{
  "id": "abc123",
  "title": "Treasury Allocation for Development Fund",
  "description": "## Summary\n\nAllocate 5% of treasury...",
  "type": "standard",
  "state": "voting",
  "proposer": {
    "address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "tier": "gold",
    "fairscore": 78
  },
  "forVotes": 150000,
  "againstVotes": 45000,
  "abstainVotes": 5000,
  "quorumRequired": 250000,
  "totalVotingPower": 1350000,
  "votingStart": "2024-02-01T00:00:00Z",
  "votingEnd": "2024-02-08T00:00:00Z",
  "timeLockExpiry": "2024-02-10T00:00:00Z",
  "createdAt": "2024-02-01T00:00:00Z",
  "updatedAt": "2024-02-03T15:30:00Z"
}

Create Proposal

Create a new governance proposal.

POST /api/proposals

Request Body

{
  "type": "standard",
  "title": "Treasury Allocation for Development Fund",
  "description": "## Summary\n\nAllocate 5% of treasury to development...",
  "proposer": "7xKXtg2C...",
  "signature": "..."
}

Response

{
  "success": true,
  "data": {
    "id": "abc124",
    "title": "Treasury Allocation for Development Fund",
    "state": "voting",
    "votingEnd": "2024-02-08T00:00:00Z",
    "timeLockExpiry": "2024-02-10T00:00:00Z"
  }
}

Cast Vote

Cast a vote on a proposal.

POST /api/proposals/:id/votes

Request Body

{
  "voter": "7xKXtg2C...",
  "vote": "for",
  "signature": "..."
}

Response

{
  "success": true,
  "data": {
    "vote": "for",
    "votingPower": 256,
    "proposalState": "voting",
    "forVotes": 150256,
    "againstVotes": 45000
  }
}

Get Proposal Votes

Get all votes for a proposal.

GET /api/proposals/:id/votes

Query Parameters

Maximum results.

Response

{
  "votes": [
    {
      "voter": "7xKXtg2C...",
      "vote": "for",
      "votingPower": 256,
      "fairscoreAtVote": 78,
      "timestamp": "2024-02-02T10:30:00Z"
    }
  ],
  "total": 156
}

Finalize Proposal

Finalize a proposal after voting ends.

POST /api/proposals/:id/finalize

Response

{
  "success": true,
  "data": {
    "state": "succeeded",
    "forVotes": 180000,
    "againstVotes": 45000,
    "quorumReached": true
  }
}

Execute Proposal

Execute a succeeded proposal.

POST /api/proposals/:id/execute

Response

{
  "success": true,
  "data": {
    "state": "executed",
    "executedAt": "2024-02-10T00:05:00Z"
  }
}
API OverviewCircuit Breaker