Read and Participate in Governance

Token metadata on Trench is governed on-chain. Holders vote on changes to a token’s name, symbol, image, and links, and on whether to lock that metadata permanently. Governance splits cleanly in two. Reads require no scope, because proposals and tallies mirror public on-chain state, and only writes are gated.

Endpoints Used

Reading a Token’s Governance

curl "https://api.tren.ch/partner/v1/governance/$MINT" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

const res = await fetch(`https://api.tren.ch/partner/v1/governance/${mint}`, {
  headers: { Authorization: `Bearer ${accessToken}` },
});

const { governance, proposals, viewerVotes } = await res.json();

import requests

res = requests.get(
  f"https://api.tren.ch/partner/v1/governance/{mint}",
  headers={"Authorization": f"Bearer {access_token}"},
)

data = res.json()

A single call returns everything needed to render a governance UI: the config, up to 100 proposals newest first, and the connected user’s own votes. If the token has no governance, the endpoint responds with 404 governance_not_found.

{
  "governance": {
    "governance": "…", "mint": "…", "creator": "…",
    "totalSupply": "…", "mutableUntilUnix": "…",
    "minVoterCount": 25, "minLockAmount": "…",
    "minParticipatingSupplyBps": 1500, "approvalBps": 6600,
    "proposalBondBps": 100, "finalized": false,
    "contentRevision": "0", "mutabilityExtended": false,
    "nameLocked": false, "symbolLocked": false, "imageLocked": false,
    "descriptionLocked": false, "websiteLocked": false,
    "twitterLocked": false, "telegramLocked": false
  },
  "proposals": [ { "…": "…" } ],
  "viewerVotes": [ { "…": "…" } ]
}

See Governance reads for a description of every field.

The viewerVotes array contains the connected user’s own votes, derived from the access token rather than from a caller-supplied address. You can use it to show that a user has already voted without making a second request and without requesting a scope.

What the Config Parameters Mean

Four parameters determine whether a proposal can pass, and we recommend surfacing them in your UI before a user commits tokens to a vote.

Parameter	Controls
`minVoterCount`	Distinct qualifying voters required
`minParticipatingSupplyBps`	Share of total supply that must vote, in basis points
`approvalBps`	Share of cast weight that must be `yes`, in basis points
`minLockAmount`	Smallest vote that counts toward the voter count

Basis points are hundredths of a percent, so 6600 is 66% and 1500 is 15%. A proposal must clear both participation thresholds as well as the approval threshold. This means a change with overwhelming support can still fail for lack of turnout, which is the outcome most worth explaining to users.

The Mutability Window

Every token launches with a finite window during which its metadata can be changed at all. After mutableUntilUnix passes, metadata locks permanently whether or not anyone votes.

The window can be extended once by proposal. A second attempt returns mutability_already_extended.
Extensions are capped, and an over-long request returns mutability_extension_exceeds_cap.
Holders can end the window early by passing a finalize-metadata proposal.
Individual fields lock independently, so check the *Locked flags before offering an edit.

A proposal cannot outlive the window. If voteDurationSeconds would run past mutableUntilUnix, creation fails with vote_duration_exceeds_window, and proposals submitted too close to the deadline fail with proposal_window_closing.

Voting

Voting requires the governance:vote scope.

cURL

curl -X POST 'https://api.tren.ch/partner/v1/governance/votes' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "proposal": "…",
    "side": "yes",
    "amount": "1000000",
    "priorityFeeLamports": "20000",
    "tipLamports": "1000000"
  }'

Vote weight is the token amount locked, which means voting locks those tokens for the duration of the proposal. Users reclaim them with votes/withdraw after settlement.

Locked tokens cannot be traded, and users who are not aware of this tend to read it as missing balance. We recommend showing both the locked amount and when it can be reclaimed.

A second vote on the same proposal returns already_voted. To change a vote, cancel the existing one first. See Voting endpoints for cancel, withdraw, and settle.

Settling

Voting coming to an end does not apply the result. Someone has to call proposals/settle, which computes the outcome and executes the action if the proposal passed. The operation is permissionless, so any token holder with governance:vote can crank it, including yours. Until a proposal is settled, bonds and locked vote tokens remain locked. If your product surfaces governance, settling closed proposals on your users’ behalf is a genuinely useful thing to offer.

Proposing

Proposing requires the governance:propose scope. Creating a proposal locks a bond from the user’s wallet, sized at proposalBondBps of supply, which is reclaimed with bonds/withdraw after settlement. Only one proposal can be active per governance at a time, and a second returns active_proposal_exists.

The voteDurationSeconds field defaults to 600 seconds, which is ten minutes and far too short for a real governance decision. We recommend setting it explicitly on every proposal.

Changing Metadata

The proposals/update-content endpoint is the only multipart endpoint in the Partner API, because it can carry a new image. Send only the fields you want to change, since omitted fields are left alone and empty strings clear text fields.

cURL

curl -X POST 'https://api.tren.ch/partner/v1/governance/proposals/update-content' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -F mint=… \
  -F voteDurationSeconds=86400 \
  -F priorityFeeLamports=20000 \
  -F tipLamports=1000000 \
  -F name="New Name" \
  -F image=@logo.png

Proposals are authored against a contentRevision. If another proposal lands first, yours becomes stale and fails with stale_content_revision. Re-read the governance, rebase the change set, and have the user confirm before resubmitting, since silently resubmitting can spend their bond on a change they did not intend.

Validation failures on website, twitter, and telegram currently surface as 500 internal rather than 400, and they are permanent rather than transient. We recommend validating these three fields on your own side before submitting. See Error Handling.

See Proposal endpoints for extend-mutability, finalize-metadata, and bond withdrawal.

Write Responses

All governance writes respond in the same shape, with identifiers included where they apply.

{ "signature": "…", "status": "processed", "mint": "…", "governance": "…", "proposal": "…" }

A status of processed means the transaction was included in a block, not that it is rooted. Confirm the signature against Solana through your own RPC before telling a user their vote counted.

The update-content endpoint additionally returns metadataUri and imageUri for the newly pinned content.

Get Started

Principles

How-to Guides

Read and Participate in Governance

Endpoints Used

Reading a Token’s Governance

What the Config Parameters Mean

The Mutability Window

Voting

Settling

Proposing

Changing Metadata

Write Responses

​Endpoints Used

​Reading a Token’s Governance

​What the Config Parameters Mean

​The Mutability Window

​Voting

​Settling

​Proposing

​Changing Metadata

​Write Responses

Endpoints Used

Reading a Token’s Governance

What the Config Parameters Mean

The Mutability Window

Voting

Settling

Proposing

Changing Metadata

Write Responses