DAO API

Manage on-chain governance.

Get DAO Information

GET /dao/:realmId

Retrieve DAO details, treasury, and proposals.

Response


{
  "realmId": "REALM123...",
  "name": "MyToken DAO",
  "symbol": "MTK",
  "type": "community",
  "governance": "GOV456...",
  "treasury": {
    "address": "TRES789...",
    "balances": {
      "MTK": 50000000,
      "SOL": 10.5
    }
  },
  "config": {
    "quorum": 10,
    "passThreshold": 60,
    "votingPeriodHours": 72,
    "minTokensToCreate": 1000000
  },
  "proposals": {
    "total": 5,
    "active": 1,
    "passed": 3,
    "failed": 1
  },
  "voters": 142
}

List Proposals

GET /dao/:realmId/proposals

List all proposals with optional filters.

Query Parameters

Parameter	Type	Description
`status`	string	`active`, `passed`, `failed`, `cancelled`
`limit`	number	Max results (default: 20)
`offset`	number	Pagination offset

Response


{
  "proposals": [
    {
      "proposalId": "PROP123...",
      "title": "Increase Marketing Budget",
      "description": "...",
      "status": "active",
      "createdAt": "2026-02-15T12:00:00Z",
      "votingEndsAt": "2026-02-18T12:00:00Z",
      "creator": "8vP2...",
      "voteResults": {
        "yes": 500000000,
        "no": 100000000,
        "total": 600000000,
        "quorumMet": true
      }
    }
  ],
  "pagination": {
    "total": 5,
    "limit": 20,
    "offset": 0
  }
}

Get Proposal Details

GET /dao/:realmId/proposals/:proposalId

Detailed view of a proposal including votes.

Create Proposal

POST /dao/:realmId/proposal

Submit a new governance proposal.

Request Body


{
  "title": "Proposal Title (max 80 chars)",
  "description": "Detailed description...",
  "type": "treasury_transfer",
  "actions": [
    {
      "type": "transfer",
      "amount": 100000000000,
      "recipient": "WALLET_ADDRESS...",
      "mint": "TOKEN_MINT..."
    }
  ],
  "options": {
    "votingPeriodHours": 48
  }
}

Proposal Types

Type	Actions	Description
`treasury_transfer`	`transfer`	Send tokens from treasury
`config_change`	`set_config`	Modify governance params
`general`	none	Community signaling

Actions

Transfer:


{
  "type": "transfer",
  "amount": 100000000000,
  "recipient": "8vP2...",
  "mint": "TOKEN_MINT..."
}

Set Config:


{
  "type": "set_config",
  "config": {
    "quorum": 15,
    "passThreshold": 65
  }
}

Response


{
  "proposalId": "PROP789...",
  "status": "active",
  "transaction": "5abc...",
  "votingEndsAt": "2026-02-18T12:00:00Z"
}

Cast Vote

POST /dao/:realmId/vote

Vote on an active proposal.

Request Body


{
  "proposal": "PROP789...",
  "vote": "yes",
  "weight": 1000000000  // Optional: specific token amount
}

Vote Options

Value	Description
`yes`	Approve the proposal
`no`	Reject the proposal
`abstain`	Count toward quorum, neutral outcome
`veto`	Council-only rejection

Response


{
  "signature": "5ghi...",
  "vote": "yes",
  "weight": 1000000000,
  "proposal": "PROP789...",
  "votingPower": 1000000000
}

Cancel Proposal

POST /dao/:realmId/proposals/:proposalId/cancel

Cancel a proposal (only by creator before voting starts).

Response


{
  "signature": "5jkl...",
  "status": "cancelled"
}

Execute Proposal

POST /dao/:realmId/proposals/:proposalId/execute

Execute a passed proposal (anyone can trigger after pass).

Response


{
  "signature": "5mno...",
  "status": "executed",
  "results": {
    "transfers": [
      { "amount": 100000000000, "recipient": "8vP2..." }
    ]
  }
}

Withdraw Governance Tokens

POST /dao/:realmId/withdraw

Withdraw tokens deposited for voting.

Request Body


{
  "amount": 1000000000
}

Get Voting Power

GET /dao/:realmId/voting-power/:wallet

Get current voting power for a wallet.

Response


{
  "wallet": "8vP2...",
  "tokenBalance": 1000000000,
  "votingPower": 1000000000,
  "isDeposited": true,
  "canCreateProposal": true
}

Webhook Events

Event	Description
`dao.proposal_created`	New proposal submitted
`dao.vote_cast`	Vote recorded
`dao.proposal_passed`	Proposal passed quorum
`dao.proposal_failed`	Proposal failed/rejected
`dao.proposal_executed`	Proposal executed
`dao.proposal_cancelled`	Proposal cancelled

Examples

Create and Vote on Proposal


async function createAndVote(
  authToken: string,
  realmId: string,
  wallet: string
) {
  // Create proposal
  const proposal = await fetch(
    `https://etch.film.fun/api/dao/${realmId}/proposal`,
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${authToken}`,
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        title: "Community Grant #1",
        description: "Send 100K tokens to marketing team",
        type: "treasury_transfer",
        actions: [{
          type: "transfer",
          amount: 100000000000,
          recipient: "MARKETING_WALLET...",
          mint: "YOUR_TOKEN_MINT..."
        }]
      })
    }
  ).then(r => r.json());
  
  console.log(`Created: ${proposal.proposalId}`);
  
  // Vote yes
  const vote = await fetch(
    `https://etch.film.fun/api/dao/${realmId}/vote`,
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${authToken}`,
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        proposal: proposal.proposalId,
        vote: "yes"
      })
    }
  ).then(r => r.json());
  
  console.log(`Voted: ${vote.signature}`);
}

Error Codes

Code	Description
`proposal_not_found`	Proposal doesn’t exist
`already_voted`	Wallet already voted
`voting_ended`	Proposal period closed
`insufficient_tokens`	Not enough tokens to create proposal
`not_authorized`	Not proposal creator
`not_executable`	Proposal conditions not met