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

# Trench Partner API

> Connect Trench users to your app and trade or vote on their behalf, without touching their keys.

Trench is a token launchpad on Solana. The Partner API lets your users connect their Trench account to your application so that you can buy, sell, and vote on token governance from inside your own product.

Your application never holds or handles user keys. Trench builds each transaction and signs it with the user's delegated wallet once they have approved your app.

On the Partner tier you can also take a cut of every trade you route, paid to a wallet you register with Trench in the same transaction as the trade. See [Partner Fees](/concepts/partner-fees).

## Getting Started

Authentication uses OAuth 2.0 Authorization Code with PKCE, so if you have implemented "Sign in with Google" before, the flow will look familiar.

<Steps>
  <Step title="Register your app">
    Sign in at [tren.ch/partner](https://tren.ch/partner), name your app, set a redirect URI, and pick your scopes. You get a `client_id` and an API key straight away, with no review step. See [Registration](/concepts/registration) for details.
  </Step>

  <Step title="Connect a user">
    Open the consent popup, then exchange the authorization code it returns for a token pair on your backend. See [Connect a User](/guides/connect-flow).
  </Step>

  <Step title="Call the API">
    Send the access token as a bearer header on every request to `/partner/v1/*`.
  </Step>
</Steps>

## Base URLs

* **Consent screen**: `https://tren.ch`
* **API**: `https://api.tren.ch`

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

## Authentication

Every Partner API call takes a single header. You do not need to send your API key, the user's wallet address, or sign anything yourself.

<CodeGroup>
  ```bash cURL theme={null}
  curl 'https://api.tren.ch/partner/v1/me' \
    -H 'Authorization: Bearer trench_at_YOUR_ACCESS_TOKEN'
  ```

  ```javascript Node.js theme={null}
  const res = await fetch('https://api.tren.ch/partner/v1/me', {
    headers: { Authorization: `Bearer ${accessToken}` }
  });

  const me = await res.json();
  ```

  ```python Python theme={null}
  import requests

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

  me = res.json()
  ```
</CodeGroup>

Access tokens are issued per user rather than per application, so every user who connects gets their own pair, which you store against your own user record.

## Credentials

| Credential         | Prefix       | Lifetime            | Used at                         |
| ------------------ | ------------ | ------------------- | ------------------------------- |
| Client ID          | `tclient_`   | Permanent           | Authorize URL                   |
| API key            | `trench_cs_` | Until you revoke it | `/oauth/token`, `/oauth/revoke` |
| Authorization code | `trench_ac_` | 10 minutes          | `/oauth/token`, once            |
| Access token       | `trench_at_` | 30 minutes          | Every `/partner/v1/*` call      |
| Refresh token      | `trench_rt_` | 60 days             | `/oauth/token`                  |

When an access token expires, your backend can refresh it silently. Each refresh mints a new 60-day refresh token, which means an actively used connection will never force the user to reconnect.

## Scopes

Request only the scopes your integration needs. Each one is shown to the user on the consent screen, and high-risk scopes are flagged.

| Scope                | Grants                                       | Risk |
| -------------------- | -------------------------------------------- | ---- |
| `profile:read`       | Wallet address, X handle, trading status     | Low  |
| `trade:execute`      | Buys and sells                               | High |
| `governance:vote`    | Vote, cancel, withdraw locked tokens, settle | High |
| `governance:propose` | Create proposals, withdraw bonds             | High |

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

Three further scopes exist in the registry but are hidden, and cannot be selected when you register. See [Scopes](/concepts/scopes).

## Rate Limits

Your app has a budget across all Partner API endpoints, and individual routes carry their own per-user limits underneath it.

* **Tier budget**: 120 requests per minute on Basic, 1,200 on Partner
* **Reads**: 300 requests per minute, per user
* **Writes**: 60 requests per minute, per user
* **OAuth**: 30 requests per minute, per IP

The tier budget is shared across your whole user base, so it is usually the limit you meet first. See [Rate Limits](/concepts/rate-limits).

## Core Principles

<Columns cols={2}>
  <Card title="Registration" icon="id-card" href="/concepts/registration">
    Self-serve registration, tiers, API keys, and redirect URIs.
  </Card>

  <Card title="Scopes" icon="shield-check" href="/concepts/scopes">
    What each scope grants and which endpoints it gates.
  </Card>

  <Card title="Tokens & Refresh" icon="key" href="/concepts/authentication">
    Lifetimes, rotation, and the reuse rules that end a connection.
  </Card>

  <Card title="Amount Conventions" icon="calculator" href="/concepts/amounts">
    Lamports, base units, and fee minimums.
  </Card>

  <Card title="Error Handling" icon="triangle-alert" href="/concepts/errors">
    Stable error codes and which ones are worth retrying.
  </Card>

  <Card title="Rate Limits" icon="gauge" href="/concepts/rate-limits">
    Your tier budget, the per-endpoint limits, and how buckets are keyed.
  </Card>

  <Card title="Partner Fees" icon="percent" href="/concepts/partner-fees">
    Charge your own rate per trade and get paid on-chain.
  </Card>

  <Card title="Security Requirements" icon="lock" href="/concepts/security">
    PKCE, state, and refresh token handling before you ship.
  </Card>
</Columns>

## Guides

<Columns cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    From registering an app to a confirmed buy.
  </Card>

  <Card title="Connect a User" icon="link" href="/guides/connect-flow">
    PKCE, the popup, your callback, and the code exchange.
  </Card>

  <Card title="Trade Tokens" icon="arrow-right-left" href="/guides/trading">
    Buy, sell, set slippage, and confirm the fill.
  </Card>

  <Card title="API Reference" icon="terminal" href="/api-reference/overview">
    Every endpoint, parameter, and response.
  </Card>
</Columns>

## Before You Ship

We recommend reading [Security Requirements](/concepts/security) before going to production. It covers the handling of PKCE, `state`, and refresh tokens, which are the areas where mistakes are most likely to affect user funds.