Portfolio Tracker Skill

An investment portfolio tracker that runs entirely locally. All data stays in

~/.portfolio-tracker/

.

Architecture

• Data:

  ~/.portfolio-tracker/data.json

  (portfolios, assets, prices)
• Config:

  ~/.portfolio-tracker/config.json

  (API keys, wallet addresses, user profile)
• Scripts: TypeScript CLI tools in

  <skill-path>/scripts/

  , run via

  npx tsx

First-Time Setup

Before running any script, ensure dependencies are installed:

npm install --prefix <skill-path>/scripts

Replace

<skill-path>

with the actual installed path of this skill.

How Scripts Work

Each script is a standalone CLI tool. Run them with:

npx tsx <skill-path>/scripts/<script>.ts <command> [args]

Scripts read from stdin when needed and output JSON to stdout.

data-store.ts

• load

  — Read portfolio data (creates default if missing)

• save

  — Write portfolio data (JSON from stdin)

• load-config

  — Read config

• save-config

  — Write config (JSON from stdin)

fetch-prices.ts

• crypto <symbol>

  — Get crypto price (Binance → CoinGecko)

• stock <symbol>

  — Get stock price (Yahoo Finance)

• fx

  — Get USD/CNY/HKD exchange rates

• historical <symbol>

  — Get 3yr monthly historical data

• search <query>

  — Search for assets by name/symbol

• refresh

  — Batch refresh prices (assets JSON from stdin)

binance-sync.ts

• sync <apiKey> <apiSecret>

  — Fetch all Binance balances (6 account types)

• validate <apiKey> <apiSecret>

  — Validate API credentials

ibkr-sync.ts

• sync <token> <queryId>

  — Fetch IBKR positions via Flex Query

• validate <token> <queryId>

  — Validate IBKR credentials

blockchain-sync.ts

• sync <address> [chain]

  — Fetch wallet balances (single chain or all 5 EVM chains)

• validate <address>

  — Validate EVM address

Data Types

Asset

{
  "id": "unique-id",
  "type": "CRYPTO | USSTOCK | HKSTOCK | ASHARE | CASH",
  "symbol": "BTC",
  "name": "Bitcoin",
  "quantity": 1.5,
  "avgPrice": 40000,
  "currentPrice": 50000,
  "currency": "USD | CNY | HKD",
  "transactions": [],
  "source": { "type": "manual | binance | wallet | ibkr" }
}

Portfolio

{
  "id": "unique-id",
  "name": "Main",
  "assets": [...]
}

Workflow Patterns

Viewing Portfolio

1. Load data via

   data-store.ts load

2. Find current portfolio by

   currentPortfolioId

3. Calculate total value using

   quantity * currentPrice

   per asset
4. Convert to display currency using

   exchangeRates

5. Present as a formatted table

Adding Assets

1. Load data
2. Search for the asset using

   fetch-prices.ts search <query>

3. Get current price via

   fetch-prices.ts crypto/stock <symbol>

4. Add asset to current portfolio with a generated unique ID
5. Save data

Refreshing Prices

1. Load data
2. Pipe current portfolio assets to

   fetch-prices.ts refresh

   via stdin
3. Also run

   fetch-prices.ts fx

   for exchange rates
4. Update each asset's

   currentPrice

   and the

   exchangeRates

5. Set

   lastPriceRefresh

   to current ISO timestamp
6. Save data

Syncing from Exchange/Wallet

1. Load config to get credentials
2. Run the appropriate sync script
3. Merge results: update existing assets (match by symbol+source), add new ones
4. Save data

Commands

Available user commands:

• /portfolio

  — View and manage portfolios

• /prices

  — Refresh all prices

• /setup

  — Configure API keys and wallets

• /sync-binance

  — Sync from Binance

• /sync-ibkr

  — Sync from Interactive Brokers

• /sync-wallet

  — Sync from blockchain wallet

• /advise

  — Get AI investment advice