tRPC route catalogue

The api and data-provider expose tRPC routers under presentation/. This page enumerates the routers; precise input / output shapes live with the code (packages/business/shared/src/ for the wire DTOs).

api (apps/backend/api)

Located in apps/backend/api/src/presentation/routers/.

Router	Role
`users`	Profile, settings, display currency, magic-link / OTP flows.
`sessions`	Session read / revoke.
`push`	Web Push subscriptions, one per browser per device: the VAPID public key, subscribe, unsubscribe, and a status that reports whether the SERVER has keys at all — so the client can say “this deployment cannot notify you” rather than showing a toggle that silently does nothing.
`accounts`	List, create, update, hide accounts.
`account-types`	Catalogue of account types.
`institutions`	List institutions. Create the synthetic manual institution.
`institution-types`	Catalogue of institution types.
`holdings`	CRUD on holdings, set/unset APY config, attach to vault / group.
`tokens`	Search tokens, materialise via `TokenIdentityService`.
`transactions`	Read the ledger. Filter by date range, kind, account, holding, transfer group.
`vaults`	CRUD on vaults, attach/detach holdings with percentage splits.
`groups`	CRUD on groups, attach holdings + accounts.
`portfolio`	Dashboard headline + chart series (reads `portfolio_value_daily`).
`dashboard`	Aggregate dashboard data — composes calls to `portfolio` + per-scope rollups.
`integrations`	Connect / disconnect provider integrations (Binance OAuth, exchange API keys, brokerage tokens, wallets). Owns encrypt/decrypt of credentials.
`wallet`	Add / discover on-chain wallets.
`screenshots`	Upload screenshot to S3, enqueue `screenshot-parse` job.
`file-import`	Upload CSV / file, enqueue `file-import` job.
`storage`	Presigned URL minting for direct S3 reads.
`payments`	Recurring bills and income: CRUD, pause / end, the occurrence feed (`upcoming` returns overdue rows too), and manual settlement.
`vendors`	Who a payment is with. List, create, rename, and merge two vendors into one.
`documents`	Upload an invoice, read its parse status, confirm or reject the extraction.
`review`	Read-model over everything awaiting the user — pending job results plus pending document extractions.
`transfer-review`	Outflows the `transfer-linking` matcher could not pair: `listPending`, `resolve` (`paired` with a deposit / `left_control` / `untracked`), `reopen`.
`jobs`	HMAC-gated operator endpoints: retry, remove, DLQ replay.
`batch-operations`	Batched mutations the SPA uses for bulk edits.
`client-errors`	Endpoint the SPA posts unhandled-error reports to.
`exports`	`renderPdf` typesets a workbook the client already assembled — it reads no holdings of its own, so a statement cannot drift from the CSV beside it; the account name comes from the session, never the input. `everything` returns the whole account for the “export everything” file.

Auth: every router except the user-facing magic-link entry points requires a Better-Auth session cookie. The jobs router additionally requires an HMAC signature using JOBS_HMAC_SECRET.

data-provider (apps/backend/data-provider)

Located in apps/backend/data-provider/src/presentation/routers/. Composed in apps/backend/data-provider/src/presentation/router.ts.

Router	Auth	Role
`pricing`	Bearer	Current and historical prices via the routed provider stack (CoinGecko, Finnhub, DeFiLlama, Frankfurter, Yahoo Finance).
`chains`	Bearer	Blockchain balance + transaction reads (Etherscan V2 across EVM chains, Helius for Solana, Bitcoin RPC, Tron, TON, ENS).
`ai`	Bearer	Screenshot parsing (OpenAI Vision). Optionally Perplexity / DeepSeek for token-identity assistance.
`tokens`	Bearer	Identity-related calls used by `TokenIdentityService` (CoinGecko slug lookup, Etherscan contract lookup, …).
`email`	Bearer	`email.send` — used by the api to send magic-link / OTP / verification emails.
`storage`	Bearer	Presigned URL minting + the rare server-side read path. The only service that holds S3/R2 credentials; api + worker request presigned URLs from here so creds never leave the data-provider.
`og`	Bearer	Open Graph metadata fetch (used by the SPA’s link previews).
`contact`	Public	Landing-page contact form: validates a submission, emails support, sends a receipt. Per-IP rate-limited. No bearer (called from the public marketing site).
`keys`	Cookie	Cloud-management surface (`CLOUD_MANAGEMENT_ENABLED=true`): mint, list, revoke cloud API keys scoped to the authenticated cloud user.
`usage`	Cookie	Cloud-management read-API: per-user / per-tier usage aggregation from `cloud_usage_events`.
`waitlist`	Public	`waitlist.join` — appends to `waitlist_signups` and sends a confirmation. Per-IP rate-limited (3/hour) with a hashed IP. The landing form that fed it is gone, but the endpoint is live and the rows are still there: everyone in that table was promised a free beta year under the older copy (SC-92).

Auth column: Bearer = DATA_PROVIDER_API_KEY (every api / worker call). Cookie = Better-Auth session, only available when CLOUD_MANAGEMENT_ENABLED=true and the data-provider is fronted by the cloud-frontend. Public = no auth (rate-limited per-IP).

Wire contracts

Input / output shapes are zod schemas in packages/business/shared/src/. Every router’s payload schema is also the source of truth for the SPA’s tRPC client types.

How calls are gated

Three gates fire in order:

Bearer / cookie auth. No bearer / cookie → UNAUTHORIZED.
Capability gate. A call needing a provider key (e.g. ai.parseScreenshot needs OPENAI_API_KEY) returns PRECONDITION_FAILED when unconfigured.
Rate limit. Per-provider rate limiter (@scani/rate-limiter) returns TOO_MANY_REQUESTS when the upstream’s quota is hit. The api retries via BullMQ’s retry policy.

Adding a new router

Create the router file in the appropriate src/presentation/routers/ directory.
Define the input / output zod schema in packages/business/shared/src/.
Register the router in the app’s root router (index.ts alongside the existing routers).
The SPA’s tRPC client picks it up automatically via the end-to-end-typed client factory.