概覽
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 SubscribeCheckpoints 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.
建築
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
特色
- GraphQL queries for coin balances (all coin types) and the 20 most recent transactions on startup
- gRPC
SubscribeCheckpointsstream 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
先決條件
- Node.js 20+
- pnpm (
npm install -g pnpm) - A Quicknode Sui mainnet endpoint
專案架構
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)
環境變數
複製 .env.example 至 .env 並填寫：
QN_ENDPOINT_URL=https://your-endpoint.sui-mainnet.quiknode.pro
QN_ENDPOINT_TOKEN=your-token-here
SUI_ADDRESS=0x...
| Variable | 說明 |
|---|---|
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...
註： 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.
開始使用
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 | 說明 |
|---|---|
pnpm start | Run with tsx (recommended) |
pnpm dev | Run with file watching |
pnpm build | Compile TypeScript |
pnpm start:compiled | Run compiled output |
預覽
- 分叉此儲存庫
- 建立功能分支：git checkout -b feature/amazing-feature
- 將您的變更提交：git commit -m "新增超棒的功能"
- 推送您的分支：git push origin feature/amazing-feature
- 開啟一個 Pull Request。
