Security Requirements

​

Secrets

• Keep your API key server-side. It is only ever used in calls to POST /oauth/token and POST /oauth/revoke from your backend, and never belongs on a Partner API request.
• Give each environment its own key, so revoking one does not disturb the others.
• Encrypt tokens at rest and treat them with the same care as passwords.
• Never log tokens or keys, including in error reports and crash traces.

​

Authorization Flow

• Send and verify state on every authorization. Generate it randomly, store it, and compare it when the user returns. This is your CSRF protection.
• Use a fresh PKCE verifier for each authorization. The verifier stays local, and only its SHA-256 hash goes in the URL.
• Verify event.origin on the postMessage from your callback before trusting anything it contains.

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;
  // safe to use event.data.code
}, { once: true });

​

Token Handling

• Handle a 401 by refreshing once, then re-authorizing if the refresh also fails. Avoid retrying in a loop.
• Never refresh concurrently for the same user. Rotation invalidates the loser’s token, and replaying it revokes the whole connection.
• Persist both values on every refresh. The old refresh token stops working as soon as a new one is issued.
• Revoke the refresh token to disconnect a user. Revoking the access token alone only forces an early refresh.

​

Trading

• Avoid sending "0" for minTokensOut or minSolOut in production, since it accepts any fill price the venue offers at execution time. Sending slippageBps instead lets Trench derive the bound for you.
• Treat submitted and processed as pending. Confirm the signature against Solana through your own RPC before telling a user that anything has landed.
• Do not retry writes automatically. The API does not support idempotency keys, so a resent request after a timeout can execute twice. Reconcile against the chain instead.

​

Environments

​

Revocation