Sui Portfolio Tracker
A real-time terminal portfolio tracker for Sui that uses Quicknode GraphQL to fetch balances and transaction history, and gRPC streaming to detect live onchain activity.
Visão geral
This sample app is a terminal-based portfolio tracker for the Sui blockchain. It combines two Quicknode Sui API layers: GraphQL for rich balance and transaction queries, and gRPC streaming for real-time checkpoint notifications. For a step-by-step walkthrough, see the companion guide.
On startup, the app fetches initial coin balances and recent transactions via GraphQL. It then opens a persistent gRPC connection to Subscrever Checkpoints on Sui's SubscriptionService, receiving a new checkpoint roughly every 400-500ms. When the stream detects onchain activity for a tracked address, it triggers a debounced GraphQL re-fetch to update the displayed state.
Arquitetura
Startup
App -> Quicknode GraphQL (HTTPS/443)
-> GetBalances + GetTransactions
-> render initial state
Live Updates
App -> Quicknode gRPC (:9000)
-> SubscribeCheckpoints (persistent stream)
-> detect address in sender or balance_changes
-> 2s debounce -> GraphQL re-fetch -> re-render
Características
- GraphQL queries for coin balances (all coin types) and the 20 most recent transactions on startup
- gRPC
Subscrever Checkpointsstream for event-driven detection (~400ms per checkpoint) - Debounced GraphQL re-fetch after relevant checkpoints to avoid redundant requests during bursts
- Inline balance change display for each relevant checkpoint (coin type, direction, amount)
- Multi-address tracking: one gRPC stream, client-side filtering across all addresses
- Automatic gRPC reconnection with exponential backoff (up to 30s)
- Split rendering: stable balance/transaction panel at the top, scrolling live feed below
Pré-requisitos
- Node.js 20+
- pnpm (
npm install -g pnpm) - A Quicknode Sui mainnet endpoint
Estrutura do projeto
src/
index.ts # Entry point, startup orchestration, rendering
graphql.ts # GraphQL queries: GetBalances, GetTransactions
grpc-stream.ts # gRPC stream subscription and checkpoint processing
portfolio.ts # Portfolio state management and terminal rendering
types.ts # TypeScript type definitions
protos/ # Sui proto files (cloned from MystenLabs/sui-apis)
Variáveis de ambiente
Copiar .env.example para .env e preencha:
QN_ENDPOINT_URL=https://your-endpoint.sui-mainnet.quiknode.pro
QN_ENDPOINT_TOKEN=your-token-here
SUI_ADDRESS=0x...
| Variable | Description |
|---|---|
QN_ENDPOINT_URL | Quicknode Sui mainnet endpoint URL (without trailing slash or token) |
QN_ENDPOINT_TOKEN | Auth token (the path segment after the hostname in your endpoint URL) |
SUI_ADDRESS | Sui address(es) to track. Comma-separate multiple addresses |
Finding your token: Your Quicknode endpoint URL looks like https://abc123xyz.sui-mainnet.quiknode.pro/abcdef1234567890. The token is the path segment after the hostname: abcdef1234567890.
To track multiple addresses, comma-separate them:
SUI_ADDRESS=0xabc...,0xdef...,0x123...
Nota: GraphQL uses the token in the URL path; gRPC uses it as an x-token metadata header. Both values come from the same Quicknode endpoint.
Introdução
1. Clone the repo
git clone https://github.com/quiknode-labs/qn-guide-examples.git
cd qn-guide-examples/sui/sui-portfolio-tracker
2. Clone Sui proto files
The gRPC client requires Sui's protobuf definitions:
git clone https://github.com/MystenLabs/sui-apis.git protos
3. Install dependencies
pnpm install
4. Configure environment
cp .env.example .env
Fill in the values from the Environment Variables section above.
5. Run
pnpm start
Scripts
| Command | Description |
|---|---|
pnpm start | Run with tsx (recommended) |
pnpm dev | Run with file watching |
pnpm build | Compile TypeScript |
pnpm start:compiled | Run compiled output |
Pré-visualização
- Fazer um fork do repositório
- Criar um ramo de funcionalidades:git checkout -b feature/amazing-feature
- Envie as suas alterações:git commit -m "Adicionar uma funcionalidade fantástica"
- Envie o seu branch:git push origin feature/amazing-feature
- Abrir um Pull Request.
