Connect a User

Open the Trench consent popup with PKCE, relay the authorization code from your callback, and exchange it for a token pair on your backend.

This guide walks you through connecting a Trench account to your application, ending with an access token you can trade with.

There are three moving parts: a popup that you open, a callback page that you host, and a token exchange that runs on your backend.

Prerequisites

Before starting, make sure you have:

• An app registered at tren.ch/partner, giving you a client_id and an API key. See Registration.
• At least one redirect URI registered, matching exactly what you will send.
• A backend that can hold the client secret, since it must never reach the browser.

Endpoints Used

• GET https://tren.ch/oauth/authorize for the consent screen
• POST /oauth/token to exchange the code

1. Open the Consent Popup

Generate a PKCE verifier and a state value, then open the popup. The window needs to be opened synchronously inside the click handler, otherwise the browser will block it.

const TRENCH = "https://tren.ch";

function base64url(bytes) {
  return btoa(String.fromCharCode(...bytes))
    .replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
}

document.querySelector("#connect-trench").addEventListener("click", async () => {
  // The verifier stays local. Only its hash goes in the URL.
  const verifier = base64url(crypto.getRandomValues(new Uint8Array(48)));
  const state = base64url(crypto.getRandomValues(new Uint8Array(16)));
  const challenge = base64url(new Uint8Array(
    await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier))
  ));

  sessionStorage.setItem("trench_verifier", verifier);
  sessionStorage.setItem("trench_state", state);

  // Open the window first, then point it at the URL.
  const popup = window.open("about:blank", "trench", "width=460,height=720");
  popup.location = `${TRENCH}/oauth/authorize?` + new URLSearchParams({
    client_id: YOUR_CLIENT_ID,
    redirect_uri: "https://yourapp.com/oauth/callback",
    scope: "profile:read trade:execute governance:vote",
    state,
    code_challenge: challenge,
    code_challenge_method: "S256",
  });

  window.addEventListener("message", (event) => {
    if (event.origin !== window.location.origin) return;
    if (event.data?.type !== "trench:oauth") return;
    if (event.data.state !== sessionStorage.getItem("trench_state")) return;
    exchangeOnYourBackend(event.data.code, sessionStorage.getItem("trench_verifier"));
  }, { once: true });
});

All six parameters are required.

Parameter	Constraint
client_id	Your registered client
redirect_uri	Exact match against a registered URI
scope	Space-separated list
state	Random per authorization, verified on return
code_challenge	43 to 128 characters of [A-Za-z0-9_-]
code_challenge_method	Must be S256

The popup runs on the Trench origin, so the user sees tren.ch in the address bar and can confirm who they are approving. Your page cannot read anything inside it.

2. Relay the Code From Your Callback

The popup lands on your redirect_uri with ?code=…&state=… in the query string. At that point it is same-origin with the opener, so it can post the code back and close itself.

<!-- https://yourapp.com/oauth/callback -->
<script>
  const q = new URLSearchParams(location.search);

  window.opener?.postMessage({
    type: "trench:oauth",
    code: q.get("code"),
    state: q.get("state"),
    error: q.get("error"),
  }, location.origin);

  window.close();
</script>

If the user declines, you will receive ?error=access_denied&state=… and no code.

Always compare the returned state against the value you stored before the popup opened. Skipping this check leaves the flow open to CSRF.

3. Exchange the Code

Send the code and the verifier from your backend, authenticating with HTTP Basic.

cURL

curl -X POST 'https://api.tren.ch/oauth/token' \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code=trench_ac_YOUR_CODE \
  -d redirect_uri=https://yourapp.com/oauth/callback \
  -d code_verifier=YOUR_VERIFIER

Response

{
  "access_token": "trench_at_…",
  "token_type": "Bearer",
  "expires_in": 1800,
  "refresh_token": "trench_rt_…",
  "scope": "profile:read trade:execute governance:vote"
}

Store both tokens against your user record. Authorization codes are single use and expire after 10 minutes, and presenting one a second time will revoke every token it issued.

4. Confirm the Connection

Call GET /partner/v1/me with the new access token.

cURL

curl 'https://api.tren.ch/partner/v1/me' \
  -H 'Authorization: Bearer trench_at_…'

{
  "user": {
    "walletSolana": "…",
    "twitterHandle": "…",
    "tradingEnabled": true
  },
  "client": "tclient_…",
  "scopes": ["profile:read", "trade:execute", "governance:vote"]
}

The scopes array in this response reflects what the token can actually do, which may differ from what you requested at authorize time. We recommend treating it as the source of truth.

Mobile Fallback

Popups are unreliable on mobile browsers. You can run the same flow by navigating the whole page instead of opening a window, then reading code from the query string server-side on your callback route. Nothing else about the flow changes.

1-Click Trading

The trade:execute and governance write scopes require the user to have delegated their wallet to Trench. The consent screen enforces this, so if delegation is off, the Approve button stays disabled until the user enables it.

This means you will never be issued a trading token that cannot trade at the time it is created. A user can revoke delegation later, though, so we recommend checking tradingEnabled before showing trade controls. Once delegation is off, writes fail with 403 delegation_missing.

Next Steps

Trade Tokens

Execute your first buy and confirm the fill.

Tokens & Refresh

Keep the connection alive without breaking it.