> ## Documentation Index
> Fetch the complete documentation index at: https://trench-446767c3.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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                          |

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

## 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.

```bash theme={null}
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](/concepts/authentication) 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](/concepts/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](/guides/connect-flow) |
| `POST` | `/oauth/token`     | Client credentials     | [Token](/api-reference/oauth-token)    |
| `POST` | `/oauth/revoke`    | Client credentials     | [Revoke](/api-reference/oauth-revoke)  |

## Reads

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

| Method | Path                                                | Scope          | Page                                               |
| ------ | --------------------------------------------------- | -------------- | -------------------------------------------------- |
| `GET`  | `/partner/v1/me`                                    | `profile:read` | [Me](/api-reference/me)                            |
| `GET`  | `/partner/v1/governance/{mint}`                     | None           | [Governance Reads](/api-reference/governance-read) |
| `GET`  | `/partner/v1/governance/proposals/{proposal}/votes` | None           | [Governance Reads](/api-reference/governance-read) |

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](/api-reference/trades) 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](/api-reference/governance-vote).

## 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](/api-reference/governance-propose).

## Shared Conventions

### Amounts

Every amount is an integer string in base units, using lamports for SOL and 1e6 units for tokens. See [Amount Conventions](/concepts/amounts).

### 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](/concepts/partner-fees).

### Write Responses

Every write returns a signature and a status.

```json theme={null}
{ "signature": "…", "mint": "…", "status": "submitted" }
```

<Warning>
  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.
</Warning>

### 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](/concepts/errors).

```json theme={null}
{ "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.