Sui Portfolio Tracker

A fullstack application that calculates the USD balance of all coins held by a wallet address on the Sui blockchain.

Tech Stack

• Frontend: Next.js 16 (App Router), TailwindCSS, TypeScript
• Backend: Next.js API Routes, node-postgres (pg)
• Database: PostgreSQL 16 (Docker)
• Blockchain: Sui Mainnet RPC

Prerequisites

• Node.js 18+
• Docker

Getting Started

1. Install dependencies

npm install

2. Start the database

docker compose up -d

This starts a PostgreSQL container and automatically runs the schema + seed SQL files. The database will be seeded with metadata and price history for 4 coins: SUI, wUSDC, DEEP, CETUS.

3. Configure environment

Create a .env.local file at the project root:

DATABASE_URL=postgresql://dev:dev@localhost:5433/portfolio

Note: The Docker container maps to port 5433 to avoid conflicts with any local PostgreSQL on port 5432. If port 5433 is already in use, update both docker-compose.yml and .env.local accordingly.

4. Run the development server

npm run dev

Open http://localhost:3000 in your browser.

Usage

1. Enter a Sui wallet address in the search bar
2. View the portfolio: total USD value, coin list with prices, PnL, and price changes

Test Wallets

0x200e6f6dd7e974904cab77e52761f8f0e4e27aabe29f44c7b0e272e8e5ecf543

0xdaf1c8ed29d89cd8f217f609bad0a668fa6f158c12000bfa5f93e670c99e24ff

API

GET /api/v1/portfolio/coins

Parameter	Required	Description
address	Yes	Sui wallet address (0x + 64 hex chars)
limit	No	Max number of coins to return

Example:

curl "http://localhost:3000/api/v1/portfolio/coins?address=0x200e6f6dd7e974904cab77e52761f8f0e4e27aabe29f44c7b0e272e8e5ecf543"

Response:

{
  "coins": [
    {
      "coin_type": "0x2::sui::SUI",
      "symbol": "SUI",
      "decimals": 9,
      "icon_url": "https://hop.ag/tokens/SUI.svg",
      "amount": 3.56,
      "usd_value": 10.14,
      "price": 2.85,
      "pnl_today": 0.5,
      "price_change_1d": 5.17,
      "price_change_7d": 9.62,
      "price_change_30d": 16.33
    }
  ],
  "total_usd": 10.55
}

Project Structure

src/
  app/
    page.tsx                          # Main UI page
    api/v1/portfolio/coins/route.ts   # API endpoint
  lib/
    types.ts                          # TypeScript interfaces
    db.ts                             # PostgreSQL connection + queries
    sui-rpc.ts                        # Sui RPC client
    portfolio.ts                      # Business logic (calculations)
  components/                         # React components
  hooks/                              # Custom hooks
db/
  01-schema.sql                       # Database schema
  02-seed.sql                         # Seed data