portfolio-tracker

# 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:

```bash
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:

```bash
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
```json
{
  "id": "unique-id",
  "type": "CRYPTO | USSTOCK | HKSTOCK | ASHARE | CASH",
  "symbol": "BTC",
  "name": "Bitcoin",
  "quantity": 1.5,...

# Portfolio Tracker — Claude Code Skill

A local-first investment portfolio tracker that runs as a Claude Code skill. All data stays on your machine — no backend, no cloud, no account needed.

## Features

- Track stocks (US, HK, A-shares), crypto, and cash across multiple portfolios
- Sync from **Binance**, **Interactive Brokers**, and **EVM blockchain wallets**
- Real-time prices from Binance, CoinGecko, and Yahoo Finance
- Multi-currency support (USD, CNY, HKD)
- AI investment advice powered by Claude (no API key needed)

## Installation

```bash
npx @anthropic-ai/claude-code skills add <github-url>
```

## Quick Start

```
/setup              # Configure API keys and wallets
/portfolio          # View your portfolio
/portfolio add BTC  # Add an asset
/prices             # Refresh all prices
/sync-binance       # Sync from Binance
/sync-ibkr          # Sync from Interactive Brokers
/sync-wallet        # Sync from blockchain wallet
/advise             # Get AI investment advice
```

## Commands

| Command | Description |
|---------|-------------|
| `/portfolio` | View current portfolio, add/remove/edit assets, manage portfolios |
| `/prices` | Refresh all asset prices and FX rates |
| `/setup` | Configure exchange API keys, wallet addresses, risk profile |
| `/sync-binance` | Sync balances from Binance (spot, funding, earn, futures) |
| `/sync-ibkr` | Sync positions from Interactive Brokers via Flex Query |
| `/sync-wallet` | Sync EVM wallet balances (ETH, BSC, Polygon, Arbitrum, Optimism) |
| `/advise` | Get personalized investment advice from Claude |

## Data Storage

All data is stored locally:

- `~/.portfolio-tracker/data.json` — Portfolios, assets, prices, settings
- `~/.portfolio-tracker/config.json` — API keys, wallet addresses, user profile

## Supported Asset Types

| Type | Examples | Price Source |
|------|----------|-------------|
| CRYPTO | BTC, ETH, SOL | Binance → CoinGecko |
| USSTOCK | AAPL, SPY, QQQ | Yahoo Finance |
| HKSTOCK | 0700.HK, 9988.H...