cryptowallet/docs/plans/2026-03-14-tron-backend-proxy-design.md

TRON Backend Proxy Design

Problem

Frontend calls TronGrid API directly from the browser. This causes:

• 429 rate-limit errors (API key passed as query param, not recognized properly)
• API key exposed in NEXT_PUBLIC_ env var (visible to clients)
• CORS issues possible depending on browser/TronGrid config

Solution

Route TRON balance requests through the backend API proxy, matching the existing relay-proxy pattern.

Architecture

Browser -> GET /api/tron/account/:address -> Express API -> GET https://api.trongrid.io/v1/accounts/:address
                                                            Header: TRON-PRO-API-KEY: <key>

Changes

Backend

1. New file: apps/api/src/routes/tron-proxy.routes.ts

   • GET /account/:address - proxies to TronGrid /v1/accounts/:address
   • Validates address format (starts with T, 34 chars, base58)
   • Sends TRON-PRO-API-KEY header (correct TronGrid auth method)
   • 10s timeout with AbortController
   • Returns TronGrid JSON response as-is

2. apps/api/src/config/env.ts - add tronApiKey field

3. apps/api/src/app.ts - register /api/tron route

Frontend

4. apps/web/src/lib/balances/trx-balances.ts - call own API instead of TronGrid
5. apps/web/src/lib/env.ts - remove tronApiUrl and tronApiKey
6. apps/web/.env.local - remove NEXT_PUBLIC_TRON_* vars

Config

7. .env - add TRON_API_KEY=b874d775-4adc-4273-965b-cd6be5f66d68