{ "openapi": "3.1.1", "info": { "title": "DAO Governance Explorer API", "version": "1.0.0", "summary": "Snapshot proposals, vote concentration, Governor state and treasury balances in one view.", "description": "Every endpoint performs the same calculation as the human page and returns inputs, result, units, assumptions, sources, warnings and computedAt. MCP endpoint: /mcp." }, "servers": [ { "url": "https://daogovernanceexplorer.usefulweb.site" } ], "paths": { "/api/v1/calculate": { "post": { "operationId": "calculate", "summary": "Snapshot proposals, vote concentration, Governor state and treasury balances in one view.", "description": "Reads a DAO's Snapshot space (proposals, state, scores, quorum, top voters and how concentrated voting power is), optionally an OpenZeppelin Governor proposal on-chain (state, for/against/abstain, quorum) and a treasury address's native and major-token balances. Works offline with pasted Snapshot GraphQL JSON.\n\nMethodology:\n- Snapshot data comes from the public Snapshot hub GraphQL API (POST https://hub.snapshot.org/graphql): space metadata and strategies, the newest proposals, and up to 1,000 votes of one proposal ordered by voting power.\n- Leading choice and share = highest score / scores_total; quorum reached = scores_total ≥ quorum (only when the space sets a quorum; some spaces count quorum differently, e.g. only \"For\").\n- Concentration: top-10 share of cast voting power and the Nakamoto coefficient (fewest voters whose combined VP exceeds 50 %). Based on the votes returned (max 1,000, largest first), so it is exact for proposals with ≤ 1,000 votes.\n- Delegation: Snapshot strategies named \"delegation\" and the space's delegation portal (type + contract) are reported; individual delegate graphs live in other indexers and are not fetched.\n- Governor: eth_call of state(uint256), proposalVotes(uint256) (GovernorCountingSimple: against, for, abstain), proposalSnapshot, proposalDeadline, quorum(snapshot) and name(). State enum: Pending, Active, Canceled, Defeated, Succeeded, Queued, Expired, Executed. Quorum reached = for + abstain ≥ quorum (OpenZeppelin counting).\n- Treasury: native balance plus balanceOf for the canonical USDC/USDT/WETH/DAI contracts of that chain and any extra token addresses you add. No USD valuation.", "tags": [ "web3" ], "x-mcp-tool": "dao_governance_explorer", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DaoGovernanceExplorerInput" }, "examples": { "example1": { "summary": "Snapshot space with an active proposal (offline)", "value": { "snapshotJson": "{\"data\":{\"space\":{\"id\":\"example-dao.eth\",\"name\":\"Example DAO\",\"network\":\"1\",\"symbol\":\"EXD\",\"followersCount\":1200,\"proposalsCount\":42,\"strategies\":[{\"name\":\"delegation\",\"network\":\"1\",\"params\":{\"symbol\":\"EXD (delegated)\"}},{\"name\":\"erc20-votes\",\"network\":\"1\",\"params\":{\"symbol\":\"EXD\"}}],\"delegationPortal\":{\"delegationType\":\"compound-governor\",\"delegationContract\":\"0x1111111111111111111111111111111111111111\"}},\"proposals\":[{\"id\":\"0xp2\",\"title\":\"Fund grants program Q4\",\"state\":\"active\",\"author\":\"0xaAaAaAaaAaAaAaaAaAAAAAAAAaaaAaAaAaaAaaAa\",\"start\":1791500000,\"end\":1792100000,\"type\":\"basic\",\"choices\":[\"For\",\"Against\",\"Abstain\"],\"scores\":[620000,300000,80000],\"scores_total\":1000000,\"votes\":9,\"quorum\":1500000},{\"id\":\"0xp1\",\"title\":\"Adopt treasury diversification policy\",\"state\":\"closed\",\"author\":\"0xbBbBBBBbbBBBbbbBbbBbbbbBBbBbbbbBbBbbBBbB\",\"start\":1790000000,\"end\":1790600000,\"type\":\"single-choice\",\"choices\":[\"Yes\",\"No\"],\"scores\":[2100000,400000],\"scores_total\":2500000,\"votes\":310,\"quorum\":1000000}],\"votes\":[{\"voter\":\"0x1000000000000000000000000000000000000001\",\"vp\":300000,\"choice\":1},{\"voter\":\"0x1000000000000000000000000000000000000002\",\"vp\":250000,\"choice\":2},{\"voter\":\"0x1000000000000000000000000000000000000003\",\"vp\":150000,\"choice\":1},{\"voter\":\"0x1000000000000000000000000000000000000004\",\"vp\":120000,\"choice\":1},{\"voter\":\"0x1000000000000000000000000000000000000005\",\"vp\":80000,\"choice\":3},{\"voter\":\"0x1000000000000000000000000000000000000006\",\"vp\":50000,\"choice\":2},{\"voter\":\"0x1000000000000000000000000000000000000007\",\"vp\":30000,\"choice\":1},{\"voter\":\"0x1000000000000000000000000000000000000008\",\"vp\":15000,\"choice\":1},{\"voter\":\"0x1000000000000000000000000000000000000009\",\"vp\":5000,\"choice\":1}]}}", "chain": "ethereum" } } } } } }, "responses": { "200": { "description": "Calculation result envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DaoGovernanceExplorerResult" } } } }, "400": { "description": "Malformed JSON body.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid input (see errors[]).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded (see Retry-After).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/tool": { "get": { "operationId": "getToolDefinition", "summary": "Inputs, output schema and examples for this tool", "responses": { "200": { "description": "Tool definition.", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "components": { "schemas": { "Problem": { "type": "object", "description": "RFC 9457 problem details. 422 responses include per-field `errors`.", "required": [ "type", "title", "status", "detail" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "DaoGovernanceExplorerInput": { "type": "object", "additionalProperties": false, "properties": { "space": { "title": "Snapshot space", "description": "Space id as in snapshot.box/#/s:.", "type": "string", "maxLength": 100 }, "snapshotProposalId": { "title": "Snapshot proposal id for vote analysis (optional)", "description": "Defaults to the newest proposal of the space.", "type": "string", "maxLength": 100 }, "proposals": { "title": "Proposals to list", "type": "integer", "minimum": 1, "maximum": 50, "default": 10 }, "snapshotJson": { "title": "Pasted Snapshot JSON (offline)", "description": "GraphQL response with data.space, data.proposals and optionally data.votes. Used instead of the live query.", "type": "string", "maxLength": 1000000 }, "chain": { "title": "Chain (Governor / treasury)", "type": "string", "enum": [ "ethereum", "base", "arbitrum", "optimism", "polygon", "avalanche", "bsc" ], "default": "ethereum" }, "governor": { "title": "Governor contract (optional)", "type": "string", "maxLength": 42 }, "governorProposalId": { "title": "Governor proposal id (decimal)", "type": "string", "maxLength": 80 }, "treasury": { "title": "Treasury address (optional)", "type": "string", "maxLength": 42 }, "extraTokens": { "title": "Extra token addresses for the treasury", "type": "array", "items": { "type": "string" }, "maxItems": 8 } }, "required": [] }, "DaoGovernanceExplorerResult": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "tool", "computedAt", "inputs", "summary", "result", "units", "assumptions", "sources", "warnings", "presentation", "links" ], "properties": { "schemaVersion": { "type": "string", "const": "1.0" }, "tool": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "version" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" } } }, "computedAt": { "type": "string", "format": "date-time" }, "inputs": { "type": "object", "description": "Normalised inputs actually used, including applied defaults." }, "summary": { "type": "string" }, "result": { "type": "object", "additionalProperties": false, "required": [ "space", "proposals", "voteAnalysis", "governor", "treasury" ], "properties": { "space": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "id", "name", "network", "symbol", "followers", "proposalsCount", "strategies", "delegation" ], "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "network": { "type": [ "string", "null" ] }, "symbol": { "type": [ "string", "null" ] }, "followers": { "type": [ "integer", "null" ] }, "proposalsCount": { "type": [ "integer", "null" ] }, "strategies": { "type": "array", "items": { "type": "string" } }, "delegation": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "usesDelegationStrategy", "type", "contract" ], "properties": { "usesDelegationStrategy": { "type": "boolean" }, "type": { "type": [ "string", "null" ] }, "contract": { "type": [ "string", "null" ] } } } } }, "proposals": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "title", "state", "author", "start", "end", "type", "choices", "scores", "scoresTotal", "votes", "quorum", "quorumReached", "leadingChoice", "leadingShare" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "state": { "type": "string" }, "author": { "type": [ "string", "null" ] }, "start": { "type": [ "string", "null" ] }, "end": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "choices": { "type": "array", "items": { "type": "string" } }, "scores": { "type": "array", "items": { "type": "number" } }, "scoresTotal": { "type": "number" }, "votes": { "type": "integer" }, "quorum": { "type": "number" }, "quorumReached": { "type": [ "boolean", "null" ] }, "leadingChoice": { "type": [ "string", "null" ] }, "leadingShare": { "type": [ "number", "null" ] } } } }, "voteAnalysis": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "proposalId", "votesAnalysed", "totalVp", "top10Share", "nakamoto", "topVoters" ], "properties": { "proposalId": { "type": "string" }, "votesAnalysed": { "type": "integer" }, "totalVp": { "type": "number" }, "top10Share": { "type": "number" }, "nakamoto": { "type": [ "integer", "null" ] }, "topVoters": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "voter", "vp", "share", "choice" ], "properties": { "voter": { "type": "string" }, "vp": { "type": "number" }, "share": { "type": "number" }, "choice": { "type": "string" } } } } } }, "governor": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "address", "name", "proposalId", "state", "stateName", "votes", "snapshot", "deadline", "quorum", "quorumReached" ], "properties": { "address": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "proposalId": { "type": "string" }, "state": { "type": [ "integer", "null" ] }, "stateName": { "type": [ "string", "null" ] }, "votes": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "against", "for", "abstain" ], "properties": { "against": { "type": "string" }, "for": { "type": "string" }, "abstain": { "type": "string" } } }, "snapshot": { "type": [ "string", "null" ] }, "deadline": { "type": [ "string", "null" ] }, "quorum": { "type": [ "string", "null" ] }, "quorumReached": { "type": [ "boolean", "null" ] } } }, "treasury": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "address", "chain", "nativeSymbol", "nativeWei", "native", "tokens" ], "properties": { "address": { "type": "string" }, "chain": { "type": "string" }, "nativeSymbol": { "type": "string" }, "nativeWei": { "type": "string" }, "native": { "type": "string" }, "tokens": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "token", "symbol", "raw", "balance" ], "properties": { "token": { "type": "string" }, "symbol": { "type": [ "string", "null" ] }, "raw": { "type": [ "string", "null" ] }, "balance": { "type": [ "string", "null" ] } } } } } } } }, "units": { "type": "object", "additionalProperties": { "type": "string" } }, "assumptions": { "type": "array", "items": { "type": "string" } }, "sources": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "title" ], "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "publisher": { "type": "string" }, "retrievedAt": { "type": "string" }, "note": { "type": "string" } } } }, "warnings": { "type": "array", "items": { "type": "string" } }, "presentation": { "type": "array", "items": { "type": "object" }, "description": "Display blocks used by the human page (same data)." }, "links": { "type": "object", "additionalProperties": false, "required": [ "human", "api", "openapi", "methodology" ], "properties": { "human": { "type": "string", "format": "uri" }, "api": { "type": "string", "format": "uri" }, "openapi": { "type": "string", "format": "uri" }, "methodology": { "type": "string", "format": "uri" } } } } } } } }