API Reference

Every Trench OAuth and Partner API endpoint in one index, with the scope each one requires, its rate limit, and the conventions shared across all of them.

The Partner API consists of seventeen endpoints that accept and return JSON, authenticated with a single bearer header. Any operation that changes on-chain state is carried out through a Solana transaction that Trench builds, signs with the user’s delegated wallet, and submits.

Hosts

Host	Serves
https://tren.ch	The consent screen at /oauth/authorize
https://api.tren.ch	Everything else

The API host is not yet final. Please confirm it with the Trench team before going live.

Authentication

OAuth endpoints authenticate with your client_id and an API key over HTTP Basic, while everything under /partner/v1/ takes a user access token. Never send an API key on a Partner API call, since the access token already identifies your app.

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

The header is checked against the trench_at_ prefix before any lookup happens. See Tokens & Refresh for lifetimes and rotation.

Every Partner API call also draws on your app’s tier budget, which is 120 requests per minute on Basic and 1,200 on Partner. The per-route limits below sit underneath it. See Rate Limits.

OAuth

These endpoints are keyed by IP at 30 requests per minute.

Method	Path	Auth	Page
GET	/oauth/authorize	None, browser redirect	Connect a User
POST	/oauth/token	Client credentials	Token
POST	/oauth/revoke	Client credentials	Revoke

Reads

Read endpoints allow 300 requests per minute, keyed by access token.

Method	Path	Scope	Page
GET	/partner/v1/me	profile:read	Me
GET	/partner/v1/governance/{mint}	None	Governance Reads
GET	/partner/v1/governance/proposals/{proposal}/votes	None	Governance Reads

Governance reads require no scope, because proposals and tallies mirror public on-chain state.

Trades

Trade endpoints allow 60 requests per minute, and all three require trade:execute.

Method	Path	Purpose
POST	/partner/v1/trades/buy	Spend up to a SOL budget
POST	/partner/v1/trades/buy-exact-out	Buy an exact token quantity
POST	/partner/v1/trades/sell	Sell tokens for SOL

Each one accepts two body shapes. Sending slippageBps has Trench quote the trade and derive the bound for you, while omitting it means supplying minTokensOut or minSolOut yourself. All three resolve the token’s venue per request, so the same call works on the bonding curve and on the Raydium pool it later migrates to.

See Trade endpoints for field constraints.

Governance Votes

These endpoints allow 60 requests per minute, and all four require governance:vote.

Method	Path	Purpose
POST	/partner/v1/governance/votes	Cast a vote, locking tokens as weight
POST	/partner/v1/governance/votes/cancel	Cancel an active vote
POST	/partner/v1/governance/votes/withdraw	Reclaim locked tokens after settlement
POST	/partner/v1/governance/proposals/settle	Compute and apply a closed proposal’s outcome

See Voting endpoints.

Governance Proposals

These endpoints allow 60 requests per minute, and all five require governance:propose.

Method	Path	Purpose
POST	/partner/v1/governance/proposals/update-content	Propose a metadata change
POST	/partner/v1/governance/proposals/extend-mutability	Propose extending the mutable window
POST	/partner/v1/governance/proposals/finalize-metadata	Propose locking metadata permanently
POST	/partner/v1/governance/metadata/finalize-expired	Lock metadata whose window already expired
POST	/partner/v1/governance/bonds/withdraw	Reclaim a proposal bond after settlement

See Proposal endpoints.

Shared Conventions

Amounts

Every amount is an integer string in base units, using lamports for SOL and 1e6 units for tokens. See Amount Conventions.

Network Fees

Every write takes priorityFeeLamports with a minimum of 1,000 and tipLamports with a minimum of 1,000,000. Both are spent whether or not the operation succeeds.

Partner Fees

The three trade endpoints also accept an optional partnerFeeBps, which pays you a cut of the trade in the same transaction. See Partner Fees.

Write Responses

Every write returns a signature and a status.

{ "signature": "…", "mint": "…", "status": "submitted" }

The status vocabulary differs between the two families, with trades returning "submitted" and governance writes returning "processed". Neither indicates that the transaction is rooted, so we recommend confirming the signature against Solana through your own RPC rather than branching on the literal string.

Idempotency

No Partner API write accepts an idempotency key, which means a blind retry after a timeout can execute the same operation twice. Reconcile against the chain instead.

Errors

Every error is JSON with a stable error code, which is what you should match on rather than message. See Error Handling.

{ "error": "insufficient_sol", "message": "…", "retryable": false }

Request Size

Constraint	Limit
JSON body	64 KiB
Uploaded file	5 MiB
Files per request	4
Form fields per request	16

The only endpoint that accepts a file is proposals/update-content, which takes at most one image.